uk.ac.starlink.ast
Class Region
java.lang.Object
uk.ac.starlink.ast.AstObject
uk.ac.starlink.ast.Mapping
uk.ac.starlink.ast.Frame
uk.ac.starlink.ast.Region
- Direct Known Subclasses:
- Box, Circle, CmpRegion, Ellipse, Interval, NullRegion, PointList, Polygon, Prism, Stc
public abstract class Region
- extends Frame
Java interface to the AST Region class
- represents a region within a coordinate system.
This class provides the basic facilities for describing a region within
a specified coordinate system. However, the Region class does not
have a constructor function of its own, as it is simply a container
class for a family of specialised sub-classes such as Circle, Box, etc,
which implement Regions with particular shapes.
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 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.
Licence
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public Licence as
published by the Free Software Foundation; either version 2 of
the Licence, or (at your option) any later version.
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
- See Also:
- AST Region
Field Summary |
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. |
Method Summary |
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. |
Methods inherited from class uk.ac.starlink.ast.Frame |
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 |
Methods inherited from class uk.ac.starlink.ast.Mapping |
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 |
Methods inherited from class uk.ac.starlink.ast.AstObject |
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 |
OVERLAP_UNKNOWN
public static final int OVERLAP_UNKNOWN
- No overlap could be determined because the other region could not
be mapped into the coordinate system of this one.
- See Also:
- Constant Field Values
OVERLAP_NONE
public static final int OVERLAP_NONE
- There is no overlap between this region and the other.
- See Also:
- Constant Field Values
OVERLAP_INSIDE
public static final int OVERLAP_INSIDE
- This region is completely inside the other one.
- See Also:
- Constant Field Values
OVERLAP_OUTSIDE
public static final int OVERLAP_OUTSIDE
- The other region is completely inside this one.
- See Also:
- Constant Field Values
OVERLAP_PARTIAL
public static final int OVERLAP_PARTIAL
- There is partial overlap between this region and the other.
- See Also:
- Constant Field Values
OVERLAP_SAME
public static final int OVERLAP_SAME
- The regions are identical to within their uncertainties.
- See Also:
- Constant Field Values
OVERLAP_NEGATE
public static final int OVERLAP_NEGATE
- The other region is the exact negation of this one to within
their uncertainties.
- See Also:
- Constant Field Values
getRegionBounds
public double[][] getRegionBounds()
- Returns the bounding box of Region.
This function
returns the upper and lower limits of a box which just encompasses
the supplied Region. The limits are returned as axis values within
the Frame represented by the Region. The value of the Negated
attribute is ignored (i.e. it is assumed that the Region has not
been negated).
Notes
The value of the Negated attribute is ignored (i.e. it is assumed that
he Region has not been negated).
If an axis has no extent on an axis then the lower limit will be
eturned larger than the upper limit. Note, this is different to an
xis which has a constant value (in which case both lower and upper
imit will be returned set to the constant value).
- Returns:
- A two-element array of naxes-element arrays giving
the bounds of a box which contains this region. The first
element is the lower bounds, and the second element is the
upper bounds. If there is no limit on a lower/upper bound
on a given axis, the corresponding value will be the
lowest negative/highest positive possible value.
- Throws:
AstException
- if an error occurred in the AST library
getRegionFrame
public Frame getRegionFrame()
- Obtain a pointer to the encapsulated Frame within a Region.
This function returns a pointer to the Frame represented by a
Region.
Notes
- A null Object pointer (AST__NULL) will be returned if this
function is invoked with the AST error status set, or if it
should fail for any reason.
- Returns:
- A pointer to a deep copy of the Frame represented by the Region.
Using this pointer to modify the Frame will have no effect on
the Region. To modify the Region, use the Region pointer directly.
- Throws:
AstException
- if an error occurred in the AST library
getRegionPoints
public double[][] getRegionPoints()
- Returns the positions that define the given Region.
This function
returns the axis values at the points that define the supplied
Region. The particular meaning of these points will depend on the
type of class supplied, as listed below under "Applicability:".
Notes
- If the coordinate system represented by the Region has been
changed since it was first created, the returned axis values refer
to the new (changed) coordinate system, rather than the original
coordinate system. Note however that if the transformation from
original to new coordinate system is non-linear, the shape within
the new coordinate system may be distorted, and so may not match
that implied by the name of the Region subclass (Circle, Box, etc).
- Returns:
- The address of the first element in a 2-dimensional array of
shape "[maxcoord][maxpoint]", in which to return
the coordinate values at the positions that define the Region.
These are stored such that the value of coordinate number
"coord" for point number "point" is found in element
"points[coord][point]".
- Throws:
AstException
- if an error occurred in the AST library
getUnc
public Region getUnc(boolean def)
- Obtain uncertainty information from a Region.
This function returns a Region which represents the uncertainty
associated with positions within the supplied Region. See
astSetUnc
for more information about Region uncertainties and their use.
Notes
- If uncertainty information is associated with a Region, and the
coordinate system described by the Region is subsequently changed
(e.g. by changing the value of its System attribute, or using the
astMapRegion
function), then the uncertainty information returned by this function
will be modified so that it refers to the coordinate system currently
described by the supplied Region.
- A null Object pointer (NULL) will be returned if this
function is invoked with the AST error status set, or if it
should fail for any reason.
- Parameters:
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).
- Returns:
- A pointer to a Region describing the uncertainty in the supplied
Region.
- Throws:
AstException
- if an error occurred in the AST library
mapRegion
public Region mapRegion(Mapping map,
Frame frame)
- Transform a Region into a new Frame using a given Mapping.
This function returns a pointer to a new Region which corresponds to
supplied Region described by some other specified coordinate system. A
Mapping is supplied which transforms positions between the old and new
coordinate systems. The new Region may not be of the same class as
the original region.
Notes
- The uncertainty associated with the supplied Region is modified
using the supplied Mapping.
- A null Object pointer (AST__NULL) will be returned if this
function is invoked with the AST error status set, or if it
should fail for any reason.
- Parameters:
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.
- Returns:
- A pointer to a new Region. This Region will represent the area
within the coordinate system specified by
"frame"
which corresponds to the supplied Region.
- Throws:
AstException
- if an error occurred in the AST library
negate
public void negate()
- Negate the area represented by a Region.
This function negates the area represented by a Region. That is,
points which were previously inside the region will then be
outside, and points which were outside will be inside. This is
acomplished by toggling the state of the Negated attribute for
the supplied region.
- Throws:
AstException
- if an error occurred in the AST library
overlap
public int overlap(Region other)
- Test if two regions overlap each other.
This function returns an integer value indicating if the two
supplied Regions overlap. The two Regions are converted to a commnon
coordinate system before performing the check. If this conversion is
not possible (for instance because the two Regions represent areas in
different domains), then the check cannot be performed and a zero value
is returned to indicate this.
Notes
- The returned values 5 and 6 do not check the value of the Closed
attribute in the two Regions.
- A value of zero will be returned if this function is invoked with the
AST error status set, or if it should fail for any reason.
- Parameters:
other
- Other region for comparison with this one
- Returns:
- value indicating overlap status - it will be one of the
OVERLAP_* static final integers defined in the Region class
- Throws:
AstException
- if an error occurred in the AST library
mask
public int mask(Mapping map,
boolean inside,
int ndim,
int[] lbnd,
int[] ubnd,
Object in,
Number val)
- Mask a region of a data grid.
This is a set of functions for masking out regions within gridded data
(e.g. an image). The functions modifies a given data grid by
assigning a specified value to all samples which are inside (or outside
if "inside" is zero)
the specified Region.
You should use a masking function which matches the numerical
type of the data you are processing by replacing in
the generic function name astMask 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).
Notes
- A value of zero will be returned if this function is invoked
with the global error status set, or if it should fail for any
reason.
- Parameters:
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.
- Returns:
- The number of pixels to which a value of
"badval"
has been assigned.
- Throws:
AstException
- if an error occurred in the AST library
maskB
public int maskB(Mapping map,
boolean inside,
int ndim,
int[] lbnd,
int[] ubnd,
byte[] in,
byte val)
- Masking method specific to byte data.
- See Also:
mask(uk.ac.starlink.ast.Mapping, boolean, int, int[], int[], java.lang.Object, java.lang.Number)
maskS
public int maskS(Mapping map,
boolean inside,
int ndim,
int[] lbnd,
int[] ubnd,
short[] in,
short val)
- Masking method specific to short data.
- See Also:
mask(uk.ac.starlink.ast.Mapping, boolean, int, int[], int[], java.lang.Object, java.lang.Number)
maskI
public int maskI(Mapping map,
boolean inside,
int ndim,
int[] lbnd,
int[] ubnd,
int[] in,
int val)
- Masking method specific to int data.
- See Also:
mask(uk.ac.starlink.ast.Mapping, boolean, int, int[], int[], java.lang.Object, java.lang.Number)
maskL
public int maskL(Mapping map,
boolean inside,
int ndim,
int[] lbnd,
int[] ubnd,
long[] in,
long val)
- Masking method specific to long data.
- See Also:
mask(uk.ac.starlink.ast.Mapping, boolean, int, int[], int[], java.lang.Object, java.lang.Number)
maskF
public int maskF(Mapping map,
boolean inside,
int ndim,
int[] lbnd,
int[] ubnd,
float[] in,
float val)
- Masking method specific to float data.
- See Also:
mask(uk.ac.starlink.ast.Mapping, boolean, int, int[], int[], java.lang.Object, java.lang.Number)
maskD
public int maskD(Mapping map,
boolean inside,
int ndim,
int[] lbnd,
int[] ubnd,
double[] in,
double val)
- Masking method specific to double data.
- See Also:
mask(uk.ac.starlink.ast.Mapping, boolean, int, int[], int[], java.lang.Object, java.lang.Number)
setUnc
public void setUnc(Region unc)
- Store uncertainty information in a Region.
Each Region (of any class) can have an "uncertainty" which specifies
the uncertainties associated with the boundary of the Region. This
information is supplied in the form of a second Region. The uncertainty
in any point on the boundary of a Region is found by shifting the
associated "uncertainty" Region so that it is centred at the boundary
point being considered. The area covered by the shifted uncertainty
Region then represents the uncertainty in the boundary position.
The uncertainty is assumed to be the same for all points.
The uncertainty is usually specified when the Region is created, but
this
function
allows it to be changed at any time.
- Parameters:
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".
- Throws:
AstException
- if an error occurred in the AST library
showMesh
public void showMesh(boolean format,
String ttl)
- Display a mesh of points covering the surface of a Region.
This function
writes a table to standard output containing the axis values at a
mesh of points covering the surface of the supplied Region. Each row
of output contains a tab-separated list of axis values, one for
each axis in the Frame encapsulated by the Region. The number of
points in the mesh is determined by the MeshSize attribute.
The table is preceeded by a given title string, and followed by a
single line containing the word "ENDMESH".
- Parameters:
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.
- Throws:
AstException
- if an error occurred in the AST library
getAdaptive
public boolean getAdaptive()
- Get
should the area adapt to changes in the coordinate system.
The coordinate system represented by a Region may be changed by
assigning new values to attributes such as System, Unit, etc.
For instance, a Region representing an area on the sky in ICRS
coordinates may have its System attribute changed so that it
represents (say) Galactic coordinates instead of ICRS. This
attribute controls what happens when the coordinate system
represented by a Region is changed in this way.
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.
- Returns:
- this object's Adaptive attribute
setAdaptive
public void setAdaptive(boolean adaptive)
- Set
should the area adapt to changes in the coordinate system.
The coordinate system represented by a Region may be changed by
assigning new values to attributes such as System, Unit, etc.
For instance, a Region representing an area on the sky in ICRS
coordinates may have its System attribute changed so that it
represents (say) Galactic coordinates instead of ICRS. This
attribute controls what happens when the coordinate system
represented by a Region is changed in this way.
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.
- Parameters:
adaptive
- the Adaptive attribute of this object
getNegated
public boolean getNegated()
- Get
region negation flag.
This attribute controls whether a Region represents the "inside" or
the "outside" of the area which was supplied when the Region was
created. If the attribute value is zero (the default), the Region
represents the inside of the original area. However, if it is non-zero,
it represents the outside of the original area. The value of this
attribute may be toggled using the
astNegate function.
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.
- Returns:
- this object's Negated attribute
setNegated
public void setNegated(boolean negated)
- Set
region negation flag.
This attribute controls whether a Region represents the "inside" or
the "outside" of the area which was supplied when the Region was
created. If the attribute value is zero (the default), the Region
represents the inside of the original area. However, if it is non-zero,
it represents the outside of the original area. The value of this
attribute may be toggled using the
astNegate function.
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.
- Parameters:
negated
- the Negated attribute of this object
getClosed
public boolean getClosed()
- Get
should the boundary be considered to be inside the region.
This attribute controls whether points on the boundary of a Region
are considered to be inside or outside the region. If the attribute
value is non-zero (the default), points on the boundary are considered
to be inside the region (that is, the Region is "closed"). However,
if the attribute value is zero, points on the bounary are considered
to be outside the region.
- Returns:
- this object's Closed attribute
setClosed
public void setClosed(boolean closed)
- Set
should the boundary be considered to be inside the region.
This attribute controls whether points on the boundary of a Region
are considered to be inside or outside the region. If the attribute
value is non-zero (the default), points on the boundary are considered
to be inside the region (that is, the Region is "closed"). However,
if the attribute value is zero, points on the bounary are considered
to be outside the region.
- Parameters:
closed
- the Closed attribute of this object
getMeshSize
public int getMeshSize()
- Get
number of points used to represent the boundary of a Region.
This attribute controls how many points are used when creating a
mesh of points covering the boundary or volume of a Region. Such a
mesh is returned by the
astGetRegionMesh
method. The boundary mesh is also used when testing for overlap
between two Regions: each point in the bomdary mesh of the first
Region is checked to see if it is inside or outside the second Region.
Thus, the reliability of the overlap check depends on the value assigned
to this attribute. If the value used is very low, it is possible for
overlaps to go unnoticed. High values produce more reliable results, but
can result in the overlap test being very slow. The default value is 200
for two dimensional Regions and 2000 for three or more dimensional
Regions (this attribute is not used for 1-dimensional regions since the
boundary of a simple 1-d Region can only ever have two points). A
value of five is used if the supplied value is less than five.
- Returns:
- this object's MeshSize attribute
setMeshSize
public void setMeshSize(int meshSize)
- Set
number of points used to represent the boundary of a Region.
This attribute controls how many points are used when creating a
mesh of points covering the boundary or volume of a Region. Such a
mesh is returned by the
astGetRegionMesh
method. The boundary mesh is also used when testing for overlap
between two Regions: each point in the bomdary mesh of the first
Region is checked to see if it is inside or outside the second Region.
Thus, the reliability of the overlap check depends on the value assigned
to this attribute. If the value used is very low, it is possible for
overlaps to go unnoticed. High values produce more reliable results, but
can result in the overlap test being very slow. The default value is 200
for two dimensional Regions and 2000 for three or more dimensional
Regions (this attribute is not used for 1-dimensional regions since the
boundary of a simple 1-d Region can only ever have two points). A
value of five is used if the supplied value is less than five.
- Parameters:
meshSize
- the MeshSize attribute of this object
getFillFactor
public double getFillFactor()
- Get
fraction of the Region which is of interest.
This attribute indicates the fraction of the Region which is of
interest. AST does not use this attribute internally for any purpose.
Typically, it could be used to indicate the fraction of the Region for
which data is available.
The supplied value must be in the range 0.0 to 1.0, and the default
value is 1.0 (except as noted below).
- Returns:
- this object's FillFactor attribute
setFillFactor
public void setFillFactor(double fillFactor)
- Set
fraction of the Region which is of interest.
This attribute indicates the fraction of the Region which is of
interest. AST does not use this attribute internally for any purpose.
Typically, it could be used to indicate the fraction of the Region for
which data is available.
The supplied value must be in the range 0.0 to 1.0, and the default
value is 1.0 (except as noted below).
- Parameters:
fillFactor
- the FillFactor attribute of this object
getBounded
public boolean getBounded()
- Get
is the Region bounded.
This is a read-only attribute indicating if the Region is bounded.
A Region is bounded if it is contained entirely within some
finite-size bounding box.
- Returns:
- this object's Bounded attribute
Copyright © 2015 Central Laboratory of the Research Councils. All Rights Reserved.