PolygonAperture#

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

Bases: PixelAperture

A polygon aperture defined in pixel coordinates.

The aperture has a single fixed shape, defined by vertex_offsets relative to each positions entry, but it can have multiple positions.

Parameters:

positionsarray_like

The pixel coordinates of the aperture center(s) in one of the following formats:

single (x, y) pair as a tuple, list, or ndarray
tuple, list, or ndarray of (x, y) pairs

vertex_offsetsarray_like

Shape (n_vertices, 2). The pixel-space offsets (dx, dy) of each polygon vertex relative to positions. The polygon must be simple (non-self-intersecting) with at least 3 vertices. The polygon may be convex or non-convex. Either clockwise or counter-clockwise vertex orderings are accepted; the input is normalized to counter-clockwise internally.

Raises:

ValueErrorValueError: If vertex_offsets is not a valid simple polygon with at least 3 vertices.

Examples

>>> import numpy as np
>>> from photutils.aperture import PolygonAperture
>>> # A regular hexagon centered on (10, 20) with circumradius 5.
>>> theta = np.linspace(0.0, 2 * np.pi, 6, endpoint=False)
>>> offsets = np.column_stack([5.0 * np.cos(theta),
...                            5.0 * np.sin(theta)])
>>> aper = PolygonAperture((10.0, 20.0), offsets)

Construct a single polygon directly from absolute vertex coordinates:

>>> verts = [(0.0, 0.0), (4.0, 0.0), (4.0, 3.0)]
>>> aper = PolygonAperture.from_vertices(verts)

Attributes Summary

`area`	The exact geometric area of the aperture shape.
`bbox`	The minimal bounding box for the aperture.
`exterior_angle`	The exterior angle of the regular polygon as an angular `Quantity` in degrees.
`inner_radius`	The inner (inscribed-circle) radius of the regular polygon in pixels, 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 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 outer (circumscribed-circle) radius of the regular polygon in pixels, i.e., the distance from `positions` to each vertex.
`perimeter`	The perimeter of the polygon in pixels.
`positions`	The center pixel position(s).
`shape`	The shape of the instance.
`side_length`	The side length of the regular polygon, in pixels.
`theta`	The rotation angle of the regular polygon as an angular `Quantity` in degrees.
`vertex_offsets`	The (n_vertices, 2) array of pixel offsets of the polygon vertices, measured relative to `positions`.
`vertices`	The absolute pixel `(x, y)` vertices of the polygon at each aperture position.

Methods Summary

`area_overlap`(data, *[, mask, method, subpixels])	Return the area of overlap between the data and the aperture.
`copy`()	Make a deep copy of this object.
`do_photometry`(data[, error, mask, method, ...])	Perform aperture photometry on the input data.
`from_regular_polygon`(positions, n_vertices, ...)	Construct a regular `PolygonAperture` from a center, vertex count, circumradius, and rotation angle.
`from_vertices`(vertices)	Construct a `PolygonAperture` from a single set of absolute pixel vertices.
`plot`([ax, origin])	Plot the aperture on a matplotlib `Axes` instance.
`to_mask`([method, subpixels])	Return a mask for the aperture.
`to_sky`(wcs)	Convert the aperture to a `SkyPolygonAperture` object defined in celestial coordinates.

Attributes Documentation

area#: The exact geometric area of the aperture shape.

bbox#

The minimal bounding box for the aperture.

If the aperture is scalar then a single BoundingBox is returned, otherwise a list of BoundingBox is returned.

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 inner (inscribed-circle) radius of the regular polygon in pixels, 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 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 outer (circumscribed-circle) radius of the regular polygon in pixels, 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 perimeter of the polygon in pixels.

The perimeter is computed as the sum of the Euclidean distances between consecutive vertices.

positions#: The center pixel position(s).

shape#: The shape of the instance.

side_length#

The side length of the regular polygon, in pixels.

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 +y axis to the first vertex, in the range [0, 360) deg. 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) array of pixel offsets of the polygon vertices, measured relative to positions.

vertices#

The absolute pixel (x, y) vertices of the polygon at each aperture position.

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

Methods Documentation

area_overlap(data, *, mask=None, method='exact', subpixels=5)#

Return the area of overlap between the data and the aperture.

This method takes into account the aperture mask method, masked data pixels (mask keyword), and partial/no overlap of the aperture with the data. In other words, it returns the area that used to compute the aperture sum (assuming identical inputs).

Use the area method to calculate the exact analytical area of the aperture shape.

Parameters:

dataarray_like or Quantity

A 2D array.

maskarray_like (bool), optional

A boolean mask with the same shape as data where a True value indicates the corresponding element of data is masked. Masked data are excluded from the area overlap.

method{‘exact’, ‘center’, ‘subpixel’}, optional

The method used to determine the pixel weights (the fraction of the pixel area covered by the aperture):

'exact' (default): Calculates the exact geometric overlap area. Weights are continuous in the range [0, 1].
'center': Binary weighting based on the pixel center. Weights are either 0 or 1. A pixel is included only if its center lies strictly inside the aperture; pixel centers lying exactly on the aperture boundary are excluded (weight 0).
'subpixel': Approximates the overlap by averaging binary samples on a subgrid. The number of samples is set by the subpixels parameter. Weights are discrete in the range [0, 1]. A subpixel is included only if its center lies strictly inside the aperture; subpixel centers lying exactly on the aperture boundary are excluded (weight 0).

subpixelsint, optional

The subsampling factor per axis used when method='subpixel'. Each pixel is divided into a grid of subpixels**2 subpixels to approximate the overlap. This parameter is ignored for other methods.

Returns:

areasfloat or array_like: The area (in pixels**2) of overlap between the data and the aperture.