Mappings and Frames APIs¶

Classes that describe frames and frame mappings are documented here.

ASTMapping¶

class cornish.mapping.ASTMapping(ast_object=None)[source]¶

Bases: cornish.ast_object.ASTObject

Parameters: ast_object – an existing starlink.Ast.Mapping object

property astString¶: Return the AST serialization of this object.

ast_description()¶: A string description of this object, customized for each subclass of ASTObject.

property id: str¶

String which may be used to identify this object.

NOTE: Unlike most other attributes, the value of the ID attribute is not transferred when an Object is copied. Instead, its value is undefined (and therefore defaults to an empty string) in any copy. However, it is retained in any external representation of an Object produced by the astWrite function.

Not sure how to handle the above in this class.

Return type: str
Returns: string identifier that can be used to uniquely identify this object

inverseMapping()[source]¶

Returns a new mapping object that is the inverse of this mapping.

For example, if the forward transformation of this mapping is pixel to sky, then the forward transformation of the returned mapping will be sky to pixel.

property isLinear: bool¶

Returns True if the mapping is linear

Return type: bool

property isSimple: bool¶

Returns True if the mapping has been simplified.

Return type: bool

property numberOfInputCoordinates¶

Number of dimensions of the space in which the Mapping’s input points reside. This property gives the number of coordinate values required to specify an input point for a Mapping.

Returns: number of input dimensions described by this mapper

property numberOfOutputCoordinates¶

Number of dimensions of the space in which the Mapping’s output points reside. This property gives the number of coordinate values required to specify an output point for a Mapping.

Returns: number of output dimensions described by this mapper

transform(points=None)[source]¶

Transform the coordinates of a set of points provided according the mapping defined by this object.

Parameters

in – input list of coordinates as numpy.ndarray, any iterable list accepted 2-dimensional array with shape (nin,npoint)
out – output coordinates

Format of points:

[ [ values on axis 1 ], [ values on axis 2 ], ... ]

e.g. sky to pixel:

[ [ra1, ra2, ...], [dec1, dec2, ...] ]

Return type: ndarray

ASTFrame¶

class cornish.mapping.ASTFrame(ast_object=None, naxes=None)[source]¶

Bases: cornish.mapping.mapping.ASTMapping

A Frame is a representation of a coordinate system, e.g. Cartesian, RA/dec. It contains information about the labels which appear on the axes, the axis units, a title, knowledge of how to format the coordinate values on each axis, etc.

List and description of starlink.Ast.Frame attributes in documentation: Section 7.5.

Ref: http://www.starlink.rl.ac.uk/docs/sun95.htx/sun95se27.html http://www.strw.leidenuniv.nl/docs/starlink/sun210.htx/node71.html

Parameters: ast_object (Optional[Frame]) – an existing starlink.Ast.Frame object

angle(vertex=None, points=None)[source]¶

Calculate the angle in this frame between two line segments connected by a point.

Let A = point1, C = point2, and B = the vertex point. This method calculates the angle between the line segments AB and CB.

If the frame is a sky frame, lines are drawn on great circles. Units are assumed to be degrees if not provided with units, e.g. as an astropy.coordinates.SkyCoord or astropy.units.Quantity values.

Parameters

vertex (Optional[Iterable]) – a two element list/tuple/Numpy array or a SkyCoord of the vertex
points (Optional[Container[Union[SkyCoord, Iterable]]]) – a two element list/tuple/etc. containing two points in this frame

Return type

Quantity

property astString¶: Return the AST serialization of this object.

ast_description()¶: A string description of this object, customized for each subclass of ASTObject.

distance(point1, point2)[source]¶

Distance between two points in this frame.

Parameters

point1 (Union[Iterable, SkyCoord]) – a two element list/tuple/Numpy array or a SkyCoord of the first point coordinates
point2 (Union[Iterable, SkyCoord]) – a two element list/tuple/Numpy array or a SkyCoord of the second point coordinates

Return type

Quantity

property domain: str¶

The physical domain of the coordinate system (string value). The Domain attribute also controls how Frames align with each other. If the Domain value in a Frame is set, then only Frames with the same Domain value can be aligned with it.

Example values: GRID, FRACTION, PIXEL, AXIS, SKY, SPECTRUM, CURPIC, NDC, BASEPIC, GRAPHICS

Frames created by the user (for instance, using WCSADD) can have any Domain value, but the standard domain names should be avoided unless the standard meanings are appropriate for the Frame being created.

Return type: str

static frameFromAstObject(ast_object=None)[source]¶

Factory method that returns the appropriate Cornish frame object (e.g. ASTSkyFrame) for a given frame.

Parameters: ast_object (Optional[Frame]) – an Ast.Frame object

static frameFromFITSHeader(header)[source]¶: Factory method that returns a new ASTFrame from the provided FITS header.

framesetWithMappingTo(template_frame=None)[source]¶

Search this frame (or set) to identify a frame that shares the same coordinate system as the provided template frame.

For example, this method can be used to see if this frame (or frame set) contains a sky frame.

Returns None if no mapping can be found.

Parameters: template_frame (Optional[ASTFrame]) – an instance of the type of frame being searched for
Return type: Optional[ASTFrame]
Returns: a frame that matches the template

property id: str¶

String which may be used to identify this object.

NOTE: Unlike most other attributes, the value of the ID attribute is not transferred when an Object is copied. Instead, its value is undefined (and therefore defaults to an empty string) in any copy. However, it is retained in any external representation of an Object produced by the astWrite function.

Not sure how to handle the above in this class.

Return type: str
Returns: string identifier that can be used to uniquely identify this object

inverseMapping()¶

Returns a new mapping object that is the inverse of this mapping.

For example, if the forward transformation of this mapping is pixel to sky, then the forward transformation of the returned mapping will be sky to pixel.

property isLinear: bool¶

Returns True if the mapping is linear

Return type: bool

property isSimple: bool¶

Returns True if the mapping has been simplified.

Return type: bool

property isSkyFrame: bool¶

Returns True if this is a SkyFrame, False otherwise.

Return type: bool

label(axis=None)[source]¶

Return the label for the specified axis.

Return type: str

property naxes: int¶

Returns the number of axes for the frame.

Return type: int

property numberOfInputCoordinates¶

Number of dimensions of the space in which the Mapping’s input points reside. This property gives the number of coordinate values required to specify an input point for a Mapping.

Returns: number of input dimensions described by this mapper

property numberOfOutputCoordinates¶

Number of dimensions of the space in which the Mapping’s output points reside. This property gives the number of coordinate values required to specify an output point for a Mapping.

Returns: number of output dimensions described by this mapper

offsetAlongGeodesicCurve(point1, point2, offset)[source]¶

Coordinates and offset value should be in the units of the frame, e.g. pixels, degrees.

In a sky frame, the line will be curved. In a basic frame, the line will be straight.

Parameters

point1 (Iterable) – a two element list/tuple/NumPy array of the first point coordinates
point2 (Iterable) – a two element list/tuple/NumPy array of the second point coordinates
offset (Quantity) – a distance along the geodesic sphere connecting the two points

setLabelForAxis(label=None)[source]¶: Set the label for the specified axis.

setUnitForAxis(axis=None, unit=None)[source]¶: Set the unit as a string value for the specified axis.

property system¶: String which identifies the coordinate system represented by the Frame. The system is Cartesian by default, but can have other values for subclasses of Frame, e.g. FK4, Galactic.

property title: str¶

Returns the frame title, a string describing the coordinate system which the frame represents.

Return type: str

transform(points=None)¶

Transform the coordinates of a set of points provided according the mapping defined by this object.

Parameters

in – input list of coordinates as numpy.ndarray, any iterable list accepted 2-dimensional array with shape (nin,npoint)
out – output coordinates

Format of points:

[ [ values on axis 1 ], [ values on axis 2 ], ... ]

e.g. sky to pixel:

[ [ra1, ra2, ...], [dec1, dec2, ...] ]

Return type: ndarray

unit(axis=None)[source]¶: Return the unit for the specified axis.

ASTFrameSet¶

class cornish.mapping.ASTFrameSet(ast_object=None, base_frame=None)[source]¶

Bases: cornish.mapping.frame.frame.ASTFrame

Create a new AST frame set. Object can be created from an starlink.Ast.FrameSet “primitive” (e.g. returned by another object).

A set of inter-related coordinate systems made up of existing mapping’s and frames. A FrameSet may be extended by adding a new Frame and associated Mapping.

A FrameSet must have a “base” frame which represents the “native” coordinate system (for example, the pixel coordinates of an image). Similarly, one Frame is termed the current Frame and represents the “currently-selected” coordinates. It might typically be a celestial or spectral coordinate system and would be used during interactions with a user, as when plotting axes on a graph or producing a table of results. Other Frames within the FrameSet represent a library of alternative coordinate systems which a software user can select by making them current.

Accepted signatures for creating an ASTFrameSet:

Parameters

ast_object (Optional[FrameSet]) – an Ast.astFrame object from the starlink-pyast library
base_frame (Union[FrameSet, ASTFrame, None]) – base frame to create the FrameSet from

addToBaseFrame(frame=None)[source]¶: Add a new frame to this frame set’s base frame.

angle(vertex=None, points=None)¶

Calculate the angle in this frame between two line segments connected by a point.

Let A = point1, C = point2, and B = the vertex point. This method calculates the angle between the line segments AB and CB.

If the frame is a sky frame, lines are drawn on great circles. Units are assumed to be degrees if not provided with units, e.g. as an astropy.coordinates.SkyCoord or astropy.units.Quantity values.

Parameters

vertex (Optional[Iterable]) – a two element list/tuple/Numpy array or a SkyCoord of the vertex
points (Optional[Container[Union[SkyCoord, Iterable]]]) – a two element list/tuple/etc. containing two points in this frame

Return type

Quantity

property astString¶: Return the AST serialization of this object.

ast_description()¶: A string description of this object, customized for each subclass of ASTObject.

property baseFrame¶: Return the base frame.

centerCoordinates()[source]¶: Returns the coordinates at the center of the frame.

convert(points, forward=True)[source]¶

property currentFrame¶: Returns the current frame.

distance(point1, point2)¶

Distance between two points in this frame.

Parameters

point1 (Union[Iterable, SkyCoord]) – a two element list/tuple/Numpy array or a SkyCoord of the first point coordinates
point2 (Union[Iterable, SkyCoord]) – a two element list/tuple/Numpy array or a SkyCoord of the second point coordinates

Return type

Quantity

property domain: str¶

The physical domain of the coordinate system (string value). The Domain attribute also controls how Frames align with each other. If the Domain value in a Frame is set, then only Frames with the same Domain value can be aligned with it.

Example values: GRID, FRACTION, PIXEL, AXIS, SKY, SPECTRUM, CURPIC, NDC, BASEPIC, GRAPHICS

Frames created by the user (for instance, using WCSADD) can have any Domain value, but the standard domain names should be avoided unless the standard meanings are appropriate for the Frame being created.

Return type: str

frameAtIndex(frame_index)[source]¶

Return the frame at the specified index within this frame set.

Return type: ASTFrame

static frameFromAstObject(ast_object=None)¶

Factory method that returns the appropriate Cornish frame object (e.g. ASTSkyFrame) for a given frame.

Parameters: ast_object (Optional[Frame]) – an Ast.Frame object

static frameFromFITSHeader(header)¶: Factory method that returns a new ASTFrame from the provided FITS header.

framesetWithMappingTo(template_frame=None)¶

Search this frame (or set) to identify a frame that shares the same coordinate system as the provided template frame.

For example, this method can be used to see if this frame (or frame set) contains a sky frame.

Returns None if no mapping can be found.

Parameters: template_frame (Optional[ASTFrame]) – an instance of the type of frame being searched for
Return type: Optional[ASTFrame]
Returns: a frame that matches the template

static fromFITSHeader(fits_header=None)[source]¶: Static method that returns a FrameSet object read from the provided FITS header.

static fromFrames(frame1, frame2)[source]¶

Static method to create a frame set from two existing frames.

A frame set is a mapping between two frames that can convert coordinates from one frame (the “base” frame) to the other frame (the “current” frame).

Parameters

frame1 (Union[ASTFrame, Frame]) – the “base” frame (frame to convert coordinates from)
frame2 (Union[ASTFrame, Frame]) – the “current” frame (frame to convert coordinates to)

property id: str¶

String which may be used to identify this object.

NOTE: Unlike most other attributes, the value of the ID attribute is not transferred when an Object is copied. Instead, its value is undefined (and therefore defaults to an empty string) in any copy. However, it is retained in any external representation of an Object produced by the astWrite function.

Not sure how to handle the above in this class.

Return type: str
Returns: string identifier that can be used to uniquely identify this object

inverseMapping()¶

Returns a new mapping object that is the inverse of this mapping.

For example, if the forward transformation of this mapping is pixel to sky, then the forward transformation of the returned mapping will be sky to pixel.

property isLinear: bool¶

Returns True if the mapping is linear

Return type: bool

property isSimple: bool¶

Returns True if the mapping has been simplified.

Return type: bool

property isSkyFrame: bool¶

Returns True if this is a SkyFrame, False otherwise.

Return type: bool

label(axis=None)¶

Return the label for the specified axis.

Return type: str

property mapping¶: Return an object that maps points from the base frame to the current frame of this frame set.

property naxes: int¶

Returns the number of axes for the frame.

Return type: int

property numberOfInputCoordinates¶

Number of dimensions of the space in which the Mapping’s input points reside. This property gives the number of coordinate values required to specify an input point for a Mapping.

Returns: number of input dimensions described by this mapper

property numberOfOutputCoordinates¶

Number of dimensions of the space in which the Mapping’s output points reside. This property gives the number of coordinate values required to specify an output point for a Mapping.

Returns: number of output dimensions described by this mapper

offsetAlongGeodesicCurve(point1, point2, offset)¶

Coordinates and offset value should be in the units of the frame, e.g. pixels, degrees.

In a sky frame, the line will be curved. In a basic frame, the line will be straight.

Parameters

point1 (Iterable) – a two element list/tuple/NumPy array of the first point coordinates
point2 (Iterable) – a two element list/tuple/NumPy array of the second point coordinates
offset (Quantity) – a distance along the geodesic sphere connecting the two points

pix2world(points)[source]¶

Convert provided coordinates from a world frame to a pixel frame.

This method will throw a cornish.exc.FrameNotAvailable exception if the frame set does not contain both a pixel and world frame.

Format of points:

[ [ values on axis 1 ], [ values on axis 2 ], ... ]

e.g. pixel to sky:

[ [x1, x2, ...], [y1, y2, ...] ]

A single point may also be specified alone, e.g. [a,b] or np.array([a,b]).

Parameters: points (Iterable) – input list of coordinates as numpy.ndarray, 2-dimensional array with shape (2,npoint)
Return type: ndarray

removeCurrentFrame()[source]¶: Remove the current frame from the frame set.

setLabelForAxis(label=None)¶: Set the label for the specified axis.

setUnitForAxis(axis=None, unit=None)¶: Set the unit as a string value for the specified axis.

property system¶: String which identifies the coordinate system represented by the Frame. The system is Cartesian by default, but can have other values for subclasses of Frame, e.g. FK4, Galactic.

property title: str¶

Returns the frame title, a string describing the coordinate system which the frame represents.

Return type: str

transform(points=None)¶

Transform the coordinates of a set of points provided according the mapping defined by this object.

Parameters

in – input list of coordinates as numpy.ndarray, any iterable list accepted 2-dimensional array with shape (nin,npoint)
out – output coordinates

Format of points:

[ [ values on axis 1 ], [ values on axis 2 ], ... ]

e.g. sky to pixel:

[ [ra1, ra2, ...], [dec1, dec2, ...] ]

Return type: ndarray

unit(axis=None)¶: Return the unit for the specified axis.

world2pix(points)[source]¶

Convert provided coordinates from a world frame to a pixel frame.

This method will throw a cornish.exc.FrameNotAvailable exception if the frame set does not contain both a pixel and world frame.

Points must have the shape (2,n), e.g.:

[ [ra1, ra2, ...], [dec1, dec2, ...] ]

A single point may also be specified alone, e.g. [a,b] or np.array([a,b]).

Parameters: points (Union[Iterable, SkyCoord]) – input list of coordinates as numpy.ndarray, 2-dimensional array with shape (2,npoints); units are assumed to be degrees if not specified via astropy.units.Quantity
Return type: ndarray

ASTSkyFrame¶

class cornish.mapping.ASTSkyFrame(ast_object=None, equinox=None, system=None, epoch=None)[source]¶

Bases: cornish.mapping.frame.frame.ASTFrame

A SkyFrame is a specialised form of Frame which describes celestial longitude/latitude coordinate systems.

Systems available in AST:

ICRS, J2000, AZEL, ECLIPTIC, FK4, FK4-NO-E, FK4_NO_E, FK5, EQUATORIAL, GALACTIC, GAPPT, GEOCENTRIC, APPARENT, HELIOECLIPTIC, SUPERGALACTIC

Parameters

ast_object (Optional[SkyFrame]) – an existing starlink.Ast.SkyFrame object
equinox (Optional[str]) – frame equinox, default value 2000.0
system (Optional[str]) – coordinate system used to describe positions within the domain, see AST System documentation, default value = ICRS
epoch (Optional[str]) – epoch of the mean equinox as a string value, e.g. J2000.0, B1950.0, default = 2000.0

angle(vertex=None, points=None)¶

Calculate the angle in this frame between two line segments connected by a point.

Let A = point1, C = point2, and B = the vertex point. This method calculates the angle between the line segments AB and CB.

If the frame is a sky frame, lines are drawn on great circles. Units are assumed to be degrees if not provided with units, e.g. as an astropy.coordinates.SkyCoord or astropy.units.Quantity values.

Parameters

vertex (Optional[Iterable]) – a two element list/tuple/Numpy array or a SkyCoord of the vertex
points (Optional[Container[Union[SkyCoord, Iterable]]]) – a two element list/tuple/etc. containing two points in this frame

Return type

Quantity

property astString¶: Return the AST serialization of this object.

ast_description()¶: A string description of this object, customized for each subclass of ASTObject.

distance(point1, point2)¶

Distance between two points in this frame.

Parameters

point1 (Union[Iterable, SkyCoord]) – a two element list/tuple/Numpy array or a SkyCoord of the first point coordinates
point2 (Union[Iterable, SkyCoord]) – a two element list/tuple/Numpy array or a SkyCoord of the second point coordinates

Return type

Quantity

property domain: str¶

The physical domain of the coordinate system (string value). The Domain attribute also controls how Frames align with each other. If the Domain value in a Frame is set, then only Frames with the same Domain value can be aligned with it.

Example values: GRID, FRACTION, PIXEL, AXIS, SKY, SPECTRUM, CURPIC, NDC, BASEPIC, GRAPHICS

Frames created by the user (for instance, using WCSADD) can have any Domain value, but the standard domain names should be avoided unless the standard meanings are appropriate for the Frame being created.

Return type: str

property epoch¶

property equinox¶: Todo

how to evaluate a valid equinox string?

static frameFromAstObject(ast_object=None)¶

Factory method that returns the appropriate Cornish frame object (e.g. ASTSkyFrame) for a given frame.

Parameters: ast_object (Optional[Frame]) – an Ast.Frame object

static frameFromFITSHeader(header)¶: Factory method that returns a new ASTFrame from the provided FITS header.

framesetWithMappingTo(template_frame=None)¶

Search this frame (or set) to identify a frame that shares the same coordinate system as the provided template frame.

For example, this method can be used to see if this frame (or frame set) contains a sky frame.

Returns None if no mapping can be found.

Parameters: template_frame (Optional[ASTFrame]) – an instance of the type of frame being searched for
Return type: Optional[ASTFrame]
Returns: a frame that matches the template

classmethod fromFITSHeader(header)[source]¶

Returns a SkyFrame built from the WCS in the provided header, if found. Creates a sky frame from the provided FITS header. :raises: exc.NoWCSFound: if no sky frame WCS found

Return type: ASTSkyFrame

property id: str¶

String which may be used to identify this object.

NOTE: Unlike most other attributes, the value of the ID attribute is not transferred when an Object is copied. Instead, its value is undefined (and therefore defaults to an empty string) in any copy. However, it is retained in any external representation of an Object produced by the astWrite function.

Not sure how to handle the above in this class.

Return type: str
Returns: string identifier that can be used to uniquely identify this object

inverseMapping()¶

Returns a new mapping object that is the inverse of this mapping.

For example, if the forward transformation of this mapping is pixel to sky, then the forward transformation of the returned mapping will be sky to pixel.

property isLinear: bool¶

Returns True if the mapping is linear

Return type: bool

property isSimple: bool¶

Returns True if the mapping has been simplified.

Return type: bool

property isSkyFrame: bool¶

Returns True if this is a SkyFrame, False otherwise.

Return type: bool

label(axis=None)¶

Return the label for the specified axis.

Return type: str

property naxes: int¶

Returns the number of axes for the frame.

Return type: int

property numberOfInputCoordinates¶

Number of dimensions of the space in which the Mapping’s input points reside. This property gives the number of coordinate values required to specify an input point for a Mapping.

Returns: number of input dimensions described by this mapper

property numberOfOutputCoordinates¶

Number of dimensions of the space in which the Mapping’s output points reside. This property gives the number of coordinate values required to specify an output point for a Mapping.

Returns: number of output dimensions described by this mapper

offsetAlongGeodesicCurve(point1, point2, offset)¶

Coordinates and offset value should be in the units of the frame, e.g. pixels, degrees.

In a sky frame, the line will be curved. In a basic frame, the line will be straight.

Parameters

point1 (Iterable) – a two element list/tuple/NumPy array of the first point coordinates
point2 (Iterable) – a two element list/tuple/NumPy array of the second point coordinates
offset (Quantity) – a distance along the geodesic sphere connecting the two points

setLabelForAxis(label=None)¶: Set the label for the specified axis.

setUnitForAxis(axis=None, unit=None)¶: Set the unit as a string value for the specified axis.

property system¶: String which identifies the coordinate system represented by the Frame. The system is Cartesian by default, but can have other values for subclasses of Frame, e.g. FK4, Galactic.

property title: str¶

Returns the frame title, a string describing the coordinate system which the frame represents.

Return type: str

transform(points=None)¶

Transform the coordinates of a set of points provided according the mapping defined by this object.

Parameters

in – input list of coordinates as numpy.ndarray, any iterable list accepted 2-dimensional array with shape (nin,npoint)
out – output coordinates

Format of points:

[ [ values on axis 1 ], [ values on axis 2 ], ... ]

e.g. sky to pixel:

[ [ra1, ra2, ...], [dec1, dec2, ...] ]

Return type: ndarray

unit(axis=None)¶: Return the unit for the specified axis.

ASTICRSFrame¶

class cornish.mapping.ASTICRSFrame(equinox='2000.0', epoch='2000.0')[source]¶

Bases: cornish.mapping.frame.sky_frame.ASTSkyFrame

Factory class that returns an ASTSkyFrame automatically set to System=ICRS, equinox=2000.0, epoch=2000.0.

angle(vertex=None, points=None)¶

Calculate the angle in this frame between two line segments connected by a point.

Let A = point1, C = point2, and B = the vertex point. This method calculates the angle between the line segments AB and CB.

If the frame is a sky frame, lines are drawn on great circles. Units are assumed to be degrees if not provided with units, e.g. as an astropy.coordinates.SkyCoord or astropy.units.Quantity values.

Parameters

vertex (Optional[Iterable]) – a two element list/tuple/Numpy array or a SkyCoord of the vertex
points (Optional[Container[Union[SkyCoord, Iterable]]]) – a two element list/tuple/etc. containing two points in this frame

Return type

Quantity

property astString¶: Return the AST serialization of this object.

ast_description()¶: A string description of this object, customized for each subclass of ASTObject.

distance(point1, point2)¶

Distance between two points in this frame.

Parameters

point1 (Union[Iterable, SkyCoord]) – a two element list/tuple/Numpy array or a SkyCoord of the first point coordinates
point2 (Union[Iterable, SkyCoord]) – a two element list/tuple/Numpy array or a SkyCoord of the second point coordinates

Return type

Quantity

property domain: str¶

The physical domain of the coordinate system (string value). The Domain attribute also controls how Frames align with each other. If the Domain value in a Frame is set, then only Frames with the same Domain value can be aligned with it.

Example values: GRID, FRACTION, PIXEL, AXIS, SKY, SPECTRUM, CURPIC, NDC, BASEPIC, GRAPHICS

Frames created by the user (for instance, using WCSADD) can have any Domain value, but the standard domain names should be avoided unless the standard meanings are appropriate for the Frame being created.

Return type: str

property epoch¶

property equinox¶: Todo

how to evaluate a valid equinox string?

static frameFromAstObject(ast_object=None)¶

Factory method that returns the appropriate Cornish frame object (e.g. ASTSkyFrame) for a given frame.

Parameters: ast_object (Optional[Frame]) – an Ast.Frame object

static frameFromFITSHeader(header)¶: Factory method that returns a new ASTFrame from the provided FITS header.

framesetWithMappingTo(template_frame=None)¶

Search this frame (or set) to identify a frame that shares the same coordinate system as the provided template frame.

For example, this method can be used to see if this frame (or frame set) contains a sky frame.

Returns None if no mapping can be found.

Parameters: template_frame (Optional[ASTFrame]) – an instance of the type of frame being searched for
Return type: Optional[ASTFrame]
Returns: a frame that matches the template

classmethod fromFITSHeader(header)¶

Returns a SkyFrame built from the WCS in the provided header, if found. Creates a sky frame from the provided FITS header. :raises: exc.NoWCSFound: if no sky frame WCS found

Return type: ASTSkyFrame

property id: str¶

String which may be used to identify this object.

NOTE: Unlike most other attributes, the value of the ID attribute is not transferred when an Object is copied. Instead, its value is undefined (and therefore defaults to an empty string) in any copy. However, it is retained in any external representation of an Object produced by the astWrite function.

Not sure how to handle the above in this class.

Return type: str
Returns: string identifier that can be used to uniquely identify this object

inverseMapping()¶

Returns a new mapping object that is the inverse of this mapping.

For example, if the forward transformation of this mapping is pixel to sky, then the forward transformation of the returned mapping will be sky to pixel.

property isLinear: bool¶

Returns True if the mapping is linear

Return type: bool

property isSimple: bool¶

Returns True if the mapping has been simplified.

Return type: bool

property isSkyFrame: bool¶

Returns True if this is a SkyFrame, False otherwise.

Return type: bool

label(axis=None)¶

Return the label for the specified axis.

Return type: str

property naxes: int¶

Returns the number of axes for the frame.

Return type: int

property numberOfInputCoordinates¶

Number of dimensions of the space in which the Mapping’s input points reside. This property gives the number of coordinate values required to specify an input point for a Mapping.

Returns: number of input dimensions described by this mapper

property numberOfOutputCoordinates¶

Number of dimensions of the space in which the Mapping’s output points reside. This property gives the number of coordinate values required to specify an output point for a Mapping.

Returns: number of output dimensions described by this mapper

offsetAlongGeodesicCurve(point1, point2, offset)¶

Coordinates and offset value should be in the units of the frame, e.g. pixels, degrees.

In a sky frame, the line will be curved. In a basic frame, the line will be straight.

Parameters

point1 (Iterable) – a two element list/tuple/NumPy array of the first point coordinates
point2 (Iterable) – a two element list/tuple/NumPy array of the second point coordinates
offset (Quantity) – a distance along the geodesic sphere connecting the two points

setLabelForAxis(label=None)¶: Set the label for the specified axis.

setUnitForAxis(axis=None, unit=None)¶: Set the unit as a string value for the specified axis.

property system¶: String which identifies the coordinate system represented by the Frame. The system is Cartesian by default, but can have other values for subclasses of Frame, e.g. FK4, Galactic.

property title: str¶

Returns the frame title, a string describing the coordinate system which the frame represents.

Return type: str

transform(points=None)¶

Transform the coordinates of a set of points provided according the mapping defined by this object.

Parameters

in – input list of coordinates as numpy.ndarray, any iterable list accepted 2-dimensional array with shape (nin,npoint)
out – output coordinates

Format of points:

[ [ values on axis 1 ], [ values on axis 2 ], ... ]

e.g. sky to pixel:

[ [ra1, ra2, ...], [dec1, dec2, ...] ]

Return type: ndarray

unit(axis=None)¶: Return the unit for the specified axis.

ASTCompoundFrame¶

class cornish.mapping.ASTCompoundFrame(ast_object=None, naxes=None)[source]¶

Bases: cornish.mapping.frame.frame.ASTFrame

A compound frame is the merging of two existing ASTFrame objects.

For example, a compound frame could have celestial coordinates on two axes and an unrelated coordinate (wavelength, perhaps) on a third. Knowledge of the relationships between the axes is preserved internally by the process of constructing the frames which represents them.

angle(vertex=None, points=None)¶

Calculate the angle in this frame between two line segments connected by a point.

Let A = point1, C = point2, and B = the vertex point. This method calculates the angle between the line segments AB and CB.

If the frame is a sky frame, lines are drawn on great circles. Units are assumed to be degrees if not provided with units, e.g. as an astropy.coordinates.SkyCoord or astropy.units.Quantity values.

Parameters

vertex (Optional[Iterable]) – a two element list/tuple/Numpy array or a SkyCoord of the vertex
points (Optional[Container[Union[SkyCoord, Iterable]]]) – a two element list/tuple/etc. containing two points in this frame

Return type

Quantity

property astString¶: Return the AST serialization of this object.

ast_description()¶: A string description of this object, customized for each subclass of ASTObject.

distance(point1, point2)¶

Distance between two points in this frame.

Parameters

point1 (Union[Iterable, SkyCoord]) – a two element list/tuple/Numpy array or a SkyCoord of the first point coordinates
point2 (Union[Iterable, SkyCoord]) – a two element list/tuple/Numpy array or a SkyCoord of the second point coordinates

Return type

Quantity

property domain: str¶

The physical domain of the coordinate system (string value). The Domain attribute also controls how Frames align with each other. If the Domain value in a Frame is set, then only Frames with the same Domain value can be aligned with it.

Example values: GRID, FRACTION, PIXEL, AXIS, SKY, SPECTRUM, CURPIC, NDC, BASEPIC, GRAPHICS

Frames created by the user (for instance, using WCSADD) can have any Domain value, but the standard domain names should be avoided unless the standard meanings are appropriate for the Frame being created.

Return type: str

static frameFromAstObject(ast_object=None)¶

Factory method that returns the appropriate Cornish frame object (e.g. ASTSkyFrame) for a given frame.

Parameters: ast_object (Optional[Frame]) – an Ast.Frame object

static frameFromFITSHeader(header)¶: Factory method that returns a new ASTFrame from the provided FITS header.

framesetWithMappingTo(template_frame=None)¶

Search this frame (or set) to identify a frame that shares the same coordinate system as the provided template frame.

For example, this method can be used to see if this frame (or frame set) contains a sky frame.

Returns None if no mapping can be found.

Parameters: template_frame (Optional[ASTFrame]) – an instance of the type of frame being searched for
Return type: Optional[ASTFrame]
Returns: a frame that matches the template

property id: str¶

String which may be used to identify this object.

NOTE: Unlike most other attributes, the value of the ID attribute is not transferred when an Object is copied. Instead, its value is undefined (and therefore defaults to an empty string) in any copy. However, it is retained in any external representation of an Object produced by the astWrite function.

Not sure how to handle the above in this class.

Return type: str
Returns: string identifier that can be used to uniquely identify this object

inverseMapping()¶

Returns a new mapping object that is the inverse of this mapping.

For example, if the forward transformation of this mapping is pixel to sky, then the forward transformation of the returned mapping will be sky to pixel.

property isLinear: bool¶

Returns True if the mapping is linear

Return type: bool

property isSimple: bool¶

Returns True if the mapping has been simplified.

Return type: bool

property isSkyFrame: bool¶

Returns True if this is a SkyFrame, False otherwise.

Return type: bool

label(axis=None)¶

Return the label for the specified axis.

Return type: str

property naxes: int¶

Returns the number of axes for the frame.

Return type: int

property numberOfInputCoordinates¶

Number of dimensions of the space in which the Mapping’s input points reside. This property gives the number of coordinate values required to specify an input point for a Mapping.

Returns: number of input dimensions described by this mapper

property numberOfOutputCoordinates¶

Number of dimensions of the space in which the Mapping’s output points reside. This property gives the number of coordinate values required to specify an output point for a Mapping.

Returns: number of output dimensions described by this mapper

offsetAlongGeodesicCurve(point1, point2, offset)¶

Coordinates and offset value should be in the units of the frame, e.g. pixels, degrees.

In a sky frame, the line will be curved. In a basic frame, the line will be straight.

Parameters

point1 (Iterable) – a two element list/tuple/NumPy array of the first point coordinates
point2 (Iterable) – a two element list/tuple/NumPy array of the second point coordinates
offset (Quantity) – a distance along the geodesic sphere connecting the two points

setLabelForAxis(label=None)¶: Set the label for the specified axis.

setUnitForAxis(axis=None, unit=None)¶: Set the unit as a string value for the specified axis.

property system¶: String which identifies the coordinate system represented by the Frame. The system is Cartesian by default, but can have other values for subclasses of Frame, e.g. FK4, Galactic.

property title: str¶

Returns the frame title, a string describing the coordinate system which the frame represents.

Return type: str

transform(points=None)¶

Transform the coordinates of a set of points provided according the mapping defined by this object.

Parameters

in – input list of coordinates as numpy.ndarray, any iterable list accepted 2-dimensional array with shape (nin,npoint)
out – output coordinates

Format of points:

[ [ values on axis 1 ], [ values on axis 2 ], ... ]

e.g. sky to pixel:

[ [ra1, ra2, ...], [dec1, dec2, ...] ]

Return type: ndarray

unit(axis=None)¶: Return the unit for the specified axis.