public abstract class Region extends Frame
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 astFormat function 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 astTran<X> 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 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 astRemoveRegions 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 astSimplify 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.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Licence for more details.
You should have received a copy of the GNU General Public Licence along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street,Fifth Floor, Boston, MA 02110-1301, USA
Mapping.Interpolator, Mapping.Spreader
Modifier and Type | Field and Description |
---|---|
static int |
OVERLAP_INSIDE
This region is completely inside the other one.
|
static int |
OVERLAP_NEGATE
The other region is the exact negation of this one to within
their uncertainties.
|
static int |
OVERLAP_NONE
There is no overlap between this region and the other.
|
static int |
OVERLAP_OUTSIDE
The other region is completely inside this one.
|
static int |
OVERLAP_PARTIAL
There is partial overlap between this region and the other.
|
static int |
OVERLAP_SAME
The regions are identical to within their uncertainties.
|
static int |
OVERLAP_UNKNOWN
No overlap could be determined because the other region could not
be mapped into the coordinate system of this one.
|
LINEAR_INTERPOLATOR, LINEAR_SPREADER, NEAREST_INTERPOLATOR, NEAREST_SPREADER
AST__BAD, AST__TUNULL, pointer
Modifier and Type | Method and Description |
---|---|
boolean |
getAdaptive()
Get
should the area adapt to changes in the coordinate system.
|
boolean |
getBounded()
Get
is the Region bounded.
|
boolean |
getClosed()
Get
should the boundary be considered to be inside the region.
|
double |
getFillFactor()
Get
fraction of the Region which is of interest.
|
int |
getMeshSize()
Get
number of points used to represent the boundary of a Region.
|
boolean |
getNegated()
Get
region negation flag.
|
double[][] |
getRegionBounds()
Returns the bounding box of Region.
|
Frame |
getRegionFrame()
Obtain a pointer to the encapsulated Frame within a Region.
|
double[][] |
getRegionPoints()
Returns the positions that define the given Region.
|
Region |
getUnc(boolean def)
Obtain uncertainty information from a Region.
|
Region |
mapRegion(Mapping map,
Frame frame)
Transform a Region into a new Frame using a given Mapping.
|
int |
mask(Mapping map,
boolean inside,
int ndim,
int[] lbnd,
int[] ubnd,
Object in,
Number val)
Mask a region of a data grid.
|
int |
maskB(Mapping map,
boolean inside,
int ndim,
int[] lbnd,
int[] ubnd,
byte[] in,
byte val)
Masking method specific to byte data.
|
int |
maskD(Mapping map,
boolean inside,
int ndim,
int[] lbnd,
int[] ubnd,
double[] in,
double val)
Masking method specific to double data.
|
int |
maskF(Mapping map,
boolean inside,
int ndim,
int[] lbnd,
int[] ubnd,
float[] in,
float val)
Masking method specific to float data.
|
int |
maskI(Mapping map,
boolean inside,
int ndim,
int[] lbnd,
int[] ubnd,
int[] in,
int val)
Masking method specific to int data.
|
int |
maskL(Mapping map,
boolean inside,
int ndim,
int[] lbnd,
int[] ubnd,
long[] in,
long val)
Masking method specific to long data.
|
int |
maskS(Mapping map,
boolean inside,
int ndim,
int[] lbnd,
int[] ubnd,
short[] in,
short val)
Masking method specific to short data.
|
void |
negate()
Negate the area represented by a Region.
|
int |
overlap(Region other)
Test if two regions overlap each other.
|
void |
setAdaptive(boolean adaptive)
Set
should the area adapt to changes in the coordinate system.
|
void |
setClosed(boolean closed)
Set
should the boundary be considered to be inside the region.
|
void |
setFillFactor(double fillFactor)
Set
fraction of the Region which is of interest.
|
void |
setMeshSize(int meshSize)
Set
number of points used to represent the boundary of a Region.
|
void |
setNegated(boolean negated)
Set
region negation flag.
|
void |
setUnc(Region unc)
Store uncertainty information in a Region.
|
void |
showMesh(boolean format,
String ttl)
Display a mesh of points covering the surface of a Region.
|
angle, axAngle, axDistance, axOffset, convert, distance, findFrame, format, getActiveUnit, getAlignSystem, getBottom, getDigits, getDigits, getDirection, getDomain, getDut1, getEpoch, getFormat, getLabel, getMatchEnd, getMaxAxes, getMinAxes, getNaxes, getNormUnit, getObsLat, getObsLon, getPermute, getPreserveAxes, getSymbol, getSystem, getTitle, getTop, getUnit, intersect, norm, offset, offset2, permAxes, pickAxes, resolve, setActiveUnit, setAlignSystem, setBottom, setDigits, setDigits, setDirection, setDomain, setDut1, setEpoch, setEpoch, setFormat, setLabel, setMatchEnd, setMaxAxes, setMinAxes, setObsLat, setObsLon, setPermute, setPreserveAxes, setSymbol, setSystem, setTitle, setTop, setUnit, unformat
decompose, getInvert, getNin, getNout, getReport, getTranForward, getTranInverse, invert, linearApprox, mapBox, mapSplit, rate, rebin, rebinD, rebinF, rebinI, resample, resampleB, resampleD, resampleF, resampleI, resampleL, resampleS, setInvert, setReport, simplify, tran1, tran2, tranGrid, tranN, tranP
annul, clear, copy, delete, equals, finalize, getAstConstantI, getB, getC, getD, getF, getI, getID, getIdent, getL, getNobject, getObjSize, getRefCount, hashCode, isThreaded, reportVersions, sameObject, set, setB, setC, setD, setF, setI, setID, setIdent, setL, show, test, tune
public static final int OVERLAP_UNKNOWN
public static final int OVERLAP_NONE
public static final int OVERLAP_INSIDE
public static final int OVERLAP_OUTSIDE
public static final int OVERLAP_PARTIAL
public static final int OVERLAP_SAME
public static final int OVERLAP_NEGATE
public double[][] getRegionBounds()
AstException
- if an error occurred in the AST librarypublic Frame getRegionFrame()
AstException
- if an error occurred in the AST librarypublic double[][] getRegionPoints()
AstException
- if an error occurred in the AST librarypublic Region getUnc(boolean def)
def
- Controls what is returned if no uncertainty information has been
associated explicitly with the supplied Region. If
a non-zero value
is supplied, then the default uncertainty Region used internally
within AST is returned (see "Applicability" below). If
zero is supplied, then NULL
will be returned (without error).AstException
- if an error occurred in the AST librarypublic Region mapRegion(Mapping map, Frame frame)
map
- Pointer to a Mapping which transforms positions from the
coordinate system represented by the supplied Region to the
coordinate system specified by
"frame".
The supplied Mapping should define both forward and inverse
transformations, and these transformations should form a genuine
inverse pair. That is, transforming a position using the forward
transformation and then using the inverse transformation should
produce the original input position. Some Mapping classes (such
as PermMap, MathMap, SphMap) can result in Mappings for which this
is not true.frame
- Pointer to a Frame describing the coordinate system in which
the new Region is required.AstException
- if an error occurred in the AST librarypublic void negate()
AstException
- if an error occurred in the AST librarypublic int overlap(Region other)
other
- Other region for comparison with this oneAstException
- if an error occurred in the AST librarypublic int mask(Mapping map, boolean inside, int ndim, int[] lbnd, int[] ubnd, Object in, Number val)
You should use a masking function which matches the numerical type of the data you are processing by replacing <X> in the generic function name astMask<X> by an appropriate 1- or 2-character type code. For example, if you are masking data with type "float", you should use the function astMaskF (see the "Data Type Codes" section below for the codes appropriate to other numerical types).
map
- Pointer to a Mapping. The forward transformation should map
positions in the coordinate system of the supplied Region
into pixel coordinates as defined by the
"lbnd" and "ubnd" parameters. A NULL pointer
can be supplied if the coordinate system of the supplied Region
corresponds to pixel coordinates. This is equivalent to
supplying a UnitMap.
The number of inputs for this Mapping (as given by its Nin attribute) should match the number of axes in the supplied Region (as given by the Naxes attribute of the Region). The number of outputs for the Mapping (as given by its Nout attribute) should match the number of grid dimensions given by the value of "ndim" below.
inside
- A boolean value which indicates which pixel are to be masked. If
a non-zero value
is supplied, then all grid pixels with centres inside the supplied
Region are assigned the value given by
"val",
and all other pixels are left unchanged. If
zero
is supplied, then all grid pixels with centres not inside the supplied
Region are assigned the value given by
"val",
and all other pixels are left unchanged. Note, the Negated
attribute of the Region is used to determine which pixel are
inside the Region and which are outside. So the inside of a Region
which has not been negated is the same as the outside of the
corresponding negated Region.
For types of Region such as PointList which have zero volume, pixel centres will rarely fall exactly within the Region. For this reason, the inclusion criterion is changed for zero-volume Regions so that pixels are included (or excluded) if any part of the Region passes through the pixel. For a PointList, this means that pixels are included (or excluded) if they contain at least one of the points listed in the PointList.
ndim
- The number of dimensions in the input grid. This should be at
least one.lbnd
- Pointer to an array of integers, with "ndim" elements,
containing the coordinates of the centre of the first pixel
in the input grid along each dimension.ubnd
- Pointer to an array of integers, with "ndim" elements,
containing the coordinates of the centre of the last pixel in
the input grid along each dimension.
Note that "lbnd" and "ubnd" together define the shape and size of the input grid, its extent along a particular (j'th) dimension being ubnd[j]-lbnd[j]+1 (assuming the index "j" to be zero-based). They also define the input grid's coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre.
in
- Pointer to an array, with one element for each pixel in the
input grid, containing the data to be masked. The
numerical type of this array should match the 1- or
2-character type code appended to the function name (e.g. if
you are using astMaskF, the type of each array element
should be "float").
The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used).
On exit, the samples specified by "inside" are set to the value of "val". All other samples are left unchanged.
val
- specifies the value used to flag the masked data.
This should be an object of the wrapper class corresponding
to the array type of the in
array.AstException
- if an error occurred in the AST librarypublic int maskB(Mapping map, boolean inside, int ndim, int[] lbnd, int[] ubnd, byte[] in, byte val)
public int maskS(Mapping map, boolean inside, int ndim, int[] lbnd, int[] ubnd, short[] in, short val)
public int maskI(Mapping map, boolean inside, int ndim, int[] lbnd, int[] ubnd, int[] in, int val)
public int maskL(Mapping map, boolean inside, int ndim, int[] lbnd, int[] ubnd, long[] in, long val)
public int maskF(Mapping map, boolean inside, int ndim, int[] lbnd, int[] ubnd, float[] in, float val)
public int maskD(Mapping map, boolean inside, int ndim, int[] lbnd, int[] ubnd, double[] in, double val)
public void setUnc(Region unc)
The uncertainty is usually specified when the Region is created, but this function allows it to be changed at any time.
unc
- Pointer to the new uncertainty Region. This must be of a class for
which all instances are centro-symetric (e.g. Box, Circle, Ellipse,
etc.) or be a Prism containing centro-symetric component Regions.
A deep copy of the supplied Region will be taken, so subsequent
changes to the uncertainty Region using the supplied pointer will
have no effect on the Region
"this".AstException
- if an error occurred in the AST librarypublic void showMesh(boolean format, String ttl)
The table is preceeded by a given title string, and followed by a single line containing the word "ENDMESH".
format
- A boolean value indicating if the displayed axis values should
be formatted according to the Format attribute associated with
the Frame's axis. Otherwise, they are displayed as simple
floating point values.ttl
- A title to display before displaying the first position.AstException
- if an error occurred in the AST librarypublic boolean getAdaptive()
If Adaptive is non-zero (the default), then area represented by the Region adapts to the new coordinate system. That is, the numerical values which define the area represented by the Region are changed by mapping them from the old coordinate system into the new coordinate system. Thus the Region continues to represent the same physical area.
If Adaptive is zero, then area represented by the Region does not adapt to the new coordinate system. That is, the numerical values which define the area represented by the Region are left unchanged. Thus the physical area represented by the Region will usually change.
As an example, consider a Region describe a range of wavelength from 2000 Angstrom to 4000 Angstrom. If the Unit attribute for the Region is changed from Angstrom to "nm" (nanometre), what happens depends on the setting of Adaptive. If Adaptive is non-zero, the Mapping from the old to the new coordinate system is found. In this case it is a simple scaling by a factor of 0.1 (since 1 Angstrom is 0.1 nm). This Mapping is then used to modify the numerical values within the Region, changing 2000 to 200 and 4000 to 400. Thus the modified region represents 200 nm to 400 nm, the same physical space as the original 2000 Angstrom to 4000 Angstrom. However, if Adaptive had been zero, then the numerical values would not have been changed, resulting in the final Region representing 2000 nm to 4000 nm.
Setting Adaptive to zero can be necessary if you want correct inaccurate attribute settings in an existing Region. For instance, when creating a Region you may not know what Epoch value to use, so you would leave Epoch unset resulting in some default value being used. If at some later point in the application, the correct Epoch value is determined, you could assign the correct value to the Epoch attribute. However, you would first need to set Adaptive temporarily to zero, because otherwise the area represented by the Region would be Mapped from the spurious default Epoch to the new correct Epoch, which is not what is required.
public void setAdaptive(boolean adaptive)
If Adaptive is non-zero (the default), then area represented by the Region adapts to the new coordinate system. That is, the numerical values which define the area represented by the Region are changed by mapping them from the old coordinate system into the new coordinate system. Thus the Region continues to represent the same physical area.
If Adaptive is zero, then area represented by the Region does not adapt to the new coordinate system. That is, the numerical values which define the area represented by the Region are left unchanged. Thus the physical area represented by the Region will usually change.
As an example, consider a Region describe a range of wavelength from 2000 Angstrom to 4000 Angstrom. If the Unit attribute for the Region is changed from Angstrom to "nm" (nanometre), what happens depends on the setting of Adaptive. If Adaptive is non-zero, the Mapping from the old to the new coordinate system is found. In this case it is a simple scaling by a factor of 0.1 (since 1 Angstrom is 0.1 nm). This Mapping is then used to modify the numerical values within the Region, changing 2000 to 200 and 4000 to 400. Thus the modified region represents 200 nm to 400 nm, the same physical space as the original 2000 Angstrom to 4000 Angstrom. However, if Adaptive had been zero, then the numerical values would not have been changed, resulting in the final Region representing 2000 nm to 4000 nm.
Setting Adaptive to zero can be necessary if you want correct inaccurate attribute settings in an existing Region. For instance, when creating a Region you may not know what Epoch value to use, so you would leave Epoch unset resulting in some default value being used. If at some later point in the application, the correct Epoch value is determined, you could assign the correct value to the Epoch attribute. However, you would first need to set Adaptive temporarily to zero, because otherwise the area represented by the Region would be Mapped from the spurious default Epoch to the new correct Epoch, which is not what is required.
adaptive
- the Adaptive attribute of this objectpublic boolean getNegated()
Note, whether the boundary is considered to be inside the Region or not is controlled by the Closed attribute. Changing the value of the Negated attribute does not change the value of the Closed attribute. Thus, if Region is closed, then the boundary of the Region will be inside the Region, whatever the setting of the Negated attribute.
public void setNegated(boolean negated)
Note, whether the boundary is considered to be inside the Region or not is controlled by the Closed attribute. Changing the value of the Negated attribute does not change the value of the Closed attribute. Thus, if Region is closed, then the boundary of the Region will be inside the Region, whatever the setting of the Negated attribute.
negated
- the Negated attribute of this objectpublic boolean getClosed()
public void setClosed(boolean closed)
closed
- the Closed attribute of this objectpublic int getMeshSize()
public void setMeshSize(int meshSize)
meshSize
- the MeshSize attribute of this objectpublic double getFillFactor()
The supplied value must be in the range 0.0 to 1.0, and the default value is 1.0 (except as noted below).
public void setFillFactor(double fillFactor)
The supplied value must be in the range 0.0 to 1.0, and the default value is 1.0 (except as noted below).
fillFactor
- the FillFactor attribute of this objectpublic boolean getBounded()
Copyright © 2024 Central Laboratory of the Research Councils. All Rights Reserved.