Next: Compound Mappings (CmpMaps)
Up: Inter-Relating Coordinate Systems (Mappings)
Previous: Example the UnitMap

## Example--the PermMap

The PermMap is a rather more complicated Mapping than we have met previously. Its purpose is to change the order, or number, of coordinates. It is also able to substitute fixed values for coordinates.

To illustrate its action, suppose our input coordinates are denoted by ( ) in a 4-dimensional space and suppose our output coordinates are to be ( ). Our PermMap, therefore, should rotate the coordinate values by one position.

To create such a PermMap, we first set up two integer arrays. One of these, ``outperm'', controls the selection of input coordinates for use in the output and the other, ``inperm'', controls selection of output coordinates for use in the input:

```int outperm[ 4 ] = { 4, 1, 2, 3 };
int inperm[ 4 ] = { 2, 3, 4, 1 };
```

Note that the numbers we store in these arrays are the indices of the coordinates that we want to select. We have chosen these so that the forward and inverse transformations will perform complementary permutations on the coordinates.

The PermMap is then created by passing these arrays to its constructor, as follows:

```AstPermMap *permmap;

...

permmap = astPermMap( 4, inperm, 4, outperm, NULL, "" );
```

Note that we specify the number of input and output coordinates separately, but set both to 4 in this example. The resulting PermMap would have the following effect when used to transform coordinates:

```Forward:
(1, 2, 3, 4) --> (4, 1, 2, 3)
(2, 4, 6, 8) --> (8, 2, 4, 6)
(3, 6, 9, 12) --> (12, 3, 6, 9)
(4, 8, 12, 16) --> (16, 4, 8, 12)
(5, 10, 15, 20) --> (20, 5, 10, 15)

Inverse:
(4, 1, 2, 3) --> (1, 2, 3, 4)
(8, 2, 4, 6) --> (2, 4, 6, 8)
(12, 3, 6, 9) --> (3, 6, 9, 12)
(16, 4, 8, 12) --> (4, 8, 12, 16)
(20, 5, 10, 15) --> (5, 10, 15, 20)
```

If the number of input and output coordinates are unequal so, also, will be the size of the ``outperm'' and ``inperm'' arrays. This means, however, that we cannot fill them with coordinate indices so that they perform complementary permutations, because one transformation will lose information (discard a coordinate) that the other cannot recover. To give an example, consider the following:

```int outperm[ 3 ] = { 4, 3, 2 };
int inperm[ 4 ] = { -1, 3, 2, 1 };
double con[ 1 ] = { 99.004 };
```

In this case, the forward transformation will change ( ) into () and will discard . The inverse transformation restores the original coordinate order, but has no value to assign to the first coordinate. In this case, the number entered in the ``inperm'' array is 1.

This negative value indicates that the coordinate value should be obtained by addressing the first element of the ``con'' array (i.e. element zero). This array, ignored in the previous example, may then be used to supply a value for the missing coordinate.

The constructor function:

```permmap = astPermMap( 4, inperm, 3, outperm, con, "" );
```

will then create a PermMap with the following effect when used to transform coordinates:

```Forward:
(1, 2, 3, 4) --> (4, 3, 2)
(2, 4, 6, 8) --> (8, 6, 4)
(3, 6, 9, 12) --> (12, 9, 6)
(4, 8, 12, 16) --> (16, 12, 8)
(5, 10, 15, 20) --> (20, 15, 10)

Inverse:
(4, 3, 2) --> (99.004, 2, 3, 4)
(8, 6, 4) --> (99.004, 4, 6, 8)
(12, 9, 6) --> (99.004, 6, 9, 12)
(16, 12, 8) --> (99.004, 8, 12, 16)
(20, 15, 10) --> (99.004, 10, 15, 20)
```

The ``con'' array may contain more than one value if necessary and may be addressed by both the ``inperm'' and ``outperm'' arrays using coordinate indices 1, 2, 3, etc. to refer to the first, second, third, etc. elements.

If there is no suitable replacement value that can be supplied via the ``con'' array, a value of zero may be entered into the ``outperm'' and/or ``inperm'' arrays. This causes the value AST__BAD to be used for the affected coordinate (as defined in the ``ast.h'' header file), thus indicating a missing coordinate value ().

The principle use for a PermMap lies in matching a coordinate system to a data array where there is a choice of storage order for the data. PermMaps are also useful for discarding unwanted coordinates so as to reduce the number of dimensions, such as when selecting a ``slice'' from a multi-dimensional array.

Next: Compound Mappings (CmpMaps)
Up: Inter-Relating Coordinate Systems (Mappings)
Previous: Example the UnitMap

AST A Library for Handling World Coordinate Systems in Astronomy