[gnuastro-commits] master f3cb24f 2/2: txtarray.h and wcs.h documented in the book.

[Mohammad Akhlaghi]

branch: master
commit f3cb24fdb07b47a4b3b11df95cc93cfd3a031b98
Author: Mohammad Akhlaghi <address@hidden>
Commit: Mohammad Akhlaghi <address@hidden>

    txtarray.h and wcs.h documented in the book.
    
    The functions in these two final headers are now documented in the book.
---
 doc/gnuastro.texi       |  133 +++++++++++++++++++++++++++++++++++++++++++++--
 lib/gnuastro/txtarray.h |    2 -
 lib/txtarray.c          |    3 ++
 lib/wcs.c               |   28 +++++-----
 4 files changed, 147 insertions(+), 19 deletions(-)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 0964ba7..ba317a7 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -519,6 +519,8 @@ Gnuastro library
 * Spatial convolution::         Doing spatial convolution on an image
 * Statistical operations::      Functions for basic statistics.
 * Multithreaded programming::   Facilitating use of pthreads.
+* World Coordinate System::     Dealing with the world coordinate system.
+* Text table into a C array::   Read an ASCII text table into a C array.
 
 FITS files (@file{fits.h})
 
@@ -14777,6 +14779,8 @@ problems. It will stabilize with the removal of this 
notice. Check the
 * Spatial convolution::         Doing spatial convolution on an image
 * Statistical operations::      Functions for basic statistics.
 * Multithreaded programming::   Facilitating use of pthreads.
+* World Coordinate System::     Dealing with the world coordinate system.
+* Text table into a C array::   Read an ASCII text table into a C array.
 @end menu
 
 @node Installation information, Array manipulation, Gnuastro library, Gnuastro 
library
@@ -16246,8 +16250,8 @@ data structure. The functions here are all meant to be 
passed onto
 manner. Because of this all these functions have the same two argument
 types.
 
address@hidden {Global variable} {float *gal_qsort_index_arr}
-Pointer to a floating point array to use as a reference in
address@hidden {Global variable} {gal_qsort_index_arr}
+Pointer to a floating point array (@code{float *}) to use as a reference in
 @code{gal_qsort_index_float_decreasing}, see the explanation there for
 more.
 @end deffn
@@ -16658,7 +16662,7 @@ ApJS 220, 1. arXiv:1505.01664).
 
 
 
address@hidden Multithreaded programming,  , Statistical operations, Gnuastro 
library
address@hidden Multithreaded programming, World Coordinate System, Statistical 
operations, Gnuastro library
 @subsection Multithreaded programming (@file{threads.h})
 
 @cindex Multithreaded programming
@@ -16836,6 +16840,129 @@ demonstration.
 
 
 
address@hidden Text table into a C array,  , World Coordinate System, Gnuastro 
library
address@hidden Text table into a C array (@file{txtarray.h})
+
+One of the most common formats to store and transfer normally sized data
+are ASCII files (which can be seen on a text editor). During your
+processing experiments (with the data, or what programmers call
+``developing'') you will also often want to see how your data is being
+processed and one of the easiest ways to check out out your arrays is to
+write them out as an ASCII file and check them. The functions here are
+mainly focused on tables that contain numbers.
+
address@hidden Macro GAL_TXTARRAY_LOG
+When an element of the input table cannot be read as a number, the column
+and row number of the element are stored along with the element into one
+row of a log file. This macro contains the name of the log-file.
address@hidden deffn
+
+
address@hidden void gal_txtarray_txt_to_array (char @code{*filename}, double 
@code{**array}, size_t @code{*s0}, size_t @code{*s1})
+Store the ASCII text table in @file{filename} into the C array @code{array}
+which has @code{s0} rows and @code{s1} columns. Any blank lines or lines
+starting with @code{#} (comments) will be ignored. The column delimiters
+(separating one column from the previous and next) are address@hidden }' 
(space),
address@hidden,}', `TAB'.
address@hidden deftypefun
+
address@hidden void gal_txtarray_printf_format (int @code{numcols}, char 
@code{**fmt}, int @code{*int_cols}, int @code{*accu_cols}, int @code{*space}, 
int @code{*prec}, char @code{forg})
+Return the @code{printf} formatting string (@code{fmt}) for @code{numcols}
+columns. Three types of output columns are assumed: integers, normal
+accuracy floating points and extra-precision floating points. Normally most
+columns will not need too much accuracy when printing (for example only 3
+decimals might be enough). However usually a very limited number of columns
+will need more precision (like RA and Dec). So to store space (each
+character is a byte) and also make the table more readable, we allow these
+two types of floating points.
+
address@hidden and @code{accu_cols} are arrays containing the column
+numbers (starting from zero) that contain integers and extra-accuracy
+columns. The ending of the column indexes in @code{int_cols} and
address@hidden is defined by a negative number. @code{space} is a three
+element array which will keep the number of characters that must be used
+for the integer, normal-accuracy and extra-accuracy columns. @code{prec} is
+a two element array which contains the number of decimas to print for the
+normal and extra accuracy columns. @code{forg} (read as `f-or-g') is the
address@hidden type for the floating point numbers: either @code{f} (as in
address@hidden, which will only print decimals) and @code{g} (as in @code{%g},
+for either printing decimals or exponentials). See
address@hidden for more.
address@hidden deftypefun
+
address@hidden void gal_txtarray_array_to_txt (double @code{*array}, size_t 
@code{s0}, size_t @code{s1}, char @code{*comments}, int @code{*int_cols}, int 
@code{*accu_cols}, int @code{*space}, int @code{*prec}, char @code{forg}, const 
char @code{*filename})
+Print the C array @code{array} (with @code{s0} rows and @code{s1} columns)
+as an ASCII text table in @code{filename}. The string pointed to by
address@hidden will be printed at the top of the table. See the
+explanation of @code{gal_txtarray_printf_format} for the other arguments.
address@hidden deftypefun
+
+
+
+
+
address@hidden World Coordinate System, Text table into a C array, 
Multithreaded programming, Gnuastro library
address@hidden World Coordinate System (@file{wcs.h})
+
+The FITS world coordinate system is a mechanism to give physical values to
+the data points. In the case of images, it can be used to convert pixel
+images to celestial coordinates like the right ascension and
+declination. Gnuastro doesn't have any functions to actually do the
+transformations, the standard tool for doing this in astronomy is WCSLIB
+(see @ref{WCSLIB}). The functions introduced here are just wrappers around
+the lower-level functions provided by WCSLIB.
+
address@hidden void gal_wcs_xy_array_to_radec (struct wcsprm @code{*wcs}, 
double @code{*xy}, double @code{*radec}, size_t @code{number}, size_t 
@code{stride})
+Convert the image coordinates @code{xy} (a two column array with
address@hidden rows) to world coordinates @code{wcs} (also a two column
+array, which has to have been allocated prior to this function) using the
+conversion parameters in @code{wcs}. @code{stride} is the number of columns
+in a larger array, see below.
+
+It might happen that you have one array which contains both the image and
+world coordinates along with many more columns. @code{stride} is the width
+of that larger array. If such an array doesn't exist and @code{xy} and
address@hidden are separately allocated arrays with
address@hidden@code{number} elements, then just set the value of
address@hidden to @code{2}.
address@hidden deftypefun
+
address@hidden void gal_wcs_radec_array_to_xy (struct wcsprm @code{*wcs}, 
double @code{*radec}, double @code{*xy}, size_t @code{number}, size_t 
@code{stride})
+Similar to @code{gal_wcs_xy_array_to_radec} but convert the world
+coordinates in @code{radec} to image coordinates in @code{xy}.
address@hidden deftypefun
+
address@hidden double gal_wcs_angular_distance (double @code{r1}, double 
@code{d1}, double @code{r2}, double @code{d2})
+Return the angular distance between a point located at (@code{r1},
address@hidden) to (@code{r2}, @code{d2}). The distance (along a great circle)
+on a sphere between two points is calculated with the equation below. Since
+the pixel sides are usually very small, we won't be using the direct
+formula:
+
address@hidden {\cos(d)=\sin(d_1)\sin(d_2)+\cos(d_1)\cos(d_2)\cos(r_1-r_2)}
+
+Here, we will be using the
address@hidden://en.wikipedia.org/wiki/Haversine_formula, Haversine formula}
+which better considering floating point errors:
+
address@hidden(d)\over 2}=\sin^2\left( {d_1-d_2\over 2} 
\right)+\cos(d_1)\cos(d_2)\sin^2\left( {r_1-r_2\over 2} \right)}
address@hidden deftypefun
+
address@hidden double gal_wcs_pixel_area_arcsec2 (struct wcsprm @code{*wcs})
+Given the WCS structure @code{wcs} calculate the pixel area in
+arcsec-squared.
address@hidden deftypefun
+
+
+
+
+
+
+
+
+
+
+
 
 
 
diff --git a/lib/gnuastro/txtarray.h b/lib/gnuastro/txtarray.h
index c394aa5..e889240 100644
--- a/lib/gnuastro/txtarray.h
+++ b/lib/gnuastro/txtarray.h
@@ -48,8 +48,6 @@ __BEGIN_C_DECLS  /* From C++ preparations */
 
 
 /* Simple macros: */
-#define GAL_TXTARRAY_FMT_LENGTH     50
-#define GAL_TXTARRAY_DELIMITERS    " ,\t\n"
 #define GAL_TXTARRAY_LOG "txtarray.log"
 
 
diff --git a/lib/txtarray.c b/lib/txtarray.c
index 279d252..6ea2123 100644
--- a/lib/txtarray.c
+++ b/lib/txtarray.c
@@ -35,6 +35,9 @@ along with Gnuastro. If not, see 
<http://www.gnu.org/licenses/>.
 
 
 
+/* Internal macros */
+#define GAL_TXTARRAY_FMT_LENGTH     50
+#define GAL_TXTARRAY_DELIMITERS    " ,\t\n"
 
 
 
diff --git a/lib/wcs.c b/lib/wcs.c
index e569f0c..5d17828 100644
--- a/lib/wcs.c
+++ b/lib/wcs.c
@@ -53,7 +53,7 @@ along with Gnuastro. If not, see 
<http://www.gnu.org/licenses/>.
 */
 void
 gal_wcs_xy_array_to_radec(struct wcsprm *wcs, double *xy, double *radec,
-                          size_t number, size_t width)
+                          size_t number, size_t stride)
 {
   size_t i;
   double imgcrd[2], phi, theta;
@@ -61,19 +61,19 @@ gal_wcs_xy_array_to_radec(struct wcsprm *wcs, double *xy, 
double *radec,
 
   for(i=0;i<number;++i)
     {
-      if(isnan(xy[i*width]) || isnan(xy[i*width+1]))
-        radec[i*width]=radec[i*width+1]=NAN;
+      if(isnan(xy[i*stride]) || isnan(xy[i*stride+1]))
+        radec[i*stride]=radec[i*stride+1]=NAN;
       else
         {
-          status=wcsp2s(wcs, ncoord, nelem, xy+i*width, imgcrd, &phi,
-                        &theta, radec+i*width, &stat);
+          status=wcsp2s(wcs, ncoord, nelem, xy+i*stride, imgcrd, &phi,
+                        &theta, radec+i*stride, &stat);
           if(status)
             error(EXIT_FAILURE, 0, "wcsp2s ERROR %d: %s", status,
                   wcs_errmsg[status]);
 
           /* For a check:
-             printf("(%f, %f) --> (%f, %f)\n", xy[i*width], xy[i*width+1],
-                    radec[i*width], radec[i*width+1]);
+             printf("(%f, %f) --> (%f, %f)\n", xy[i*stride], xy[i*stride+1],
+                    radec[i*stride], radec[i*stride+1]);
           */
         }
     }
@@ -87,7 +87,7 @@ gal_wcs_xy_array_to_radec(struct wcsprm *wcs, double *xy, 
double *radec,
    array of RA-Dec to X-Y. */
 void
 gal_wcs_radec_array_to_xy(struct wcsprm *wcs, double *radec, double *xy,
-                          size_t number, size_t width)
+                          size_t number, size_t stride)
 {
   size_t i;
   double imgcrd[2], phi, theta;
@@ -95,19 +95,19 @@ gal_wcs_radec_array_to_xy(struct wcsprm *wcs, double 
*radec, double *xy,
 
   for(i=0;i<number;++i)
     {
-      if(isnan(radec[i*width]) || isnan(radec[i*width+1]))
-        radec[i*width]=radec[i*width+1]=NAN;
+      if(isnan(radec[i*stride]) || isnan(radec[i*stride+1]))
+        radec[i*stride]=radec[i*stride+1]=NAN;
       else
         {
-          status=wcss2p(wcs, ncoord, nelem, radec+i*width, &phi, &theta,
-                        imgcrd, xy+i*width, &stat);
+          status=wcss2p(wcs, ncoord, nelem, radec+i*stride, &phi, &theta,
+                        imgcrd, xy+i*stride, &stat);
           if(status)
             error(EXIT_FAILURE, 0, "wcss2p ERROR %d: %s", status,
                   wcs_errmsg[status]);
 
           /* For a check:
-          printf("(%f, %f) --> (%f, %f)\n", radec[i*width], radec[i*width+1],
-                 xy[i*width], xy[i*width+1]);
+          printf("(%f, %f) --> (%f, %f)\n", radec[i*stride], radec[i*stride+1],
+                 xy[i*stride], xy[i*stride+1]);
           */
         }
     }