next up previous
Next: AST_NORM - Normalise a set of Frame coordinates
Up: AST Routine Descriptions
Previous: AST_MATHMAP - Create a MathMap

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

Invocation:
RESULT = AST_MATRIXMAP( NIN, NOUT, FORM, MATRIX, OPTIONS, STATUS )

Arguments:
NIN = INTEGER (Given)
The number of input coordinates, which determines the number of columns in the matrix.
NOUT = INTEGER (Given)
The number of output coordinates, which determines the number of rows in the matrix.
FORM = INTEGER (Given)
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 argument (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 argument is not used.

MATRIX( * ) = DOUBLE PRECISION (Given)
The array of matrix elements to be used, stored according to the value of FORM.
OPTIONS = CHARACTER * ( * ) (Given)
A character 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 AST_SET routine.
STATUS = INTEGER (Given and Returned)
The global status.

Returned Value:
AST_MATRIXMAP = INTEGER
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 STATUS set to an error value, or if it should fail for any reason.



next up previous
Next: AST_NORM - Normalise a set of Frame coordinates
Up: AST Routine Descriptions
Previous: AST_MATHMAP - Create a MathMap

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
R.F. Warren-Smith & D.S. Berry
30th April 2003
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2003 Central Laboratory of the Research Councils