uk.ac.starlink.ast

Class FrameSet

java.lang.Object

uk.ac.starlink.ast.AstObject

uk.ac.starlink.ast.Mapping

uk.ac.starlink.ast.Frame

uk.ac.starlink.ast.FrameSet

Direct Known Subclasses:

Plot

public class FrameSet
extends Frame

Java interface to the AST FrameSet class - set of inter-related coordinate systems. A FrameSet consists of a set of one or more Frames (which describe coordinate systems), connected together by Mappings (which describe how the coordinate systems are inter-related). A FrameSet makes it possible to obtain a Mapping between any pair of these Frames (i.e. to convert between any of the coordinate systems which it describes). The individual Frames are identified within the FrameSet by an integer index, with Frames being numbered consecutively from one as they are added to the FrameSet.

Every FrameSet has a "base" Frame and a "current" Frame (which are allowed to be the same). Any of the Frames may be nominated to hold these positions, and the choice is determined by the values of the FrameSet's Base and Current attributes, which hold the indices of the relevant Frames. By default, the first Frame added to a FrameSet is its base Frame, and the last one added is its current Frame.

The base Frame describes the "native" coordinate system of whatever the FrameSet is used to calibrate (e.g. the pixel coordinates of an image) and the current Frame describes the "apparent" coordinate system in which it should be viewed (e.g. displayed, etc.). Any further Frames represent a library of alternative coordinate systems, which may be selected by making them current.

When a FrameSet is used in a context that requires a Frame, (e.g. obtaining its Title value, or number of axes), the current Frame is used. A FrameSet may therefore be used in place of its current Frame in most situations.

When a FrameSet is used in a context that requires a Mapping, the Mapping used is the one between its base Frame and its current Frame. Thus, a FrameSet may be used to convert "native" coordinates into "apparent" ones, and vice versa. Like any Mapping, a FrameSet may also be inverted (see astInvert), which has the effect of interchanging its base and current Frames and hence of reversing the Mapping between them.

Regions may be added into a FrameSet (since a Region is a type of Frame), either explicitly or as components within CmpFrames. In this case the Mapping between a pair of Frames within a FrameSet will include the effects of the clipping produced by any Regions included in the path between the Frames.

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 FrameSet

Nested Class Summary

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

Mapping.Interpolator, Mapping.Spreader

Field Summary

Fields

Modifier and Type	Field and Description
static int	AST__BASE Frame index of Base coordinate frame of FrameSet.
static int	AST__CURRENT Frame index of Current coordinate frame of FrameSet.
static int	AST__NOFRAME Frame index which applies to no frame in the FrameSet.

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

Modifier	Constructor and Description
protected	FrameSet() Dummy constructor.
	FrameSet(Frame frame) Creates a FrameSet.

Method Summary

Modifier and Type	Method and Description
void	addFrame(int iframe, Mapping map, Frame frame) Add a Frame to a FrameSet to define a new coordinate system.
int	getBase() Get frameSet base Frame index.
int	getCurrent() Get frameSet current Frame index.
Frame	getFrame(int iframe) Obtain a pointer to a specified Frame in a FrameSet.
Mapping	getMapping(int iframe1, int iframe2) Obtain a Mapping that converts between two Frames in a FrameSet.
int	getNframe() Get number of Frames in a FrameSet.
void	remapFrame(int iframe, Mapping map) Modify a Frame's relationship to other Frames in a FrameSet.
void	removeFrame(int iframe) Remove a Frame from a FrameSet.
void	setBase(int base) Set frameSet base Frame index.
void	setCurrent(int current) Set frameSet current Frame index.

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__BASE

public static final int AST__BASE

Frame index of Base coordinate frame of FrameSet.

AST__CURRENT

public static final int AST__CURRENT

Frame index of Current coordinate frame of FrameSet.

AST__NOFRAME

public static final int AST__NOFRAME

Frame index which applies to no frame in the FrameSet.

Constructor Detail

FrameSet

public FrameSet(Frame frame)

Creates a FrameSet.

Parameters:

frame - Pointer to the first Frame to be inserted into the FrameSet. This initially becomes both the base and the current Frame. (Further Frames may be added using the astAddFrame function.)

Throws:

AstException - if an error occurred in the AST library

FrameSet

protected FrameSet()

Dummy constructor. This constructor does not create a valid FrameSet object, but is required for inheritance by FrameSet's subclasses.

Method Detail

addFrame

public void addFrame(int iframe,
                     Mapping map,
                     Frame frame)

Add a Frame to a FrameSet to define a new coordinate system. This function adds a new Frame and an associated Mapping to a FrameSet so as to define a new coordinate system, derived from one which already exists within the FrameSet. The new Frame then becomes the FrameSet's current Frame.

This function may also be used to merge two FrameSets, or to append extra axes to every Frame in a FrameSet.

Notes

- A value of AST__BASE or AST__CURRENT may be given for the "iframe" parameter to specify the base Frame or the current Frame respectively.
- This function sets the value of the Current attribute for the FrameSet so that the new Frame subsequently becomes the current Frame.
- The number of input coordinate values accepted by the supplied Mapping (its Nin attribute) must match the number of axes in the Frame identified by the "iframe" parameter. Similarly, the number of output coordinate values generated by this Mapping (its Nout attribute) must match the number of axes in the new Frame.
- As a special case, if a pointer to a FrameSet is given for the "frame" parameter, this is treated as a request to merge a pair of FrameSets. This is done by appending all the new Frames (in the "frame" FrameSet) to the original FrameSet, while preserving their order and retaining all the inter-relationships (i.e. Mappings) between them. The two sets of Frames are inter-related within the merged FrameSet by using the Mapping supplied. This should convert between the Frame identified by the "iframe" parameter (in the original FrameSet) and the current Frame of the "frame" FrameSet. This latter Frame becomes the current Frame in the merged FrameSet.
- As another special case, if a value of AST__ALLFRAMES is supplied for parameter "iframe", then the supplied Mapping is ignored, and the axes defined by the supplied Frame are appended to each Frame in the FrameSet. In detail, each Frame in the FrameSet is replaced by a CmpFrame containing the original Frame and the Frame specified by parameter "frame". In addition, each Mapping in the FrameSet is replaced by a CmpMap containing the original Mapping and a UnitMap in parallel. The Nin and Nout attributes of the UnitMap are set equal to the number of axes in the supplied Frame. Each new CmpMap is simplified using astSimplify before being stored in the FrameSet.

Parameters:

iframe - The index of the Frame within the FrameSet which describes the coordinate system upon which the new one is to be based. This value should lie in the range from 1 to the number of Frames already in the FrameSet (as given by its Nframe attribute). As a special case, AST__ALLFRAMES may be supplied, in which case the axes defined by the supplied Frame are appended to every Frame in the FrameSet (see the Notes section for details).

map - Pointer to a Mapping which describes how to convert coordinates from the old coordinate system (described by the Frame with index "iframe") into coordinates in the new system. The Mapping's forward transformation should perform this conversion, and its inverse transformation should convert in the opposite direction. The supplied Mapping is ignored if parameter "iframe"is equal to AST__ALLFRAMES.

frame - Pointer to a Frame that describes the new coordinate system. Any class of Frame may be supplied (including Regions and FrameSets).

This function may also be used to merge two FrameSets by supplying a pointer to a second FrameSet for this parameter (see the Notes section for details).

Throws:

AstException - if an error occurred in the AST library

getFrame

public Frame getFrame(int iframe)

Obtain a pointer to a specified Frame in a FrameSet. This function returns a pointer to a specified Frame in a FrameSet.

Notes

- A value of AST__BASE or AST__CURRENT may be given for the "iframe" parameter to specify the base Frame or the current Frame respectively.
- This function increments the RefCount attribute of the selected Frame by one.
- 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:

iframe - The index of the required Frame within the FrameSet. This value should lie in the range from 1 to the number of Frames in the FrameSet (as given by its Nframe attribute).

Returns:

A pointer to the requested Frame.

Throws:

AstException - if an error occurred in the AST library

getMapping

public Mapping getMapping(int iframe1,
                          int iframe2)

Obtain a Mapping that converts between two Frames in a FrameSet. This function returns a pointer to a Mapping that will convert coordinates between the coordinate systems represented by two Frames in a FrameSet.

Notes

- The returned Mapping will include the clipping effect of any Regions which occur on the path between the two supplied Frames (this includes the two supplied Frames themselves).
- The values given for the "iframe1" and "iframe2" parameters should lie in the range from 1 to the number of Frames in the FrameSet (as given by its Nframe attribute). A value of AST__BASE or AST__CURRENT may also be given to identify the FrameSet's base Frame or current Frame respectively. It is permissible for both these parameters to have the same value, in which case a unit Mapping (UnitMap) is returned.
- It should always be possible to generate the Mapping requested, but this does necessarily guarantee that it will be able to perform the required coordinate conversion. If necessary, the TranForward and TranInverse attributes of the returned Mapping should be inspected to determine if the required transformation is available.
- 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:

iframe1 - The index of the first Frame in the FrameSet. This Frame describes the coordinate system for the "input" end of the Mapping.

iframe2 - The index of the second Frame in the FrameSet. This Frame describes the coordinate system for the "output" end of the Mapping.

Returns:

Pointer to a Mapping whose forward transformation converts coordinates from the first coordinate system to the second one, and whose inverse transformation converts coordinates in the opposite direction.

Throws:

AstException - if an error occurred in the AST library

remapFrame

public void remapFrame(int iframe,
                       Mapping map)

Modify a Frame's relationship to other Frames in a FrameSet. This function modifies the relationship (i.e. Mapping) between a specified Frame in a FrameSet and the other Frames in that FrameSet.

Typically, this might be required if the FrameSet has been used to calibrate (say) an image, and that image is re-binned. The Frame describing the image will then have undergone a coordinate transformation, and this should be communicated to the associated FrameSet using this function.

Notes

- A value of AST__BASE or AST__CURRENT may be given for the "iframe" parameter to specify the base Frame or the current Frame respectively.
- The relationship between the selected Frame and any other Frame within the FrameSet will be modified by this function, but the relationship between all other Frames in the FrameSet remains unchanged.
- The number of input coordinate values accepted by the Mapping (its Nin attribute) and the number of output coordinate values generated (its Nout attribute) must be equal and must match the number of axes in the Frame being modified.
- If a simple change of axis order is required, then the astPermAxes function may provide a more straightforward method of making the required changes to the FrameSet.
- This function cannot be used to change the number of Frame axes. To achieve this, a new Frame must be added to the FrameSet (astAddFrame) and the original one removed if necessary (astRemoveFrame).

Parameters:

iframe - The index within the FrameSet of the Frame to be modified. This value should lie in the range from 1 to the number of Frames in the FrameSet (as given by its Nframe attribute).

map - Pointer to a Mapping whose forward transformation converts coordinate values from the original coordinate system described by the Frame to the new one, and whose inverse transformation converts in the opposite direction.

Throws:

AstException - if an error occurred in the AST library

removeFrame

public void removeFrame(int iframe)

Remove a Frame from a FrameSet. This function removes a Frame from a FrameSet. All other Frames in the FrameSet have their indices re-numbered from one (if necessary), but are otherwise unchanged.

Notes

- Removing a Frame from a FrameSet does not affect the relationship between other Frames in the FrameSet, even if they originally depended on the Frame being removed.
- The number of Frames in a FrameSet cannot be reduced to zero. An error will result if an attempt is made to remove the only remaining Frame.
- A value of AST__BASE or AST__CURRENT may be given for the "iframe" parameter to specify the base Frame or the current Frame respectively.
- If a FrameSet's base or current Frame is removed, the Base or Current attribute (respectively) of the FrameSet will have its value cleared, so that another Frame will then assume its role by default.
- If any other Frame is removed, the base and current Frames will remain the same. To ensure this, the Base and/or Current attributes of the FrameSet will be changed, if necessary, to reflect any change in the indices of these Frames.

Parameters:

iframe - The index within the FrameSet of the Frame to be removed. This value should lie in the range from 1 to the number of Frames in the FrameSet (as given by its Nframe attribute).

Throws:

AstException - if an error occurred in the AST library

getBase

public int getBase()

Get frameSet base Frame index. This attribute gives the index of the Frame which is to be regarded as the "base" Frame within a FrameSet. The default is the first Frame added to the FrameSet when it is created (this Frame always has an index of 1).

Notes

- Inverting a FrameSet (inverting the boolean sense of its Invert attribute, with the astInvert function for example) will interchange the values of its Base and Current attributes.

Returns:

this object's Base attribute

setBase

public void setBase(int base)

Set frameSet base Frame index. This attribute gives the index of the Frame which is to be regarded as the "base" Frame within a FrameSet. The default is the first Frame added to the FrameSet when it is created (this Frame always has an index of 1).

Notes

- Inverting a FrameSet (inverting the boolean sense of its Invert attribute, with the astInvert function for example) will interchange the values of its Base and Current attributes.

Parameters:

base - the Base attribute of this object

getCurrent

public int getCurrent()

Get frameSet current Frame index. This attribute gives the index of the Frame which is to be regarded as the "current" Frame within a FrameSet. The default is the most recent Frame added to the FrameSet (this Frame always has an index equal to the FrameSet's Nframe attribute).

Notes

- Inverting a FrameSet (inverting the boolean sense of its Invert attribute, with the astInvert function for example) will interchange the values of its Base and Current attributes.

Returns:

this object's Current attribute

setCurrent

public void setCurrent(int current)

Set frameSet current Frame index. This attribute gives the index of the Frame which is to be regarded as the "current" Frame within a FrameSet. The default is the most recent Frame added to the FrameSet (this Frame always has an index equal to the FrameSet's Nframe attribute).

Notes

- Inverting a FrameSet (inverting the boolean sense of its Invert attribute, with the astInvert function for example) will interchange the values of its Base and Current attributes.

Parameters:

current - the Current attribute of this object

getNframe

public int getNframe()

Get number of Frames in a FrameSet. This attrbute gives the number of Frames in a FrameSet. This value will change as Frames are added or removed, but will always be at least one.

Returns:

this object's Nframe attribute