This library operates on the output files of SAO DS9281. 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 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).
Macros to identify the coordinate mode of the DS9 file.
Their names are sufficiently descriptive.
The last one (INVALID) is for sanity checks (for example, to know if the mode is already selected).
gal_data_t *(char *filename) ¶Returns an allocated generic data container (gal_data_t, with an array of GAL_TYPE_FLOAT64) containing the vertices of a polygon within the SAO DS9 region file given by *filename.
Since SAO DS9 region files are 2 dimensional, if there are \(N\) vertices in the SAO DS9 region file, the returned dataset will have \(2\times N\) elements (first two elements belonging to first vertice, etc.).
The mode to interpret the vertice coordinates is also read from the SAO DS9 region file and written into the status attribute of the output gal_data_t.
The coordinate mode can be one of the GAL_DS9_COORD_MODE_* macros, mentioned above.
It is assumed that the file begins with # 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 fk5 or image),
a line with the polygon vertices following this format: polygon(V1X,V1Y,V2X,V2Y,...) where V1X and V1Y are the horizontal and vertical coordinates of the first vertice, and so on.
For example, here is a minimal acceptable SAO DS9 region file:
# Region file format: DS9 fk5 polygon(53.187414,-27.779152,53.159507,-27.759633,...)
JavaScript license information
GNU Astronomy Utilities 0.23 manual, July 2024.