uk.ac.starlink.ast
Class CmpRegion

java.lang.Object
  extended by uk.ac.starlink.ast.AstObject
      extended by uk.ac.starlink.ast.Mapping
          extended by uk.ac.starlink.ast.Frame
              extended by uk.ac.starlink.ast.Region
                  extended by uk.ac.starlink.ast.CmpRegion

public class CmpRegion
extends Region

Java interface to the AST CmpRegion class - a combination of two regions within a single Frame. A CmpRegion is a Region which allows two component Regions (of any class) to be combined to form a more complex Region. This combination may be performed a boolean AND, OR or XOR (exclusive OR) operator. If the AND operator is used, then a position is inside the CmpRegion only if it is inside both of its two component Regions. If the OR operator is used, then a position is inside the CmpRegion if it is inside either (or both) of its two component Regions. If the XOR operator is used, then a position is inside the CmpRegion if it is inside one but not both of its two component Regions. Other operators can be formed by negating one or both component Regions before using them to construct a new CmpRegion.

The two component Region need not refer to the same coordinate Frame, but it must be possible for the astConvert function to determine a Mapping between them (an error will be reported otherwise when the CmpRegion is created). For instance, a CmpRegion may combine a Region defined within an ICRS SkyFrame with a Region defined within a Galactic SkyFrame. This is acceptable because the SkyFrame class knows how to convert between these two systems, and consequently the astConvert function will also be able to convert between them. In such cases, the second component Region will be mapped into the coordinate Frame of the first component Region, and the Frame represented by the CmpRegion as a whole will be the Frame of the first component Region.

Since a CmpRegion is itself a Region, it can be used as a component in forming further CmpRegions. Regions of arbitrary complexity may be built from simple individual Regions in this way.

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 CmpRegion

Nested Class Summary
 
Nested classes/interfaces inherited from class uk.ac.starlink.ast.Mapping
Mapping.Interpolator, Mapping.Spreader
 
Field Summary
static int AST__AND
          Constant indicating AND-type region combination.
static int AST__OR
          Constant indicating OR-type region combination.
 
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
CmpRegion(Region region1, Region region2, int oper)
          Create a CmpRegion.
 
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
 

Field Detail

AST__AND

public static final int AST__AND
Constant indicating AND-type region combination.


AST__OR

public static final int AST__OR
Constant indicating OR-type region combination.

Constructor Detail

CmpRegion

public CmpRegion(Region region1,
                 Region region2,
                 int oper)
Create a CmpRegion. This function creates a new CmpRegion and optionally initialises its attributes.

A CmpRegion is a Region which allows two component Regions (of any class) to be combined to form a more complex Region. This combination may be performed a boolean AND, OR or XOR (exclusive OR) operator. If the AND operator is used, then a position is inside the CmpRegion only if it is inside both of its two component Regions. If the OR operator is used, then a position is inside the CmpRegion if it is inside either (or both) of its two component Regions. If the XOR operator is used, then a position is inside the CmpRegion if it is inside one but not both of its two component Regions. Other operators can be formed by negating one or both component Regions before using them to construct a new CmpRegion.

The two component Region need not refer to the same coordinate Frame, but it must be possible for the astConvert function to determine a Mapping between them (an error will be reported otherwise when the CmpRegion is created). For instance, a CmpRegion may combine a Region defined within an ICRS SkyFrame with a Region defined within a Galactic SkyFrame. This is acceptable because the SkyFrame class knows how to convert between these two systems, and consequently the astConvert function will also be able to convert between them. In such cases, the second component Region will be mapped into the coordinate Frame of the first component Region, and the Frame represented by the CmpRegion as a whole will be the Frame of the first component Region.

Since a CmpRegion is itself a Region, it can be used as a component in forming further CmpRegions. Regions of arbitrary complexity may be built from simple individual Regions in this way.

Notes


- If one of the supplied Regions has an associated uncertainty, that uncertainty will also be used for the returned CmpRegion. If both supplied Regions have associated uncertainties, the uncertainty associated with the first Region will be used for the returned CmpRegion.
- Deep copies are taken of the supplied Regions. This means that any subsequent changes made to the component Regions using the supplied pointers will have no effect on the CmpRegion.
- 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:
region1 - Pointer to the first component Region.
region2 - Pointer to the second component Region. This Region will be transformed into the coordinate Frame of the first region before use. An error will be reported if this is not possible.
oper - The boolean operator with which to combine the two Regions. This must be one of the symbolic constants AST__AND, AST__OR or AST__XOR.
Throws:
AstException - if an error occurred in the AST library


Copyright © 2017 Central Laboratory of the Research Councils. All Rights Reserved.