astMatrixMap - Create a MatrixMap

**Description:**- This function creates a new MatrixMap and optionally initialises
its attributes.
A MatrixMap is a form of Mapping which performs a general linear transformation. Each set of input coordinates, regarded as a column-vector, are pre-multiplied by a matrix (whose elements are specified when the MatrixMap is created) to give a new column-vector containing the output coordinates. If appropriate, the inverse transformation may also be performed.

- This function creates a new MatrixMap and optionally initialises
its attributes.
**Synopsis:**`AstMatrixMap astMatrixMap( int nin, int nout, int form, const double matrix[], const char options, ... )`

**Parameters:****nin**- The number of input coordinates, which determines the number of columns in the matrix.
**nout**- The number of output coordinates, which determines the number of rows in the matrix.
**form**-
An integer which indicates the form in which the matrix
elements will be supplied.
A value of zero indicates that a full

`"`nout`"`x`"`nin`"`matrix of values will be supplied via the`"`matrix`"`parameter (below). In this case, the elements should be given in row order (the elements of the first row, followed by the elements of the second row, etc.).A value of 1 indicates that only the diagonal elements of the matrix will be supplied, and that all others should be zero. In this case, the elements of

`"`matrix`"`should contain only the diagonal elements, stored consecutively.A value of 2 indicates that a

`"`unit`"`matrix is required, whose diagonal elements are set to unity (with all other elements zero). In this case, the`"`matrix`"`parameter is ignored and a NULL pointer may be supplied. **matrix**-
The array of matrix elements to be used, stored according to
the value of
`"`form`"`. **options**-
Pointer to a null-terminated string containing an optional
comma-separated list of attribute assignments to be used for
initialising the new MatrixMap. 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:****astMatrixMap()**- A pointer to the new MatrixMap.

**Notes:**- In general, a MatrixMap's forward transformation will always
be available (as indicated by its TranForward attribute), but
its inverse transformation (TranInverse attribute) will only be
available if the associated matrix is square and non-singular.
- As an exception to this, the inverse transformation is always
available if a unit or diagonal matrix is specified. In this
case, if the matrix is not square, one or more of the input
coordinate values may not be recoverable from a set of output
coordinates. Any coordinates affected in this way will simply be
set to the value zero.
- 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.

- In general, a MatrixMap's forward transformation will always
be available (as indicated by its TranForward attribute), but
its inverse transformation (TranInverse attribute) will only be
available if the associated matrix is square and non-singular.

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