Create a UnitNormMap


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

The forward transformation of a UnitNormMap subtracts the specified centre and then transforms the resulting vector to a unit vector and the vector norm. The output contains one more coordinate than the input: the initial Nin outputs are in the same order as the input; the final output is the norm. If the norm is 0, then the output of the forward transformation is AST__BAD for each component of the unit vector and 0 for the norm (the final value).

The inverse transformation of a UnitNormMap multiplies each component of the provided vector by the provided norm and adds the specified centre. The output contains one fewer coordinate than the input: the initial Nin inputs are in the same order as the output; the final input is the norm. If the provided norm is 0 then the other input values are ignored, and the output vector is the centre.

Example: if centre = [1, -1] then [5, 2] transforms to [4, 3] after subtracting the centre; the norm is 5, so the output is [0.8, 0.6, 5].

UnitNormMap enables radially symmetric transformations, as follows:


AstUnitNormMap astUnitNormMap( int ncoord, const double centre[], const char options, ... )


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). Output will include one additional coordinate.
An array containing the values to be subtracted from the input coordinates before computing unit vector and norm. A separate value must be supplied for each coordinate.
Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new UnitNormMap. 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 " 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

A pointer to the new UnitNormMap.


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