#### Description:

This function creates a new SpecMap and optionally initialises its attributes.

An SpecMap is a specialised form of Mapping which can be used to represent a sequence of conversions between standard spectral coordinate systems. This includes conversions between frequency, wavelength, and various forms of velocity, as well as conversions between different standards of rest.

When a SpecMap is first created, it simply performs a unit (null) Mapping. Using the astSpecAdd function, a series of coordinate conversion steps may then be added, selected from the list of supported conversions. This allows multi-step conversions between a variety of spectral coordinate systems to be assembled out of the building blocks provided by this class.

For details of the individual coordinate conversions available, see the description of the astSpecAdd function.

Conversions are available to transform between standards of rest. Such conversions need to know the source position as an RA and DEC. This information can be supplied in the form of parameters for the relevant conversions, in which case the SpecMap is 1-dimensional, simply transforming the spectral axis values. This means that the same source position will always be used by the SpecMap. However, this may not be appropriate for an accurate description of a 3-D spectral cube, where changes of spatial position can produce significant changes in the Doppler shift introduced when transforming between standards of rest. For this situation, a 3-dimensional SpecMap can be created in which axes 2 and 3 correspond to the source RA and DEC The SpecMap simply copies values for axes 2 and 3 from input to output).

#### Synopsis

AstSpecMap ∗astSpecMap( int nin, int flags, const char ∗options, ... )

#### Parameters:

##### nin

The number of inputs to the Mapping (this will also equal the number of outputs). This value must be either 1 or 3. In either case, the first input and output correspoindis the spectral axis. For a 3-axis SpecMap, the second and third axes give the RA and DEC (J2000 FK5) of the source. This positional information is used by conversions which transform between standards of rest, and replaces the `"` RA`"` and `"` DEC`"` arguments for the individual conversions listed in description of the `"` SpecAdd`"` function.

##### flags

This parameter is reserved for future use and should currently always be set to zero.

##### options

Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SpecMap. 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 no initialisation is required, a zero-length string may be supplied.

##### ...

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

##### astSpecMap()

A pointer to the new SpecMap.

#### Notes:

- The nature and units of the coordinate values supplied for the first input (i.e. the spectral input) of a SpecMap must be appropriate to the first conversion step applied by the SpecMap. For instance, if the first conversion step is `"` FRTOVL`"` (frequency to relativistic velocity), then the coordinate values for the first input should be frequency in units of Hz. Similarly, the nature and units of the coordinate values returned by a SpecMap will be determined by the last conversion step applied by the SpecMap. For instance, if the last conversion step is `"` VLTOVO`"` (relativistic velocity to optical velocity), then the coordinate values for the first output will be optical velocity in units of metres per second. See the description of the astSpecAdd function for the units expected and returned by each conversion.

- 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.

Copyright (C) 2021 East Asian Observatory