WCSLIB  5.16
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 and tabprm, 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 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:

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 and tabprm) 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.