Loading...
Searching...
No Matches
tab.h File Reference

Go to the source code of this file.

## Data Structures

struct | tabprm
| Tabular transformation parameters. More...

## Macros

#define | TABLEN (sizeof(struct tabprm)/sizeof(int))
| Size of the tabprm struct in int units.
#define | tabini_errmsg tab_errmsg
| Deprecated.
#define | tabcpy_errmsg tab_errmsg
| Deprecated.
#define | tabfree_errmsg tab_errmsg
| Deprecated.
#define | tabprt_errmsg tab_errmsg
| Deprecated.
#define | tabset_errmsg tab_errmsg
| Deprecated.
#define | tabx2s_errmsg tab_errmsg
| Deprecated.
#define | tabs2x_errmsg tab_errmsg
| Deprecated.

## Enumerations

enum | tabenq_enum { TABENQ_MEM = 1 , TABENQ_SET = 2 , TABENQ_BYP = 4 }
enum | tab_errmsg_enum { TABERR_SUCCESS = 0 , TABERR_NULL_POINTER = 1 , TABERR_MEMORY = 2 , TABERR_BAD_PARAMS = 3 , TABERR_BAD_X = 4 , TABERR_BAD_WORLD = 5 }

## Functions

int | tabini (int alloc, int M, const int K[], struct tabprm *tab)
| Default constructor for the tabprm struct.
int | tabmem (struct tabprm *tab)
| Acquire tabular memory.
int | tabcpy (int alloc, const struct tabprm *tabsrc, struct tabprm *tabdst)
| Copy routine for the tabprm struct.
int | tabcmp (int cmp, double tol, const struct tabprm *tab1, const struct tabprm *tab2, int *equal)
| Compare two tabprm structs for equality.
int | tabfree (struct tabprm *tab)
| Destructor for the tabprm struct.
int | tabsize (const struct tabprm *tab, int size[2])
| Compute the size of a tabprm struct.
int | tabenq (const struct tabprm *tab, int enquiry)
| enquire about the state of a tabprm struct.
int | tabprt (const struct tabprm *tab)
| Print routine for the tabprm struct.
int | tabperr (const struct tabprm *tab, const char *prefix)
| Print error messages from a tabprm struct.
int | tabset (struct tabprm *tab)
| Setup routine for the tabprm struct.
int | tabx2s (struct tabprm *tab, int ncoord, int nelem, const double x[], double world[], int stat[])
| Pixel-to-world transformation.
int | tabs2x (struct tabprm *tab, int ncoord, int nelem, const double world[], double x[], int stat[])
| World-to-pixel transformation.

## Variables

const char * | tab_errmsg []
| Status return messages.

## Detailed Description

Routines in this suite implement the part of the FITS World Coordinate System (WCS) standard that deals with tabular coordinates, i.e. coordinates that are defined via a lookup table, as described in

"Representations of world coordinates in FITS",
Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
"Representations of spectral coordinates in FITS",
Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
2006, A&A, 446, 747 (WCS Paper III)

These routines define methods to be used for computing tabular world coordinates from intermediate world coordinates (a linear transformation of image pixel coordinates), and vice versa. They are based on the tabprm struct which contains all information needed for the computations. The struct contains some members that must be set by the user, and others that are maintained by these routines, somewhat like a C++ class but with no encapsulation.

tabini(), tabmem(), tabcpy(), and tabfree() are provided to manage the tabprm struct, tabsize() computes its total size including allocated memory, tabenq() returns information about the state of the struct, and tabprt() prints its contents.

tabperr() prints the error message(s) (if any) stored in a tabprm struct.

A setup routine, tabset(), computes intermediate values in the tabprm struct from parameters in it that were supplied by the user. The struct always needs to be set up by tabset() but it need not be called explicitly - refer to the explanation of tabprm::flag.

tabx2s() and tabs2x() implement the WCS tabular coordinate transformations.

Accuracy:
No warranty is given for the accuracy of these routines (refer to the copyright notice); intending users must satisfy for themselves their adequacy for the intended purpose. However, closure effectively to within double precision rounding error was demonstrated by test routine ttab.c which accompanies this software.

## Macro Definition Documentation

## TABLEN

#define TABLEN (sizeof(struct tabprm)/sizeof(int))

Size of the tabprm struct in int units.

Size of the tabprm struct in int units, used by the Fortran wrappers.

## tabini_errmsg

#define tabini_errmsg tab_errmsg

Deprecated.

Deprecated
  Added for backwards compatibility, use tab_errmsg directly now instead.

## tabcpy_errmsg

#define tabcpy_errmsg tab_errmsg

Deprecated.

Deprecated
  Added for backwards compatibility, use tab_errmsg directly now instead.

## tabfree_errmsg

#define tabfree_errmsg tab_errmsg

Deprecated.

Deprecated
  Added for backwards compatibility, use tab_errmsg directly now instead.

## tabprt_errmsg

#define tabprt_errmsg tab_errmsg

Deprecated.

Deprecated
  Added for backwards compatibility, use tab_errmsg directly now instead.

## tabset_errmsg

#define tabset_errmsg tab_errmsg

Deprecated.

Deprecated
  Added for backwards compatibility, use tab_errmsg directly now instead.

## tabx2s_errmsg

#define tabx2s_errmsg tab_errmsg

Deprecated.

Deprecated
  Added for backwards compatibility, use tab_errmsg directly now instead.

## tabs2x_errmsg

#define tabs2x_errmsg tab_errmsg

Deprecated.

Deprecated
  Added for backwards compatibility, use tab_errmsg directly now instead.

## Enumeration Type Documentation

## tabenq_enum

enum tabenq_enum

Enumerator
TABENQ_MEM |
TABENQ_SET |
TABENQ_BYP |

## tab_errmsg_enum

enum tab_errmsg_enum

Enumerator
TABERR_SUCCESS |
TABERR_NULL_POINTER |
TABERR_MEMORY |
TABERR_BAD_PARAMS |
TABERR_BAD_X |
TABERR_BAD_WORLD |

## Function Documentation

## tabini()

int tabini | ( | int | alloc,
|  | int | M,
|  | const int | K[],
|  | struct tabprm * | tab )

Default constructor for the tabprm struct.

tabini() allocates memory for arrays in a tabprm struct and sets all members of the struct to default values.

PLEASE NOTE: every tabprm struct should be initialized by tabini(), possibly repeatedly. On the first invokation, and only the first invokation, the flag member of the tabprm struct must be set to -1 to initialize memory management, regardless of whether tabini() will actually be used to allocate memory.

Parameters

  [in] | alloc | If true, allocate memory unconditionally for arrays in the tabprm struct. If false, it is assumed that pointers to these arrays have been set by the user except if they are null pointers in which case memory will be allocated for them regardless. (In other words, setting alloc true saves having to initalize these pointers to zero.)
  [in] | M | The number of tabular coordinate axes.

  [in]

  K

  Vector of length M whose elements record the lengths of the axes of the coordinate array and of each indexing vector. M and K[] are used to determine the length of the various tabprm arrays and therefore the amount of memory to allocate for them. Their values are copied into the tabprm struct.
  It is permissible to set K (i.e. the address of the array) to zero which has the same effect as setting each element of K[] to zero. In this case no memory will be allocated for the index vectors or coordinate array in the tabprm struct. These together with the K vector must be set separately before calling tabset().

  [in,out] | tab | Tabular transformation parameters. Note that, in order to initialize memory management tabprm::flag should be set to -1 when tab is initialized for the first time (memory leaks may result if it had already been initialized).

Returns
  Status return value:
  - 0: Success.
  - 1: Null tabprm pointer passed.
  - 2: Memory allocation failed.
  - 3: Invalid tabular parameters.
  For returns > 1, a detailed error message is set in tabprm::err if enabled, see wcserr_enable().

## tabmem()

int tabmem | ( | struct tabprm * | tab | ) |

Acquire tabular memory.

tabmem() takes control of memory allocated by the user for arrays in the tabprm struct.

Parameters

  [in,out] | tab | Tabular transformation parameters.

Returns
  Status return value:
  - 0: Success.
  - 1: Null tabprm pointer passed.
  - 2: Memory allocation failed.
  For returns > 1, a detailed error message is set in tabprm::err if enabled, see wcserr_enable().

## tabcpy()

int tabcpy | ( | int | alloc,
|  | const struct tabprm * | tabsrc,
|  | struct tabprm * | tabdst )

Copy routine for the tabprm struct.

tabcpy() does a deep copy of one tabprm struct to another, using tabini() to allocate memory for its arrays if required. Only the "information to be provided" part of the struct is copied; a call to tabset() is required to set up the remainder.

Parameters

  [in] | alloc | If true, allocate memory unconditionally for arrays in the tabprm struct. If false, it is assumed that pointers to these arrays have been set by the user except if they are null pointers in which case memory will be allocated for them regardless. (In other words, setting alloc true saves having to initalize these pointers to zero.)
  [in] | tabsrc | Struct to copy from.
  [in,out] | tabdst | Struct to copy to. tabprm::flag should be set to -1 if tabdst was not previously initialized (memory leaks may result if it was previously initialized).

Returns
  Status return value:
  - 0: Success.
  - 1: Null tabprm pointer passed.
  - 2: Memory allocation failed.
  For returns > 1, a detailed error message is set in tabprm::err (associated with tabdst) if enabled, see wcserr_enable().

## tabcmp()

int tabcmp | ( | int | cmp,
|  | double | tol,
|  | const struct tabprm * | tab1,
|  | const struct tabprm * | tab2,
|  | int * | equal )

Compare two tabprm structs for equality.

tabcmp() compares two tabprm structs for equality.

Parameters

  [in] | cmp | A bit field controlling the strictness of the comparison. At present, this value must always be 0, indicating a strict comparison. In the future, other options may be added.
  [in] | tol | Tolerance for comparison of floating-point values. For example, for tol == 1e-6, all floating-point values in the structs must be equal to the first 6 decimal places. A value of 0 implies exact equality.
  [in] | tab1 | The first tabprm struct to compare.
  [in] | tab2 | The second tabprm struct to compare.
  [out] | equal | Non-zero when the given structs are equal.

Returns
  Status return value:
  - 0: Success.
  - 1: Null pointer passed.

## tabfree()

int tabfree | ( | struct tabprm * | tab | ) |

Destructor for the tabprm struct.

tabfree() frees memory allocated for the tabprm arrays by tabini(). tabini() records the memory it allocates and tabfree() will only attempt to free this.

PLEASE NOTE: tabfree() must not be invoked on a tabprm struct that was not initialized by tabini().

Parameters

  [in,out] | tab | Coordinate transformation parameters.

Returns
  Status return value:
  - 0: Success.
  - 1: Null tabprm pointer passed.

## tabsize()

int tabsize | ( | const struct tabprm * | tab,
|  | int | size[2] )

Compute the size of a tabprm struct.

tabsize() computes the full size of a tabprm struct, including allocated memory.

Parameters

  [in] | tab | Tabular transformation parameters. If NULL, the base size of the struct and the allocated size are both set to zero.

  [out]

  sizes

  The first element is the base size of the struct as returned by sizeof(struct tabprm). The second element is the total allocated size, in bytes, assuming that the allocation was done by tabini(). This figure includes memory allocated for the constituent struct, tabprm::err.
  It is not an error for the struct not to have been set up via tabset(), which normally results in additional memory allocation.

Returns
  Status return value:
  - 0: Success.

## tabenq()

int tabenq | ( | const struct tabprm * | tab,
|  | int | enquiry )

enquire about the state of a tabprm struct.

tabenq() may be used to obtain information about the state of a tabprm struct. The function returns a true/false answer for the enquiry asked.

Parameters

  [in] | tab | Tabular transformation parameters.

  [in]

  enquiry

  Enquiry according to the following parameters:
  - TABENQ_MEM: memory in the struct is being managed by WCSLIB (see tabini()).
  - TABENQ_SET: the struct has been set up by tabset().
  - TABENQ_BYP: the struct is in bypass mode (see tabset()).
  These may be combined by logical OR, e.g. TABENQ_MEM | TABENQ_SET. The enquiry result will be the logical AND of the individual results.

Returns
  Enquiry result:
  - 0: No.
  - 1: Yes.

## tabprt()

int tabprt | ( | const struct tabprm * | tab | ) |

Print routine for the tabprm struct.

tabprt() prints the contents of a tabprm struct using wcsprintf(). Mainly intended for diagnostic purposes.

Parameters

  [in] | tab | Tabular transformation parameters.

Returns
  Status return value:
  - 0: Success.
  - 1: Null tabprm pointer passed.

## tabperr()

int tabperr | ( | const struct tabprm * | tab,
|  | const char * | prefix )

Print error messages from a tabprm struct.

tabperr() prints the error message(s) (if any) stored in a tabprm struct. If there are no errors then nothing is printed. It uses wcserr_prt(), q.v.

Parameters

  [in] | tab | Tabular transformation parameters.
  [in] | prefix | If non-NULL, each output line will be prefixed with this string.

Returns
  Status return value:
  - 0: Success.
  - 1: Null tabprm pointer passed.

## tabset()

int tabset | ( | struct tabprm * | tab | ) |

Setup routine for the tabprm struct.

tabset() allocates memory for work arrays in the tabprm struct and sets up the struct according to information supplied within it.

Note that this routine need not be called directly; it will be invoked by tabx2s() and tabs2x() if tabprm::flag is anything other than a predefined magic value.

tabset() normally operates regardless of the value of tabprm::flag; i.e. even if a struct was previously set up it will be reset unconditionally. However, a tabprm struct may be put into "bypass" mode by invoking tabset() initially with tabprm::flag == 1 (rather than 0). tabset() will return immediately if invoked on a struct in that state. To take a struct out of bypass mode, simply reset tabprm::flag to zero. See also tabenq().

Parameters

  [in,out] | tab | Tabular transformation parameters.

Returns
  Status return value:
  - 0: Success.
  - 1: Null tabprm pointer passed.
  - 3: Invalid tabular parameters.
  For returns > 1, a detailed error message is set in tabprm::err if enabled, see wcserr_enable().

## tabx2s()

int tabx2s | ( | struct tabprm * | tab,
|  | int | ncoord,
|  | int | nelem,
|  | const double | x[],
|  | double | world[],
|  | int | stat[] )

Pixel-to-world transformation.

tabx2s() transforms intermediate world coordinates to world coordinates using coordinate lookup.

Parameters

  [in,out] | tab | Tabular transformation parameters.
  [in] | ncoord,nelem | The number of coordinates, each of vector length nelem.
  [in] | x | Array of intermediate world coordinates, SI units.
  [out] | world | Array of world coordinates, in SI units.

  [out]

  stat

  Status return value status for each coordinate:
  - 0: Success.
  - 1: Invalid intermediate world coordinate.

Returns
  Status return value:
  - 0: Success.
  - 1: Null tabprm pointer passed.
  - 3: Invalid tabular parameters.
  - 4: One or more of the x coordinates were invalid, as indicated by the stat vector.
  For returns > 1, a detailed error message is set in tabprm::err if enabled, see wcserr_enable().

## tabs2x()

int tabs2x | ( | struct tabprm * | tab,
|  | int | ncoord,
|  | int | nelem,
|  | const double | world[],
|  | double | x[],
|  | int | stat[] )

World-to-pixel transformation.

tabs2x() transforms world coordinates to intermediate world coordinates.

Parameters

  [in,out] | tab | Tabular transformation parameters.
  [in] | ncoord,nelem | The number of coordinates, each of vector length nelem.
  [in] | world | Array of world coordinates, in SI units.
  [out] | x | Array of intermediate world coordinates, SI units.

  [out]

  stat

  Status return value status for each vector element:
  - 0: Success.
  - 1: Invalid world coordinate.

Returns
  Status return value:
  - 0: Success.
  - 1: Null tabprm pointer passed.
  - 3: Invalid tabular parameters.
  - 5: One or more of the world coordinates were invalid, as indicated by the stat vector.
  For returns > 1, a detailed error message is set in tabprm::err if enabled, see wcserr_enable().

## Variable Documentation

## tab_errmsg

const char* tab_errmsg[]

extern

Status return messages.

Error messages to match the status value returned from each function.