Libraries and Packages: The VOS Interface

The mini-World Coordinate System (

- All WCS functions are built in (hard coded), hence the interface is not extensible at runtime and the only way to support new applications is through modification of the interface (by adding new function drivers).
- There is no support for modeling geometric distortions, except possibly in one dimension.
- There is no provision for storing more than one world coordinate system in FITS oriented image headers, although multiple WCS are supported internally by the interface, and are preserved and restored across mw_save() and mw_load() operations.
- Coordinate transforms involving dependent axes must include all such axes explicitly in the transform. Dependent axes are axes which are related, either by a rotation, or by a WCS function. Operations which could subset dependent axis groups, and which are therefore disallowed, include setting up a transform with an axes bitmap which excludes dependent axes, or more importantly, an image section involving dimensional reduction, where the axis to be removed is not independent. This could happen, for example, if a two-dimensional image were rotated and one tried to open a one-dimensional section of the rotated image.

**Physical**- The physical coordinate system is the raw coordinate system of the data. In the case of an image, the physical coordinate system refers to the pixel coordinates of the original data frame. All other coordinates systems are defined in terms of the physical system (reference frame).**Logical**- The logical coordinate system is defined by the*Lterm*(see below) in terms of the physical coordinate system. In the case of an image, the logical coordinate system specifies raw pixel coordinates relative to some image section or derived image, i.e., the coordinates used for image I/O. In the**mwcs**the Lterm specifies a simple linear transformation, in pixel units, between the original physical image matrix and the current image section.**World**- The world coordinate system is defined by the*Wterm*(see below) in terms of the physical coordinate system. Any number of different kinds of world coordinate systems are conceivable. Examples are the tangent (gnomonic) projection, specifying right ascension and declination relative to the original data image, or any linear WCS, e.g., a linear dispersion relation for spectral data. Multiple world coordinate systems may be simultaneously defined in terms of the same physical system.

**Retrieve**or**Create**the Lterm and/or Wterm using mw_open(), mw_openim(), etc.**Modify**the Lterm and/or Wterm (if necessary) using mw_slterm(), mw_swterm(), etc.**Precompute**the transformations between the coordinate systems using the procedure mw_sctran()**Perform**the transformations for specific coordinates using mw_ctran(), etc.

`wattr`

argument input to mw_swtype(), or in a subsequent call to mw_swattrs(). The WCS attributes for a specific axis may be queried with the function mw_gwattrs(). Attribute values may be modified, or new attributes defined, with mw_swattrs(). The issue of WCS attributes is discussed further in the next section. The WCS attributes which can be set by the `wattr`

term consist of a number of standard attributes, plus an arbitrary number of additional WCS specific (application defined) attributes. The following standard attributes are reserved (but not necessarily defined) for each WCS:

call mw_gwattrs (mw, 1, "wtype", wtype, SZ_WTYPE)

`[*,5,*]`

, an axis mapping may be set up which maps physical axis one to logical axis one, physical axis two to the constant 5, and physical axis three to logical axis two. The internal system remains three dimensional, but the application sees a two dimensional system. Upon input, the missing axis y=5 is added to the two dimensional input coordinate vectors, producing a three dimensional coordinate vector for internal use. During output, axis two is dropped and replaced by axis three. The axis map is entered with `mw`

_saxmap() and queried with mw_gaxmap(). Here, `axno`

is a vector, with axno[i] specifying the logical axis to be mapped onto physical axis i. If zero is specified, the constant axval[i] is used instead. Axis mapping may be enabled or disabled with a call to mw_seti(). Axis mapping affects all of the coordinate transformation procedures and all of the coordinate system specification procedures. Axis mapping is not used with those procedures which directly access or modify the physical or world systems (e.g., mw_slterm() or mw_swterm()) since full knowledge of the physical system is necessary for such operations.`mw_open()`

creates a new `bufptr`

is `NULL`

, then an identity transformation is created with the dimension specified by `ndim`

. If `bufptr`

is pointing to an encoded `mw_openim()`

initializes an `im`

. If the image contains no mwcs information, an identity transformation is loaded instead. `mw_newcopy()`

creates a new mwcs object that is a copy of the `mw`

. `mw_close()`

deallocates the memory structures associated with the `mw`

. `mw_save()`

will save the contents of the `mw`

into the memory pointed to by the char pointer `bufptr`

. If `bufptr`

is `NULL`

, a memory buffer is allocated whose pointer is returned in `bufptr`

. If `bufptr`

is not `NULL`

, the buffer, of length `buflen`

, is used (and resized if necessary). The length of the buffer is returned. The buffer `bufptr`

can be used in the calls `mw_open()`

and `mw_load()`

. `mw_load()`

reloads the `mw`

with information contained in the buffer `bufptr`

saved by `mw_save()`

. `mw_loadim()`

reloads an existing mwcs object `mw`

with information from the image pointed to by the image descriptor `im`

. `mw_saveim()`

saves the contents of the `mw`

into the image pointed to by the image descriptor `im`

.`mw_sctran()`

procedure precomputes the transformation from one coordinate system, `system1`

, to another, `system2`

, for the specified axes in the `mw`

returning a pointer to the optimized coordinate transformation. This pointer, `ct`

is used in the subsequent coordinate transformation calls, `mw_c2tran()`

, etc. The `axes`

argument is a bitfield that represents which axes the transformation should apply to. That is, if you wish to transform the first two axes (x and y), set `axis = 3`

. The `mw_gctrant()`

procedure retrieves a compiled linear transformation and returns the dimensionality of the transformation. The argument `ltm`

contains the coefficient determination matrix, `ltv`

contains the translation vector, `axtype1`

contains the axis types for each of the axes in the source coordinate system, `axtype2`

contains the axis types in the destination coordinate system, and `maxdim`

specifies the maximum dimensionality that the arrays can handle.`mw_slterm`

`()`

and `mw_glterm`

`()`

are used to directly enter or inspect the Lterm of the `mw`

, which consists of the linear transformation matrix `ltm`

and the translation vector `ltv`

, both of dimension `ndim`

, defining the transformation from the physical system to the logical system. `mw_translate()`

may be used to translate, rather than replace, the Lterm of the `mw_rotate()`

, `mw_scale()`

, and `mw_shift()`

.
Generic coordinate transformations are available using the procedures `mw_translate()`

, `mw_rotate()`

, `mw_scale`

, and `mw_shift`

. The `mw_translate()`

procedure is the most general, with the others provided as convenient front-ends. Note that `mw_rotate()`

rotates the Lterm of the **mwcs** object `mw`

through the angle theta, specified in radians, about an arbitrary point center for the specified axes. The axes argument is a *bitfield* representing which axes to which the transformation applies. That is, each bit represents an axis to transform.

`MW_NDIM`

may differ from `MW_NPHYSDIM`

if dimensional reduction has been specified and axis mapping is enabled. `MW_NWCS`

returns the number of WCS currently defined; at least two WCS are always defined, i.e., the logical and physical systems (the world system will default to the physical system if not otherwise defined).`real`

and `double`

variables. They operate on square matrices whose dimensions are specified by `ndim`

, i.e.,` ltm[ndim,ndim]`

.
Example 2.31 shows how to retrieve the **mwcs** information from an image. Example 2.32 will create a WCS such that the world system is centered on an image and the axis decrease value with increasing pixel value. Example 2.33 shows some examples of transforming coordinates with an already opened **mwcs** object. Assume that the **mwcs** object describes a transformations for a three dimensional image. The final example (Example 2.34) prints all the values for all the attributes of all the axis of an image's **mwcs**.

This next example creates a WCS such that the world system is centered on an image and the axis decreases with increasing pixel values.

The following examples transform coordinates with an already opened **mwcs** object. Assume that the object describes a transformation for a 3-dimensional image.

The example below prints all values for all attributes of all axes of an image's **mwcs**.

- Coordinate Systems
**Table 2.76:**- WCS Standard Attributes.**Table 2.77:**- WCS Attributes.- Axis Mapping
- Object Creation and Storage
**Table 2.78:**- MWCS Object Functions.- Coordinate Transformation Procedures
**Table 2.79:**- MWCS Coordinate Transformation Procedures.- Coordinate System Specification
**Table 2.80:**- MWCS System Specification Functions.**Table 2.81:**- Axis Specification Functions.**Table 2.82:**- Applying Transformations to Lterm.- mwcs Parameters
**Table 2.83:**- MWCS Status Procedures.**Table 2.84:**- MWCS Interface Parameters.- Matrix Routines
**Table 2.85:**- Matrix Routines.- Examples

Generated with CERN WebMaker