uk.ac.starlink.ast

Class Box

java.lang.Object

uk.ac.starlink.ast.AstObject

uk.ac.starlink.ast.Mapping

uk.ac.starlink.ast.Frame

uk.ac.starlink.ast.Region

uk.ac.starlink.ast.Box

public class Box
extends Region

Java interface to the AST Box class - a box region with sides parallel to the axes of a Frame. The Box class implements a Region which represents a box with sides parallel to the axes of a Frame (i.e. an area which encloses a given range of values on each axis). A Box is similar to an Interval, the only real difference being that the Interval class allows some axis limits to be unspecified. Note, a Box will only look like a box if the Frame geometry is approximately flat. For instance, a Box centred close to a pole in a SkyFrame will look more like a fan than a box (the Polygon class can be used to create a box-like region close to a pole).

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 Box

Nested Class Summary

Nested classes/interfaces inherited from class uk.ac.starlink.ast.Mapping

Mapping.Interpolator, Mapping.Spreader

Field Summary

Fields inherited from class uk.ac.starlink.ast.Region

OVERLAP_INSIDE, OVERLAP_NEGATE, OVERLAP_NONE, OVERLAP_OUTSIDE, OVERLAP_PARTIAL, OVERLAP_SAME, OVERLAP_UNKNOWN

Fields inherited from class uk.ac.starlink.ast.Mapping

LINEAR_INTERPOLATOR, LINEAR_SPREADER, NEAREST_INTERPOLATOR, NEAREST_SPREADER

Fields inherited from class uk.ac.starlink.ast.AstObject

AST__BAD, AST__TUNULL, pointer

Constructor Summary

Constructors

Constructor and Description
Box(Frame frame, int form, double[] point1, double[] point2, Region unc) Create a Box.

Method Summary

Methods inherited from class uk.ac.starlink.ast.Region

getAdaptive, getBounded, getClosed, getFillFactor, getMeshSize, getNegated, getRegionBounds, getRegionFrame, getRegionPoints, getUnc, mapRegion, mask, maskB, maskD, maskF, maskI, maskL, maskS, negate, overlap, setAdaptive, setClosed, setFillFactor, setMeshSize, setNegated, setUnc, showMesh

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

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Box

public Box(Frame frame,
           int form,
           double[] point1,
           double[] point2,
           Region unc)

Create a Box. This function creates a new Box and optionally initialises its attributes.

The Box class implements a Region which represents a box with sides parallel to the axes of a Frame (i.e. an area which encloses a given range of values on each axis). A Box is similar to an Interval, the only real difference being that the Interval class allows some axis limits to be unspecified. Note, a Box will only look like a box if the Frame geometry is approximately flat. For instance, a Box centred close to a pole in a SkyFrame will look more like a fan than a box (the Polygon class can be used to create a box-like region close to a pole).

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.

Status Handling

The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: "int *status".

Parameters:

frame - A pointer to the Frame in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region.

form - Indicates how the box is described by the remaining parameters. A value of zero indicates that the box is specified by a centre position and a corner position. A value of one indicates that the box is specified by a two opposite corner positions.

point1 - An array of double, with one element for each Frame axis (Naxes attribute). If "form" is zero, this array should contain the coordinates at the centre of the box. If "form" is one, it should contain the coordinates at the corner of the box which is diagonally opposite the corner specified by "point2".

point2 - An array of double, with one element for each Frame axis (Naxes attribute) containing the coordinates at any corner of the box.

unc - An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Box being created. The uncertainty in any point on the boundary of the Box is found by shifting the supplied "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.

If supplied, the uncertainty Region 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 created Box. Alternatively, a NULL Object pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Box being created.

The uncertainty Region has two uses: 1) when the astOverlap function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using astSimplify), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region.

Throws:

AstException - if an error occurred in the AST library