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). More...

#include <FrameSet.h>

Inheritance diagram for ast::FrameSet:

Public Member Functions
	FrameSet (Frame const &frame, std::string const &options="")
	Construct a FrameSet from a Frame.
	FrameSet (Frame const &baseFrame, Mapping const &mapping, Frame const &currentFrame, std::string const &options="")
	Construct a FrameSet from two frames and a mapping that connects them.
virtual	~FrameSet ()
	FrameSet (FrameSet const &)=default
	Copy constructor: make a deep copy.
	FrameSet (FrameSet &&)=default
FrameSet &	operator= (FrameSet const &)=delete
FrameSet &	operator= (FrameSet &&)=default
std::shared_ptr< FrameSet >	copy () const
	Return a deep copy of this object.
void	addAxes (Frame const &frame)
	Append the axes from a specified Frame to every existing Frame in this FrameSet.
virtual void	addFrame (int iframe, Mapping const &map, Frame const &frame)
	Add a new Frame and an associated Mapping to this FrameSet so as to define a new coordinate system, derived from one which already exists within this FrameSet.
void	addVariant (Mapping const &map, std::string const &name)
	Store a new variant Mapping with the current Frame.
std::string	getAllVariants () const
	Get AllVariants: a list of all variant mappings stored with the current Frame.
int	getBase () const
	Get Base: index of base Frame.
int	getCurrent () const
	Get Current: index of current Frame, starting from 1.
std::shared_ptr< Frame >	getFrame (int iframe, bool copy=true) const
	Obtain a deep copy of the specified Frame.
std::shared_ptr< Mapping >	getMapping (int from=BASE, int to=CURRENT) const
	Obtain a Mapping that converts between two Frames in a FrameSet.
int	getNFrame () const
	Get FrameSet_NFrame "NFrame": number of Frames in the FrameSet, starting from 1.
std::string	getVariant () const
	Variant: name of variant mapping in use by current Frame
void	mirrorVariants (int iframe)
	Indicates that all access to the Variant attribute of the current Frame should should be forwarded to some other nominated Frame in the FrameSet.
void	remapFrame (int iframe, Mapping &map)
	Modify the relationship (i.e.
virtual void	removeFrame (int iframe)
	Remove a Frame from a FrameSet.
void	renameVariant (std::string const &name)
	Rename the current Variant of the current Mapping.
void	setBase (int ind)
	Set Base: index of base Frame.
void	setCurrent (int ind)
	Set Current: index of current Frame, starting from 1.

Static Public Attributes
static int constexpr	BASE = AST__BASE
	index of base frame
static int constexpr	CURRENT = AST__CURRENT
	index of current frame
static int constexpr	NOFRAME = AST__NOFRAME
	an invalid frame index

Protected Member Functions
virtual std::shared_ptr< Object >	copyPolymorphic () const override
	FrameSet (AstFrameSet *rawPtr)
	Construct a FrameSet from a raw AST pointer.

Friends
class	Frame
class	Object

Detailed Description

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 Mapping::inverted), which has the effect of returning a copy with base and current Frames swapped, 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.

Attributes

In addition to those attributes common to Frame Mapping and Object, FrameSet also has the following attributes:

AllVariants: a list of all variant mappings stored with the current Frame
Base: index of base Frame, starting from 1
Current: index of current Frame, starting from 1
NFrame: Number of Frames in a FrameSet
Variant: name of variant mapping in use by current Frame

Every FrameSet also inherits any further attributes that belong to its current Frame, regardless of that Frame's class. (For example, the Equinox attribute, defined by SkyFrame, is inherited by any FrameSet which has a SkyFrame as its current Frame.) The set of attributes belonging to a FrameSet may therefore change when a new current Frame is selected.

Definition at line 99 of file FrameSet.h.

Constructor & Destructor Documentation

◆ FrameSet() [1/5]

ast::FrameSet::FrameSet	(	Frame const &	frame,
		std::string const &	options = "" )

inlineexplicit

Construct a FrameSet from a Frame.

The frame is deep copied.

Parameters

[in]	frame	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 addFrame
[in]	options	Comma-separated list of attribute assignments.

Definition at line 117 of file FrameSet.h.

◆ FrameSet() [2/5]

ast::FrameSet::FrameSet	(	Frame const &	baseFrame,
		Mapping const &	mapping,
		Frame const &	currentFrame,
		std::string const &	options = "" )

inlineexplicit

Construct a FrameSet from two frames and a mapping that connects them.

Both frames and the mapping are deep copied.

Parameters

[in]	baseFrame	base Frame.
[in]	mapping	mapping connecting baseFrame to currentFrame.
[in]	currentFrame	current Frame.
[in]	options	Comma-separated list of attribute assignments.

Definition at line 132 of file FrameSet.h.

◆ ~FrameSet()

virtual ast::FrameSet::~FrameSet ( )

inlinevirtual

Definition at line 138 of file FrameSet.h.

◆ FrameSet() [3/5]

ast::FrameSet::FrameSet ( FrameSet const & )

default

Copy constructor: make a deep copy.

◆ FrameSet() [4/5]

ast::FrameSet::FrameSet ( FrameSet && )

default

◆ FrameSet() [5/5]

ast::FrameSet::FrameSet ( AstFrameSet * rawPtr )

inlineexplicitprotected

Construct a FrameSet from a raw AST pointer.

This method is public so Frame can call it.

Exceptions

std::invalid_argument if rawPtr is not an AstFrameSet.

Definition at line 490 of file FrameSet.h.

Member Function Documentation

◆ addAxes()

void ast::FrameSet::addAxes ( Frame const & frame )

inline

Append the axes from a specified Frame to every existing Frame in this FrameSet.

In detail, each Frame in this 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 before being stored in the FrameSet.

Parameters

[in] frame Frame whose axes are to be appended to each Frame in this FrameSet.

Definition at line 160 of file FrameSet.h.

◆ addFrame()

virtual void ast::FrameSet::addFrame	(	int	iframe,
		Mapping const &	map,
		Frame const &	frame )

inlinevirtual

Add a new Frame and an associated Mapping to this FrameSet so as to define a new coordinate system, derived from one which already exists within this FrameSet.

If frame is a Frame then it becomes the current frame and its index is the new number of frames. If frame is a FrameSet then its current frame becomes the new current frame and the indices of all its frames are increased by the number of frames originally in this FrameSet. In both cases the indices of the Frames already in this FrameSet are left unchanged.

Parameters

[in]	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 this FrameSet (as given by getNFrame). A value of FrameSet::BASE or FrameSet::CURRENT may be given to specify the base Frame or the current Frame respectively. A value of AST__ALLFRAMES is not permitted; call addAllFrames instead.
[in]	map	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.
[in]	frame	A Frame that describes the new coordinate system. Any type 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).

Notes

Deep copies of the supplied map and frame are stored within the modified FrameSet. So any changes made to the FrameSet after calling this method will have no effect on the supplied Mapping and Frame objects.
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 map (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 map (its NOut attribute) must match the number of axes in 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 frame into this FrameSet. This is done by appending all the new Frames in the frame FrameSet to this 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 this FrameSet) and the current Frame of the frame FrameSet. This latter Frame becomes the current Frame in this FrameSet.

Reimplemented in ast::FrameDict.

Definition at line 210 of file FrameSet.h.

◆ addVariant()

void ast::FrameSet::addVariant	(	Mapping const &	map,
		std::string const &	name )

inline

Store a new variant Mapping with the current Frame.

The newly added variant becomes the current variant (attribute the Variant is set to name).

See the Variant attribute for more details. See also getVariant, renameVariant and mirrorVariants

Parameters

[in]	map	A Mapping which describes how to convert coordinates from the current frame to the new variant of the current Frame.
[in]	name	The name to associate with the new variant Mapping.

Exceptions

std::runtime_error

if:

A variant with the supplied name already exists in the current Frame.
The current Frame is a mirror for the variant Mappings in another Frame. This is only the case if the astMirrorVariants function has been called to make the current Frame act as a mirror.

Definition at line 234 of file FrameSet.h.

◆ copy()

std::shared_ptr< FrameSet > ast::FrameSet::copy ( ) const

inline

Return a deep copy of this object.

Definition at line 147 of file FrameSet.h.

◆ copyPolymorphic()

virtual std::shared_ptr< Object > ast::FrameSet::copyPolymorphic ( ) const

inlineoverrideprotectedvirtual

Reimplemented in ast::FrameDict.

Definition at line 479 of file FrameSet.h.

◆ getAllVariants()

std::string ast::FrameSet::getAllVariants ( ) const

inline

Get AllVariants: a list of all variant mappings stored with the current Frame.

Definition at line 243 of file FrameSet.h.

◆ getBase()

int ast::FrameSet::getBase ( ) const

inline

Get Base: index of base Frame.

Definition at line 248 of file FrameSet.h.

◆ getCurrent()

int ast::FrameSet::getCurrent ( ) const

inline

Get Current: index of current Frame, starting from 1.

Definition at line 253 of file FrameSet.h.

◆ getFrame()

std::shared_ptr< Frame > ast::FrameSet::getFrame	(	int	iframe,
		bool	copy = true ) const

inline

Obtain a deep copy of the specified Frame.

Parameters

[in]	iframe	The index of the required Frame within this FrameSet. This value should lie in the range 1 to the number of frames already in this FrameSet (as given by getNFrame). A value of FrameSet::Base or FrameSet::CURRENT may be given to specify the base Frame or the current Frame, respectively.
[in]	copy	If true return a deep copy, else a shallow copy.

Warning: : to permute axes of a frame in a FrameSet, such that the connecting mappings are updated: set the current frame to the frame in question and call permAxes directly on the FrameSet. Do not call permAxes on a shallow copy of the frame (retrieved by getFrame) as this will not affect the connected mappings.

Definition at line 270 of file FrameSet.h.

◆ getMapping()

std::shared_ptr< Mapping > ast::FrameSet::getMapping	(	int	from = BASE,
		int	to = CURRENT ) const

inline

Obtain a Mapping that converts between two Frames in a FrameSet.

Parameters

[in]	from	The index of the first Frame in the FrameSet, the frame describing the coordinate system for the "input" end of the Mapping. This value should lie in the range 1 to the number of frames already in this FrameSet (as given by getNFrame).
[in]	to	The index of the second Frame in the FrameSet, the frame describing the coordinate system for the "output" end of the Mapping. This value should lie in the range 1 to the number of frames already in this FrameSet (as given by getNFrame).

Returns: A Mapping whose forward transformation converts coordinates from the first frame to the second one, and whose inverse transformation converts coordinates in the opposite direction.

Notes

The returned Mapping will include the clipping effect of any Regions which occur on the path between the two supplied Frames, including the specified end frames.
It should always be possible to generate the Mapping requested, but this does not necessarily guarantee that it will be able to perform the required coordinate conversion. If necessary, call hasForward or hasInverse on the returned Mapping to determine if the required transformation is available.

Definition at line 304 of file FrameSet.h.

◆ getNFrame()

int ast::FrameSet::getNFrame ( ) const

inline

Get FrameSet_NFrame "NFrame": number of Frames in the FrameSet, starting from 1.

Definition at line 316 of file FrameSet.h.

◆ getVariant()

std::string ast::FrameSet::getVariant ( ) const

inline

Variant: name of variant mapping in use by current Frame

See also addVariant, mirrorVariants and renameVariant

Definition at line 323 of file FrameSet.h.

◆ mirrorVariants()

void ast::FrameSet::mirrorVariants ( int iframe )

inline

Indicates that all access to the Variant attribute of the current Frame should should be forwarded to some other nominated Frame in the FrameSet.

For instance, if a value is set subsequently for the Variant attribute of the current Frame, the current Frame will be left unchanged and the setting is instead applied to the nominated Frame. Likewise, if the value of the Variant attribute is requested, the value returned is the value stored for the nominated Frame rather than the current Frame itself.

This provides a mechanism for propagating the effects of variant Mappings around a FrameSet. If a new Frame is added to a FrameSet by connecting it to an pre-existing Frame that has two or more variant Mappings, then it may be appropriate to set the new Frame so that it mirrors the variants Mappings of the pre-existing Frame. If this is done, then it will be possible to select a specific variant Mapping using either the pre-existing Frame or the new Frame.

See also addVariant, getVariant and renameVariant.

Parameters

[in] iframe The index of the Frame within the FrameSet which is to be mirrored by the current Frame. This value should lie in the range from 1 to the number of Frames in the FrameSet (as given by getNFrame). If AST__NOFRAME is supplied (or the current Frame is specified), then any mirroring established by a previous call to this function is disabled. A value of FrameSet::BASE may be given to specify the base frame.

Notes:

Mirrors can be chained. That is, if Frame B is set to be a mirror of Frame A, and Frame C is set to be a mirror of Frame B, then Frame C will act as a mirror of Frame A.
Variant Mappings cannot be added to the current Frame if it is mirroring another Frame. So calls to addVariant will cause an error to be reported if the current Frame is mirroring another Frame.
Any variant Mappings explicitly added to the current Frame using addVariant will be ignored if the current Frame is mirroring another Frame.

Definition at line 367 of file FrameSet.h.

◆ operator=() [1/2]

FrameSet & ast::FrameSet::operator= ( FrameSet && )

default

◆ operator=() [2/2]

FrameSet & ast::FrameSet::operator= ( FrameSet const & )

delete

◆ remapFrame()

void ast::FrameSet::remapFrame	(	int	iframe,
		Mapping &	map )

inline

Modify 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.

See also addVariant, getVariant and mirrorVariants.

Parameters

[in]	iframe	The index within the FrameSet of the Frame to be modified. This value should lie in the range 1 to the number of frames already in this FrameSet (as given by getNFrame). A value of FrameSet::BASE or FrameSet::CURRENT may be given to specify the base Frame or the current Frame respectively.
[in]	map	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.

Notes

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 and output coordinate values of the Mapping 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 permAxes 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 (with addFrame) and the original one removed if necessary (with removeFrame).
Any variant Mappings associated with the remapped Frame (except for the current variant) will be lost as a consequence of calling this method (see attribute Variant).

Definition at line 410 of file FrameSet.h.

◆ removeFrame()

virtual void ast::FrameSet::removeFrame ( int iframe )

inlinevirtual

Remove a Frame from a FrameSet.

Other Frame indices in the FrameSet are re-numbered as follows: Frame indices greater than iframe are decremented by one; other Frame indeces retain the same index.

Parameters

[in] iframe The index of the required Frame within this FrameSet. This value should lie in the range 1 to the number of Frames in this FrameSet (as given by getNFrame). A value of FrameSet::BASE or FrameSet::CURRENT may be given to specify the base Frame or the current Frame, respectively.

Notes

Removing a Frame from a FrameSet does not affect the relationship between other Frames in this FrameSet, even if they originally depended on the Frame being removed.
The number of Frames in a FrameSet cannot be reduced to zero.
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.

Exceptions

std::runtime_error if you attempt to remove the last frame

Reimplemented in ast::FrameDict.

Definition at line 442 of file FrameSet.h.

◆ renameVariant()

void ast::FrameSet::renameVariant ( std::string const & name )

inline

Rename the current Variant of the current Mapping.

The Variant attribute is updated to name.

See the Variant attribute for more details. See also addVariant, getVariant and mirrorVariants.

Parameters

[in] name The new name of the current variant Mapping.

Exceptions

std::runtime_error

if:

A variant with the supplied name already exists in the current Frame.
The current Frame is a mirror for the variant Mappings in another Frame. This is only the case if the astMirrorVariants function has been called to make the current Frame act as a mirror.

Definition at line 463 of file FrameSet.h.

◆ setBase()

void ast::FrameSet::setBase ( int ind )

inline

Set Base: index of base Frame.

Definition at line 471 of file FrameSet.h.

◆ setCurrent()

void ast::FrameSet::setCurrent ( int ind )

inline

Set Current: index of current Frame, starting from 1.

Definition at line 476 of file FrameSet.h.

◆ Frame

friend class Frame

friend

Definition at line 100 of file FrameSet.h.

◆ Object

friend class Object

friend

Definition at line 101 of file FrameSet.h.

Member Data Documentation

◆ BASE

int constexpr ast::FrameSet::BASE = AST__BASE

staticconstexpr

index of base frame

Definition at line 104 of file FrameSet.h.

◆ CURRENT

int constexpr ast::FrameSet::CURRENT = AST__CURRENT

staticconstexpr

index of current frame

Definition at line 105 of file FrameSet.h.

◆ NOFRAME

int constexpr ast::FrameSet::NOFRAME = AST__NOFRAME

staticconstexpr

an invalid frame index

Definition at line 106 of file FrameSet.h.

The documentation for this class was generated from the following files:

include/astshim/FrameSet.h
src/FrameSet.cc

Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Detailed Description

Attributes

Constructor & Destructor Documentation

◆ FrameSet() [1/5]

◆ FrameSet() [2/5]

◆ ~FrameSet()

◆ FrameSet() [3/5]

◆ FrameSet() [4/5]

◆ FrameSet() [5/5]

Member Function Documentation

◆ addAxes()

◆ addFrame()

Notes

◆ addVariant()

◆ copy()

◆ copyPolymorphic()

◆ getAllVariants()

◆ getBase()

◆ getCurrent()

◆ getFrame()

◆ getMapping()

Notes

◆ getNFrame()

◆ getVariant()

◆ mirrorVariants()

Notes:

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ remapFrame()

Notes

◆ removeFrame()

Notes

◆ renameVariant()

◆ setBase()

◆ setCurrent()

Friends And Related Symbol Documentation

◆ Frame

◆ Object

Member Data Documentation

◆ BASE

◆ CURRENT

◆ NOFRAME