Polygon#

class lsst.images.Polygon(*, x_vertices, y_vertices)#

Bases: Region

A simple 2-d polygon in Euclidean coordinates, with no holes.

Parameters:

x_vertices (TypeAliasType) – The x coordinates of the vertices of the polygon.
y_vertices (TypeAliasType) – The y coordinate of the vertices of the polygon.

Attributes Summary

`area`	The area of the region (`float`).
`bbox`	The integer-coordinate bounding box of the region (`Box`).
`centroid`	The centroid of the polygon (`XY` [`float`]).
`n_vertices`	The number of vertices in the polygon.
`wkt`	The 'Well-Known Text' representation of this region (`str`).
`x_vertices`	The x coordinates of the vertices of the polygon.
`y_vertices`	The y coordinates of the vertices of the polygon.

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_box`(box)	Construct from an integer-coordinate box.
`from_legacy`(legacy)	Convert from a legacy `lsst.afw.geom.Polygon` instance.
`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_legacy`()	Convert to a legacy `lsst.afw.geom.Polygon` instance.
`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.

centroid#: The centroid of the polygon (XY [float]).

n_vertices#: The number of vertices in the polygon.

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

x_vertices#

The x coordinates of the vertices of the polygon.

This is a read-only array; polygons are immutable.

y_vertices#

The y coordinates of the vertices of the polygon.

This is a read-only array; polygons are immutable.

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_box(box)#

Construct from an integer-coordinate box.

Parameters:: box (Box) – Integer-coordinate box to convert to a polygon.
Return type:: Polygon

Notes

Because the integer min and max coordinates of the box are interpreted as pixel centers, these are expanded by 0.5 on all sides before using them to form the polygon vertices.

static from_legacy(legacy)#

Convert from a legacy lsst.afw.geom.Polygon instance.

Parameters:: legacy (TypeAliasType) – Legacy lsst.afw.geom.Polygon to convert.
Return type:: Polygon

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_legacy()#

Convert to a legacy lsst.afw.geom.Polygon instance.

Return type:: TypeAliasType

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:: Polygon

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