astSwitchMapastSwitchMap - Create a SwitchMap

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

A SwitchMap is a MappingMapping which represents a set of alternate Mappings, each of which is used to transform positions within a particular region of the input or output coordinate system of the SwitchMap.

A SwitchMap can encapsulate any number of Mappings, but they must all have the same number of inputs (NinNin attribute value) and the same number of outputs (NoutNout attribute value). The SwitchMap itself inherits these same values for its Nin and Nout attributes. Each of these Mappings represents a "route" through the switch, and are referred to as "route" Mappings below. Each route Mapping transforms positions between the input and output coordinate space of the entire SwitchMap, but only one Mapping will be used to transform any given position. The selection of the appropriate route Mapping to use with any given input position is made by another Mapping, called the "selector" Mapping. Each SwitchMap encapsulates two selector Mappings in addition to its route Mappings; one for use with the SwitchMap's forward transformation (called the "forward selector Mapping"), and one for use with the SwitchMap's inverse transformation (called the "inverse selector Mapping"). The forward selector Mapping must have the same number of inputs as the route Mappings, but should have only one output. Likewise, the inverse selector Mapping must have the same number of outputs as the route Mappings, but should have only one input.

When the SwitchMap is used to transform a position in the forward direction (from input to output), each supplied input position is first transformed by the forward transformation of the forward selector Mapping. This produces a single output value for each input position referred to as the selector value. The nearest integer to the selector value is found, and is used to index the array of route Mappings (the first supplied route Mapping has index 1, the second route Mapping has index 2, etc). If the nearest integer to the selector value is less than 1 or greater than the number of route Mappings, then the SwitchMap output position is set to a value of AST__BAD on every axis. Otherwise, the forward transformation of the selected route Mapping is used to transform the supplied input position to produce the SwitchMap output position.

When the SwitchMap is used to transform a position in the inverse direction (from "output" to "input"), each supplied "output" position is first transformed by the inverse transformation of the inverse selector Mapping. This produces a selector value for each "output" position. Again, the nearest integer to the selector value is found, and is used to index the array of route Mappings. If this selector index value is within the bounds of the array of route Mappings, then the inverse transformation of the selected route Mapping is used to transform the supplied "output" position to produce the SwitchMap "input" position. If the selector index value is outside the bounds of the array of route Mappings, then the SwitchMap "input" position is set to a value of AST__BAD on every axis.

In practice, appropriate selector Mappings should be chosen to associate a different route Mapping with each region of coordinate space. Note that the SelectorMapSelectorMap class of Mapping is particularly appropriate for this purpose.

If a compound Mapping contains a SwitchMap in series with its own inverse, the combination of the two adjacent SwitchMaps will be replaced by a UnitMapUnitMap when the compound Mapping is simplified using astSimplifyastSimplify.

Synopsis:
AstSwitchMap $*$astSwitchMap( AstMapping $*$fsmap, AstMapping $*$ismap, int nroute, AstMapping $*$routemaps[], const char $*$options, ... )
Parameters:
fsmap
Pointer to the forward selector Mapping. This must have a defined forward transformation, but need not have a defined inverse transformation. It must have one output, and the number of inputs must match the number of inputs of each of the supplied route Mappings. NULL may be supplied, in which case the SwitchMap will have an undefined forward Mapping.
ismap
Pointer to the inverse selector Mapping. This must have a defined inverse transformation, but need not have a defined forward transformation. It must have one input, and the number of outputs must match the number of outputs of each of the supplied route Mappings. NULL may be supplied, in which case the SwitchMap will have an undefined inverse Mapping.
nroute
The number of supplied route Mappings.
routemaps
An array of pointers to the route Mappings. All the supplied route Mappings must have common values for the Nin and Nout attributes, and these values define the number of inputs and outputs of the SwitchMap.
options
Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SwitchMap. The syntax used is identical to that for the astSetastSet 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:
astSwitchMap()
A pointer to the new SwitchMap.
Notes:
  • Note that the component Mappings supplied are not copied by astSwitchMap (the new SwitchMap simply retains a reference to them). They may continue to be used for other purposes, but should not be deleted. If a SwitchMap containing a copy of its component Mappings is required, then a copy of the SwitchMap should be made using astCopyastCopy.

  • A null ObjectObject 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.