# The "wcs" Package

These routines are meant to provide support for Astronomical sky-projections. NOTE: THIS PACKAGE IS WORK IN PROGRESS. THE INTERFACE MAY CHANGE IN THE NEXT RELEASE, POSSIBLY WITHOUT NOTICE.

Library: karma
Link With: -lkarma

#### Functions

wcs_astro_get_associated | Create/get associated Astronomical Sky Co-ordinate projections.
wcs_astro_setup | Setup for Astronomical Sky Co-ordinate projections.
wcs_astro_destroy | Destroy KwcsAstro object.
wcs_astro_test_radec | Test if a KwcsAstro object has RA/GLON and DEC/GLAT defined.
wcs_astro_test_velocity | Test if a KwcsAstro object has velocity or frequency defined.
wcs_astro_test_if_ra | Test if an axis is a Right Ascension axis.
wcs_astro_test_if_dec | Test if an axis is a Declination axis.
wcs_astro_test_if_glon | Test if an axis is a Galactic Longitude axis.
wcs_astro_test_if_glat | Test if an axis is a Galactic Latitude axis.
wcs_astro_test_if_lon | Test if an axis is a longitude axis.
wcs_astro_test_if_lat | Test if an axis is a latitude axis.
wcs_astro_test_if_velocity | Test if an axis is a velocity axis.
wcs_astro_transform | Transform between linear and projected co-ordinates.
wcs_astro_transform3 | Transform between linear and projected co-ordinates.
wcs_astro_breakdown_hms | Breakdown a time value into components.
wcs_astro_format_hms | Format a time value into a string.
wcs_astro_breakdown_dms | Break down an angular value into degrees, minutes and seconds.
wcs_astro_format_dms | Format an angle value into a string.
wcs_astro_format_vel | Format a velocity value into a string.
wcs_astro_breakdown_time | Breakdown a time value into components.
wcs_astro_format_time | Format a time value into a string.
wcs_astro_format | Format a value. No transformation is applied.
wcs_astro_format_all | Transform and format all available information.
wcs_astro_get_preferred_units | Get preferred units for data.
wcs_astro_get_equinox | Get the Equinox.
wcs_astro_get_reference | Get reference value for an axis.
wcs_astro_get_increment | Get increment value for an axis.
wcs_astro_update_location | Update the location ("CRVALn" and "CRPIXn") values.
wcs_astro_compare_axes | Compare axis names.
wcs_astro_has_chromatic_aberration | Test if a co-ordinate system has chromatic aberration.
wcs_compare_grids_2D | Compare if two images have the same world co-ordinate grid.

## Functions

#### EXPERIMENTAL FUNCTION: subject to change without notice

KwcsAstro wcs_astro_get_associated (multi_array *multi_desc,unsigned int index)

This routine will attempt create/get the associated Astronomical Sky Co-ordinate projection information for a general data structure. If the projection information is found, it is associated with the general data structure in the multi_array descriptor, to speed subsequent accesses.

Parameters:

- multi_desc : The multi_array descriptor.
- index : The index of the general data structure in the descriptor.

Returns: A KwcsAstro object on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

KwcsAstro wcs_astro_setup (CONST packet_desc *pack_desc, CONST char *packet)

Setup for Astronomical Sky Co-ordinate projections.

Parameters:

- pack_desc : The packet descriptor containing the FITS-style keywords.
- packet : The packet data containing the FITS-stype keyword data.

Returns: A KwcsAstro object on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void wcs_astro_destroy (KwcsAstro ap)

Destroy KwcsAstro object.

Parameters:

- ap : The KwcsAstro object.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_test_radec (KwcsAstro ap)

Test if a KwcsAstro object has RA/GLON and DEC/GLAT defined.

Parameters:

- ap : The KwcsAstro object. This may be NULL.

Returns: TRUE if the KwcsAstro object has RA and DEC defined, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_test_velocity (KwcsAstro ap)

Test if a KwcsAstro object has velocity or frequency defined.

Parameters:

- ap : The KwcsAstro object. This may be NULL.

Returns: TRUE if the KwcsAstro object has velocity or frequency defined, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_test_if_ra (KwcsAstro ap, CONST char *axis_name)

Test if an axis is a Right Ascension axis.

Parameters:

- ap : The KwcsAstro object. This may be NULL.
- axis_name : The name of the axis.

Returns: TRUE the axis is a Right Ascension axis, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_test_if_dec (KwcsAstro ap, CONST char *axis_name)

Test if an axis is a Declination axis.

Parameters:

- ap : The KwcsAstro object. This may be NULL.
- axis_name : The name of the axis.

Returns: TRUE the axis is a Declination axis, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_test_if_glon (KwcsAstro ap, CONST char *axis_name)

Test if an axis is a Galactic Longitude axis.

Parameters:

- ap : The KwcsAstro object. This may be NULL.
- axis_name : The name of the axis.

Returns: TRUE the axis is a Galactic Longitude axis, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_test_if_glat (KwcsAstro ap, CONST char *axis_name)

Test if an axis is a Galactic Latitude axis.

Parameters:

- ap : The KwcsAstro object. This may be NULL.
- axis_name : The name of the axis.

Returns: TRUE the axis is a Galactic Latitude axis, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_test_if_lon (KwcsAstro ap, CONST char *axis_name)

Test if an axis is a longitude axis.

Parameters:

- ap : The KwcsAstro object. This may be NULL.
- axis_name : The name of the axis.

Returns: TRUE the axis is a longitude axis, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_test_if_lat (KwcsAstro ap, CONST char *axis_name)

Test if an axis is a latitude axis.

Parameters:

- ap : The KwcsAstro object. This may be NULL.
- axis_name : The name of the axis.

Returns: TRUE the axis is a latitude axis, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_test_if_velocity (KwcsAstro ap, CONST char *axis_name)

Test if an axis is a velocity axis.

Parameters:

- ap : The KwcsAstro object. This may be NULL.
- axis_name : The name of the axis.

Returns: TRUE the axis is a velocity axis, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_transform (KwcsAstro ap, flag thread, unsigned int num_coords, double *ra, flag ra_to_linear, double *dec, flag dec_to_linear, double *vel, flag vel_to_linear, unsigned int num_restr, CONST char **restr_names, CONST double *restr_values)

Transform between linear and projected co-ordinates.

Parameters:

- ap : The KwcsAstro object.
- thread : If TRUE, the operation may be threaded, else it will not be.
- num_coords : The number of co-ordinates to transform.
- ra : A pointer to the right ascension values. These will be modified.
- ra_to_linear : If TRUE the right ascension values are transformed to linear co-ordinates, else they are transformed to non-linear co-ordinates.
- dec : A pointer to the declination values. These will be modified.
- dec_to_linear : If TRUE the declination values are transformed to linear co-ordinates, else they are transformed to non-linear co-ordinates.
- vel : A pointer to the velocity values. These will be modified.
- vel_to_linear : If TRUE the velocity values are transformed to linear co-ordinates, else they are transformed to non-linear co-ordinates.
- num_restr : The number of restrictions.
- restr_names : The array of restriction names.
- restr_values : The restriction values.

Returns: TRUE on success, else FALSE. If nothing is to be transformed, TRUE is returned.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_transform3 (KwcsAstro ap, flag thread, unsigned int num_coords, CONST char *name0, double *coords0, flag to_lin0, CONST char *name1, double *coords1, flag to_lin1, CONST char *name2, double *coords2, flag to_lin2, unsigned int num_restr, CONST char **restr_names, CONST double *restr_values)

This routine will convert up to three arrays of co-ordinates using an astronomical projection system. The co-ordinate arrays are named. If a co-ordinate array is not defined the co-ordinates are unchanged.

Parameters:

- ap : The KwcsAstro object.
- thread : If TRUE, the operation may be threaded, else it will not be.
- num_coords : The number of co-ordinates to transform.
- name0 : The name of co-ordinate array 0.
- coords0 : Co-ordinate array 0.
- to_lin0 : If TRUE the co-ordinate 0 values are transformed to linear co-ordinates, else they are transformed to non-linear co-ordinates.
- name1 : The name of co-ordinate array 1.
- coords1 : Co-ordinate array 1.
- to_lin1 : If TRUE the co-ordinate 1 values are transformed to linear co-ordinates, else they are transformed to non-linear co-ordinates.
- name2 : The name of co-ordinate array 2.
- coords2 : Co-ordinate array 2.
- to_lin2 : If TRUE the co-ordinate 2 values are transformed to linear co-ordinates, else they are transformed to non-linear co-ordinates.
- num_restr : The number of restrictions.
- restr_names : The array of restriction names.
- restr_values : The restriction values.

Returns: TRUE on success, else FALSE. If nothing is to be transformed, TRUE is returned.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_breakdown_hms (int *hours, int *minutes, double *seconds, int *whole_seconds, double *subseconds, double input, double offset)

Breakdown a time value into components.

Parameters:

- hours : The hours are written here. This may be NULL.
- minutes : The minutes are written here. This may be NULL.
- seconds : The seconds are written here. This may be NULL.
- whole_seconds : The integer truncated seconds are written here. This may be NULL.
- subseconds : The fractional seconds are written here. This may be NULL.
- input : The time value in hours.
- offset : The offset (in seconds) to apply for rounding purposes.

Returns: TRUE if the value was legal, else FALSE.
Multithreading Level: Unsafe
Note:

- All component values are guaranteed to be positive.

#### EXPERIMENTAL FUNCTION: subject to change without notice

void wcs_astro_format_hms (char *string, double hours)

Format a time value into a string.

Parameters:

- string : The string to write to. Sufficient storage must be available.
- hours : The time value in hours.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_breakdown_dms (flag *negative, int *degrees, int *minutes, double *seconds, int *whole_seconds, double *subseconds, double input, double offset)

Break down an angular value into degrees, minutes and seconds.

Parameters:

- negative : If the value is negative the value TRUE is written here, else FALSE is written here. This may be NULL.
- degrees : The degrees are written here. This may be NULL.
- minutes : The minutes are written here. This may be NULL.
- seconds : The seconds are written here. This may be NULL.
- whole_seconds : The integer truncated seconds are written here. This may be NULL.
- subseconds : The fractional seconds are written here. This may be NULL.
- input : The input value in degrees.
- offset : The offset (in arcseconds) to apply for rounding purposes.

Returns: TRUE if the value was legal, else FALSE.
Multithreading Level: Unsafe
Note:

- All component values are guaranteed to be positive.

#### EXPERIMENTAL FUNCTION: subject to change without notice

void wcs_astro_format_dms (char *string, double deg)

Format an angle value into a string.

Parameters:

- string : The string to write to. Sufficient storage must be available.
- deg : The input value in degrees.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void wcs_astro_format_vel (KwcsAstro ap, char *string, double vel)

Format a velocity value into a string.

Parameters:

- ap : The KwcsAstro object.
- string : The string to write to. Sufficient storage must be available.
- vel : The velocity value.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void wcs_astro_breakdown_time (unsigned int *year, unsigned int *month, unsigned int *day_of_month, unsigned int *day_of_year, unsigned int *hours, unsigned int *minutes, double *seconds, unsigned int *whole_seconds, double *subseconds, double time_val)

Breakdown a time value into components.

Parameters:

- time_val : The time in Modified Julian Date (units of seconds).
- year : The year is written here.
- month : The month is written here.
- day_of_month : The day of the month is written here.
- hours : The hours are written here. This may be NULL.
- minutes : The minutes are written here. This may be NULL.
- seconds : The seconds are written here. This may be NULL.
- whole_seconds : The integer truncated seconds are written here. This may be NULL.
- subseconds : The fractional seconds are written here. This may be NULL.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void wcs_astro_format_time (char *string, double time_val)

Format a time value into a string.

Parameters:

- string : The string to write to. Sufficient storage must be available.
- time_val : The time in Modified Julian Date (units of seconds).

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void wcs_astro_format (KwcsAstro ap, unsigned int spherical_format, CONST char *dim_name, char string[STRING_LENGTH], double value)

Format a value. No transformation is applied.

Parameters:

- ap : The KwcsAstro object.
- spherical_format : The format type for a spherical axis.
- dim_name : The name of the dimension.
- string : The string to write to.
- value : The value.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void wcs_astro_format_all (KwcsAstro ap, unsigned int spherical_format, char coord_string[STRING_LENGTH], CONST char *name0, double coord0, CONST char *name1, double coord1, CONST char *name2, double coord2, unsigned int num_restr, CONST char **restr_names, CONST double *restr_values, char other_string[STRING_LENGTH])

This routine will transform and format all available information. The data are transformed from linear to non-linear values.

Parameters:

- ap : The KwcsAstro object.
- spherical_format : The format type for a spherical axis.
- coord_string : Formatted co-ordinate information is written here.
- name0 : The name of co-ordinate 0.
- coord0 : Co-ordinate 0.
- name1 : The name of co-ordinate 1. If this is NULL, it is ignored.
- coord1 : Co-ordinate 1.
- name2 : The name of co-ordinate 2. If this is NULL, it is ignored.
- coord2 : Co-ordinate 2.
- num_restr : The number of restrictions.
- restr_names : The array of restriction names.
- restr_values : The restriction values.
- other_string : Formatted extra information is written here.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_get_preferred_units (char new_units[STRING_LENGTH], char format_str[STRING_LENGTH], double *scale, CONST char *old_units)

Get preferred units for data.

Parameters:

- new_units : The new units string is written here.
- format_str : The format string is written here.
- scale : The scale value to convert to the new units will be written here.
- old_units : The old units string.

Returns: TRUE if preferred units were found, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

unsigned int wcs_astro_get_equinox (KwcsAstro ap)

Get the Equinox.

Parameters:

- ap : The KwcsAstro object.

Returns: The year of the Equinox (typically 1950 or 2000).
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

double wcs_astro_get_reference (KwcsAstro ap, CONST char *name, flag linear)

Get reference value for an axis.

Parameters:

- ap : The KwcsAstro object.
- name : The axis name.
- linear : If TRUE, the linear reference position is given, else the non-linear reference value is given.

Returns: The reference value.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

double wcs_astro_get_increment (KwcsAstro ap, CONST char *name)

Get increment value for an axis.

Parameters:

- ap : The KwcsAstro object.
- name : The axis name.

Returns: The increment along the axis. This is prior to projection.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void wcs_astro_update_location (KwcsAstro ap, unsigned int axis_number, CONST packet_desc *pack_desc, CONST char *packet)

Update the location ("CRVALn" and "CRPIXn") values.

Parameters:

- ap : The KwcsAstro object to update.
- axis_number : The FITS axis number to update.
- pack_desc : The packet descriptor to extract the new values from.
- packet : The packet to extract the new values from.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_compare_axes (KwcsAstro ap1, CONST char *name1, KwcsAstro ap2, CONST char *name2)

This function will compare axis name to see if they are the same. Different reference frames and equinoxes will prevent a match.

Parameters:

- ap1 : The KwcsAstro object for one axis name. This may be NULL.
- name1 : One of the axis names.
- ap2 : The KwcsAstro object for the other axis name. This may be NULL.
- name2 : The other axis name.

Returns: TRUE if the axes are the same, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_astro_has_chromatic_aberration (KwcsAstro ap)

Test if a co-ordinate system has chromatic aberration.

Parameters:

- ap : The KwcsAstro object.

Returns: TRUE if chromatic aberration is present, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag wcs_compare_grids_2D (KwcsAstro ap1, CONST dim_desc *hd1, CONST dim_desc *vd1, unsigned int num_restr1, CONST char **restr_names1, CONST double *restr_values1, KwcsAstro ap2, CONST dim_desc *hd2, CONST dim_desc *vd2, unsigned int num_restr2, CONST char **restr_names2, CONST double *restr_values2, flag *same)

Compare if two images have the same world co-ordinate grid.

Parameters:

- ap1 : The KwcsAstro object for the first image.
- hd1 : The horizontal dimension of the first image.
- vd1 : The vertical dimension of the first image.
- ap2 : The KwcsAstro object for the second image.
- hd2 : The horizontal dimension of the second image.
- vd2 : The vertical dimension of the second image.
- same : TRUE is written here if the grids are the same, else FALSE is written here.

Returns: TRUE on success, else FALSE, indicating that comparison failed.
Multithreading Level: Unsafe

Back to Karma Home Page