PixelRegion

class regions.PixelRegion

Bases: Region

Base class for all regions defined in pixel coordinates.

Attributes Summary

area	The exact analytical area of the region shape.
bounding_box	The minimal bounding box (in integer pixel coordinates) that contains the region.
meta
visual

Methods Summary

as_artist([origin])	Convert to matplotlib patch object for this region.
contains(pixcoord)	Check whether a position or positions fall inside the region.
intersection(other)	Return a region representing the intersection of this region with other.
plot([origin, ax])	Plot the region on a matplotlib Axes instance.
symmetric_difference(other)	Return the union of the two regions minus any areas contained in the intersection of the two regions.
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.
union(other)	Return a region representing the union of this region with other.

Attributes Documentation

area

The exact analytical area of the region shape.

bounding_box

The minimal bounding box (in integer pixel coordinates) that contains the region.

meta = {}

visual = {}

Methods Documentation

abstractmethod as_artist(origin=(0, 0), **kwargs)

Convert to matplotlib patch object for this region.

Parameters:

originarray_like, optional

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

**kwargsdict

Any keyword arguments accepted by Patch.

Returns:

patchPatch

A matplotlib patch.

abstractmethod contains(pixcoord)

Check whether a position or positions fall inside the region.

Parameters:

pixcoordPixCoord

The position or positions to check.

intersection(other)

Return a region representing the intersection of this region with other.

Parameters:

otherRegion

The other region to use for the intersection.

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

Plot the region on a matplotlib Axes instance.

Parameters:

originarray_like, optional

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

axAxes or None, optional

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

**kwargsdict

Any keyword arguments accepted by Patch.

Returns:

artistmatplotlib.artist.Artist

The matplotlib artist (typically a Patch object) for the plotted region. The artist can be used, for example, when adding a plot legend.

symmetric_difference(other)

Return the union of the two regions minus any areas contained in the intersection of the two regions.

Parameters:

otherRegion

The other region to use for the symmetric difference.

abstractmethod to_mask(mode='center', subpixels=5)

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.

abstractmethod to_sky(wcs)

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.

Notes

The conversion between pixel and sky coordinates is an approximation. The pixel region shape is mapped to a sky region shape using the local pixel scale and angle at the region center. Projection effects over the extent of the region are not accounted for. The region shape type is always preserved (e.g., a CirclePixelRegion converts to a CircleSkyRegion).

For WCS with distortions (e.g., SIP), the local Jacobian matrix of the WCS transformation is used to compute directional scale factors and angle. For WCS without distortions, a local pixel scale and angle are computed using offset-based methods.

abstractmethod to_spherical_sky(wcs=None, include_boundary_distortions=False, n_points=None)

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

union(other)

Return a region representing the union of this region with other.

Parameters:

otherRegion

The other region to use for the union.