astWcsMap - Create a WcsMap

**Description:**- This function creates a new WcsMap and optionally initialises its
attributes.
A WcsMap is used to represent sky coordinate projections as described in the (draft) FITS world coordinate system (FITS-WCS) paper by E.W. Griesen and M. Calabretta (A & A, in preparation). This paper defines a set of functions, or sky projections, which transform longitude-latitude pairs representing spherical celestial coordinates into corresponding pairs of Cartesian coordinates (and vice versa).

A WcsMap is a specialised form of Mapping which implements these sky projections and applies them to a specified pair of coordinates. All the projections in the FITS-WCS paper are supported, plus the now deprecated

`"`TAN with polynomial correction terms`"`projection which is refered to here by the code`"`TPN`"`. Using the FITS-WCS terminology, the transformation is between`"`native spherical`"`and`"`projection plane`"`coordinates. These coordinates may, optionally, be embedded in a space with more than two dimensions, the remaining coordinates being copied unchanged. Note, however, that for consistency with other AST facilities, a WcsMap handles coordinates that represent angles in radians (rather than the degrees used by FITS-WCS).The type of FITS-WCS projection to be used and the coordinates (axes) to which it applies are specified when a WcsMap is first created. The projection type may subsequently be determined using the WcsType attribute and the coordinates on which it acts may be determined using the WcsAxis(lonlat) attribute.

Each WcsMap also allows up to 100

`"`projection parameters`"`to be associated with each axis. These specify the precise form of the projection, and are accessed using PVi_m attribute, where`"`i`"`is the integer axis index (starting at 1), and m is an integer`"`parameter index`"`in the range 0 to 99. The number of projection parameters required by each projection, and their meanings, are dependent upon the projection type (most projections either do not use any projection parameters, or use parameters 1 and 2 associated with the latitude axis). Before creating a WcsMap you should consult the FITS-WCS paper for details of which projection parameters are required, and which have defaults. When creating the WcsMap, you must explicitly set values for all those required projection parameters which do not have defaults defined in this paper.

- This function creates a new WcsMap and optionally initialises its
attributes.
**Synopsis:**`AstWcsMap astWcsMap( int ncoord, int type, int lonax, int latax, const char options, ... )`

**Parameters:****ncoord**- The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). This must be at least 2. The same number is applicable to both input and output points.
**type**-
The type of FITS-WCS projection to apply. This should be
given using a macro value such as AST__TAN (for a tangent
plane projection), where the characters following the double
underscore give the projection type code (in upper case) as
used in the FITS-WCS
`"`CTYPEi`"`keyword. You should consult the FITS-WCS paper for a list of the available projections. The additional code of AST__TPN can be supplied which represents a TAN projection with polynomial correction terms as defined in an early draft of the FITS-WCS paper. **lonax**-
The index of the longitude axis. This should lie in the range
1 to
`"`ncoord`"`. **latax**-
The index of the latitude axis. This should lie in the range
1 to
`"`ncoord`"`and be distinct from`"`lonax`"`. **options**-
Pointer to a null-terminated string containing an optional
comma-separated list of attribute assignments to be used for
initialising the new WcsMap. The syntax used is identical to
that for the astSet function and may include
`"`printf`"`format specifiers identified by`"`%`"`symbols in the normal way.If the sky projection to be implemented requires projection parameter values to be set, then this should normally be done here via the PVi_m attribute (see the

`"`Examples`"`section). Setting values for these parameters is mandatory if they do not have default values (as defined in the FITS-WCS paper). **...**-
If the
`"`options`"`string contains`"`%`"`format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C`"`printf`"`function).

**Returned Value:****astWcsMap()**- A pointer to the new WcsMap.

**Examples:**`wcsmap = astWcsMap( 2, AST__MER, 1, 2,``""`);-

Creates a WcsMap that implements a FITS-WCS Mercator projection on pairs of coordinates, with coordinates 1 and 2 representing the longitude and latitude respectively. Note that the FITS-WCS Mercator projection does not require any projection parameters. `wcsmap = astWcsMap( 3, AST__COE, 2, 3,``"`PV3_1=40.0`"`);-

Creates a WcsMap that implements a FITS-WCS conical equal area projection. The WcsMap acts on points in a 3-dimensional space; coordinates 2 and 3 represent longitude and latitude respectively, while the values of coordinate 1 are copied unchanged. Projection parameter 1 associatyed with the latitude axis (corresponding to FITS keyword`"`PV3_1`"`) is required and has no default, so is set explicitly to 40.0 degrees. Projection parameter 2 (corresponding to FITS keyword`"`PV3_2`"`) is required but has a default of zero, so need not be specified.

**Notes:**- The forward transformation of a WcsMap converts between
FITS-WCS
`"`native spherical`"`and`"`relative physical`"`coordinates, while the inverse transformation converts in the opposite direction. This arrangement may be reversed, if required, by using astInvert or by setting the Invert attribute to a non-zero value. - If any set of coordinates cannot be transformed (for example,
many projections do not cover the entire celestial sphere), then
a WcsMap will yield coordinate values of AST__BAD.
- The validity of any projection parameters given via the PVi_m
parameter in the
`"`options`"`string is not checked by this function. However, their validity is checked when the resulting WcsMap is used to transform coordinates, and an error will result if the projection parameters do not satisfy all the required constraints (as defined in the FITS-WCS paper). - A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

- The forward transformation of a WcsMap converts between
FITS-WCS

**Status Handling**- The protected interface to this function includes an extra
parameter at the end of the parameter list descirbed above. This
parameter is a pointer to the integer inherited status
variable:
`"`int status`"`.

- The protected interface to this function includes an extra
parameter at the end of the parameter list descirbed above. This
parameter is a pointer to the integer inherited status
variable:

Starlink User Note 211

R.F. Warren-Smith & D.S. Berry

7th December 2012

E-mail:starlink@jiscmail.ac.uk

Copyright (C) 2012 Science \& Technology Facilities Council