next up previous 264
Next: AST_SET - Set attribute values for an Object
Up: AST Routine Descriptions
Previous: AST_SAME - Test if two AST pointers refer to the same Object


AST_SELECTORMAP - Create a SelectorMap

Description:
This function creates a new SelectorMap and optionally initialises its attributes.

A SelectorMap is a Mapping that identifies which Region contains a given input position.

A SelectorMap encapsulates a number of Regions that all have the same number of axes and represent the same coordinate Frame. The number of inputs (Nin attribute) of the SelectorMap equals the number of axes spanned by one of the encapsulated Region. All SelectorMaps have only a single output. SelectorMaps do not define an inverse transformation.

For each input position, the forward transformation of a SelectorMap searches through the encapsulated Regions (in the order supplied when the SelectorMap was created) until a Region is found which contains the input position. The index associated with this Region is returned as the SelectorMap output value (the index value is the position of the Region within the list of Regions supplied when the SelectorMap was created, starting at 1 for the first Region). If an input position is not contained within any Region, a value of zero is returned by the forward transformation.

If a compound Mapping contains a SelectorMap in series with its own inverse, the combination of the two adjacent SelectorMaps will be replaced by a UnitMap when the compound Mapping is simplified using AST_SIMPLIFY.

In practice, SelectorMaps are often used in conjunction with SwitchMaps.

Invocation:
RESULT = AST_SELECTORMAP( NREG, REGS, BADVAL, OPTIONS, STATUS )
Arguments:
NREG = INTEGER (Given)
The number of supplied Regions.
REGS( NREG ) = INTEGER (Given)
An array of pointers to the Regions. All the supplied Regions must relate to the same coordinate Frame. The number of axes in this coordinate Frame defines the number of inputs for the SelectorMap.
BADVAL = DOUBLE PRECISION (Given)
The value to be returned by the forward transformation of the SelectorMap for any input positions that have a bad (AST__BAD) value on any axis.
OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new SelectorMap. The syntax used is identical to that for the AST_SET routine.
STATUS = INTEGER (Given and Returned)
The global status.
Returned Value:
AST_SELECTORMAP = INTEGER
A pointer to the new SelectorMap.
Notes:
  • Deep copies are taken of the supplied Regions. This means that any subsequent changes made to the component Regions using the supplied pointers will have no effect on the SelectorMap.

  • 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 264
Next: AST_SET - Set attribute values for an Object
Up: AST Routine Descriptions
Previous: AST_SAME - Test if two AST pointers refer to the same Object

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

Copyright (C) 2009 Science \& Technology Facilities Council