AxesSpecifier.h

AxesSpecifier makes it possible to specify which axes should be used in a shape. Degenerate axes (i.e. axes with length 0) can be thrown away which makes it possible to reduce the dimensionality of an array. All degenerate axes can be thrown away, but one can also specify which ones should be kept.

Another option of this class is to reorder the axes, thus to make the axes of a lattice appear in a different order. This can be useful when two images with diferent axes orders have to be combined.

When an AxesSpecifier has to be used for a lattice, the lattice's shape has to be applied to the AxesSpecifier. The result is a AxesMapping object. This object is (for example) used internally in the SubLattice class to know how to map the axes form the original lattice to the sublattice.

Reordering axes is not supported (yet) by the other AIPS++ classes like Lattices and Images.

Example

This example tells that all degenerate axes have to be kept. The axes are reordered to 1,0,2. Thus the first and second axes are swapped.

    AxesSpecifier spec(True, IPosition(3,1,0,2));
    AxesMapping map = spec.apply (IPosition(3,4,1,5));
    AlwaysAssertExit (map.posToNew (IPosition(3,2,0,3)) == IPosition(3,0,2,3));
    AlwaysAssertExit (map.posToOld (IPosition(3,0,2,3)) == IPosition(3,2,0,3));
    
    The following specification would have the same effect, because the
    unspecified axes are kept in their natural order.
    AxesSpecifier spec(True, IPosition(1,1));

The same example as above, but now degenerated axes are removed. Note that because the second axis is removed, the third axis now get the second axis, thus gets swapped with the first axis.
Also note the difference between the functions posToOld and shapeToOld.

    AxesSpecifier spec(False, IPosition(1,1));
    AxesMapping map = spec.apply (IPosition(3,4,1,5));
    AlwaysAssertExit (map.posToNew (IPosition(3,2,0,3)) == IPosition(2,3,2));
    AlwaysAssertExit (map.posToOld (IPosition(3,3,2)) == IPosition(3,2,0,3);
    AlwaysAssertExit (map.shapeToOld (IPosition(3,3,2)) == IPosition(3,2,1,3);

Member Description

AxesSpecifier()

The default constructor keeps all axes.

explicit AxesSpecifier (Bool keepDegenerate)

Tell if no or all degenerate axes have to be removed.

explicit AxesSpecifier (Bool keepDegenerate, const IPosition& axisPath)

Tell if no or all degenerate axes have to be removed.
The argument axisPath makes it possible to specify in which order the KEPT axes have to be used. Unspecified axes are appended to the end. It gives a means to reorder the axes of a lattice.
E.g. for a 4-dim lattice axisPath [2,0] means axis order [2,0,1,3].

explicit AxesSpecifier (const IPosition& keepAxes)

Tell which (degenerate) axes have to be kept. Non-degenerate axes will always be kept.

AxesSpecifier (const IPosition& keepAxes, const IPosition& axisPath)

The argument keepAxes tells which degenerate axes have to be kept. Non-degenerate axes will always be kept.
The argument axisPath makes it possible to specify in which order the KEPT axes have to be used. Unspecified axes are appended to the end. It gives a means to reorder the axes of a lattice.
E.g. for a 4-dim lattice axisPath [2,0] means axis order [2,0,1,3].

AxesSpecifier(const AxesSpecifier& other)

Copy constructor (copy semantics).

~AxesSpecifier()

AxesSpecifier& operator= (const AxesSpecifier& other)

Assignment (copy semantics). This and that do not have to have the same length.

AxesMapping apply (const IPosition& shape) const

Apply the specification to a shape. It returns an AxesMapping object which takes care of mapping old to new axes order.

Bool keep() const

Are we keeping all degenerate axes ?