A Mapping that encapsulates a set of alternate Mappings
A SwitchMap can encapsulate any number of Mappings, but they must all have the same
number of inputs (Nin attribute value) and the same number of outputs (Nout 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 SelectorMap 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 UnitMap when the compound Mapping is simplified using astSimplify.