Region#

class lsst.images.Region(geometry)#

Bases: object

A 2-d Euclidean region represented as one or more polygons with optional holes.

Parameters:: geometry (Polygon | MultiPolygon) – A polygon or multi-polygon from the Shapely library.

Attributes Summary

`area`	The area of the region (`float`).
`bbox`	The integer-coordinate bounding box of the region (`Box`).
`wkt`	The 'Well-Known Text' representation of this region (`str`).

Methods Summary

`contains`([other, x, y])	Test whether the geometry contains the given points or another geometry.
`difference`(other)	Compute the point-set difference of this region with another.
`from_wkt`(wkt)	Construct from a 'Well-Known Text' string.
`intersection`(other)	Compute the intersection of this region with a `Bounds` object.
`serialize`()	Serialize the region to a Pydantic model.
`to_shapely`()	Convert to a `shapely.Polygon` or `shapely.MultiPolygon` object.
`transform`(transform)	Transform the coordinates of the region, returning a new one.
`try_to_box`()	If the underlying geometry is a rectangle that fully covers integer pixels (i.e. has all vertices at half-integer positions), return the equivalent `Box`.
`try_to_polygon`()	If the underlying geometry is a single polygon with no holes, return a `Polygon` instance holding it.
`union`(other)	Compute the point-set union of this region with another.

Attributes Documentation

area#: The area of the region (float).

bbox#

The integer-coordinate bounding box of the region (Box).

Because a Box logically contains the entirety of the pixels on its boundary, but the centers of those pixels are the numerical values of its bounds, the region may contain vertices that are up to 0.5 beyond the integer box coordinates in either dimension.

wkt#: The ‘Well-Known Text’ representation of this region (str).

Methods Documentation

contains(other=None, /, *, x=None, y=None)#

Test whether the geometry contains the given points or another geometry.

Parameters:

other (Union[Region, XY[Any], YX[Any], None], default: None) – Another geometry, or an XY or YX coordinate pair, to compare to. Mutually exclusive with x and y.
x (Any, default: None) – One or more X coordinates to test for containment, as a scalar or any array-like. Results are broadcast against y. Mutually exclusive with other.
y (Any, default: None) – One or more Y coordinates to test for containment, as a scalar or any array-like. Results are broadcast against x. Mutually exclusive with other.

Return type:

bool | ndarray

difference(other)#

Compute the point-set difference of this region with another.

Parameters:: other (Region) – Region to subtract from this one.
Return type:: Region

static from_wkt(wkt)#

Construct from a ‘Well-Known Text’ string.

Parameters:: wkt (str) – Well-Known Text representation of the region.
Return type:: Region

intersection(other)#

Compute the intersection of this region with a Bounds object.

Notes

Because Region implements the Bounds interface, its intersections need to support all other Bounds objects. This is not true of other Region point-set operations like union and difference.

Parameters:: other (Bounds) – Bounds to intersect with this region.
Return type:: Bounds

serialize()#

Serialize the region to a Pydantic model.

Region serialization uses a subset of the GeoJSON specification (IETF RFC 7946).

Return type:: RegionSerializationModel

to_shapely()#

Convert to a shapely.Polygon or shapely.MultiPolygon object.

Return type:: Polygon | MultiPolygon

transform(transform)#

Transform the coordinates of the region, returning a new one.

Parameters:: transform (Transform[Any, Any]) – Coordinate transform to apply (in the forward direction).
Return type:: Region

Notes

This applies the transform to all vertices, assuming that the transform is close enough to affine that the topology of the geometry does not change and straight-line edges do not need to be subsampled.

try_to_box()#

If the underlying geometry is a rectangle that fully covers integer pixels (i.e. has all vertices at half-integer positions), return the equivalent Box.

In all other cases self is returned.

Return type:: Region | Box

try_to_polygon()#

If the underlying geometry is a single polygon with no holes, return a Polygon instance holding it.

In all other cases self is returned.

Return type:: Region

union(other)#

Compute the point-set union of this region with another.

Parameters:: other (Region) – Region to union with this one.
Return type:: Region