WCSLIB 7.7

WCSLIB data structures

The WCSLIB routines are based on data structures specific to them: wcsprm for the wcs.h,c routines, celprm for cel.h,c, and likewise spcprm, linprm, prjprm, tabprm, and disprm, with struct definitions contained in the corresponding header files: wcs.h, cel.h, etc. The structs store the parameters that define a coordinate transformation and also intermediate values derived from those parameters. As a high-level object, the wcsprm struct contains linprm, tabprm, spcprm, and celprm structs, and in turn the linprm struct contains disprm structs, and the celprm struct contains a prjprm struct. Hence the wcsprm struct contains everything needed for a complete coordinate description.

Applications programmers who use the top- and middle-level routines generally only need to pass wcsprm structs from one routine that fills them to another that uses them. However, since these structs are fundamental to WCSLIB it is worthwhile knowing something about the way they work.

Three basic operations apply to all WCSLIB structs:

- Initialize. Each struct has a specific initialization routine, e.g. wcsinit(), celini(), spcini(), etc. These allocate memory (if required) and set all struct members to default values.
- Fill in the required values. Each struct has members whose values must be provided. For example, for wcsprm these values correspond to FITS WCS header keyvalues as are provided by the top-level header parsing routine, wcspih().
- Compute intermediate values. Specific setup routines, e.g. wcsset(), celset(), spcset(), etc., compute intermediate values from the values provided. In particular, wcsset() analyses the FITS WCS keyvalues provided, fills the required values in the lower-level structs contained in wcsprm, and invokes the setup routine for each of them.

Each struct contains a flag member that records its setup state. This is cleared by the initialization routine and checked by the routines that use the struct; they will invoke the setup routine automatically if necessary, hence it need not be invoked specifically by the application programmer. However, if any of the required values in a struct are changed then either the setup routine must be invoked on it, or else the flag must be zeroed to signal that the struct needs to be reset.

The initialization routine may be invoked repeatedly on a struct if it is desired to reuse it. However, the flag member of structs that contain allocated memory (wcsprm, linprm, tabprm, and disprm) must be set to -1 before the first initialization to initialize memory management, but not subsequently or else memory leaks will result.

Each struct has one or more service routines: to do deep copies from one to another, to print its contents, and to free allocated memory. Refer to the header files for a detailed description.