All sub-classes of Region require a FrameFrame to be supplied when the Region is created. This Frame describes the coordinate system in which the Region is defined, and is referred to as the "encapsulated Frame" below. Constructors will also typically required one or more positions to be supplied which define the location and extent of the region. These positions must be supplied within the encapsulated Frame.
The Region class inherits from the Frame class, and so a Region can be supplied where-ever a Frame is expected. In these cases, supplying a Region is equivalent to supplying a reference to its encapsulated Frame. Thus all the methods of the Frame class can be used on the Region class. For instance, the astFormatastFormat function may be used on a Region to format an axis value.
In addition, since Frame inherits from MappingMapping, a Region is also a sort
of Mapping. Transforming positions by supplying a Region to one of the
astTranX
functions
is the way to determine if a given position is inside or outside the
Region. When used as a Mapping, most classes of Frame are equivalent to
a UnitMapUnitMap. However, the Region class modifies this behaviour so that a
Region acts like a UnitMap only for input positions which are within the
area represented by the Region. Input positions which are outside the
area produce bad output values (i.e. the output values are equal to
AST__BAD). This behaviour is the same for both the forward and the
inverse transformation. In this sense the "inverse transformation"
is not a true inverse of the forward transformation, since applying
the forward transformation to a point outside the Region, and then
applying the inverse transformation results, in a set of AST__BAD axis
values rather than the original axis values. If required, the
astRemoveRegionsastRemoveRegions
function can be used to remove the "masking" effect of any Regions
contained within a compound Mapping or FrameSetFrameSet. It does this by
replacing each Region with a UnitMap or equivalent Frame (depending
on the context in which the Region is used).
If the coordinate system represented by the Region is changed (by changing the values of one or more of the attribute which the Region inherits from its encapsulated Frame), the area represented by the Region is mapped into the new coordinate system. For instance, let's say a Circle (a subclass of Region) is created, a SkyFrameSkyFrame being supplied to the constructor so that the Circle describes a circular area on the sky in FK4 equatorial coordinates. Since Region inherits from Frame, the Circle will have a SystemSystem attribute and this attribute will be set to "FK4". If the System attribute of the Region is then changed from FK4 to FK5, the circular area represented by the Region will automatically be mapped from the FK4 system into the FK5 system. In general, changing the coordinate system in this way may result in the region changing shape - for instance, a circle may change into an ellipse if the transformation from the old to the new coordinate system is linear but with different scales on each axis. Thus the specific class of a Region cannot be used as a guarantee of the shape in any particular coordinate system. If the astSimplifyastSimplify function is used on a Region, it will endeavour to return a new Region of a sub-class which accurately describes the shape in the current coordinate system of the Region (but this may not always be possible).
It is possible to negate an existing Region so that it represents all areas of the encapsulated Frame except for the area specified when the Region was created.