Represents a region within a coordinate system
All sub-classes of Region require a Frame 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 AST_FORMAT routine may be used on a Region to format an axis value.
In addition, since Frame inherits from Mapping, a Region is also a sort
of Mapping. Transforming positions by supplying a Region to one of the
AST_TRAN<X>
routines is the way to determine if a given position is inside or outside the Region (but see also the
convenience function AST_POINTINREGION). When used as a Mapping, most classes of Frame are
equivalent to a UnitMap. 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 AST_REMOVEREGIONS function can be used to remove the "
masking"
effect of any
Regions contained within a compound Mapping or FrameSet. 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 SkyFrame 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
System 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 AST_SIMPLIFY routine 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.
Adaptive: Should the area adapt to changes in the coordinate system?
Negated: Has the original region been negated?
Closed: Should the boundary be considered to be inside the region?
MeshSize: Number of points used to create a mesh covering the Region
FillFactor: Fraction of the Region which is of interest
Bounded: Is the Region bounded?
Every Region also inherits any further attributes that belong to the encapsulated Frame, regardless of
that Frame’
s class. (For example, the Equinox attribute, defined by the SkyFrame class,
is inherited by any Region which represents a SkyFrame.)
AST_GETREGIONBOUNDS: Get the bounds of a box containing a Region
AST_GETREGIONFRAME: Get a copy of the Frame represent by a Region
AST_GETREGIONFRAMESET: Get a copy of the Frameset encapsulated by a Region
AST_GETREGIONMESH: Get a mesh of points covering a Region
AST_GETREGIONPOINTS: Get the positions that define a Region
AST_GETREGIONDISC: Get the bounds of disc containing a Region
AST_GETUNC: Obtain uncertainty information from a Region
AST_MAPREGION: Transform a Region into a new coordinate system
AST_NEGATE: Toggle the value of the Negated attribute
AST_OVERLAP: Determines the nature of the overlap between two Regions
AST_POINTINREGION: Test if a single point is inside a Region
AST_MASK<X>: Mask a region of a data grid
AST_SETUNC: Associate a new uncertainty with a Region
AST_SHOWMESH: Display a mesh of points on the surface of a Region