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:

```      INTEGER OUTPERM( 4 ), INPERM( 4 )
DATA OUTPERM / 4, 1, 2, 3 /
DATA INPERM / 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:

```      INTEGER PERMMAP
DOUBLE PRECISION DUMMY( 1 )

...

PERMMAP = AST_PERMMAP( 4, INPERM, 4, OUTPERM, DUMMY, ' ', STATUS )
```

(the fifth argument is not being used, so a dummy array has been supplied). 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:

```      INTEGER OUTPERM( 3 ), INPERM( 4 )
DOUBLE PRECISION CONST( 1 )
DATA OUTPERM / 4, 3, 2 /
DATA INPERM / -1, 3, 2, 1 /
DATA CONST / 99.004D0 /
```

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 CONST array using an index of 1 (the absolute value). This array, ignored in the previous example, may then be used to supply a value for the missing coordinate.

The constructor function:

```      PERMMAP = AST_PERMMAP( 4, INPERM, 3, OUTPERM, CONST, ' ', STATUS )
```

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 CONST 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 CONST 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_PAR include 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