Create a MatrixMap
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.
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.
"
form"
. "
printf"
format specifiers identified
by "
%"
symbols in the normal way. "
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). 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.
"
int
$\ast $status"
.