CompoundPixelRegion

class regions.CompoundPixelRegion(region1, region2, operator, meta=None, visual=None)

Bases: PixelRegion

A class that represents the logical combination of two regions in pixel coordinates.

Parameters:

region1PixelRegion

The inner Pixel region.

region2PixelRegion

The outer Pixel region.

operatorcallable

A callable binary operator.

metaRegionMeta, optional

A dictionary that stores the meta attributes of this region.

visualRegionVisual, optional

A dictionary that stores the visual meta attributes of this region.

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.
operator
region1()
region2()

Methods Summary

as_artist([origin])	Return a matplotlib patch object for this region (matplotlib.patches.PathPatch).
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_sky(wcs)	Return a region defined in sky coordinates.
to_spherical_sky(wcs, *[, ...])	Convert to an equivalent spherical SphericalSkyRegion instance.

Attributes Documentation

area

bounding_box

operator

region1

region2

Methods Documentation

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

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

Parameters:

originarray_like, optional

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

**kwargsdict

Any keyword arguments accepted by PathPatch.

Returns:

patchPathPatch

A matplotlib patch object.

contains(pixcoord)

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

covers

Check if points are inside or on the boundary.

covers(pixcoord)

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

This method considers points on the boundary as inside the region, consistent with Shapely’s covers 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 or on the boundary of the region.

See also

contains

Check if points are strictly inside (excludes boundary).

rotate(center, angle)

Rotate the region.

Positive angle corresponds to counter-clockwise rotation.

Parameters:

centerPixCoord

The rotation center point.

angleAngle

The rotation angle.

Returns:

regionCompoundPixelRegion

The rotated region (which is an independent copy).

to_mask(mode='center', subpixels=1)

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)

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.

to_spherical_sky(wcs, *, boundary_distortions=False, n_vertices=None)

Convert to an equivalent spherical SphericalSkyRegion instance.

Parameters:

wcsWCS instance

The world coordinate system transformation to use to convert between pixel and sky coordinates.

boundary_distortionsbool, optional

If True, the projection-induced distortions of the region’s boundary are preserved by discretizing the boundary into a polygon and transforming that polygon. If False (default), the region is converted to an equivalent idealized shape that ignores these boundary distortions.

n_verticesint, optional

The number of polygon vertices for boundary discretization. This keyword will have no effect unless boundary_distortions=True. Default is 100.

Returns:

spherical_sky_regionSphericalSkyRegion

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