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

Contact: Richard Gooch
Web Development: Ariel Internet Services