CirclePixelRegion#

class regions.CirclePixelRegion(center, radius, meta=None, visual=None)[source]#

Bases: PixelRegion

A circle defined using pixel coordinates.

Parameters:

centerPixCoord: The center position.
radiusfloat: The radius in pixels.
metaRegionMeta or dict, optional: A dictionary that stores the meta attributes of the region.
visualRegionVisual or dict, optional: A dictionary that stores the visual meta attributes of the region.

Examples

import matplotlib.pyplot as plt
from regions import CirclePixelRegion, PixCoord

fig, ax = plt.subplots()

reg = CirclePixelRegion(PixCoord(x=8, y=7), radius=3.5)
patch = reg.plot(ax=ax, facecolor='none', edgecolor='red', lw=2,
                 label='Circle')

ax.legend(handles=(patch,), loc='upper center')
ax.set_xlim(0, 15)
ax.set_ylim(0, 15)
ax.set_aspect('equal')

(Source code, png, hires.png, pdf, svg)

../_images/regions-CirclePixelRegion-1.png

Attributes Summary

`area`	The exact analytical area of the region shape.
`bounding_box`	Bounding box (`RegionBoundingBox`).
`center`	The center pixel position as a `PixCoord`.
`meta`	The meta attributes as a `RegionMeta`
`radius`	The radius in pixels as a float.
`visual`	The visual attributes as a `RegionVisual`.

Methods Summary

`as_artist`([origin])	Return a matplotlib patch object for this region (`matplotlib.patches.Circle`).
`contains`(pixcoord)	Check whether a position or positions fall inside the region, excluding the boundary.
`covers`(pixcoord)	Check whether a position or positions fall inside the region, including the boundary.
`rotate`(center, angle)	Rotate the region.
`to_mask`([mode, subpixels])	Return a mask for the region.
`to_polygon`([n_points])	Return a `PolygonPixelRegion` that approximates this circle.
`to_sky`(wcs, *[, as_ellipse])	Return a sky region from this pixel region.
`to_spherical_sky`([wcs, ...])	Convert to an equivalent spherical `SphericalSkyRegion` instance.

Attributes Documentation

area#

bounding_box#: Bounding box (RegionBoundingBox).

center#: The center pixel position as a PixCoord.

meta#: The meta attributes as a RegionMeta

radius#: The radius in pixels as a float.

visual#: The visual attributes as a RegionVisual.

Methods Documentation

as_artist(origin=(0, 0), **kwargs)[source]#

Return a matplotlib patch object for this region (matplotlib.patches.Circle).

Parameters:

originarray_like, optional: The (x, y) pixel position of the origin of the displayed image.
**kwargsdict: Any keyword arguments accepted by Circle. These keywords will override any visual meta attributes of this region.

Returns:

artistCircle: A matplotlib circle patch.

contains(pixcoord)[source]#

Check whether a position or positions fall inside the region, excluding the boundary.

This method considers points on the boundary as outside the region, consistent with Shapely’s contains function and DE-9IM semantics.

Parameters:

pixcoordPixCoord: The position or positions to check.

Returns:

resultbool or ndarray: A boolean or boolean array indicating whether the position(s) are inside the region.

See also

contains: Check if points are strictly inside (excludes boundary).

rotate(center, angle)[source]#

Rotate the region.

Positive angle corresponds to counter-clockwise rotation.

Parameters:

centerPixCoord: The rotation center point.
angleAngle: The rotation angle.

Returns:

regionCirclePixelRegion: The rotated region (which is an independent copy).

to_mask(mode='center', subpixels=1)[source]#

Return a mask for the region.

Parameters:

mode{‘center’, ‘exact’, ‘subpixels’}, optional

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

'center': A pixel is considered to be entirely in or out of the region depending on whether its center is in or out of the region. The returned mask will contain values only of 0 (out) and 1 (in).
'exact' (default): The exact fractional overlap of the region and each pixel is calculated. The returned mask will contain values between 0 and 1.
'subpixel': A pixel is divided into subpixels (see the subpixels keyword), each of which are considered to be entirely in or out of the region depending on whether its center is in or out of the region. If subpixels=1, this method is equivalent to 'center'. The returned mask will contain values between 0 and 1.

subpixelsint, optional

For the 'subpixel' mode, resample pixels by this factor in each dimension. That is, each pixel is divided into subpixels ** 2 subpixels.

Returns:

maskRegionMask: A mask for the region.

to_polygon(n_points=100)[source]#

Return a PolygonPixelRegion that approximates this circle.

Parameters:

n_pointsint, optional: The number of polygon vertices. Default is 100.

Returns:

polygonPolygonPixelRegion: A polygon region approximating the circle.

to_sky(wcs, *, as_ellipse=False)[source]#

Return a sky region from this pixel region.

Parameters:

wcsWCS object: A world coordinate system (WCS) transformation that supports the astropy shared interface for WCS (e.g., astropy.wcs.WCS).
as_ellipsebool, optional: If True, return an EllipseSkyRegion instead of a CircleSkyRegion. An ellipse is generally a better approximation when the WCS has distortions or different pixel scales along different axes. Default is False.

Returns:

regionCircleSkyRegion or EllipseSkyRegion: The sky region. An ellipse is returned if as_ellipse is True.

to_spherical_sky(wcs=None, include_boundary_distortions=False, n_points=None)[source]#

Convert to an equivalent spherical SphericalSkyRegion instance.

Parameters:

wcsWCS instance, optional: The world coordinate system transformation to use to convert between sky and pixel coordinates. Required if transforming with boundary distortions (if include_boundary_distortions is True). Ignored if boundary distortions not included.
include_boundary_distortionsbool, optional: If True, accounts for boundary distortions in spherical to planar conversions, by discretizing the boundary and converting the boundary polygon. Default is False, which converts to an equivalent idealized shape.
n_pointsint, optional: The number of polygon vertices for boundary discretization. This keyword will have no effect unless include_boundary_distortions=True. Default is 100.

Returns:

spherical_sky_regionSphericalSkyRegion: A spherical sky region, with an equivalent shape (if include_boundary_distortions is False), or a discretized polygon of the boundary (if include_boundary_distortions is True).