[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnuastro-commits] master ae6b9d80 3/3: Book: added new section in wcs.h
From: |
Mohammad Akhlaghi |
Subject: |
[gnuastro-commits] master ae6b9d80 3/3: Book: added new section in wcs.h description on freeing |
Date: |
Thu, 29 Sep 2022 12:28:00 -0400 (EDT) |
branch: master
commit ae6b9d80d52cb07f11cd642c0b4dc0d62562c247
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Book: added new section in wcs.h description on freeing
Until now, the example on how to properly free a WCS structure was only in
the description of the 'gal_wcs_create' function. However, there were two
issues: 1) It wasn't a complete program for someone to just copy-paste. 2)
It can be useful for other functions that read a WCS structure also.
With this commit, the example has been completed and moved to a whole new
section under the description of wcs.h functions.
---
doc/gnuastro.texi | 102 ++++++++++++++++++++++++++++++++++++++++--------------
1 file changed, 76 insertions(+), 26 deletions(-)
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 1f8e3f1b..0ff3910b 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -33187,6 +33187,78 @@ The FITS standard defines the world coordinate system
(WCS) as a mechanism to as
For example, it can be used to convert pixel coordinates in an image to
celestial coordinates like the right ascension and declination.
The functions in this section are mainly just wrappers over CFITSIO, WCSLIB
and GSL library functions to help in common applications.
+In the two sub-sub-sections below, we will first explain the best approach to
avoid memory leaks when freeing a WCS structure.
+Afterwards, we'll describe all the WCS-related functions of Gnuastro.
+
+@node Freeing a WCS structure
+@subsubsection Freeing a WCS structure
+Through the functions in @ref{WCS Function and global constants} you can read
a WCS structure from a file (@code{gal_wcs_read}), an already-open CFITSIO FITS
pointer (@code{gal_wcs_read_fitsptr}) or create one yourself
(@code{gal_wcs_create}).
+In any of these cases, after you have completed your work with the WCS
structure, you should free it.
+
+To free a WCS pointer that comes from Gnuastro's functions, first free the WCS
structure's contents using WCSLIB's @code{wcsfree} function.
+Afterwards, free the actual structure with the @code{free} function of the
standard C library (@file{stdlib.h}).
+Remember that @code{wcsfree} only frees the contents, not the structure that
was allocated inside Gnuastro's library.
+
+Below you can see a fully working example program that will create a WCS
structure from scratch and will later free it properly (without any memory
leak).
+If you save the code below in a file called @file{wcs-create-free.c}, you can
compile and run it using @ref{BuildProgram} with this command:
@command{astbuildprog wcs-create-free.c}.
+
+@example
+@verbatim
+#include <stdio.h>
+#include <stdlib.h>
+#include <gnuastro/wcs.h>
+
+int
+main(void)
+{
+ int status;
+ size_t ndim=2;
+ struct wcsprm *wcs;
+ double crpix[]={50, 50};
+ double pc[]={-1, 0, 0, 1};
+ double cdelt[]={0.4, 0.4};
+ double crval[]={178.23, 36.98};
+ char *cunit[]={"deg", "deg"};
+ char *ctype[]={"RA---TAN", "DEC--TAN"};
+ int linearmatrix = GAL_WCS_LINEAR_MATRIX_PC;
+
+ /* Allocate and fill the 'wcsprm' structure. */
+ wcs=gal_wcs_create(crpix, crval, cdelt, pc, cunit,
+ ctype, ndim, linearmatrix);
+ printf("WCS structure created.\n");
+
+ /* Free the contents (and check if there was a problem). */
+ status=wcsfree(wcs);
+ if(status)
+ {
+ /* Inform the user of the problem. */
+ fprintf(stderr, "%s: WCSLIB wcsfree ERROR %d: %s",
+ __func__, status, wcs_errmsg[status]);
+
+ /* Return with a failure (don't continue with the
+ rest of the function). */
+ return EXIT_FAILURE;
+ }
+
+ /* Let the user know */
+ printf("WCS structure's contents freed.\n");
+
+ /* Free the actual 'wcsprm' structure. */
+ free(wcs);
+ printf("WCS structure freed.\n");
+
+ /* Return successfully. */
+ return EXIT_SUCCESS;
+}
+@end verbatim
+@end example
+
+@node WCS Function and global constants
+@subsubsection WCS Function and macros
+
+The full set of functions and global constants that are defined by Gnuastro's
@file{gnuastro/wcs.h} are described below.
+For freeing a WCS structure after reading or creating one, see @ref{Freeing a
WCS structure}.
+
@deffn Macro GAL_WCS_DISTORTION_TPD
@deffnx Macro GAL_WCS_DISTORTION_SIP
@deffnx Macro GAL_WCS_DISTORTION_TPV
@@ -33244,11 +33316,7 @@ Limit of rounding for floating point errors.
[@strong{Not thread-safe}] Return the WCSLIB @code{wcsprm} structure that is
read from the CFITSIO @code{fptr} pointer to an opened FITS file.
Also put the number of coordinate representations found into the space that
@code{nwcs} points to.
To read the WCS structure directly from a filename, see @code{gal_wcs_read}
below.
-After processing has finished, you can free the returned structure with
WCSLIB's @code{wcsvfree} keyword:
-
-@example
-status = wcsvfree(&nwcs,&wcs);
-@end example
+After processing has finished, you should free the WCS structure, for doing
that properly, see @ref{Freeing a WCS structure}.
The @code{linearmatrix} argument takes one of three values: @code{0},
@code{GAL_WCS_LINEAR_MATRIX_PC} and @code{GAL_WCS_LINEAR_MATRIX_CD}.
It will determine the format of the WCS when it is later written to file with
@code{gal_wcs_write} or @code{gal_wcs_write_in_fitsptr} (which is called by
@code{gal_fits_img_write})
@@ -33270,6 +33338,8 @@ Therefore, be sure to not call this function
simultaneously (over multiple threa
[@strong{Not thread-safe}] Return the WCSLIB structure that is read from the
HDU/extension @code{hdu} of the file @code{filename}.
Also put the number of coordinate representations found into the space that
@code{nwcs} points to.
Please see @code{gal_wcs_read_fitsptr} for more.
+
+After processing has finished, you should free the WCS structure, for doing
that properly, see @ref{Freeing a WCS structure}.
@end deftypefun
@deftypefun {struct wcsprm *} gal_wcs_create (double @code{*crpix}, double
@code{*crval}, double @code{*cdelt}, double @code{*pc}, char @code{**cunit},
char @code{**ctype}, size_t @code{ndim}, int @code{linearmatrix})
@@ -33280,27 +33350,7 @@ Also, @code{cunit} and @code{ctype} are arrays of
strings.
If @code{GAL_WCS_LINEAR_MATRIX_CD} is passed to @code{linearmatrix} then the
output WCS structure will have a CD matrix (even though you have given a PC and
CDELT matrix as input to this function).
Otherwise, the output will have a PC and CDELT matrix (which is the
recommended format by WCSLIB).
-To prevent memory-leak, free the WCS structure first by WCSLIB's
@code{wcsfree} function, and then the pointer with @code{stdlib.h}'s
@code{free} when the process is finished:
-
-@example
-@verbatim
-int status;
-size_t ndim=2;
-double crpix[]={50, 50};
-double pc[]={-1, 0, 0, 1};
-double cdelt[]={0.4, 0.4};
-double crval[]={178.23, 36.98};
-char *cunit[]={"deg", "deg"};
-char *ctype[]={"RA---TAN", "DEC--TAN"};
-int linearmatrix = GAL_WCS_LINEAR_MATRIX_PC;
-struct wcsprm *wcsp =
- gal_wcs_create(crpix, crval, cdelt, pc, cunit,
- ctype, ndim, linearmatrix);
-status = wcsfree(wcsp);
-free(wcsp);
-@end verbatim
-@end example
-
+For a fully working example of creating a WCS structure with this function and
how to later free it, see @ref{Freeing a WCS structure}.
@end deftypefun
@deftypefun {char *} gal_wcs_dimension_name (struct wcsprm @code{*wcs}, size_t
@code{dimension})