[gnuastro-commits] master d2bca9d 6/9: Crop and Table: --polygonfile new name for --polygonname

[Mohammad Akhlaghi]

branch: master
commit d2bca9d3c4e2a1aa09f9115d515113c0c6f2132b
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Crop and Table: --polygonfile new name for --polygonname
    
    Until now, the '--polygonname' option was used to specify the SAO DS9
    region file that contains the polygon to use. However, this could be
    confused with the actual name of some polygons that have a name: for
    example "tiangle" or "octagon"!
    
    With this commit, the option has been renamed to '--polygonfile' in both
    Crop and Table. Also, I noticed that the short '-t' option was only used
    for Crop and not Table. Generally, when there is a similar option between
    two programs, they should behave similarly to avoid confusion for the
    users. So the short format of this option was removed in Crop is well.
    
    In the process, some other changes have been made which are listed below:
    
     - The NEWS file has been updated with all the new features added.
    
     - In Table, the coordinate system of the vertices is irrelevant: the user
       specifies the columns to check with and there is no way we can know if
       they are image or WCS. So the check on having a reasonable coordinate
       has been removed. But generally, Natáli, when you want to break a
       conditional into two lines, bring the conditional operator to the start
       of the next/second line, not the end of the first line. This helps a lot
       in readability (the eye is much less prone to miss something at the
       start of a line, rather than at the end of it), like below:
    
          if( ds9regmode!=GAL_DS9_COORD_MODE_IMG
              && ds9regmode!=GAL_DS9_COORD_MODE_WCS )
    
     - In the book, I generally noticed that sometimes "SAO ds9" was used and
       some times "SAO DS9" (long before this branch). So to unify things, they
       are all now "SAO DS9" (following its own webpage).
    
     - In the book, some index items were added (with '@cindex').
    
     - In the book, the expected format of the region file has been taken to
       the 'gal_ds9_reg_read_polygon' function. In the description of
       '--polygonfile', it only points the interested reader to there. This
       helps most users of Crop or Table (a high-level user will generally not
       be interested in low-level things and can even find them annoying and
       distracting).
    
     - In the book, the polygon line of the example region file was too long
       for the printed format (created with 'make pdf'). So I shortened the
       example vertices.
    
     - In the book, at the start of the library section on SAO DS9, there was
       no description of what SAO DS9 actually is. I know its clear for most
       astronomers, but the library is sometimes inspected by non-astronomers,
       so its always good to start each section with the most basic description
       and explain a little more on what the whole purpose is for someone with
       no background.
    
     - In the book, the three macros were brought into one '@deffn' (second and
       third with a '@deffnx') Since they are related, this helps in
       readability and avoids the need to repeat things in the description.
---
 NEWS              |  16 +++--
 bin/crop/args.h   |   6 +-
 bin/crop/main.h   |   2 +-
 bin/crop/ui.c     |  12 ++--
 bin/crop/ui.h     |   4 +-
 bin/table/args.h  |   6 +-
 bin/table/main.h  |   2 +-
 bin/table/ui.c    |  31 ++++------
 bin/table/ui.h    |   2 +-
 doc/gnuastro.texi | 182 +++++++++++++++++++++++++++++-------------------------
 lib/ds9.c         |   5 +-
 11 files changed, 144 insertions(+), 124 deletions(-)

diff --git a/NEWS b/NEWS
index ecc3160..e0c4920 100644
--- a/NEWS
+++ b/NEWS
@@ -81,6 +81,13 @@ See the end of the file for license conditions.
      Arithmetic. Until now it was necessary to call '--hdu' three times if
      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).
+
   Fits:
    --hastablehdu: print 1 if at least one table HDU exists in file.
    --hasimagehdu: print 1 if at least one image HDU exists in file.
@@ -130,17 +137,15 @@ See the end of the file for license conditions.
      "clean" (no NaN values in any column) table, but the table has many
      columns. Until now, '--noblank' needed the name/number of each column
      to "clean".
-
    --rowlimit: new option to specify the positional interval of rows to
      show. Until now, the '--head' or '--tail' options would just allow
      seeing the first or last few rows. You can use this new option to view
      a contiguous set of rows in the middle of the table.
-
    --rowrandom: Make a random selection of the rows. This option is useful
      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 and returns them.
-
+     randomly.
+   --polygonfile: 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
@@ -170,6 +175,9 @@ See the end of the file for license conditions.
      This feature was suggested by Ignacio Trujillo.
 
   Library:
+   - gal_ds9_reg_read_polygon: Parse the polygon from an SAO DS9 region file.
+   - gal_units_counts_to_mag: Convert counts to magnitudes.
+   - gal_units_counts_to_jy: Convert counts to Janskys.
    - New arithmetic operator macros (for the 'gal_arithmetic' function):
      - GAL_ARITHMETIC_OP_SIN: sine (input in deg).
      - GAL_ARITHMETIC_OP_COS: cosine (input in deg).
diff --git a/bin/crop/args.h b/bin/crop/args.h
index 6bbd6b2..dd1b7d3 100644
--- a/bin/crop/args.h
+++ b/bin/crop/args.h
@@ -308,13 +308,13 @@ struct argp_option program_options[] =
       GAL_OPTIONS_NOT_SET
     },
     {
-      "polygonname",
-      UI_KEY_POLYGONNAME,
+      "polygonfile",
+      UI_KEY_POLYGONFILE,
       "REG",
       0,
       "Input polygon filename made in DS9.",
       UI_GROUP_REGION,
-      &p->polygonname,
+      &p->polygonfile,
       GAL_TYPE_STRING,
       GAL_OPTIONS_RANGE_ANY,
       GAL_OPTIONS_NOT_MANDATORY,
diff --git a/bin/crop/main.h b/bin/crop/main.h
index 31098d2..919d186 100644
--- a/bin/crop/main.h
+++ b/bin/crop/main.h
@@ -99,7 +99,7 @@ struct cropparams
   gal_data_t          *polygon;  /* Input string of polygon vertices.     */
   uint8_t           polygonout;  /* ==1: Keep the inner polygon region.   */
   uint8_t          polygonsort;  /* Don't sort polygon vertices.          */
-  char            *polygonname;  /* Name of input polygon file.           */
+  char            *polygonfile;  /* Name of input polygon file.           */
 
   /* Internal */
   size_t                 numin;  /* Number of input images.               */
diff --git a/bin/crop/ui.c b/bin/crop/ui.c
index b6f4e2e..4c2e18b 100644
--- a/bin/crop/ui.c
+++ b/bin/crop/ui.c
@@ -278,11 +278,11 @@ ui_check_polygon_from_ds9(struct cropparams *p)
   int ds9regmode;
 
   /* This is only relevant when a region file is actually given. */
-  if(p->polygonname)
+  if(p->polygonfile)
     {
       /* These two options cannot be called together. */
       if(p->polygon)
-        error(EXIT_FAILURE, errno, "'--polygon' and '--polygonname' "
+        error(EXIT_FAILURE, errno, "'--polygon' and '--polygonfile' "
               "cannot be given together. With the first you specify the "
               "polygon vertices directly on the command-line. With the "
               "second, you give a DS9 region file and the polygon "
@@ -290,7 +290,7 @@ ui_check_polygon_from_ds9(struct cropparams *p)
       else
         {
           /* Extract the polygon and the coordinate mode. */
-          p->polygon=gal_ds9_reg_read_polygon(p->polygonname,
+          p->polygon=gal_ds9_reg_read_polygon(p->polygonfile,
                                               &ds9regmode);
           switch(ds9regmode)
             {
@@ -306,8 +306,8 @@ ui_check_polygon_from_ds9(struct cropparams *p)
         }
 
       /* Clean up. */
-      free(p->polygonname);
-      p->polygonname=NULL;
+      free(p->polygonfile);
+      p->polygonfile=NULL;
     }
 }
 
@@ -325,7 +325,7 @@ ui_read_check_only_options(struct cropparams *p)
 
   /* If a DS9 region file should be used for the polygon, read it. This is
      done first for two reasons. 1) It can change the value of '--mode'. 2)
-     It will set the '--polygon' option's value. */
+     It will set the '--polygon' option's value (if not set). */
   ui_check_polygon_from_ds9(p);
 
   /* Make sure that only one of the crop definitions is given. */
diff --git a/bin/crop/ui.h b/bin/crop/ui.h
index 7826f63..d6f4326 100644
--- a/bin/crop/ui.h
+++ b/bin/crop/ui.h
@@ -45,7 +45,7 @@ enum program_args_groups
 
 /* Available letters for short options:
 
-   a d e f g i j k m r u v y
+   a d e f g i j k m r t u v y
    A B E G H J L Q R W X Y
 */
 enum option_keys_enum
@@ -62,7 +62,6 @@ enum option_keys_enum
   UI_KEY_WIDTH          = 'w',
   UI_KEY_CENTER         = 'c',
   UI_KEY_COORDCOL       = 'x',
-  UI_KEY_POLYGONNAME    = 't',
 
   /* Only with long version (start with a value 1000, the rest will be set
      automatically). */
@@ -71,6 +70,7 @@ enum option_keys_enum
   UI_KEY_HENDWCS,
   UI_KEY_POLYGONOUT,
   UI_KEY_POLYGONSORT,
+  UI_KEY_POLYGONFILE,
   UI_KEY_CHECKCENTER,
   UI_KEY_PRIMARYIMGHDU,
 };
diff --git a/bin/table/args.h b/bin/table/args.h
index a3e82d5..91991d3 100644
--- a/bin/table/args.h
+++ b/bin/table/args.h
@@ -236,13 +236,13 @@ struct argp_option program_options[] =
       gal_options_parse_colon_sep_csv
     },
     {
-      "polygonname",
-      UI_KEY_POLYGONNAME,
+      "polygonfile",
+      UI_KEY_POLYGONFILE,
       "REG",
       0,
       "Polygon filename for '--inpolygon' or '--outpolygon'.",
       UI_GROUP_OUTROWS,
-      &p->polygonname,
+      &p->polygonfile,
       GAL_TYPE_STRING,
       GAL_OPTIONS_RANGE_ANY,
       GAL_OPTIONS_NOT_MANDATORY,
diff --git a/bin/table/main.h b/bin/table/main.h
index d536367..11235bd 100644
--- a/bin/table/main.h
+++ b/bin/table/main.h
@@ -98,7 +98,7 @@ struct tableparams
   gal_data_t       *inpolygon;  /* Columns to check if inside polygon.  */
   gal_data_t      *outpolygon;  /* Columns to check if outside polygon. */
   gal_data_t         *polygon;  /* Values of vertices of the polygon.   */
-  char           *polygonname;  /* Name of input polygon file           */
+  char           *polygonfile;  /* Name of input polygon file           */
   gal_data_t           *equal;  /* Values to keep in output.            */
   gal_data_t        *notequal;  /* Values to not include in output.     */
   char                  *sort;  /* Column name or number for sorting.   */
diff --git a/bin/table/ui.c b/bin/table/ui.c
index 8a4715a..50845b9 100644
--- a/bin/table/ui.c
+++ b/bin/table/ui.c
@@ -229,37 +229,30 @@ ui_check_polygon_from_ds9(struct tableparams *p)
   int ds9regmode;
 
   /* This is only relevant when a region file is actually given. */
-  if(p->polygonname)
+  if(p->polygonfile)
     {
-      if(p->polygon)
       /* These two options cannot be called together. */
-       error(EXIT_FAILURE, errno, "'--polygon' and '--polygonname' "
+      if(p->polygon)
+       error(EXIT_FAILURE, errno, "'--polygon' and '--polygonfile' "
               "cannot be given together. With the first you specify the "
               "polygon vertices directly on the command-line. With the "
               "second, you give a DS9 region file and the polygon "
               "vertices are read from that.");
+
+      /* Extract the polygon and the coordinate mode. */
       else
-        {
-          /* Extract the polygon and the coordinate mode. */
-          p->polygon=gal_ds9_reg_read_polygon(p->polygonname,
-                                              &ds9regmode);
-
-          /* Check if the coordinate's mode in the file is valid. */
-          if(ds9regmode!=GAL_DS9_COORD_MODE_IMG &&
-             ds9regmode!=GAL_DS9_COORD_MODE_WCS)
-            error(EXIT_FAILURE, 0, "%s: a bug! Please contact us at "
-                  "'%s' to fix the problem. The output coordinate mode "
-                  "of 'gal_ds9_reg_read_polygon' (%d) isn't recognized "
-                  "by this function", __func__, PACKAGE_BUGREPORT,
-                  ds9regmode);
-        }
+        p->polygon=gal_ds9_reg_read_polygon(p->polygonfile, &ds9regmode);
 
       /* Clean up. */
-      free(p->polygonname);
-      p->polygonname=NULL;
+      free(p->polygonfile);
+      p->polygonfile=NULL;
     }
 }
 
+
+
+
+
 /* Read and check ONLY the options. When arguments are involved, do the
    check in 'ui_check_options_and_arguments'. */
 static void
diff --git a/bin/table/ui.h b/bin/table/ui.h
index 4743b7f..8f13311 100644
--- a/bin/table/ui.h
+++ b/bin/table/ui.h
@@ -73,8 +73,8 @@ enum option_keys_enum
   UI_KEY_ROWRANDOM,
   UI_KEY_INPOLYGON,
   UI_KEY_OUTPOLYGON,
+  UI_KEY_POLYGONFILE,
   UI_KEY_CATCOLUMNRAWNAME,
-  UI_KEY_POLYGONNAME,
 };
 
 
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index e22a510..cd50b42 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -673,7 +673,7 @@ Gnuastro library
 * Unit conversion library (@file{units.h})::  Convert between units.
 * Spectral lines library::      Functions for operating on Spectral lines.
 * Cosmology library::           Cosmological calculations.
-* DS9 library::                 DS9 files operations.
+* SAO DS9 library::             Take inputs from files generated by SAO DS9.
 
 Multithreaded programming (@file{threads.h})
 
@@ -762,12 +762,12 @@ Contributing to Gnuastro
 
 Other useful software
 
-* SAO ds9::                     Viewing FITS images.
+* SAO DS9::                     Viewing FITS images.
 * PGPLOT::                      Plotting directly in C
 
-SAO ds9
+SAO DS9
 
-* Viewing multiextension FITS images::  Configure SAO ds9 for multiextension 
images.
+* Viewing multiextension FITS images::  Configure SAO DS9 for multiextension 
images.
 
 @end detailmenu
 @end menu
@@ -1996,7 +1996,7 @@ So please don't rush, and go through the steps patiently 
to optimally master Gnu
 @cindex eXtreme Deep Field (XDF) survey
 In this tutorial, we'll use the HST@url{https://archive.stsci.edu/prepds/xdf, 
eXtreme Deep Field} dataset.
 Like almost all astronomical surveys, this dataset is free for download and 
usable by the public.
-You will need the following tools in this tutorial: Gnuastro, SAO DS9 
@footnote{See @ref{SAO ds9}, available at 
@url{http://ds9.si.edu/site/Home.html}}, GNU 
Wget@footnote{@url{https://www.gnu.org/software/wget}}, and AWK (most common 
implementation is GNU AWK@footnote{@url{https://www.gnu.org/software/gawk}}).
+You will need the following tools in this tutorial: Gnuastro, SAO DS9 
@footnote{See @ref{SAO DS9}, available at 
@url{http://ds9.si.edu/site/Home.html}}, GNU 
Wget@footnote{@url{https://www.gnu.org/software/wget}}, and AWK (most common 
implementation is GNU AWK@footnote{@url{https://www.gnu.org/software/gawk}}).
 
 This tutorial was first prepared for the ``Exploring the Ultra-Low Surface 
Brightness Universe'' workshop (November 2017) at the ISSI in Bern, Switzerland.
 It was further extended in the ``4th Indo-French Astronomy School'' (July 
2018) organized by LIO, CRAL CNRS UMR5574, UCBL, and IUCAA in Lyon, France.
@@ -4996,7 +4996,7 @@ Open the output @file{r_segmented.fits} as a 
multi-extension data cube with the
 To optimize the parameters and make sure you have detected what you wanted, we 
recommend to visually inspect the detected clumps on the input image.
 
 For visual inspection, you can make a simple shell script like below.
-It will first call MakeCatalog to estimate the positions of the clumps, then 
make an SAO ds9 region file and open ds9 with the image and region file.
+It will first call MakeCatalog to estimate the positions of the clumps, then 
make an SAO DS9 region file and open ds9 with the image and region file.
 Recall that in a shell script, the numeric variables (like @code{$1}, 
@code{$2}, and @code{$3} in the example below) represent the arguments given to 
the script.
 But when used in the AWK arguments, they refer to column numbers.
 
@@ -8699,7 +8699,7 @@ The size of the regular tiles (in units of data-elements, 
or pixels in an image)
 It takes multiple numbers (separated by a comma) which will be the length 
along the respective dimension (in FORTRAN/FITS dimension order).
 Divisions are also acceptable, but must result in an integer.
 For example @option{--tilesize=30,40} can be used for an image (a 2D dataset).
-The regular tile size along the first FITS axis (horizontal when viewed in SAO 
ds9) will be 30 pixels and along the second it will be 40 pixels.
+The regular tile size along the first FITS axis (horizontal when viewed in SAO 
DS9) will be 30 pixels and along the second it will be 40 pixels.
 Ideally, @option{--tilesize} should be selected such that all tiles in the 
image have exactly the same size.
 In other words, that the dataset length in each dimension is divisible by the 
tile size in that dimension.
 
@@ -10727,11 +10727,13 @@ This option is very similar to the 
@option{--inpolygon} option, so see the descr
 
 @item --polygon=FLT:FLT,...
 The polygon to use for the @code{--inpolygon} and @option{--outpolygon} 
options.
-The values to this option is parsed in the same way that the Crop program, see 
its description there for more: @ref{Crop 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}.
 
-@item --polygonname=REG
-The filename of the polygon region to use for the @code{--inpolygon} and 
@option{--outpolygon} options.
-The file format is in the same way that the Crop program, see its description 
there for more: @ref{Crop options}.
+@item --polygonfile=STR
+@cindex SAO DS9 region file
+@cindex Region file (SAO DS9)
+The filename of the SAO DS9 polygon region file 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}.
 
 @item -e STR,INT/FLT,...
 @itemx --equal=STR,INT/FLT,...
@@ -11556,7 +11558,7 @@ If the colon is omitted for a dimension, then the full 
range is automatically us
 So the same string is also equal to @command{2:,} or @command{2:} or even 
@command{2}.
 If you want such a case for the second axis, you should set it to: 
@command{,2}.
 
-If you specify a negative value, it will be seen as before the indexes of the 
image which are outside the image along the bottom or left sides when viewed in 
SAO ds9.
+If you specify a negative value, it will be seen as before the indexes of the 
image which are outside the image along the bottom or left sides when viewed in 
SAO DS9.
 In case you want to count from the top or right sides of the image, you can 
use an asterisk (@option{*}).
 When confronted with a @option{*}, Crop will replace it with the maximum 
length of the image in that dimension.
 So @command{*-10:*+10,*-20:*+20} will mean that the crop box will be 
@math{20\times40} pixels in size and only include the top corner of the input 
image with 3/4 of the image being covered by blank pixels, see @ref{Blank 
pixels}.
@@ -11573,7 +11575,7 @@ See @ref{Command-line} for a description of how the 
command-line works.
 The cropped box can potentially include pixels that are beyond the image range.
 For example when a target in the input catalog was very near the edge of the 
input image.
 The parts of the cropped image that were not in the input image will be filled 
with the following two values depending on the data type of the image.
-In both cases, SAO ds9 will not color code those pixels.
+In both cases, SAO DS9 will not color code those pixels.
 @itemize
 @item
 If the data type of the image is a floating point type (float or double), IEEE 
NaN (Not a number) will be used.
@@ -11756,9 +11758,36 @@ $ astcrop --mode=wcs desired-filter-image(s).fits      
     \
               53.134517,-27.787144 : 53.161906,-27.807208"
 @end example
 
-In other cases, you have an image and want to define the polygon yourself (it 
isn't already published like the example above).
-As the number of vertices increases, checking the vertex coordinates on a FITS 
viewer (for example SAO ds9) and typing them in one by one can be very tedious 
and prone to typo errors. Then, you can use the @option{--polygonname} option 
to give the name of a @command{REG} file (made in SAO ds9).
-Check the description for more.
+@cindex SAO DS9 region file
+@cindex Region file (SAO DS9)
+More generally, you have an image and want to define the polygon yourself (it 
isn't already published like the example above).
+As the number of vertices increases, checking the vertex coordinates on a FITS 
viewer (for example SAO DS9) and typing them in, one by one, can be very 
tedious and prone to typo errors.
+In such cases, you can make a polygon ``region'' in DS9 and using your mouse, 
easily define (and visually see) it.
+Afterwards, you can save the ``region'' into a DS9 region file and pass its 
name to the @option{--polygonfile} option
+Check the description of @option{--polygonfile} for more.
+
+@item --polygonfile=STR
+@cindex SAO DS9
+@cindex SAO DS9 region file
+@cindex Region file (SAO DS9)
+File name of the SAO DS9 region file containing the vertices from a polygon.
+This option is only parsed if @option{--polygon} hasn't been called.
+When used, the coordinate mode of Crop will be determined by the contents of 
this file and any value given to @code{--mode} is ignored.
+
+Given that SAO DS9 has a graphic user interface (GUI), if you don't have the 
polygon vertices before-hand, it is much more easier build your polygon there 
and pass it onto Crop through the region file.
+
+You can take the following steps to make an SAO DS9 region file containing 
your polygon.
+Open your desired FITS image with SAO DS9 and activate its ``region'' mode 
with @clicksequence{Edit@click{}Region}.
+Then define the region as a polygon with 
@clicksequence{Region@click{}Shape@click{}Polygon}.
+Click on the approximate center of the region you want and a small square will 
appear.
+By clicking on the vertices of the square you can shrink or expand it, 
clicking and dragging anywhere on the edges will enable you to define a new 
vertex.
+After the region has been nicely defined, save it as a file with 
@clicksequence{Region@click{}``Save Regions''}.
+You can then select the name and address of the output file, keep the format 
as @command{REG (*.reg)} and press the ``OK'' button.
+In the next window, keep format as ``ds9'' and ``Coordinate System'' as 
``fk5'' for RA and Dec (or ``Image'' for pixel coordinates).
+A plain text file is now created (let's call it @file{ds9.reg}) which you can 
pass onto Crop with @command{--polygonfile=ds9.reg}.
+
+For the expected format of the region file, see the description of 
@code{gal_ds9_reg_read_polygon} in @ref{SAO DS9 library}.
+However, since SAO DS9 makes this file for you, you don't usually need to 
worry about its internal format unless something un-expected happens and you 
find a bug.
 
 @item --polygonout
 Keep all the regions outside the polygon and mask the inner ones with blank 
pixels (see @ref{Blank pixels}).
@@ -11791,29 +11820,6 @@ By contrast, a convex polygon is one where an inner 
angle may be more than 180 d
               A--------B             A ----------B
 @end example
 
-@item -t REG
-@itemx --polygonname=REG
-File name of the region containing the vertices from a polygon.
-We assume that the @command{REG} file begins with ``# Region file format: 
DS9'' and it has, at least, two more lines: one containing the mode of the 
coordinates (``fk5'' or ``image'') and other with the polygon vertices folowing 
this format: ``polygon(AAA,BBB,...)'' where ``AAA'' and ``BBB'' are numbers and 
``...'' signifies that any number of points are possible:
-
-@example
-# Region file format: DS9
-fk5
-polygon(53.187414,-27.779152,53.159507,-27.759633,53.134517,-27.787144,63.161906,-27.807208)
-@end example
-
-@cindex SAO DS9
-You can take the following steps to make a @command{REG} file that 
automatically uses the above syntax using SAO ds9: Open the image with ds9 and 
activate its ``region'' mode with @clicksequence{Edit@click{}Region}.
-Then define the region as a polygon with 
@clicksequence{Region@click{}Shape@click{}Polygon}.
-Click on the approximate center of the region you want and a small square will 
appear.
-By clicking on the vertices of the square you can shrink or expand it, 
clicking and dragging anywhere on the edges will enable you to define a new 
vertex.
-After the region has been nicely defined, save it as a file with 
@clicksequence{Region@click{}Save Regions}.
-You can then select the name and address of the output file, keep the format 
as @command{REG} and press ``OK''.
-In the next window, keep format as ``ds9'' and ``Coordinate System'' as 
``fk5''.
-A plain text file (let's call it @file{ds9.reg}) is now created. Then, you can 
run Crop with @command{--polygonname=ds9.reg}.
-
-The mode that Crop will use is defined by the mode on the file. So, if you 
have ``fk5'' on the file, there is no need to call @command{--mode=wcs}.
-
 @item -s STR
 @itemx --section=STR
 Section of the input image which you want to be cropped.
@@ -14562,7 +14568,7 @@ Otherwise, the value will not be fully passed onto the 
option.
 See the examples above as a demonstration.
 
 @cindex FITS standard
-Based on the FITS standard, integer values are assigned to the center of a 
pixel and the coordinate [1.0, 1.0] is the center of the first pixel (bottom 
left of the image when viewed in SAO ds9).
+Based on the FITS standard, integer values are assigned to the center of a 
pixel and the coordinate [1.0, 1.0] is the center of the first pixel (bottom 
left of the image when viewed in SAO DS9).
 So the coordinate center [0.0, 0.0] is half a pixel away (in each axis) from 
the bottom left vertex of the first pixel.
 The resampling that is done in Warp (see @ref{Resampling}) is done on the 
coordinate axes and thus directly depends on the coordinate center.
 In some situations this if fine, for example when rotating/aligning a real 
image, all the edge pixels will be similarly affected.
@@ -14575,7 +14581,7 @@ In such cases, you can use the 
@option{--centeroncorner} option which will shift
 @item -a
 @itemx --align
 Align the image and celestial (WCS) axes given in the input.
-After it, the  vertical image direction (when viewed in SAO ds9) corresponds 
to thedeclination and the horizontal axis is the inverse of the Right Ascension 
(RA).
+After it, the  vertical image direction (when viewed in SAO DS9) corresponds 
to thedeclination and the horizontal axis is the inverse of the Right Ascension 
(RA).
 The inverse of the RA is chosen so the image can correspond to what you would 
actually see on the sky and is common in most survey images.
 
 Align is internally treated just like a rotation (@option{--rotation}), but 
uses the input image's WCS to find the rotation angle.
@@ -14584,7 +14590,7 @@ Thus, if you have rotated the image before calling 
@option{--align}, you might g
 @item -r FLT
 @itemx --rotate=FLT
 Rotate the input image by the given angle in degrees: @mymath{\theta} in 
@ref{Warping basics}.
-Note that commonly, the WCS structure of the image is set such that the RA is 
the inverse of the image horizontal axis which increases towards the right in 
the FITS standard and as viewed by SAO ds9.
+Note that commonly, the WCS structure of the image is set such that the RA is 
the inverse of the image horizontal axis which increases towards the right in 
the FITS standard and as viewed by SAO DS9.
 So the default center for rotation is on the right of the image.
 If you want to rotate about other points, you have to translate the warping 
center first (with @option{--translate}) then apply your rotation and then 
return the center back to the original position (with another call to 
@option{--translate}, see @ref{Merging multiple warpings}.
 
@@ -14644,7 +14650,7 @@ The raw matrix takes precedence over all the modular 
warping options listed abov
 
 @item -c
 @itemx --centeroncorer
-Put the center of coordinates on the corner of the first (bottom-left when 
viewed in SAO ds9) pixel.
+Put the center of coordinates on the corner of the first (bottom-left when 
viewed in SAO DS9) pixel.
 This option is applied after the final warping matrix has been finalized: 
either through modular warpings or the raw matrix.
 See the explanation above for coordinates in the FITS standard to better 
understand this option and when it should be used.
 
@@ -18050,14 +18056,14 @@ Hence if only object catalogs are required, it has 
the same effect as @option{--
 
 @item -x
 @itemx --x
-The flux weighted center of all objects and clumps along the first FITS axis 
(horizontal when viewed in SAO ds9), see @mymath{\overline{x}} in 
@ref{Measuring elliptical parameters}.
+The flux weighted center of all objects and clumps along the first FITS axis 
(horizontal when viewed in SAO DS9), see @mymath{\overline{x}} in 
@ref{Measuring elliptical parameters}.
 The weight has to have a positive value (pixel value larger than the Sky 
value) to be meaningful! Specially when doing matched photometry, this might 
not happen: no pixel value might be above the Sky value.
 For such detections, the geometric center will be reported in this column (see 
@option{--geox}).
 You can use @option{--weightarea} to see which was used.
 
 @item -y
 @itemx --y
-The flux weighted center of all objects and clumps along the second FITS axis 
(vertical when viewed in SAO ds9).
+The flux weighted center of all objects and clumps along the second FITS axis 
(vertical when viewed in SAO DS9).
 See @option{--x}.
 
 @item -z
@@ -19518,7 +19524,7 @@ Effective radius (@mymath{r_e}) if S@'ersic, FWHM if 
Moffat or Gaussian.
 The S@'ersic index (@mymath{n}) or Moffat @mymath{\beta}.
 
 @item --pcol=STR/INT
-The position angle (in degrees) of the profiles relative to the first FITS 
axis (horizontal when viewed in SAO ds9).
+The position angle (in degrees) of the profiles relative to the first FITS 
axis (horizontal when viewed in SAO DS9).
 When building a 3D profile, this is the first Euler angle: first rotation of 
the ellipsoid major axis from the first FITS axis (rotating about the third 
axis).
 See @ref{Defining an ellipse and ellipsoid}.
 
@@ -21335,7 +21341,7 @@ This parameter is used as the option @option{--qcol} in 
the generation of the ap
 
 @item -p FLT
 @itemx --positionangle=FLT
-The position angle (in degrees) of the profiles relative to the first FITS 
axis (horizontal when viewed in SAO ds9).
+The position angle (in degrees) of the profiles relative to the first FITS 
axis (horizontal when viewed in SAO DS9).
 By default, it is @option{--pangle=0}, which means that the semi-major axis of 
the profiles will be parallel to the first FITS axis.
 
 @item -m STR
@@ -21428,7 +21434,7 @@ Once your desired catalog (containing the positions of 
some objects) is created
 For example you want to see their positions relative to each other.
 
 In this section we describe a simple installed script that is provided within 
Gnuastro for converting your given columns to an SAO DS9 region file to help in 
this process.
-SAO DS9@footnote{@url{https://sites.google.com/cfa.harvard.edu/saoimageds9}} 
is one of the most common FITS image vizualization tools in astronomy and is 
free software.
+SAO DS9@footnote{@url{http://ds9.si.edu}} is one of the most common FITS image 
vizualization tools in astronomy and is free software.
 
 @menu
 * Invoking astscript-ds9-region::  How to call astscript-ds9-region
@@ -22246,7 +22252,7 @@ If you use the Info version of this manual (see 
@ref{Info}), you don't have to w
 * Unit conversion library (@file{units.h})::  Convert between units.
 * Spectral lines library::      Functions for operating on Spectral lines.
 * Cosmology library::           Cosmological calculations.
-* DS9 library::                 DS9 files operations.
+* SAO DS9 library::             Take inputs from files generated by SAO DS9.
 @end menu
 
 @node Configuration information, Multithreaded programming, Gnuastro library, 
Gnuastro library
@@ -29443,7 +29449,7 @@ emitted from (assuming its a specific spectra line, 
identified with
 
 
 
-@node Cosmology library, DS9 library, Spectral lines library, Gnuastro library
+@node Cosmology library, SAO DS9 library, Spectral lines library, Gnuastro 
library
 @subsection Cosmology library (@file{cosmology.h})
 
 This library does the main cosmological calculations that are commonly
@@ -29510,33 +29516,43 @@ Return the redshift corresponding to the given 
velocity (@code{v} in km/s).
 
 
 
-@node DS9 library,  , Cosmology library, Gnuastro library
-@subsection DS9 library (@file{ds9.h})
-
-This library operates on ds9 output files that Crop and Table can use.
-The function in this section can be used to parse a ds9 Region file 
(@code{REG}), provided that the region is a polygon.
+@node SAO DS9 library,  , Cosmology library, Gnuastro library
+@subsection SAO DS9 library (@file{ds9.h})
 
-@deffn Macro GAL_DS9_COORD_MODE_INVALID
-Used for sanity checks (for example, to know if the mode is already selected).
+@cindex SAO DS9
+This library operates on the output files of SAO 
DS9@footnote{@url{https://sites.google.com/cfa.harvard.edu/saoimageds9}}.
+SAO DS9 is one of the most commonly used FITS image and cube viewers today 
with an easy to use graphic user interface (GUI), see @ref{SAO DS9}.
+But besides merely opening FITS data, it can also produce certain kinds of 
files that can be useful in common analysis.
+For example, on DS9's GUI, it is very easy to define a (possibly complex) 
polygon as a ``region''.
+You can then save that ``region'' into a file and using the functions below, 
feed the polygon into Gnuastro's programs (or your custom programs).
+
+@deffn  Macro GAL_DS9_COORD_MODE_IMG
+@deffnx Macro GAL_DS9_COORD_MODE_WCS
+@deffnx Macro GAL_DS9_COORD_MODE_INVALID
+Macros to identify the coordinate mode of the DS9 file.
+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
 
-@deffn Macro GAL_DS9_COORD_MODE_IMG
-The coordinates on the DS9 file are in the ``image'' mode.
-@end deffn
+@deftypefun {gal_data_t *} gal_ds9_reg_read_polygon (char @code{*filename}, 
int @code{*coordmode})
+@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).
 
-@deffn Macro GAL_DS9_COORD_MODE_WCS
-The coordinates on the DS9 file are in the ``fk5'' mode.
-@end deffn
+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 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):
+a line containing the mode of the coordinates (the line should only contain 
either @code{fk5} or @code{image}),
+a line with the polygon vertices folowing this format: 
@code{polygon(V1X,V1Y,V2X,V2Y,...)} where @code{V1X} and @code{V1Y} are the 
horizontal and vertical coordinates of the first vertice, and so on.
 
-@deftypefun {gal_data_t *} gal_ds9_reg_read_polygon(char @code{*filename}, int 
@code{*coordmode})
-Returns an allocated generic data container @code{gal_data_t} containing the 
vertices of a polygon on the ds9 region file given by @code{*filename}.
-The @code{*coordmode} is set as one of the Macros above accordingly to the 
coordinates on the file.
-It's important to note that the @code{REG} file is assumed to begin with ``# 
Region file format: DS9'' and it has, at least, two more lines: one containing 
the mode of the coordinates (``fk5'' or ``image'') and other with the polygon 
vertices folowing this format: ``polygon(AAA,BBB,...)'' where ``AAA'' and 
``BBB'' are numbers and ``...'' signifies that any number of points are 
possible:
+For example, here is a minimal acceptable SAO DS9 region file:
 
 @example
 # Region file format: DS9
 fk5
-polygon(53.187414,-27.779152,53.159507,-27.759633,53.134517,-27.787144,63.161906,-27.807208)
+polygon(53.187414,-27.779152,53.159507,-27.759633,...)
 @end example
 @end deftypefun
 
@@ -32043,16 +32059,16 @@ not direct Gnuastro dependencies are discussed. 
However they can be
 useful for working with Gnuastro.
 
 @menu
-* SAO ds9::                     Viewing FITS images.
+* SAO DS9::                     Viewing FITS images.
 * PGPLOT::                      Plotting directly in C
 @end menu
 
-@node SAO ds9, PGPLOT, Other useful software, Other useful software
-@section SAO ds9
+@node SAO DS9, PGPLOT, Other useful software, Other useful software
+@section SAO DS9
 
 @cindex SAO DS9
 @cindex FITS image viewer
-SAO ds9@footnote{@url{http://ds9.si.edu/}} is not a requirement of
+SAO DS9@footnote{@url{http://ds9.si.edu/}} is not a requirement of
 Gnuastro, it is a FITS image viewer. So to check your inputs and
 outputs, it is one of the best options. Like the other packages, it
 might already be available in your distribution's repositories. It is
@@ -32079,10 +32095,10 @@ export XPA_METHOD=local
 
 
 @menu
-* Viewing multiextension FITS images::  Configure SAO ds9 for multiextension 
images.
+* Viewing multiextension FITS images::  Configure SAO DS9 for multiextension 
images.
 @end menu
 
-@node Viewing multiextension FITS images,  , SAO ds9, SAO ds9
+@node Viewing multiextension FITS images,  , SAO DS9, SAO DS9
 @subsection Viewing multiextension FITS images
 
 @cindex Multiextension FITS
@@ -32090,9 +32106,9 @@ export XPA_METHOD=local
 The FITS definition allows for multiple extensions inside one FITS file,
 each extension can have a completely independent dataset inside of it. If
 you just double click on a multi-extension FITS file or run @command{$ds9
-foo.fits}, SAO ds9 will only show you the first extension. If you have a
+foo.fits}, SAO DS9 will only show you the first extension. If you have a
 multi-extension file containing 2D images, one way to load and switch
-between the each 2D extension is to take the following steps in the SAO ds9
+between the each 2D extension is to take the following steps in the SAO DS9
 window: @clicksequence{``File''@click{}''Open Other''@click{}''Open Multi
 Ext Cube''} and then choose the Multi extension FITS file in your
 computer's file structure.
@@ -32100,7 +32116,7 @@ computer's file structure.
 @cindex @option{-mecube} (ds9)
 The method above is a little tedious to do every time you want view a
 multi-extension FITS file. A different series of steps is also necessary if
-you the extensions are 3D data cubes. Fortunately SAO ds9 also provides
+you the extensions are 3D data cubes. Fortunately SAO DS9 also provides
 command-line options that you can use to specify a particular behavior. One
 of those options is @option{-mecube} which opens a FITS image as a
 multi-extension data cube (treating each 2D extension as a slice in a 3D
@@ -32112,17 +32128,17 @@ on the output of @ref{NoiseChisel}). If the file has 
multiple extensions, a
 small window will also be opened along with the main ds9 window. This small
 window allows you to slide through the image extensions of
 @file{foo.fits}. If @file{foo.fits} only consists of one extension, then
-SAO ds9 will open as usual. Just to avoid confusion, note that SAO ds9 does
+SAO DS9 will open as usual. Just to avoid confusion, note that SAO DS9 does
 not follow the GNU style of separating long and short options as explained
 in @ref{Arguments and options}. In the GNU style, this `long'
 (multi-character) option should have been called like @option{--mecube},
-but SAO ds9 follows its own conventions.
+but SAO DS9 follows its own conventions.
 
 Recall the @option{-mecube} opens each 2D input extension as a slice in
 3D. Therefore, when you want to inspect a multi-extension FITS file
 containing a 3D dataset, the @option{-mecube} option is no good any more
 (it only opens the first slice of the 3D cube in each extension). In that
-case, we have to use SAO ds9's @option{-multiframe} option to open each
+case, we have to use SAO DS9's @option{-multiframe} option to open each
 extension as a separate frame. Since the input is a 3D dataset, we get the
 same small window as the 2D case above for scrolling through the 3D
 slices. We then have to also ask ds9 to match the frames and lock the
@@ -32251,10 +32267,10 @@ 
Categories=Graphics;RasterGraphics;2DGraphics;3DGraphics
 Exec=BINDIR/ds9-multi-ext %f
 @end example
 
-The steps above will add SAO ds9 as one of your applications. To make it
+The steps above will add SAO DS9 as one of your applications. To make it
 default, take the following steps (just once is enough). Right click on a
 FITS file and select @clicksequence{Open with other application@click{}View
-all applications@click{}SAO ds9}.
+all applications@click{}SAO DS9}.
 
 @cindex GNOME 2
 In case you are using GNOME 2 you can take the following steps: right click
@@ -32271,7 +32287,7 @@ button.
 
 
 
-@node PGPLOT,  , SAO ds9, Other useful software
+@node PGPLOT,  , SAO DS9, Other useful software
 @section PGPLOT
 
 @cindex PGPLOT
diff --git a/lib/ds9.c b/lib/ds9.c
index 9fb6155..707665f 100644
--- a/lib/ds9.c
+++ b/lib/ds9.c
@@ -34,6 +34,9 @@ along with Gnuastro. If not, see 
<http://www.gnu.org/licenses/>.
 #include <gnuastro-internal/options.h>
 
 
+
+
+
 /* Read the polygon specified in the given DS9 region file and parse it in
    the standard format. */
 gal_data_t *
@@ -146,7 +149,7 @@ gal_ds9_reg_read_polygon(char *filename, int *coordmode)
   if(out==NULL)
     error(EXIT_FAILURE, 0, "%s: no polygon statement found! We expect "
           "one line in the format of 'polygon(AAA,BBB,...)' in the "
-          "file given to '--polygonname' option. %s", filename,
+          "file given to '--polygonfile' option. %s", filename,
           polygonformaterr);
 
   /* Clean up and return. */