Region APIs¶
Classes that describe regions are documented here.
ASTRegion¶
- class cornish.ASTRegion(ast_object=None, uncertainty=None)[source]¶
Bases:
cornish.mapping.frame.frame.ASTFrame
Represents a region within a coordinate system. This is an abstract superclass - there is no supported means to create an ASTRegion object directly (see
ASTBox
,ASTPolygon
, etc.).Accepted signatures for creating an ASTRegion:
r = ASTRegion(ast_object)
- Parameters
ast_object (
Optional
[Region
]) –uncertainty –
- 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 vertexpoints (
Optional
[Container
[Union
[SkyCoord
,Iterable
]]]) – a two element list/tuple/etc. containing two points in this frame
- Return type
- property astString¶
Return the AST serialization of this object.
- ast_description()¶
A string description of this object, customized for each subclass of
ASTObject
.
- boundaryPointMesh(npoints=None)[source]¶
Returns an array of evenly distributed points that cover the boundary of the region. For example, if the region is a box, it will generate a list of points that trace the edges of the box.
The default value of ‘npoints’ is 200 for 2D regions and 2000 for three or more dimensions.
- Parameters
npoints (
Optional
[int
]) – the approximate number of points to generate in the mesh- Return type
- Returns
list of points in degrees
- boundingBox()[source]¶
Returns an ASTBox region that bounds this region where the box sides align with RA, dec.
- Return type
- boundingCircle()[source]¶
Returns the smallest circle (
ASTCircle
) that bounds this region.It is up to the caller to know that this is a 2D region (only minimal checks are made). :raises cornish.exc.NotA2DRegion: raised when attempting to get a bounding circle for a region that is not 2D
- Return type
- property bounds: Tuple¶
Returns lower and upper coordinate points that bound this region.
- Return type
Tuple
- containsPoint(point=None)[source]¶
Returns
True
if the provided point lies inside this region,False
otherwise.This method is a direct synonym for
pointInRegion()
. The name “containsPoint” is more appropriate from an object perspective, but thepointInRegion
method is present for consistency with the AST library.- Parameters
point (
Union
[Iterable
,SkyCoord
,None
]) – a coordinate point in the same frame as this region- Return type
bool
- 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 coordinatespoint2 (
Union
[Iterable
,SkyCoord
]) – a two element list/tuple/Numpy array or a SkyCoord of the second point coordinates
- Return type
- 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 fillFactor¶
<Fraction of the Region which is of interest>
- frame()[source]¶
Returns a copy of the frame encapsulated by this region.
Note that the frame is not directly accessible; both this method and the underlying
starlink-pyast
function returns a copy.- Return type
- 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
]) – anAst.Frame
object
- static frameFromFITSHeader(header)¶
Factory method that returns a new ASTFrame from the provided FITS header.
- frameSet()[source]¶
Returns a copy of the frameset encapsulated by this region.
From AST docs:
The base Frame is the Frame in which the box was originally defined, and the current Frame is the Frame into which the Region is currently mapped (i.e. it will be the same as the Frame returned by astGetRegionFrame).
- Return type
- 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.
- classmethod fromFITSHeader(fits_header=None, uncertainty=4.848e-06)[source]¶
Factory method to create a region from the provided FITS header; the returned object will be as specific as possible (but probably an
ASTPolygon
).The frame is determined from the FITS header.
- Parameters
fits_header – a FITS header (Astropy, fitsio, an array of cards)
uncertainty (
float
) – defaults to 4.848e-6, an uncertainty of 1 arcsec
- fullyEncloses(region)[source]¶
Returns ‘True’ if this region fully encloses the provided region.
- Return type
bool
- 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
- interiorPointMesh(npoints=None)[source]¶
Returns an array of evenly distributed points that cover the surface of the region. For example, if the region is a box, it will generate a list of points that fill the interior area of the box.
The default value of ‘npoints’ is 200 for 2D regions and 2000 for three or more dimensions.
- Parameters
npoints (
Optional
[int
]) – the approximate number of points to generate in the mesh- Returns
array of points in degrees
- 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 isAdaptive¶
Boolean attribute that indicates whether the area adapt to changes in the coordinate system.
- property isBounded: bool¶
Boolean attribute that indicates whether the region is bounded.
- Return type
bool
- property isClosed: bool¶
Boolean attribute that indicates whether the boundary be considered to be inside the region.
- Return type
bool
- isFullyWithin(region)[source]¶
Returns ‘True’ if this region is fully within the provided region.
- Return type
bool
- isIdenticalTo(region)[source]¶
Returns ‘True’ if this region is identical (to within their uncertainties) to the provided region, ‘False’ otherwise.
- Return type
bool
- property isLinear: bool¶
Returns True if the mapping is linear
- Return type
bool
- property isNegated¶
Boolean attribute that indicates whether the original region has been negated.
- isNegationOf(region)[source]¶
Returns ‘True’ if this region is the exact negation of the provided region.
- 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
- mapRegionMesh(mapping=None, frame=None)[source]¶
Returns a new ASTRegion that is the same as this one but with the specified coordinate system.
- Parameters
mapping (~cornish.mapping.ASTMapping class) – The mapping to transform positions from the current ASTRegion to those specified by the given frame.
frame (~cornish.frame.ASTFrame class) – Coordinate system frame to convert the current ASTRegion to.
- Returns
region – A new region object covering the same area but in the frame specified in frame.
- Return type
ASTRegion
- Raises
Exception – An exception is raised for missing parameters.
- maskOnto(image=None, mapping=None, fits_coordinates=True, lower_bounds=None, mask_inside=True, mask_value=nan)[source]¶
Apply this region as a mask on top of the provided image; note: the image values are overwritten!
- Parameters
image – numpy.ndarray of pixel values (or other array of values)
mapping – mapping from this region to the pixel coordinates of the provided image
fits_coordinates (
bool
) – use the pixel coordinates of a FITS file (i.e. origin = [0.5, 0.5] for 2D)lower_bounds – lower bounds of provided image, only specify if not using FITS coordinates
mask_inside – True: mask the inside of this region; False: mask outside of this region
mask_value – the value to set the masked image pixels to
- Returns
number of pixels in image masked
- property meshSize: int¶
Number of points used to create a mesh covering the region.
- Return type
int
- 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 coordinatespoint2 (
Iterable
) – a two element list/tuple/NumPy array of the second point coordinatesoffset (
Quantity
) – a distance along the geodesic sphere connecting the two points
- overlaps(region)[source]¶
Return
True
if this region overlaps with the provided one.- Return type
bool
- pointInRegion(point)[source]¶
Returns
True
if the provided point lies inside this region,False
otherwise.If no units are specified degrees are assumed.
- Parameters
point (
Union
[Iterable
,SkyCoord
,ndarray
]) – a coordinate point in the same frame as this region- Return type
bool
- property points: numpy.ndarray¶
The array of points that define the region. The interpretation of the points is dependent on the type of shape in question.
Box: returns two points; the center and a box corner. Circle: returns two points; the center and a point on the circumference. CmpRegion: no points returned; to get points that define a compound region, call this method on each of the component regions via the method “decompose”. Ellipse: three points: 1) center, 2) end of one axis, 3) end of the other axis Interval: two points: 1) lower bounds position, 2) upper bounds position (reversed when interval is an excluded interval) NullRegion: no points PointList: positions that the list was constructed with Polygon: vertex positions used to construct the polygon Prism: no points (see CmpRegion)
NOTE: points returned reflect the current coordinate system and may be different from the initial construction
- Return type
- Returns
NumPy array of coordinate points in degrees, shape (ncoord,2), e.g. [[ra1,dec1], [ra2, dec2], …, [ra_n, dec_n]]
- regionWithMapping(map=None, frame=None)[source]¶
Returns a new ASTRegion with the coordinate system from the supplied frame.
Corresponds to the
astMapRegion
C function (starlink.Ast.mapregion
).- Parameters
map – A mapping that can convert coordinates from the system of the current region to that of the supplied frame.
frame – A frame containing the coordinate system for the new region.
- Return type
- Returns
new ASTRegion with a new coordinate system
- 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
- abstract toPolygon(npoints=200, maxerr=<Quantity 1. arcsec>)[source]¶
Method that guarantees returning a polygon that describes or approximates this region.
This method provides a common interface to create polygons from different region types. Calling this on an ASTPolygon will return itself; calling it on an ASTCircle will return a polygon that approximates the circle. The parameters ‘npoints’ and ‘maxerr’ will be used only when appropriate.
- Parameters
npoints – number of points to sample from the region’s boundary for the resulting polygon
maxerr (astropy.units.Quantity) –
- Return type
- 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
- property uncertainty¶
Uncertainties associated with the boundary of the Box.
The uncertainty in any point on the boundary of the Box is found by shifting the supplied “uncertainty” Region so that it is centered 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.
- unit(axis=None)¶
Return the unit for the specified axis.
ASTBox¶
- class cornish.ASTBox(ast_object=None)[source]¶
Bases:
cornish.region.region.ASTRegion
ASTBox is an ASTRegion that represents a box with sides parallel to the axes of an ASTFrame.
Accepted signatures for creating an ASTBox:
b = ASTBox(frame, cornerPoint, cornerPoint2) b = ASTBox(frame, cornerPoint, centerPoint) b = ASTBox(frame, dimensions) b = ASTBox(ast_box) (where ast_box is an Ast.Box object)
Points and dimensions can be any two element container, e.g.
(1,2) [1,2] np.array([1,2])
If
dimensions
is specified, a box enclosing the entire area will be defined.The ‘frame’ parameter may either be an ASTFrame object or a
starlink.Ast.frame
object.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 centered 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).
- Parameters
ast_box – an existing object of type
starlink.Ast.Box
frame – a frame the box is to be defined in, uses
ASTICRSFrame
if NonecornerPoint –
cornerPoint2 –
centerPoint –
dimensions – dimensions of the box in pixels for use on a Cartesian frame (AST frame=’Cartesian’ and system=’GRID’)
- 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 vertexpoints (
Optional
[Container
[Union
[SkyCoord
,Iterable
]]]) – a two element list/tuple/etc. containing two points in this frame
- Return type
- property area: astropy.units.quantity.Quantity¶
The area of the box within its frame (e.g. on a Cartesian plane or sphere). [Not yet implemented.]
- Return type
- property astString¶
Return the AST serialization of this object.
- ast_description()¶
A string description of this object, customized for each subclass of
ASTObject
.
- boundaryPointMesh(npoints=None)¶
Returns an array of evenly distributed points that cover the boundary of the region. For example, if the region is a box, it will generate a list of points that trace the edges of the box.
The default value of ‘npoints’ is 200 for 2D regions and 2000 for three or more dimensions.
- Parameters
npoints (
Optional
[int
]) – the approximate number of points to generate in the mesh- Return type
- Returns
list of points in degrees
- boundingBox()¶
Returns an ASTBox region that bounds this region where the box sides align with RA, dec.
- Return type
- boundingCircle()¶
Returns the smallest circle (
ASTCircle
) that bounds this region.It is up to the caller to know that this is a 2D region (only minimal checks are made). :raises cornish.exc.NotA2DRegion: raised when attempting to get a bounding circle for a region that is not 2D
- Return type
- property bounds: Tuple¶
Returns lower and upper coordinate points that bound this region.
- Return type
Tuple
- property center: numpy.ndarray¶
Returns “self.centre”. This is a British library, after all.
- Return type
- property centre: numpy.ndarray¶
Returns the location of the Box’s center as a coordinate pair, in degrees if a sky frame.
- Return type
- Returns
a Numpy array of points (axis1, axis2)
- containsPoint(point=None)¶
Returns
True
if the provided point lies inside this region,False
otherwise.This method is a direct synonym for
pointInRegion()
. The name “containsPoint” is more appropriate from an object perspective, but thepointInRegion
method is present for consistency with the AST library.- Parameters
point (
Union
[Iterable
,SkyCoord
,None
]) – a coordinate point in the same frame as this region- Return type
bool
- property corner: numpy.ndarray¶
Returns the location of one of the box’s corners as a coordinate pair, in degrees if a sky frame.
- Return type
- Returns
a Numpy array of points (axis1, axis2)
- corners(mapping=None)[source]¶
Returns a list of all four corners of box.
- Parameters
mapping (ASTMapping) – A mapping object.
- Returns
A list of points in degrees, e.g.
[(p1,p2), (p3, p4), (p5, p6), (p7, p8)]
- Return type
list
- 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 coordinatespoint2 (
Union
[Iterable
,SkyCoord
]) – a two element list/tuple/Numpy array or a SkyCoord of the second point coordinates
- Return type
- 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 fillFactor¶
<Fraction of the Region which is of interest>
- frame()¶
Returns a copy of the frame encapsulated by this region.
Note that the frame is not directly accessible; both this method and the underlying
starlink-pyast
function returns a copy.- Return type
- 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
]) – anAst.Frame
object
- static frameFromFITSHeader(header)¶
Factory method that returns a new ASTFrame from the provided FITS header.
- frameSet()¶
Returns a copy of the frameset encapsulated by this region.
From AST docs:
The base Frame is the Frame in which the box was originally defined, and the current Frame is the Frame into which the Region is currently mapped (i.e. it will be the same as the Frame returned by astGetRegionFrame).
- Return type
- 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.
- classmethod fromCentreAndCorner(frame, centre=None, corner=None, center=None, uncertainty=None)[source]¶
Create a new ASTBox object defined by the provided corner and centre points.
- Parameters
frame (
Union
[Frame
,ASTFrame
]) – the frame the provided points lie in, accepts eitherASTFrame
orstarlink.Ast.Frame
objectscentre (
Optional
[Iterable
]) – the coordinate of the point at the centre of the box in the frame providedcorner (
Optional
[Iterable
]) – the coordinate of the point at any corner of the box in the frame providedcenter (
Optional
[Iterable
]) – synonym for ‘centre’, ignored if ‘centre’ is defineduncertainty (
Union
[ASTRegion
,Region
,None
]) –
- Return type
- classmethod fromCorners(frame, corners=None, uncertainty=None)[source]¶
Create a new ASTBox object defined by two corner points.
- Parameters
frame (
Union
[Frame
,ASTFrame
]) – the frame the provided points lie in, accepts eitherASTFrame
orstarlink.Ast.Frame
objectscorners (
Optional
[Iterable
[Iterable
]]) – a collection (list, tuple, array, etc.) of coordinates of two corners of the box in the frame provideduncertainty (
Union
[ASTRegion
,Region
,None
]) –
- Return type
- classmethod fromFITSHeader(fits_header=None, uncertainty=4.848e-06)¶
Factory method to create a region from the provided FITS header; the returned object will be as specific as possible (but probably an
ASTPolygon
).The frame is determined from the FITS header.
- Parameters
fits_header – a FITS header (Astropy, fitsio, an array of cards)
uncertainty (
float
) – defaults to 4.848e-6, an uncertainty of 1 arcsec
- fullyEncloses(region)¶
Returns ‘True’ if this region fully encloses the provided region.
- Return type
bool
- 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
- interiorPointMesh(npoints=None)¶
Returns an array of evenly distributed points that cover the surface of the region. For example, if the region is a box, it will generate a list of points that fill the interior area of the box.
The default value of ‘npoints’ is 200 for 2D regions and 2000 for three or more dimensions.
- Parameters
npoints (
Optional
[int
]) – the approximate number of points to generate in the mesh- Returns
array of points in degrees
- 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 isAdaptive¶
Boolean attribute that indicates whether the area adapt to changes in the coordinate system.
- property isBounded: bool¶
Boolean attribute that indicates whether the region is bounded.
- Return type
bool
- property isClosed: bool¶
Boolean attribute that indicates whether the boundary be considered to be inside the region.
- Return type
bool
- isFullyWithin(region)¶
Returns ‘True’ if this region is fully within the provided region.
- Return type
bool
- isIdenticalTo(region)¶
Returns ‘True’ if this region is identical (to within their uncertainties) to the provided region, ‘False’ otherwise.
- Return type
bool
- property isLinear: bool¶
Returns True if the mapping is linear
- Return type
bool
- property isNegated¶
Boolean attribute that indicates whether the original region has been negated.
- isNegationOf(region)¶
Returns ‘True’ if this region is the exact negation of the provided region.
- 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
- mapRegionMesh(mapping=None, frame=None)¶
Returns a new ASTRegion that is the same as this one but with the specified coordinate system.
- Parameters
mapping (~cornish.mapping.ASTMapping class) – The mapping to transform positions from the current ASTRegion to those specified by the given frame.
frame (~cornish.frame.ASTFrame class) – Coordinate system frame to convert the current ASTRegion to.
- Returns
region – A new region object covering the same area but in the frame specified in frame.
- Return type
ASTRegion
- Raises
Exception – An exception is raised for missing parameters.
- maskOnto(image=None, mapping=None, fits_coordinates=True, lower_bounds=None, mask_inside=True, mask_value=nan)¶
Apply this region as a mask on top of the provided image; note: the image values are overwritten!
- Parameters
image – numpy.ndarray of pixel values (or other array of values)
mapping – mapping from this region to the pixel coordinates of the provided image
fits_coordinates (
bool
) – use the pixel coordinates of a FITS file (i.e. origin = [0.5, 0.5] for 2D)lower_bounds – lower bounds of provided image, only specify if not using FITS coordinates
mask_inside – True: mask the inside of this region; False: mask outside of this region
mask_value – the value to set the masked image pixels to
- Returns
number of pixels in image masked
- property meshSize: int¶
Number of points used to create a mesh covering the region.
- Return type
int
- property naxes: int¶
Returns the number of axes for the frame.
- Return type
int
- negate()¶
Negate the region, i.e. points inside the region will be outside, and vice versa.
- 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 coordinatespoint2 (
Iterable
) – a two element list/tuple/NumPy array of the second point coordinatesoffset (
Quantity
) – a distance along the geodesic sphere connecting the two points
- overlaps(region)¶
Return
True
if this region overlaps with the provided one.- Return type
bool
- pointInRegion(point)¶
Returns
True
if the provided point lies inside this region,False
otherwise.If no units are specified degrees are assumed.
- Parameters
point (
Union
[Iterable
,SkyCoord
,ndarray
]) – a coordinate point in the same frame as this region- Return type
bool
- property points: numpy.ndarray¶
The array of points that define the region. The interpretation of the points is dependent on the type of shape in question.
Box: returns two points; the center and a box corner. Circle: returns two points; the center and a point on the circumference. CmpRegion: no points returned; to get points that define a compound region, call this method on each of the component regions via the method “decompose”. Ellipse: three points: 1) center, 2) end of one axis, 3) end of the other axis Interval: two points: 1) lower bounds position, 2) upper bounds position (reversed when interval is an excluded interval) NullRegion: no points PointList: positions that the list was constructed with Polygon: vertex positions used to construct the polygon Prism: no points (see CmpRegion)
NOTE: points returned reflect the current coordinate system and may be different from the initial construction
- Return type
- Returns
NumPy array of coordinate points in degrees, shape (ncoord,2), e.g. [[ra1,dec1], [ra2, dec2], …, [ra_n, dec_n]]
- regionWithMapping(map=None, frame=None)¶
Returns a new ASTRegion with the coordinate system from the supplied frame.
Corresponds to the
astMapRegion
C function (starlink.Ast.mapregion
).- Parameters
map – A mapping that can convert coordinates from the system of the current region to that of the supplied frame.
frame – A frame containing the coordinate system for the new region.
- Return type
- Returns
new ASTRegion with a new coordinate system
- 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
- toPolygon(npoints=200, maxerr=<Quantity 1. arcsec>)[source]¶
Returns a four-vertex ASTPolygon that describes this box in the same frame.
The parameters ‘npoints’ and ‘maxerr’ are ignored.
- Return type
- 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
- property uncertainty¶
Uncertainties associated with the boundary of the Box.
The uncertainty in any point on the boundary of the Box is found by shifting the supplied “uncertainty” Region so that it is centered 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.
- unit(axis=None)¶
Return the unit for the specified axis.
ASTCircle¶
- class cornish.ASTCircle(ast_object=None, frame=None, center=None, edge_point=None, radius=None)[source]¶
Bases:
cornish.region.region.ASTRegion
ASTCircle is an
ASTRegion
that represents a circle.Accepted signatures for creating an ASTCircle
- Parameters
ast_object – a circle object from the
starlink-pyast
moduleframe – a frame the circle is to be defined in, uses
ASTICRSFrame
if Nonecenter – two elements that describe the center point of the circle in the provided frame in degrees
edge_point – two elements that describe a point on the circumference of the circle in the provided frame in degrees
radius – radius of the circle in degrees
- 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 vertexpoints (
Optional
[Container
[Union
[SkyCoord
,Iterable
]]]) – a two element list/tuple/etc. containing two points in this frame
- Return type
- property area¶
The area of the circle within its frame (e.g. on a Cartesian plane or sphere). [Not yet implemented.]
- property astString¶
Return the AST serialization of this object.
- ast_description()¶
A string description of this object, customized for each subclass of
ASTObject
.
- boundaryPointMesh(npoints=None)¶
Returns an array of evenly distributed points that cover the boundary of the region. For example, if the region is a box, it will generate a list of points that trace the edges of the box.
The default value of ‘npoints’ is 200 for 2D regions and 2000 for three or more dimensions.
- Parameters
npoints (
Optional
[int
]) – the approximate number of points to generate in the mesh- Return type
- Returns
list of points in degrees
- boundingBox()¶
Returns an ASTBox region that bounds this region where the box sides align with RA, dec.
- Return type
- boundingCircle()[source]¶
This method returns itself; a circle region is its own bounding circle.
- Return type
- property bounds: Tuple¶
Returns lower and upper coordinate points that bound this region.
- Return type
Tuple
- property center¶
The center of this circle region in degrees (a synonym for
self.centre()
” for the Americans).- Returns
- Return type
returns: a list of points [x,y] that describe the centre of the circle in degrees
- property centre¶
The centre of this circle region in degrees.
- Returns
- Return type
returns: a list of points [x,y] that describe the centre of the circle in degrees
- containsPoint(point=None)¶
Returns
True
if the provided point lies inside this region,False
otherwise.This method is a direct synonym for
pointInRegion()
. The name “containsPoint” is more appropriate from an object perspective, but thepointInRegion
method is present for consistency with the AST library.- Parameters
point (
Union
[Iterable
,SkyCoord
,None
]) – a coordinate point in the same frame as this region- Return type
bool
- 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 coordinatespoint2 (
Union
[Iterable
,SkyCoord
]) – a two element list/tuple/Numpy array or a SkyCoord of the second point coordinates
- Return type
- 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 fillFactor¶
<Fraction of the Region which is of interest>
- frame()¶
Returns a copy of the frame encapsulated by this region.
Note that the frame is not directly accessible; both this method and the underlying
starlink-pyast
function returns a copy.- Return type
- 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
]) – anAst.Frame
object
- static frameFromFITSHeader(header)¶
Factory method that returns a new ASTFrame from the provided FITS header.
- frameSet()¶
Returns a copy of the frameset encapsulated by this region.
From AST docs:
The base Frame is the Frame in which the box was originally defined, and the current Frame is the Frame into which the Region is currently mapped (i.e. it will be the same as the Frame returned by astGetRegionFrame).
- Return type
- 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.
- classmethod fromFITSHeader(fits_header=None, uncertainty=4.848e-06)¶
Factory method to create a region from the provided FITS header; the returned object will be as specific as possible (but probably an
ASTPolygon
).The frame is determined from the FITS header.
- Parameters
fits_header – a FITS header (Astropy, fitsio, an array of cards)
uncertainty (
float
) – defaults to 4.848e-6, an uncertainty of 1 arcsec
- fullyEncloses(region)¶
Returns ‘True’ if this region fully encloses the provided region.
- Return type
bool
- 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
- interiorPointMesh(npoints=None)¶
Returns an array of evenly distributed points that cover the surface of the region. For example, if the region is a box, it will generate a list of points that fill the interior area of the box.
The default value of ‘npoints’ is 200 for 2D regions and 2000 for three or more dimensions.
- Parameters
npoints (
Optional
[int
]) – the approximate number of points to generate in the mesh- Returns
array of points in degrees
- 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 isAdaptive¶
Boolean attribute that indicates whether the area adapt to changes in the coordinate system.
- property isBounded: bool¶
Boolean attribute that indicates whether the region is bounded.
- Return type
bool
- property isClosed: bool¶
Boolean attribute that indicates whether the boundary be considered to be inside the region.
- Return type
bool
- isFullyWithin(region)¶
Returns ‘True’ if this region is fully within the provided region.
- Return type
bool
- isIdenticalTo(region)¶
Returns ‘True’ if this region is identical (to within their uncertainties) to the provided region, ‘False’ otherwise.
- Return type
bool
- property isLinear: bool¶
Returns True if the mapping is linear
- Return type
bool
- property isNegated¶
Boolean attribute that indicates whether the original region has been negated.
- isNegationOf(region)¶
Returns ‘True’ if this region is the exact negation of the provided region.
- 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
- mapRegionMesh(mapping=None, frame=None)¶
Returns a new ASTRegion that is the same as this one but with the specified coordinate system.
- Parameters
mapping (~cornish.mapping.ASTMapping class) – The mapping to transform positions from the current ASTRegion to those specified by the given frame.
frame (~cornish.frame.ASTFrame class) – Coordinate system frame to convert the current ASTRegion to.
- Returns
region – A new region object covering the same area but in the frame specified in frame.
- Return type
ASTRegion
- Raises
Exception – An exception is raised for missing parameters.
- maskOnto(image=None, mapping=None, fits_coordinates=True, lower_bounds=None, mask_inside=True, mask_value=nan)¶
Apply this region as a mask on top of the provided image; note: the image values are overwritten!
- Parameters
image – numpy.ndarray of pixel values (or other array of values)
mapping – mapping from this region to the pixel coordinates of the provided image
fits_coordinates (
bool
) – use the pixel coordinates of a FITS file (i.e. origin = [0.5, 0.5] for 2D)lower_bounds – lower bounds of provided image, only specify if not using FITS coordinates
mask_inside – True: mask the inside of this region; False: mask outside of this region
mask_value – the value to set the masked image pixels to
- Returns
number of pixels in image masked
- property meshSize: int¶
Number of points used to create a mesh covering the region.
- Return type
int
- property naxes: int¶
Returns the number of axes for the frame.
- Return type
int
- negate()¶
Negate the region, i.e. points inside the region will be outside, and vice versa.
- 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 coordinatespoint2 (
Iterable
) – a two element list/tuple/NumPy array of the second point coordinatesoffset (
Quantity
) – a distance along the geodesic sphere connecting the two points
- overlaps(region)¶
Return
True
if this region overlaps with the provided one.- Return type
bool
- pointInRegion(point)¶
Returns
True
if the provided point lies inside this region,False
otherwise.If no units are specified degrees are assumed.
- Parameters
point (
Union
[Iterable
,SkyCoord
,ndarray
]) – a coordinate point in the same frame as this region- Return type
bool
- property points: numpy.ndarray¶
The array of points that define the region. The interpretation of the points is dependent on the type of shape in question.
Box: returns two points; the center and a box corner. Circle: returns two points; the center and a point on the circumference. CmpRegion: no points returned; to get points that define a compound region, call this method on each of the component regions via the method “decompose”. Ellipse: three points: 1) center, 2) end of one axis, 3) end of the other axis Interval: two points: 1) lower bounds position, 2) upper bounds position (reversed when interval is an excluded interval) NullRegion: no points PointList: positions that the list was constructed with Polygon: vertex positions used to construct the polygon Prism: no points (see CmpRegion)
NOTE: points returned reflect the current coordinate system and may be different from the initial construction
- Return type
- Returns
NumPy array of coordinate points in degrees, shape (ncoord,2), e.g. [[ra1,dec1], [ra2, dec2], …, [ra_n, dec_n]]
- property radius: astropy.units.quantity.Quantity¶
The radius of this circle region in degrees.
- Return type
- Returns
The radius as a geodesic distance in the associated coordinate system as an
astropy.units.Quantity
object in degrees.
- regionWithMapping(map=None, frame=None)¶
Returns a new ASTRegion with the coordinate system from the supplied frame.
Corresponds to the
astMapRegion
C function (starlink.Ast.mapregion
).- Parameters
map – A mapping that can convert coordinates from the system of the current region to that of the supplied frame.
frame – A frame containing the coordinate system for the new region.
- Return type
- Returns
new ASTRegion with a new coordinate system
- 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
- toPolygon(npoints=200, maxerr=<Quantity 1. arcsec>)[source]¶
Returns a new polygon region that approximates this circle in the same frame.
The algorithm used in this method leads to the new polygon being fully inscribed by the originating circle; all points generated are on the circle’s circumference. Although the default number of points is 200, typically a much smaller number (e.g. 20) is sufficient.
- Parameters
npoints – number of points to sample from the circle for the resulting polygon
maxerr (
Quantity
) –
- 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
- property uncertainty¶
Uncertainties associated with the boundary of the Box.
The uncertainty in any point on the boundary of the Box is found by shifting the supplied “uncertainty” Region so that it is centered 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.
- unit(axis=None)¶
Return the unit for the specified axis.
ASTCompoundRegion¶
- class cornish.ASTCompoundRegion(ast_object=None, regions=None, operation=None)[source]¶
Bases:
cornish.region.region.ASTRegion
A region that is created as the composite of multiple regions.
Regions are composited two at a time in the order they are supplied, e.g. if regions=[r1, r2, r3, r4] the result would be
region = compound( compound( compound(r1, r2), r3 ) r4 )
all using the same operator as specified.
- Parameters
regions (
Optional
[Iterable
[Union
[ASTRegion
,Region
]]]) – a list of regions to compoundoperation (
Optional
[int
]) – one of starlink.Ast.AND, `starlink.Ast.OR, starlink.Ast.XOR
- 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 vertexpoints (
Optional
[Container
[Union
[SkyCoord
,Iterable
]]]) – a two element list/tuple/etc. containing two points in this frame
- Return type
- property area¶
The area of the compound region on the sphere. [Not yet implemented.]
- property astString¶
Return the AST serialization of this object.
- ast_description()¶
A string description of this object, customized for each subclass of
ASTObject
.
- boundaryPointMesh(npoints=None)¶
Returns an array of evenly distributed points that cover the boundary of the region. For example, if the region is a box, it will generate a list of points that trace the edges of the box.
The default value of ‘npoints’ is 200 for 2D regions and 2000 for three or more dimensions.
- Parameters
npoints (
Optional
[int
]) – the approximate number of points to generate in the mesh- Return type
- Returns
list of points in degrees
- boundingBox()¶
Returns an ASTBox region that bounds this region where the box sides align with RA, dec.
- Return type
- boundingCircle()¶
Returns the smallest circle (
ASTCircle
) that bounds this region.It is up to the caller to know that this is a 2D region (only minimal checks are made). :raises cornish.exc.NotA2DRegion: raised when attempting to get a bounding circle for a region that is not 2D
- Return type
- property bounds: Tuple¶
Returns lower and upper coordinate points that bound this region.
- Return type
Tuple
- containsPoint(point=None)¶
Returns
True
if the provided point lies inside this region,False
otherwise.This method is a direct synonym for
pointInRegion()
. The name “containsPoint” is more appropriate from an object perspective, but thepointInRegion
method is present for consistency with the AST library.- Parameters
point (
Union
[Iterable
,SkyCoord
,None
]) – a coordinate point in the same frame as this region- Return type
bool
- 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 coordinatespoint2 (
Union
[Iterable
,SkyCoord
]) – a two element list/tuple/Numpy array or a SkyCoord of the second point coordinates
- Return type
- 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 fillFactor¶
<Fraction of the Region which is of interest>
- frame()¶
Returns a copy of the frame encapsulated by this region.
Note that the frame is not directly accessible; both this method and the underlying
starlink-pyast
function returns a copy.- Return type
- 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
]) – anAst.Frame
object
- static frameFromFITSHeader(header)¶
Factory method that returns a new ASTFrame from the provided FITS header.
- frameSet()¶
Returns a copy of the frameset encapsulated by this region.
From AST docs:
The base Frame is the Frame in which the box was originally defined, and the current Frame is the Frame into which the Region is currently mapped (i.e. it will be the same as the Frame returned by astGetRegionFrame).
- Return type
- 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.
- classmethod fromFITSHeader(fits_header=None, uncertainty=4.848e-06)¶
Factory method to create a region from the provided FITS header; the returned object will be as specific as possible (but probably an
ASTPolygon
).The frame is determined from the FITS header.
- Parameters
fits_header – a FITS header (Astropy, fitsio, an array of cards)
uncertainty (
float
) – defaults to 4.848e-6, an uncertainty of 1 arcsec
- fullyEncloses(region)¶
Returns ‘True’ if this region fully encloses the provided region.
- Return type
bool
- 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
- interiorPointMesh(npoints=None)¶
Returns an array of evenly distributed points that cover the surface of the region. For example, if the region is a box, it will generate a list of points that fill the interior area of the box.
The default value of ‘npoints’ is 200 for 2D regions and 2000 for three or more dimensions.
- Parameters
npoints (
Optional
[int
]) – the approximate number of points to generate in the mesh- Returns
array of points in degrees
- 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 isAdaptive¶
Boolean attribute that indicates whether the area adapt to changes in the coordinate system.
- property isBounded: bool¶
Boolean attribute that indicates whether the region is bounded.
- Return type
bool
- property isClosed: bool¶
Boolean attribute that indicates whether the boundary be considered to be inside the region.
- Return type
bool
- isFullyWithin(region)¶
Returns ‘True’ if this region is fully within the provided region.
- Return type
bool
- isIdenticalTo(region)¶
Returns ‘True’ if this region is identical (to within their uncertainties) to the provided region, ‘False’ otherwise.
- Return type
bool
- property isLinear: bool¶
Returns True if the mapping is linear
- Return type
bool
- property isNegated¶
Boolean attribute that indicates whether the original region has been negated.
- isNegationOf(region)¶
Returns ‘True’ if this region is the exact negation of the provided region.
- 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
- mapRegionMesh(mapping=None, frame=None)¶
Returns a new ASTRegion that is the same as this one but with the specified coordinate system.
- Parameters
mapping (~cornish.mapping.ASTMapping class) – The mapping to transform positions from the current ASTRegion to those specified by the given frame.
frame (~cornish.frame.ASTFrame class) – Coordinate system frame to convert the current ASTRegion to.
- Returns
region – A new region object covering the same area but in the frame specified in frame.
- Return type
ASTRegion
- Raises
Exception – An exception is raised for missing parameters.
- maskOnto(image=None, mapping=None, fits_coordinates=True, lower_bounds=None, mask_inside=True, mask_value=nan)¶
Apply this region as a mask on top of the provided image; note: the image values are overwritten!
- Parameters
image – numpy.ndarray of pixel values (or other array of values)
mapping – mapping from this region to the pixel coordinates of the provided image
fits_coordinates (
bool
) – use the pixel coordinates of a FITS file (i.e. origin = [0.5, 0.5] for 2D)lower_bounds – lower bounds of provided image, only specify if not using FITS coordinates
mask_inside – True: mask the inside of this region; False: mask outside of this region
mask_value – the value to set the masked image pixels to
- Returns
number of pixels in image masked
- property meshSize: int¶
Number of points used to create a mesh covering the region.
- Return type
int
- property naxes: int¶
Returns the number of axes for the frame.
- Return type
int
- negate()¶
Negate the region, i.e. points inside the region will be outside, and vice versa.
- 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 coordinatespoint2 (
Iterable
) – a two element list/tuple/NumPy array of the second point coordinatesoffset (
Quantity
) – a distance along the geodesic sphere connecting the two points
- overlaps(region)¶
Return
True
if this region overlaps with the provided one.- Return type
bool
- pointInRegion(point)¶
Returns
True
if the provided point lies inside this region,False
otherwise.If no units are specified degrees are assumed.
- Parameters
point (
Union
[Iterable
,SkyCoord
,ndarray
]) – a coordinate point in the same frame as this region- Return type
bool
- property points: numpy.ndarray¶
The array of points that define the region. The interpretation of the points is dependent on the type of shape in question.
Box: returns two points; the center and a box corner. Circle: returns two points; the center and a point on the circumference. CmpRegion: no points returned; to get points that define a compound region, call this method on each of the component regions via the method “decompose”. Ellipse: three points: 1) center, 2) end of one axis, 3) end of the other axis Interval: two points: 1) lower bounds position, 2) upper bounds position (reversed when interval is an excluded interval) NullRegion: no points PointList: positions that the list was constructed with Polygon: vertex positions used to construct the polygon Prism: no points (see CmpRegion)
NOTE: points returned reflect the current coordinate system and may be different from the initial construction
- Return type
- Returns
NumPy array of coordinate points in degrees, shape (ncoord,2), e.g. [[ra1,dec1], [ra2, dec2], …, [ra_n, dec_n]]
- regionWithMapping(map=None, frame=None)¶
Returns a new ASTRegion with the coordinate system from the supplied frame.
Corresponds to the
astMapRegion
C function (starlink.Ast.mapregion
).- Parameters
map – A mapping that can convert coordinates from the system of the current region to that of the supplied frame.
frame – A frame containing the coordinate system for the new region.
- Return type
- Returns
new ASTRegion with a new coordinate system
- 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
- abstract toPolygon(npoints=200, maxerr=<Quantity 1. arcsec>)¶
Method that guarantees returning a polygon that describes or approximates this region.
This method provides a common interface to create polygons from different region types. Calling this on an ASTPolygon will return itself; calling it on an ASTCircle will return a polygon that approximates the circle. The parameters ‘npoints’ and ‘maxerr’ will be used only when appropriate.
- Parameters
npoints – number of points to sample from the region’s boundary for the resulting polygon
maxerr (astropy.units.Quantity) –
- Return type
- 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
- property uncertainty¶
Uncertainties associated with the boundary of the Box.
The uncertainty in any point on the boundary of the Box is found by shifting the supplied “uncertainty” Region so that it is centered 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.
- unit(axis=None)¶
Return the unit for the specified axis.
ASTPolygon¶
- class cornish.ASTPolygon(ast_object=None, frame=None, points=None, fits_header=None)[source]¶
Bases:
cornish.region.region.ASTRegion
ASTPolygon is an ASTRegion that represents a polygon, a collection of vertices on a sphere in a 2D plane.
Accepted signatures for creating an ASTPolygon:
p = ASTPolygon(frame, points) p = ASTPolygon(fits_header, points) # get the frame from the FITS header provided p = ASTPolygon(ast_object) # where ast_object is a starlink.Ast.Polygon object
Points may be provided as a list of coordinate points, e.g.
[(x1, y1), (x2, y2), ... , (xn, yn)]
or as two parallel arrays, e.g.
[[x1, x2, x3, ..., xn], [y1, y2, y3, ..., yn]]
A string format that can be parsed as above is also accepted, e.g.:
"((131.758,5.366),(131.759,3.766),(132.561,3.767),(133.363,3.766),(133.364,5.366),(132.577,5.367))"
- Parameters
ast_object (
Optional
[Polygon
]) – create a new ASTPolygon from an existingstarlink.Ast.Polygon
objectframe (
Union
[ASTFrame
,Frame
,ASTRegion
,Region
,None
]) – the frame the provided points lie in, accepts eitherASTFrame
orstarlink.Ast.Frame
objectspoints – points in degrees that describe the polygon, may be a list of pairs of points or two parallel arrays of axis points
- Returns
Returns a new
ASTPolygon
object.
- 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 vertexpoints (
Optional
[Container
[Union
[SkyCoord
,Iterable
]]]) – a two element list/tuple/etc. containing two points in this frame
- Return type
- property area: astropy.units.quantity.Quantity¶
Returns the area of the polygon as an
astropy.units.quantity.Quantity
. [Not yet implemented for non-sky frames.]- Return type
- property astString¶
Return the AST serialization of this object.
- ast_description()¶
A string description of this object, customized for each subclass of
ASTObject
.
- boundaryPointMesh(npoints=None)¶
Returns an array of evenly distributed points that cover the boundary of the region. For example, if the region is a box, it will generate a list of points that trace the edges of the box.
The default value of ‘npoints’ is 200 for 2D regions and 2000 for three or more dimensions.
- Parameters
npoints (
Optional
[int
]) – the approximate number of points to generate in the mesh- Return type
- Returns
list of points in degrees
- boundingBox()¶
Returns an ASTBox region that bounds this region where the box sides align with RA, dec.
- Return type
- boundingCircle()¶
Returns the smallest circle (
ASTCircle
) that bounds this region.It is up to the caller to know that this is a 2D region (only minimal checks are made). :raises cornish.exc.NotA2DRegion: raised when attempting to get a bounding circle for a region that is not 2D
- Return type
- property bounds: Tuple¶
Returns lower and upper coordinate points that bound this region.
- Return type
Tuple
- containsPoint(point=None)¶
Returns
True
if the provided point lies inside this region,False
otherwise.This method is a direct synonym for
pointInRegion()
. The name “containsPoint” is more appropriate from an object perspective, but thepointInRegion
method is present for consistency with the AST library.- Parameters
point (
Union
[Iterable
,SkyCoord
,None
]) – a coordinate point in the same frame as this region- Return type
bool
- 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 coordinatespoint2 (
Union
[Iterable
,SkyCoord
]) – a two element list/tuple/Numpy array or a SkyCoord of the second point coordinates
- Return type
- 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
- downsize(maxerr=None, maxvert=0)[source]¶
Returns a new ASTPolygon that contains a subset of the vertices of this polygon.
The subset is chosen so that the returned polygon is a good approximation of this polygon, within the limits specified. The density of points in the new polygon is greater where the curvature of the boundary is greater.
The ‘maxerr’ parameter set the maximum allowed discrepancy between the original and new polygons as a geodesic distance within the polygon’s coordinate frame. Setting this to zero returns a new polygon with the number of vertices set in “maxvert”.
The ‘maxvert’ parameter set the maximum number of vertices the new polygon can have. If this is less than 3, the number of vertices in the returned polygon will be the minimum needed to achieve the maximum discrepancy specified by “maxerr”. The unadorned value is in radians, but accepts Astropy unit objects.
- Parameters
maxerr – maximum allowed discrepancy in radians between the original and new polygons as a geodesic distance within the polygon’s coordinate frame
maxvert – maximum allowed number of vertices in the returned polygon
- Returns
a new ASTPolygon.
- property fillFactor¶
<Fraction of the Region which is of interest>
- frame()¶
Returns a copy of the frame encapsulated by this region.
Note that the frame is not directly accessible; both this method and the underlying
starlink-pyast
function returns a copy.- Return type
- 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
]) – anAst.Frame
object
- static frameFromFITSHeader(header)¶
Factory method that returns a new ASTFrame from the provided FITS header.
- frameSet()¶
Returns a copy of the frameset encapsulated by this region.
From AST docs:
The base Frame is the Frame in which the box was originally defined, and the current Frame is the Frame into which the Region is currently mapped (i.e. it will be the same as the Frame returned by astGetRegionFrame).
- Return type
- 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.
- static fromFITSFilepath(path=None, hdu=1)[source]¶
Create a polygon bounding the region of a 2D image.
- Parameters
path (
Union
[str
,PathLike
,None
]) – the path to the FITS filehdu (
int
) – the HDU to open, first HDU = 1
- static fromFITSHeader(header=None, uncertainty=4.848e-06)[source]¶
Creates an ASTPolygon in a sky frame from a FITS header. Header of HDU must be a 2D image and contain WCS information.
- Parameters
header – a FITS header
uncertainty – TODO: parameter not yet used
- static fromPointsOnSkyFrame(frame=None, points=None, expand_by=<Quantity 20. pix>)[source]¶
Create an
ASTPolygon
specifically in a sky frame from an array of points.Points can be provided in degrees either as an array or coordinate pairs, e.g.
np.array([[1,2], [3,4], [5,6]])
or as parallel arrays of ra,dec:
np.array([[1,3,5], [2,4,6]])
- Parameters
points (
Optional
[ndarray
]) – coordinate points, either as a list of coordinate pairs or two parallel ra,dec arraysframe (
Optional
[ASTSkyFrame
]) – the frame the points lie in, specified as anASTSkyFrame
objectexpand_by (
Quantity
) – number of pixels to extend the polygon beyond the provided points
- Returns
new
ASTPolygon
object
- fullyEncloses(region)¶
Returns ‘True’ if this region fully encloses the provided region.
- Return type
bool
- 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
- interiorPointMesh(npoints=None)¶
Returns an array of evenly distributed points that cover the surface of the region. For example, if the region is a box, it will generate a list of points that fill the interior area of the box.
The default value of ‘npoints’ is 200 for 2D regions and 2000 for three or more dimensions.
- Parameters
npoints (
Optional
[int
]) – the approximate number of points to generate in the mesh- Returns
array of points in degrees
- 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 isAdaptive¶
Boolean attribute that indicates whether the area adapt to changes in the coordinate system.
- property isBounded: bool¶
Boolean attribute that indicates whether the region is bounded.
- Return type
bool
- property isClosed: bool¶
Boolean attribute that indicates whether the boundary be considered to be inside the region.
- Return type
bool
- isFullyWithin(region)¶
Returns ‘True’ if this region is fully within the provided region.
- Return type
bool
- isIdenticalTo(region)¶
Returns ‘True’ if this region is identical (to within their uncertainties) to the provided region, ‘False’ otherwise.
- Return type
bool
- property isLinear: bool¶
Returns True if the mapping is linear
- Return type
bool
- property isNegated¶
Boolean attribute that indicates whether the original region has been negated.
- isNegationOf(region)¶
Returns ‘True’ if this region is the exact negation of the provided region.
- 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
- mapRegionMesh(mapping=None, frame=None)¶
Returns a new ASTRegion that is the same as this one but with the specified coordinate system.
- Parameters
mapping (~cornish.mapping.ASTMapping class) – The mapping to transform positions from the current ASTRegion to those specified by the given frame.
frame (~cornish.frame.ASTFrame class) – Coordinate system frame to convert the current ASTRegion to.
- Returns
region – A new region object covering the same area but in the frame specified in frame.
- Return type
ASTRegion
- Raises
Exception – An exception is raised for missing parameters.
- maskOnto(image=None, mapping=None, fits_coordinates=True, lower_bounds=None, mask_inside=True, mask_value=nan)¶
Apply this region as a mask on top of the provided image; note: the image values are overwritten!
- Parameters
image – numpy.ndarray of pixel values (or other array of values)
mapping – mapping from this region to the pixel coordinates of the provided image
fits_coordinates (
bool
) – use the pixel coordinates of a FITS file (i.e. origin = [0.5, 0.5] for 2D)lower_bounds – lower bounds of provided image, only specify if not using FITS coordinates
mask_inside – True: mask the inside of this region; False: mask outside of this region
mask_value – the value to set the masked image pixels to
- Returns
number of pixels in image masked
- property meshSize: int¶
Number of points used to create a mesh covering the region.
- Return type
int
- property naxes: int¶
Returns the number of axes for the frame.
- Return type
int
- negate()¶
Negate the region, i.e. points inside the region will be outside, and vice versa.
- 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 coordinatespoint2 (
Iterable
) – a two element list/tuple/NumPy array of the second point coordinatesoffset (
Quantity
) – a distance along the geodesic sphere connecting the two points
- overlaps(region)¶
Return
True
if this region overlaps with the provided one.- Return type
bool
- pointInRegion(point)¶
Returns
True
if the provided point lies inside this region,False
otherwise.If no units are specified degrees are assumed.
- Parameters
point (
Union
[Iterable
,SkyCoord
,ndarray
]) – a coordinate point in the same frame as this region- Return type
bool
- property points: numpy.ndarray¶
The array of points that define the region. The interpretation of the points is dependent on the type of shape in question.
Box: returns two points; the center and a box corner. Circle: returns two points; the center and a point on the circumference. CmpRegion: no points returned; to get points that define a compound region, call this method on each of the component regions via the method “decompose”. Ellipse: three points: 1) center, 2) end of one axis, 3) end of the other axis Interval: two points: 1) lower bounds position, 2) upper bounds position (reversed when interval is an excluded interval) NullRegion: no points PointList: positions that the list was constructed with Polygon: vertex positions used to construct the polygon Prism: no points (see CmpRegion)
NOTE: points returned reflect the current coordinate system and may be different from the initial construction
- Return type
- Returns
NumPy array of coordinate points in degrees, shape (ncoord,2), e.g. [[ra1,dec1], [ra2, dec2], …, [ra_n, dec_n]]
- regionWithMapping(map=None, frame=None)¶
Returns a new ASTRegion with the coordinate system from the supplied frame.
Corresponds to the
astMapRegion
C function (starlink.Ast.mapregion
).- Parameters
map – A mapping that can convert coordinates from the system of the current region to that of the supplied frame.
frame – A frame containing the coordinate system for the new region.
- Return type
- Returns
new ASTRegion with a new coordinate system
- 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
- toPolygon(npoints=200, maxerr=<Quantity 1. arcsec>)[source]¶
Common interface to return a polygon from a region; here ‘self’ is returned.
The parameters ‘npoints’ and ‘maxerr’ are ignored.
- Return type
- 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
- property uncertainty¶
Uncertainties associated with the boundary of the Box.
The uncertainty in any point on the boundary of the Box is found by shifting the supplied “uncertainty” Region so that it is centered 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.
- unit(axis=None)¶
Return the unit for the specified axis.