EllipsePixelRegion¶

class regions.EllipsePixelRegion(center, width, height, angle=<Quantity 0. deg>, meta=None, visual=None)[source]¶

Bases: PixelRegion

An ellipse in pixel coordinates.

Parameters:

centerPixCoord: The position of the center of the ellipse.
widthfloat: The width of the ellipse (before rotation) in pixels.
heightfloat: The height of the ellipse (before rotation) in pixels.
angleQuantity, optional: The rotation angle of the ellipse, measured anti-clockwise. If set to zero (the default), the width axis is lined up with the x axis.
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

from astropy.coordinates import Angle
from regions import PixCoord, EllipsePixelRegion
import matplotlib.pyplot as plt

fig, ax = plt.subplots(1, 1)

reg = EllipsePixelRegion(PixCoord(15, 10), width=16, height=10,
                         angle=Angle(30, 'deg'))
patch = reg.plot(ax=ax, facecolor='none', edgecolor='red', lw=2,
                 label='Ellipse')

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

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

../_images/regions-EllipsePixelRegion-1.png

Attributes Summary

`angle`	The rotation angle measured anti-clockwise as a `astropy.units.Quantity` angle.
`area`	The exact analytical area of the region shape.
`bounding_box`	The minimal bounding box (`RegionBoundingBox`) enclosing the exact elliptical region.
`center`	The center pixel position as a `PixCoord`.
`height`	The height of the ellipse (before rotation) in pixels as a float.
`meta`	The meta attributes as a `RegionMeta`
`visual`	The visual attributes as a `RegionVisual`.
`width`	The width of the ellipse (before rotation) in pixels as a float.

Methods Summary

`as_artist`([origin])	Return a matplotlib patch object for the region (`matplotlib.patches.Ellipse`).
`as_mpl_selector`(ax[, active, sync, ...])	Return a matplotlib editable widget for this region (`matplotlib.widgets.EllipseSelector`).
`contains`(pixcoord)	Check whether a position or positions fall inside the region.
`rotate`(center, angle)	Rotate the region.
`to_mask`([mode, subpixels])	Return a mask for the region.
`to_sky`(wcs)	Return a region defined in sky coordinates.
`to_spherical_sky`([wcs, ...])	Convert to an equivalent spherical `SphericalSkyRegion` instance.

Attributes Documentation

angle¶: The rotation angle measured anti-clockwise as a astropy.units.Quantity angle.

area¶

bounding_box¶: The minimal bounding box (RegionBoundingBox) enclosing the exact elliptical region.

center¶: The center pixel position as a PixCoord.

height¶: The height of the ellipse (before rotation) in pixels as a float.

meta¶: The meta attributes as a RegionMeta

visual¶: The visual attributes as a RegionVisual.

width¶: The width of the ellipse (before rotation) in pixels as a float.

Methods Documentation

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

Return a matplotlib patch object for the region (matplotlib.patches.Ellipse).

Parameters:

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

Returns:

artistEllipse: A matplotlib ellipse patch.

as_mpl_selector(ax, active=True, sync=True, callback=None, drag_from_anywhere=False, **kwargs)[source]¶

Return a matplotlib editable widget for this region (matplotlib.widgets.EllipseSelector).

Parameters:

axAxes: The matplotlib axes to add the selector to.
activebool, optional: Whether the selector should be active by default.
syncbool, optional: If True (the default), the region will be kept in sync with the selector. Otherwise, the selector will be initialized with the values from the region but the two will then be disconnected.
callbackcallable, optional: If specified, this function will be called every time the region is updated. This only has an effect if sync is True. If a callback is set, it is called for the first time once the selector has been created.
drag_from_anywherebool, optional: If True, the selector can be moved by clicking anywhere within its bounds, else only at the central anchor (only available with matplotlib 3.5 upwards; default: False).
**kwargsdict: Additional keyword arguments that are passed to matplotlib.widgets.EllipseSelector.

Returns:

selectormatplotlib.widgets.EllipseSelector: The matplotlib selector.

Notes

Once a selector has been created, you will need to keep a reference to it until you no longer need it. In addition, you can enable/disable the selector at any point by calling selector.set_active(True) or selector.set_active(False).

contains(pixcoord)[source]¶

Check whether a position or positions fall inside the region.

Parameters:

pixcoordPixCoord: The position or positions to check.

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:

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

to_mask(mode='center', subpixels=5)[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_sky(wcs)[source]¶

Return a region defined in sky coordinates.

Parameters:

wcsWCS: The world coordinate system transformation to use to convert from pixels to sky coordinates.

Returns:

sky_regionSkyRegion: The sky region.

to_spherical_sky(wcs=None, include_boundary_distortions=False, discretize_kwargs=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 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.
discretize_kwargsdict, optional: Optional keyword arguments to pass to discretize_boundary() method if including boundary distortions.

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

Navigation

EllipsePixelRegion¶