Next: Text files, Previous: FITS files, Up: Gnuastro library [Contents][Index]

The FITS standard defines the world coordinate system (WCS) as a mechanism to associate physical values to positions within a dataset. For example, it can be used to convert pixel coordinates in an image to celestial coordinates like the right ascension and declination. The functions in this section are mainly just wrappers over CFITSIO, WCSLIB and GSL library functions to help in common applications.

- Function:

*struct wcsprm **

**gal_wcs_read_fitsptr***(fitsfile*`*fptr`

, size_t`hstartwcs`

, size_t`hendwcs`

, int`*nwcs`

) [

**Not thread-safe**] Return the WCSLIB`wcsprm`

structure that is read from the CFITSIO`fptr`

pointer to an opened FITS file. Also put the number of coordinate representations found into the space that`nwcs`

points to. To read the WCS structure directly from a filename, see`gal_wcs_read`

below. After processing has finished, you can free the returned structure with WCSLIB’s`wcsvfree`

keyword:status = wcsvfree(&nwcs,&wcs);

If you don’t want to search the full FITS header for WCS-related FITS keywords (for example due to conflicting keywords), but only a specific range of the header keywords you can use the

`hstartwcs`

and`hendwcs`

arguments to specify the keyword number range (counting from zero). If`hendwcs`

is larger than`hstartwcs`

, then only keywords in the given range will be checked. Hence, to ignore this feature (and search the full FITS header), give both these arguments the same value.If the WCS information couldn’t be read from the FITS file, this function will return a

`NULL`

pointer and put a zero in`nwcs`

. A WCSLIB error message will also be printed in`stderr`

if there was an error.This function is just a wrapper over WCSLIB’s

`wcspih`

function which is not thread-safe. Therefore, be sure to not call this function simultaneously (over multiple threads).

- Function:

*struct wcsprm **

**gal_wcs_read***(char*`*filename`

, char`*hdu`

, size_t`hstartwcs`

, size_t`hendwcs`

, int`*nwcs`

) [

**Not thread-safe**] Return the WCSLIB structure that is read from the HDU/extension`hdu`

of the file`filename`

. Also put the number of coordinate representations found into the space that`nwcs`

points to. Please see`gal_wcs_read_fitsptr`

for more.

- Function:

*struct wcsprm **

**gal_wcs_copy***(struct wcsprm*`*wcs`

) Return a fully allocated (independent) copy of

`wcs`

.

- Function:

*void*

**gal_wcs_on_tile***(gal_data_t*`*tile`

) Create a WCSLIB

`wcsprm`

structure for`tile`

using WCS parameters of the tile’s allocated block dataset, see Tessellation library (`tile.h`) for the definition of tiles. If`tile`

already has a WCS structure, this function won’t do anything.In many cases, tiles are created for internal/low-level processing. Hence for performance reasons, when creating the tiles they don’t have any WCS structure. When needed, this function can be used to add a WCS structure to each tile tile by copying the WCS structure of its block and correcting the reference point’s coordinates within the tile.

- Function:

*double **

**gal_wcs_warp_matrix***(struct wcsprm*`*wcs`

) Return the Warping matrix of the given WCS structure as an array of double precision floating points. This will be the final matrix, irrespective of the type of storage in the WCS structure. Recall that the FITS standard has several methods to store the matrix. The output is an allocated square matrix with each side equal to the number of dimensions.

- Function:

*void*

**gal_wcs_decompose_pc_cdelt***(struct wcsprm*`*wcs`

) Decompose the

`PCi_j`

and`CDELTi`

elements of`wcs`

. According to the FITS standard, in the`PCi_j`

WCS formalism, the rotation matrix elements \(m_{ij}\) are encoded in the`PCi_j`

keywords and the scale factors are encoded in the`CDELTi`

keywords. There is also another formalism (the`CDi_j`

formalism) which merges the two into one matrix.However, WCSLIB’s internal operations are apparently done in the

`PCi_j`

formalism. So its outputs are also all in that format by default. When the input is a`CDi_j`

, WCSLIB will still read the matrix directly into the`PCi_j`

matrix and the`CDELTi`

values are set to`1`

(one). This function is designed to correct such issues: after it is finished, the`CDELTi`

values in`wcs`

will correspond to the pixel scale, and the`PCi_j`

will correction show the rotation.

- Function:

*double*

**gal_wcs_angular_distance_deg***(double*`r1`

, double`d1`

, double`r2`

, double`d2`

) Return the angular distance (in degrees) between a point located at (

`r1`

,`d1`

) to (`r2`

,`d2`

). All input coordinates are in degrees. The distance (along a great circle) on a sphere between two points is calculated with the equation below.$$\cos(d)=\sin(d_1)\sin(d_2)+\cos(d_1)\cos(d_2)\cos(r_1-r_2)$$

However, since the the pixel scales are usually very small numbers, this function won’t use that direct formula. It will be use the Haversine formula which is better considering floating point errors:

$${\sin^2(d)\over 2}=\sin^2\left( {d_1-d_2\over 2} \right)+\cos(d_1)\cos(d_2)\sin^2\left( {r_1-r_2\over 2} \right)$$

- Function:

*double **

**gal_wcs_pixel_scale***(struct wcsprm*`*wcs`

) Return the pixel scale for each dimension of

`wcs`

in degrees. The output is an array of double precision floating point type with one element for each dimension.

- Function:

*double*

**gal_wcs_pixel_area_arcsec2***(struct wcsprm*`*wcs`

) Return the pixel area of

`wcs`

in arcsecond squared. If the input WCS structure is not two dimensional and the units (`CUNIT`

keywords) are not`deg`

(for degrees), then this function will return a NaN.

- Function:

*gal_data_t **

**gal_wcs_world_to_img***(gal_data_t*`*coords`

, struct wcsprm`*wcs`

, int`inplace`

) Convert the linked list of world coordinates in

`coords`

to a linked list of image coordinates given the input WCS structure.`coords`

must be a linked list of data structures of float64 (‘double’) type, seeLinked lists (`list.h`) and List of`gal_data_t`

. The top (first popped/read) node of the linked list must be the first WCS coordinate (RA in an image usually) and etc. Similarly, the top node of the output will be the first image coordinate (in the FITS standard).If

`inplace`

is zero, then the output will be a newly allocated list and the input list will be untouched. However, if`inplace`

is non-zero, the output values will be written into the input’s already allocated array and the returned pointer will be the same pointer to`coords`

(in other words, you can ignore the returned value). Note that in the latter case, only the values will be changed, things like units or name (if present) will be untouched.

- Function:

*gal_data_t **

**gal_wcs_img_to_world***(gal_data_t*`*coords`

, struct wcsprm`*wcs`

, int`inplace`

) Convert the linked list of image coordinates in

`coords`

to a linked list of world coordinates given the input WCS structure. See the description of`gal_wcs_world_to_img`

for more details.

Next: Text files, Previous: FITS files, Up: Gnuastro library [Contents][Index]

JavaScript license information

GNU Astronomy Utilities 0.5 manual, December 2017.