BoundaryPolygon¶

class petres.models.BoundaryPolygon[source]¶

Bases: object

Represent a 2D area-of-interest boundary as a closed polygon in XY space.

The class stores validated polygon vertices and a cached Shapely polygon object used for geometric operations such as point-in-polygon queries.

Parameters:

vertices (numpy.typing.ArrayLike) – Polygon vertices with shape (N, 2). The ring is automatically closed if the first and last points are not equal within tolerance.
name (str or None, default=None) – Optional boundary label.

Raises:

ValueError – Raised during initialization when vertices cannot form a valid finite polygon.

Notes

Initialization validates vertex shape, enforces finite coordinates, closes the ring, and constructs an internal Shapely Polygon.

vertices: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]¶

name: str | None = None¶

__post_init__()[source]¶

Validate vertices, close the ring, and build the internal polygon.

Raises:: ValueError – If fewer than three unique points are provided or the polygon is invalid (self-intersections, degenerate ring).

property bounds: tuple[float, float, float, float]¶

Return the axis-aligned bounding box of the boundary polygon.

Parameters:: None
Returns:: Bounding box in the form (xmin, ymin, xmax, ymax).
Return type:: tuple of float

contains(xy)[source]¶

Evaluate whether points are strictly inside the polygon.

Uses Shapely’s contains predicate, so points on the polygon boundary are evaluated as False.

Parameters:: xy (numpy.typing.ArrayLike) – Candidate points of shape (N, 2).
Returns:: Boolean mask indicating whether each point lies inside the polygon.
Return type:: ndarray of bool
Raises:: ValueError – If xy is not a 2D array with two columns.

classmethod from_vertices(vertices, *, name=None)[source]¶

Create a boundary polygon from raw vertices.

Parameters:

vertices (numpy.typing.ArrayLike) – Sequence of (x, y) coordinate pairs.
name (str or None, optional) – Optional label for the polygon.

Returns:

Constructed boundary instance.

Return type:

BoundaryPolygon

Examples

>>> verts = [(0, 0), (100, 0), (100, 50), (0, 50)]
>>> boundary = BoundaryPolygon.from_vertices(verts, name="Field A")

classmethod from_xy(x, y, *, name=None)[source]¶

Create a boundary polygon from separate x and y sequences.

Parameters:

x (Sequence[float]) – X-coordinates.
y (Sequence[float]) – Y-coordinates; must match shape of x.
name (str or None, optional) – Optional label for the polygon.

Returns:

Constructed boundary instance.

Return type:

BoundaryPolygon

Raises:

ValueError – If x and y shapes differ.

Examples

>>> boundary = BoundaryPolygon.from_xy([0, 100, 100, 0], [0, 0, 50, 50], name="Box")

classmethod from_bbox(xmin, ymin, xmax, ymax, *, name=None)[source]¶

Create an axis-aligned rectangular boundary from bounding box limits.

Parameters:

xmin (float) – Lower-left corner.
ymin (float) – Lower-left corner.
xmax (float) – Upper-right corner; must satisfy xmax > xmin and ymax > ymin.
ymax (float) – Upper-right corner; must satisfy xmax > xmin and ymax > ymin.
name (str or None, optional) – Optional label for the polygon.

Returns:

Rectangular boundary instance.

Return type:

BoundaryPolygon

Raises:

ValueError – If the bounds are invalid.

Examples

>>> boundary = BoundaryPolygon.from_bbox(0.0, 0.0, 200.0, 150.0, name="AOI")

show(*, facecolor='#7ec8e3', edgecolor='#1f2937', linewidth=1.8, alpha=0.3, show_fill=True, show_vertices=False, vertex_size=24.0, aspect='auto', title=None, wells=None, **kwargs)[source]¶

Quick visualization of the boundary polygon using Matplotlib.

Parameters:

facecolor (str or tuple, default="#7ec8e3") – Fill color of the polygon.
edgecolor (str or tuple, default="#1f2937") – Edge (border) color of the polygon.
linewidth (float, default=1.8) – Width of the polygon boundary line.
alpha (float, default=0.30) – Transparency of the fill (0-1).
show_fill (bool, default=True) – Whether to fill the polygon.
show_vertices (bool, default=False) – Whether to show vertex markers.
vertex_size (float, default=24.0) – Size of vertex markers.
aspect ({"auto", "equal"}, default="auto") – Axes aspect ratio used by the viewer theme.
title (str or None, default=None) – Title of the plot. If None, no title is shown.
wells (VerticalWell or Sequence[VerticalWell] or None, optional) – Well(s) to plot on top of the grid. Can be a single VerticalWell or a sequence of them. If None, no wells are plotted.
**kwargs (Any) – Additional keyword arguments passed to Matplotlib2DViewer.add_boundary_polygon.

Returns:

Viewer instance with the polygon added and shown.

Return type:

Matplotlib2DViewer

Examples

>>> boundary = BoundaryPolygon.from_bbox(0.0, 0.0, 100.0, 80.0)
>>> viewer = boundary.show(title="Boundary")
>>> type(viewer).__name__
'Matplotlib2DViewer'

__init__(vertices, name=None)¶