SkyPolygonAperture#

class photutils.aperture.SkyPolygonAperture(positions, vertex_offsets)[source]#

Bases: SkyAperture

A polygon aperture defined in sky coordinates.

The aperture has a single fixed shape, defined by angular vertex_offsets relative to each positions entry, but it can have multiple positions. The angular offsets are interpreted on the local tangent plane at each position.

Parameters:

positionsSkyCoord: The celestial coordinates of the aperture center(s). This can be either scalar coordinates or an array of coordinates.
vertex_offsetsQuantity: Shape (n_vertices, 2) angular Quantity of polygon vertex offsets (d_lon, d_lat) relative to positions, applied as spherical offsets on the local tangent plane. The polygon must be simple (non-self-intersecting) with at least 3 vertices. The polygon may be convex or non-convex.

Examples

>>> import astropy.units as u
>>> import numpy as np
>>> from astropy.coordinates import SkyCoord
>>> from photutils.aperture import SkyPolygonAperture
>>> positions = SkyCoord(ra=[10.0, 20.0], dec=[30.0, 40.0], unit='deg')
>>> theta = np.linspace(0, 2 * np.pi, 5, endpoint=False)
>>> r = 1.0
>>> offsets = np.column_stack([r * np.cos(theta),
...                            r * np.sin(theta)]) * u.arcsec
>>> aper = SkyPolygonAperture(positions, offsets)

Attributes Summary

`exterior_angle`	The exterior angle of the regular polygon as an angular `Quantity` in degrees.
`inner_radius`	The angular inner (inscribed-circle) radius of the regular polygon as a `Quantity`, i.e., the distance from `positions` to the midpoint of each side.
`interior_angle`	The interior angle of the regular polygon as an angular `Quantity` in degrees.
`is_regular`	`True` if the polygon is regular (equal-length sides and equal interior angles, with all vertices at the same angular distance from `positions`).
`isscalar`	Whether the instance is scalar (i.e., a single position).
`n_vertices`	The number of vertices of the polygon.
`outer_radius`	The angular outer (circumscribed-circle) radius of the regular polygon as a `Quantity`, i.e., the distance from `positions` to each vertex.
`perimeter`	The angular perimeter of the polygon as a `Quantity`.
`positions`	The center position(s) in sky coordinates.
`shape`	The shape of the instance.
`side_length`	The angular side length of the regular polygon as a `Quantity`.
`theta`	The rotation angle of the regular polygon as an angular `Quantity` in degrees.
`vertex_offsets`	The (n_vertices, 2) angular Quantity of polygon vertex offsets (d_lon, d_lat) relative to `positions`.
`vertices`	The absolute sky vertices of the polygon at each aperture position, as a `SkyCoord`.

Methods Summary

`copy`()	Make a deep copy of this object.
`from_regular_polygon`(positions, n_vertices, ...)	Construct a regular `SkyPolygonAperture` from a center, vertex count, angular circumradius, and rotation angle.
`from_vertices`(vertices)	Construct a `SkyPolygonAperture` from a single set of absolute sky vertices.
`to_pixel`(wcs)	Convert the aperture to a `PolygonAperture` object defined in pixel coordinates.

Attributes Documentation

exterior_angle#

The exterior angle of the regular polygon as an angular Quantity in degrees.

This attribute is only defined for regular polygons. Accessing it for a non-regular polygon raises ValueError.

inner_radius#

The angular inner (inscribed-circle) radius of the regular polygon as a Quantity, i.e., the distance from positions to the midpoint of each side.

This is also called the inradius

This attribute is only defined for regular polygons. Accessing it for a non-regular polygon raises ValueError.

interior_angle#

The interior angle of the regular polygon as an angular Quantity in degrees.

This attribute is only defined for regular polygons. Accessing it for a non-regular polygon raises ValueError.

is_regular#: True if the polygon is regular (equal-length sides and equal interior angles, with all vertices at the same angular distance from positions).

isscalar#: Whether the instance is scalar (i.e., a single position).

n_vertices#: The number of vertices of the polygon.

outer_radius#

The angular outer (circumscribed-circle) radius of the regular polygon as a Quantity, i.e., the distance from positions to each vertex.

This is also called the circumradius.

This attribute is only defined for regular polygons. Accessing it for a non-regular polygon raises ValueError.

perimeter#

The angular perimeter of the polygon as a Quantity.

The perimeter is computed as the sum of the angular distances between consecutive vertices on the local tangent plane.

positions#: The center position(s) in sky coordinates.

shape#: The shape of the instance.

side_length#

The angular side length of the regular polygon as a Quantity.

This attribute is only defined for regular polygons. Accessing it for a non-regular polygon raises ValueError.

theta#

The rotation angle of the regular polygon as an angular Quantity in degrees.

The angle is measured counter-clockwise from the +lat axis on the local tangent plane to the first vertex, in the range [0, 360) deg. This assumes a right-handed coordinate system (e.g., standard celestial coordinates). This convention matches the theta parameter of from_regular_polygon.

This attribute is only defined for regular polygons. Accessing it for a non-regular polygon raises ValueError.

vertex_offsets#: The (n_vertices, 2) angular Quantity of polygon vertex offsets (d_lon, d_lat) relative to positions.

vertices#

The absolute sky vertices of the polygon at each aperture position, as a SkyCoord.

For a scalar aperture, the returned SkyCoord has shape (n_vertices,). For an aperture with n_positions positions, the returned SkyCoord has shape (n_positions, n_vertices).

Methods Documentation

copy()#

Make a deep copy of this object.

Returns:

resultAperture: A deep copy of the Aperture object.

classmethod from_regular_polygon(positions, n_vertices, radius, *, theta=<Quantity 0. deg>)[source]#

Construct a regular SkyPolygonAperture from a center, vertex count, angular circumradius, and rotation angle.

The first vertex is placed at the +lat edge of the local tangent plane (typically northward for standard right-handed celestial coordinates) for theta == 0 and is rotated counter-clockwise by theta.

Parameters:

positionsSkyCoord: The celestial coordinates of the aperture center(s).
n_verticesint: The number of vertices (must be at least 3).
radiusQuantity: The angular circumradius (outer radius) of the polygon (must be a positive angular Quantity).
thetaQuantity, optional: The rotation angle of the polygon, measured counter- clockwise from the +lat axis on the local tangent plane. This assumes a right-handed coordinate system (e.g., standard celestial coordinates).

Returns:

apertureSkyPolygonAperture: The regular sky polygon aperture.

classmethod from_vertices(vertices)[source]#

Construct a SkyPolygonAperture from a single set of absolute sky vertices.

The aperture’s positions is set to an approximate centroid of the input vertices, computed as a single tangent-plane mean of the spherical offsets from the first vertex (i.e., the vertices’ spherical offsets from this centroid average to approximately zero), and vertex_offsets is set to the spherical offsets of the vertices from this centroid.

Parameters:

verticesSkyCoord: A SkyCoord with shape (n_vertices,) of absolute polygon vertex coordinates.

Returns:

apertureSkyPolygonAperture: A scalar sky polygon aperture whose vertices property reproduces the input.

to_pixel(wcs)[source]#

Convert the aperture to a PolygonAperture object defined in pixel coordinates.

The conversion uses wcs.world_to_pixel directly on the absolute sky vertex coordinate, evaluated at the first aperture position.

Parameters:

wcsWCS object: A world coordinate system (WCS) transformation that supports the astropy shared interface for WCS (e.g., astropy.wcs.WCS, gwcs.wcs.WCS).

Returns:

aperturePolygonAperture: The equivalent pixel-coordinate polygon aperture.