[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnuastro-commits] master d2bca9d 6/9: Crop and Table: --polygonfile new
From: |
Mohammad Akhlaghi |
Subject: |
[gnuastro-commits] master d2bca9d 6/9: Crop and Table: --polygonfile new name for --polygonname |
Date: |
Fri, 21 May 2021 23:39:18 -0400 (EDT) |
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. */
- [gnuastro-commits] master updated (27df4f2 -> 3dff1e4), Mohammad Akhlaghi, 2021/05/21
- [gnuastro-commits] master d3cfd8e 1/9: Crop: added option to crop polygon from ds9 file, Mohammad Akhlaghi, 2021/05/21
- [gnuastro-commits] master 326b42a 2/9: Crop: polished the implementation of new --polygonname option, Mohammad Akhlaghi, 2021/05/21
- [gnuastro-commits] master 05c660a 3/9: Library: new ds9.h library functions for parsing ds9 files, Mohammad Akhlaghi, 2021/05/21
- [gnuastro-commits] master cbf8a79 4/9: Table: added the --polygonname option, Mohammad Akhlaghi, 2021/05/21
- [gnuastro-commits] master c3d437d 8/9: Book: adjusted --polygon option, Mohammad Akhlaghi, 2021/05/21
- [gnuastro-commits] master 564da39 5/9: Book: new --polygonname option and new ds9 library added, Mohammad Akhlaghi, 2021/05/21
- [gnuastro-commits] master 89be245 7/9: Crop and Table: --polygon now accepts filenames, Mohammad Akhlaghi, 2021/05/21
- [gnuastro-commits] master d2bca9d 6/9: Crop and Table: --polygonfile new name for --polygonname,
Mohammad Akhlaghi <=
- [gnuastro-commits] master 3dff1e4 9/9: Book: edited gal_ds9_reg_read_polygon from DS9 Library, corrected NEWS, Mohammad Akhlaghi, 2021/05/21