# CircularAperture¶

class photutils.aperture.CircularAperture(positions, r)[source]

A circular aperture defined in pixel coordinates.

The aperture has a single fixed size/shape, but it can have multiple positions (see the `positions` input).

Parameters:
positionsarray_like

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

rfloat

The radius of the circle in pixels.

Raises:
ValueError`ValueError`

If the input radius, `r`, is negative.

Examples

```>>> from photutils.aperture import CircularAperture
>>> aper = CircularAperture([10.0, 20.0], 3.0)
>>> aper = CircularAperture((10.0, 20.0), 3.0)
```
```>>> pos1 = (10.0, 20.0)  # (x, y)
>>> pos2 = (30.0, 40.0)
>>> pos3 = (50.0, 60.0)
>>> aper = CircularAperture([pos1, pos2, pos3], 3.0)
>>> aper = CircularAperture((pos1, pos2, pos3), 3.0)
```

Attributes Summary

 `area` The exact analytical area of the aperture shape. `bbox` The minimal bounding box for the aperture. `isscalar` Whether the instance is scalar (i.e., a single position). `positions` The center pixel position(s). `r` The radius in pixels. `shape` The shape of the instance.

Methods Summary

 `area_overlap`(data, *[, mask, method, subpixels]) Return the area of overlap between the data and the aperture. Make an independent (deep) copy. `do_photometry`(data[, error, mask, method, ...]) Perform aperture photometry on the input data. `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 `SkyCircularAperture` object defined in celestial coordinates.

Attributes Documentation

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

isscalar

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

positions

The center pixel position(s).

r

shape

The shape of the instance.

Methods Documentation

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.

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 overlap of the aperture on the pixel grid. Not all options are available for all aperture types. Note that the more precise methods are generally slower. The following methods are available:

• `'exact'` (default): The the exact fractional overlap of the aperture and each pixel is calculated. The aperture weights will contain values between 0 and 1.

• `'center'`: A pixel is considered to be entirely in or out of the aperture depending on whether its center is in or out of the aperture. The aperture weights will contain values only of 0 (out) and 1 (in).

• `'subpixel'`: A pixel is divided into subpixels (see the `subpixels` keyword), each of which are considered to be entirely in or out of the aperture depending on whether its center is in or out of the aperture. If `subpixels=1`, this method is equivalent to `'center'`. The aperture weights will contain values between 0 and 1.

subpixelsint, optional

For the `'subpixel'` method, resample pixels by this factor in each dimension. That is, each pixel is divided into `subpixels**2` subpixels. This keyword is ignored unless `method='subpixel'`.

Returns:
areasfloat or array_like

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

copy()

Make an independent (deep) copy.

Perform aperture photometry on the input data.

Parameters:
dataarray_like or `Quantity` instance

The 2D array on which to perform photometry. `data` should be background subtracted.

errorarray_like or `Quantity`, optional

The pixel-wise Gaussian 1-sigma errors of the input `data`. `error` is assumed to include all sources of error, including the Poisson error of the sources (see `calc_total_error`) . `error` must have the same shape as the input `data`.

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 all calculations.

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

The method used to determine the overlap of the aperture on the pixel grid. Not all options are available for all aperture types. Note that the more precise methods are generally slower. The following methods are available:

• `'exact'` (default): The the exact fractional overlap of the aperture and each pixel is calculated. The aperture weights will contain values between 0 and 1.

• `'center'`: A pixel is considered to be entirely in or out of the aperture depending on whether its center is in or out of the aperture. The aperture weights will contain values only of 0 (out) and 1 (in).

• `'subpixel'`: A pixel is divided into subpixels (see the `subpixels` keyword), each of which are considered to be entirely in or out of the aperture depending on whether its center is in or out of the aperture. If `subpixels=1`, this method is equivalent to `'center'`. The aperture weights will contain values between 0 and 1.

subpixelsint, optional

For the `'subpixel'` method, resample pixels by this factor in each dimension. That is, each pixel is divided into `subpixels**2` subpixels. This keyword is ignored unless `method='subpixel'`.

Returns:
aperture_sums

The sums within each aperture.

aperture_sum_errs

The errors on the sums within each aperture.

Notes

`RectangularAperture` and `RectangularAnnulus` photometry with the “exact” method uses a subpixel approximation by subdividing each data pixel by a factor of 1024 (`subpixels = 32`). For rectangular aperture widths and heights in the range from 2 to 100 pixels, this subpixel approximation gives results typically within 0.001 percent or better of the exact value. The differences can be larger for smaller apertures (e.g., aperture sizes of one pixel or smaller). For such small sizes, it is recommend to set `method='subpixel'` with a larger `subpixels` size.

plot(ax=None, origin=(0, 0), **kwargs)

Plot the aperture on a matplotlib `Axes` instance.

Parameters:
ax`matplotlib.axes.Axes` or `None`, optional

The matplotlib axes on which to plot. If `None`, then the current `Axes` instance is used.

originarray_like, optional

The `(x, y)` position of the origin of the displayed image.

**kwargs`dict`

Any keyword arguments accepted by `matplotlib.patches.Patch`.

Returns:
patchlist of `Patch`

A list of matplotlib patches for the plotted aperture. The patches can be used, for example, when adding a plot legend.

Return a mask for the aperture.

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

The method used to determine the overlap of the aperture on the pixel grid. Not all options are available for all aperture types. Note that the more precise methods are generally slower. The following methods are available:

• `'exact'` (default): The the exact fractional overlap of the aperture and each pixel is calculated. The aperture weights will contain values between 0 and 1.

• `'center'`: A pixel is considered to be entirely in or out of the aperture depending on whether its center is in or out of the aperture. The aperture weights will contain values only of 0 (out) and 1 (in).

• `'subpixel'`: A pixel is divided into subpixels (see the `subpixels` keyword), each of which are considered to be entirely in or out of the aperture depending on whether its center is in or out of the aperture. If `subpixels=1`, this method is equivalent to `'center'`. The aperture weights will contain values between 0 and 1.

subpixelsint, optional

For the `'subpixel'` method, resample pixels by this factor in each dimension. That is, each pixel is divided into `subpixels**2` subpixels. This keyword is ignored unless `method='subpixel'`.

Returns:

A mask for the aperture. If the aperture is scalar then a single `ApertureMask` is returned, otherwise a list of `ApertureMask` is returned.

to_sky(wcs)[source]

Convert the aperture to a `SkyCircularAperture` object defined in celestial coordinates.

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:
aperture

A `SkyCircularAperture` object.