[gnuastro-commits] master 3dff1e4 9/9: Book: edited gal_ds9_reg_read_polygon from DS9 Library, corrected NEWS

[Mohammad Akhlaghi]

branch: master
commit 3dff1e41bd6f1b9c4224c50cf9c795208624ee8e
Author: Natáli D. Anzanello <natali.anzanello@ufrgs.br>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Book: edited gal_ds9_reg_read_polygon from DS9 Library, corrected NEWS
    
    Until now, the function 'gal_ds9_reg_read_polygon' from the DS9 Library had
    '*coordmode' as input to save the mode of the coordinates read from the DS9
    region file. Also, the NEWS file still mentioned the '--polygonfile'
    option!
    
    With this commit, the change removing '*coordmode' as input and writing the
    coordinate mode into the 'status' component of the output 'gal_data_t' is
    now documented. Also, the NEWS file now includes this new feature under the
    '--polygon' option.
    
    Finally, the formatting of the value of this option in 'args.h' and also in
    the book have been corrected. In 'args.h', we simply use 'FLT,FLT[:...]' to
    avoid confusion, and say that a DS9 region file is also possible in the
    description. In the book, there are two '--polygon' items: one with 'STR'
    and one with 'FLT,FLT[:...]'.
---
 NEWS              | 15 +++++++++------
 bin/crop/args.h   |  4 ++--
 bin/table/args.h  |  4 ++--
 doc/gnuastro.texi | 13 ++++++++-----
 4 files changed, 21 insertions(+), 15 deletions(-)

diff --git a/NEWS b/NEWS
index e0c4920..b43c3a8 100644
--- a/NEWS
+++ b/NEWS
@@ -82,11 +82,14 @@ See the end of the file for license conditions.
      you had three input FITS files with input in the same HDU.
 
   Crop:
-   --polygonfile: Draw your polygon in SAO DS9, save it as a "region" file
-     and feed it into Crop with this option. Until now, the only way to
-     define the polygon was to give all the polygon vertice coordinates to
-     the '--polygon' option (which was tedious and buggy when the vertice
-     coordinates aren't defined a-priori).
+   --polygon: now also accepts an SAO DS9 region file as input (as well as
+     coordinates). This enables you to draw your polygon over the image
+     through the GUI interface of SAO DS9, save your polygon as a "region"
+     file, and feed the region file into Crop directly. Until now, the only
+     way to define the polygon was to give all the polygon vertice
+     coordinates, one-by-one to the '--polygon' option (which was tedious
+     and buggy), but is still possible. This was implemented by Natáli
+     Anzanello.
 
   Fits:
    --hastablehdu: print 1 if at least one table HDU exists in file.
@@ -145,7 +148,7 @@ See the end of the file for license conditions.
      when you have a large table and just want to see a random sub-set of
      the rows. It takes an integer, selects that many rows from the input
      randomly.
-   --polygonfile: Similar to same option in Crop (mentioned above).
+   --polygon: Similar to same option in Crop (mentioned above).
    - New column arithmetic operators:
      - 'set-AAA' operator (which allows storing the popped operand into a
        named variable for easy usage in complex operations) is also usable
diff --git a/bin/crop/args.h b/bin/crop/args.h
index 7eddd38..e820275 100644
--- a/bin/crop/args.h
+++ b/bin/crop/args.h
@@ -270,9 +270,9 @@ struct argp_option program_options[] =
     {
       "polygon",
       UI_KEY_POLYGON,
-      "STR",
+      "FLT,FLT[:...]",
       0,
-      "Polygon vertices of region to crop, keep inside.",
+      "Polygon vertices, also a DS9 region file.",
       UI_GROUP_REGION,
       &p->polygon,
       GAL_TYPE_STRING,
diff --git a/bin/table/args.h b/bin/table/args.h
index 7e07bff..efc2402 100644
--- a/bin/table/args.h
+++ b/bin/table/args.h
@@ -224,9 +224,9 @@ struct argp_option program_options[] =
     {
       "polygon",
       UI_KEY_POLYGON,
-      "STR,FLT:FLT[,...]",
+      "FLT,FLT[:...]",
       0,
-      "Polygon for '--inpolygon' or '--outpolygon'.",
+      "Polygon vertices, also a DS9 region file.",
       UI_GROUP_OUTROWS,
       &p->polygon,
       GAL_TYPE_STRING,
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 49888ea..2a74662 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -10725,7 +10725,8 @@ We are working on other options for this.
 Only return rows where the given coordinates are outside the polygon specified 
by the @option{--polygon} option.
 This option is very similar to the @option{--inpolygon} option, so see the 
description there for more.
 
-@item --polygon=STR,FLT:FLT,...
+@item --polygon=STR
+@itemx --polygon=FLT,FLT:FLT,FLT:...
 The polygon to use for the @code{--inpolygon} and @option{--outpolygon} 
options.
 This option behaves identically to the same option in the Crop program, so for 
more information on how to use it, see @ref{Crop options}.
 
@@ -11718,9 +11719,11 @@ For example if you want the width of your crop to be 3 
by 5 arcseconds along RA
 If you want an even sided crop, you can run Crop afterwards with 
@option{--section=":*-1,:*-1"} or @option{--section=2:,2:} (depending on which 
side you don't need), see @ref{Crop section syntax}.
 
 @item -l STR
+@itemx -l FLT:FLT,...
 @itemx --polygon=STR
-String of vertices or the filename of a SAO DS9 region file to define a 
polygon to crop.
-The vertices are used to define the polygon in the same order given to this 
option.
+@itemx --polygon=FLT,FLT:FLT,FLT:...
+Polygon vertice coordinates (when value is in @option{FLT,FLT:FLT,FLT:...} 
format) or the filename of a SAO DS9 region file (when the value has no 
@file{,} or @file{:} characters).
+The vertices are used to define the polygon: in the same order given to this 
option.
 When the vertices are not necessarily ordered in the proper order (for example 
one vertice in a square comes after its diagonal opposite), you can add the 
@option{--polygonsort} option which will attempt to sort the vertices before 
cropping.
 Note that for concave polygons, sorting is not recommended because there is no 
unique solution, for more, see the description under @option{--polygonsort}.
 
@@ -29517,13 +29520,13 @@ Their names are sufficiently descriptive.
 The last one (@code{INVALID}) is for sanity checks (for example, to know if 
the mode is already selected).
 @end deffn
 
-@deftypefun {gal_data_t *} gal_ds9_reg_read_polygon (char @code{*filename}, 
int @code{*coordmode})
+@deftypefun {gal_data_t *} gal_ds9_reg_read_polygon (char @code{*filename})
 @cindex SAO DS9 region file
 @cindex Region file (SAO DS9)
 Returns an allocated generic data container (@code{gal_data_t}, with an array 
of @code{GAL_TYPE_FLOAT64}) containing the vertices of a polygon within the SAO 
DS9 region file given by @code{*filename}.
 Since SAO DS9 region files are 2 dimensional, if there are @mymath{N} vertices 
in the SAO DS9 region file, the returned dataset will have @mymath{2\times N} 
elements (first two elements belonging to first vertice, and etc).
 
-The mode to interpret the vertice coordiantes is also read from the SAO DS9 
region file and written into the space that @code{*coordmode} points to.
+The mode to interpret the vertice coordiantes is also read from the SAO DS9 
region file and written into the @code{status} attribute of the output 
@code{gal_data_t}.
 The coordinate mode can be one of the @code{GAL_DS9_COORD_MODE_*} macros, 
mentioned above.
 
 It is assumed that the file begins with @code{# Region file format: DS9} and 
it has two more lines (at least):