Creates a Mapping and optionally adds a new co-ordinate Frame into the WCS component of an NDF
When adding a new Frame to a WCS component, the Mapping is used to connect the new
Frame to an existing one (called the basis Frame: see Parameter FRAME). The specific
type of Frame to add is specified using Parameter FRMTYPE (the default is to simply
copy the basis Frame). Optionally (see Parameter TRANSFER), attributes which have been
assigned an explicit value in the basis Frame are transferred to the new Frame (but
only if they are relevant to the type of the new Frame). The value of the Domain
attribute for the new Frame can be specified using Parameter DOMAIN. Other attribute
values for the new Frame may be specified using Parameter ATTRS. The new Frame
becomes the current co-ordinate Frame in the NDF (unless Parameter RETAIN is set
TRUE
).
WCSADD will only generate Mappings with the same number of input and output axes; this number is determined by the number of axes in the basis Frame if an NDF is supplied, or by the NAXES parameter otherwise.
A comma-separated list of strings should be given in which each string is either an
attribute setting, or the name of a text file preceded by an up-arrow character
"
.
Such text files should contain further comma-separated lists which will be read and
interpreted in the same manner. Attribute settings are applied in the order in which
they occur within the list, with later settings overriding any earlier settings given
for the same attribute.
"
Each individual attribute setting should be of the form:
<name>=<value>
where <name> is the name of an attribute appropriate to the type of Frame specified by Parameter FRMTYPE (see SUN/210 for a complete description of all attributes), and <value> is the value to assign to the attribute. Default values will be used for any unspecified attributes–-these defaults are inherited from the basis Frame. Any unrecognised attributes are ignored (no error is reported).
"PINCUSHION"
. See also DISCO. [0,0]
"DIAG"
.
where (X,Y)
are the input co-ordinates, (XX,YY)
the output co-ordinates, D
is DISCO, and C1
and C2
are the two elements of CENTRE. DISCO is only used when MAPTYPE="PINCUSHION"
.
Note, if Parameter MAPTYPE is set to "REFNDF"
, then the value supplied for
Parameter DOMAIN indicates the Domain of the Frame within the reference NDF that
is to be copied (see Parameter REFNDF).
"1996.8"
for example). Such values are interpreted as a Besselian epoch
if less than 1984.0 and as a Julian epoch otherwise. The suggested default
is the value stored in the basis Frame. "^
"
character. Individual expression should be separated by commas or, if they are supplied
in a file, newlines (see Section 4.13).
The syntax for each expression is Fortran-like; see the "Examples"
section below, and
Appendix G for details. FOREXP is only used when MAPTYPE="MATH"
.
A domain name such as SKY, AXIS, PIXEL. The two "pseudo-domains"
WORLD and
DATA may be supplied and will be translated into PIXEL and AXIS respectively,
so long as the WCS component of the NDF does not contain Frames with these
domains.
An integer value giving the index of the required Frame within the WCS component.
An IRAS90 Sky Co-ordinate System (SCS) values such as "EQUAT(J2000)"
(see SUN/163).
!
) value is
supplied, a copy of the basis Frame is used (as modified by Parameters ATTRS and
DOMAIN). The allowed values are as follows.
"FRAME"
–- A simple Cartesian Frame (the number of axes is equal to the number of
outputs from the Mapping)
"SKYFRAME"
–- A two-dimensional Frame representing positions on the celestial
sphere.
"SPECFRAME"
–- A one-dimensional Frame representing positions within an electromagnetic
spectrum.
"TIMEFRAME"
–- A one-dimensional Frame representing moments in time.
Note, if Parameter MAPTYPE is set to "REFNDF"
, then Parameter FRMTYPE will
not be used–-the Frame used will instead always be a copy of the Frame from
the reference NDF (as selected by Parameter DOMAIN). [!]
"MATH"
. "FILE"
. !
) value is
supplied, no file is created. [!]
"DIAGONAL"
–- A linear mapping with no translation of off-diagonal coefficients (see
Parameter DIAG)
"FILE"
–- A mapping defined by an AST Mapping supplied in a separate file (see
Parameter MAPIN)
"LINEAR"
–- A general linear mapping (see Parameter TR)
"MATH"
–- A general algebraically defined mapping (see Parameters FOREXP, INVEXP,
SIMPFI, SIMPIF)
"PINCUSHION"
–- A pincushion/barrel distortion (see Parameters DISCO and CENTRE)
"REFNDF"
–- The Mapping is obtained by aligning the NDF with a second reference NDF
(see Parameter REFNDF)
"SHIFT"
–- A translation (see Parameter SHIFT)
"UNIT"
–- A unit mapping
"ZOOM"
–- A uniform expansion/contraction (see Parameter ZOOM)
["LINEAR"]
!
) value if you do not wish to add a Frame to an NDF (you can still use the MAPOUT
parameter to write the Mapping to a text file). "REFNDF"
,
in which case a value must also be supplied for Parameter NDF (an error will
be reported otherwise). FALSE
, the newly added Frame is the current Frame
on exit. Otherwise, the original current Frame is retained on exit. [FALSE]
"SHIFT"
. "MATH"
. [TRUE]
"MATH"
. [TRUE]
MAPTYPE="LINEAR"
. For instance, if a feature has co-ordinates
(X,Y,Z,…)
in the basis Frame, and co-ordinates
(U,V,W,…)
in the new Frame, then the following transformations would be used, depending on how
many axes the two Frames have:
The correct number of values must be supplied (that is,
N∗(N+1) where
N is
the number of axes in the new and old Frames). If a null value (!
) is given it is
assumed that the new Frame and the basis Frame are connected using a unit mapping (i.e.
corresponding axis values are identical in the two Frames). This parameter is
only used when MAPTYPE="LINEAR"
. [!]
TRUE
,
attributes which have explicitly set values in the basis Frame (specified by
Parameter FRAME) are transferred to the new Frame (specified by Parameter FRMTYPE),
if they are applicable to the new Frame. If FALSE
, no attribute values are
transferred. The dynamic default is TRUE
if and only if the two Frames are
of the same class and have the same value for their Domain attributes. []
"ZOOM"
. "AU"
. zoom.ast
. ^
ft
invexp=^
it
ft
and it
, instead of being supplied directly. Each file could contain the
two expression on two separate lines. The new Frame has the same number of axes as the basis Frame.
An error is reported if the transformation supplied using Parameter TR is singular.