lapy.Polygon¶

class lapy.Polygon(points, closed=None)[source]¶

Class representing a polygon path (open or closed).

This class handles 2D and 3D polygon paths with operations for resampling, smoothing, and computing geometric properties like length, centroid, and area.

Parameters:

pointsnp.ndarray

Array of shape (n, d) containing coordinates of polygon vertices in order, where d is 2 or 3 for 2D (x, y) or 3D (x, y, z) paths. If the last point duplicates the first point and closed is None, the duplicate endpoint will be removed and the polygon will be marked as closed automatically.

closedbool or None, default=None

If None (default): Auto-detect by checking if first and last points are exactly equal (np.array_equal). Only an exact duplicate is removed; nearly-equal but geometrically distinct endpoints are left untouched and the polygon is treated as open.
If True: Treats the path as a closed polygon. If the last point is nearly equal to the first (np.allclose), it is removed.
If False: Treats the path as an open polyline regardless of endpoints.

Parameters:

points (ndarray)
closed (bool | None)

Attributes

points	(np.ndarray) Polygon vertex coordinates, shape (n_points, d). For closed polygons, the last point does not duplicate the first.
closed	(bool) Whether the polygon is closed or open.
_is_2d	(bool) Internal flag indicating if polygon is 2D (True) or 3D (False).

Methods

`area`()	Compute area enclosed by closed 2D polygon.
`centroid`()	Compute centroid of polygon.
`close`()	Mark the polygon as closed in-place.
`get_points`()	Get polygon points.
`is_2d`()	Check if the polygon is 2D.
`is_closed`()	Check if the polygon is closed.
`length`()	Compute total length of polygon path.
`n_points`()	Get number of points in polygon.
`resample`([n_points, n_iter, inplace])	Resample polygon to have equidistant points.
`smooth_laplace`([n, lambda_, inplace])	Smooth polygon using Laplace smoothing.
`smooth_taubin`([n, lambda_, mu, inplace])	Smooth polygon using Taubin smoothing.

Raises:

ValueError: If points array is empty. If points don’t have 2 or 3 coordinates.

Parameters:

points (ndarray)
closed (bool | None)

Examples

>>> import numpy as np
>>> from lapy.polygon import Polygon
>>> # Create a 2D closed polygon (square) - auto-detected
>>> square = np.array([[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]])
>>> poly = Polygon(square)  # closed=None, will auto-detect and remove duplicate
>>> poly.closed
True
>>> poly.points.shape[0]
4
>>> # Explicitly open polygon
>>> path = np.array([[0, 0, 0], [1, 0, 0], [1, 1, 0], [1, 1, 1]])
>>> poly3d = Polygon(path, closed=False)
>>> poly3d.closed
False

area()[source]¶

Compute area enclosed by closed 2D polygon.

Uses the shoelace formula. Only valid for closed 2D polygons.

Returns:

float: Enclosed area (always positive).

Raises:

ValueError: If polygon is not closed or not 2D.

Return type:

float

centroid()[source]¶

Compute centroid of polygon.

For open polygons or closed 3D polygons, returns the simple arithmetic mean of all vertex coordinates.

For closed 2D polygons, returns the area-weighted centroid (geometric center of mass). The area weighting accounts for the shape’s geometry, ensuring the centroid lies at the balance point of the polygon as if it were a uniform plate. This differs from the simple average of vertices, which would not account for how vertices are distributed around the polygon’s boundary.

Returns:

np.ndarray: Centroid coordinates, shape (2,) or (3,).

Return type:

ndarray

Notes

For closed 2D polygons, uses the standard formula: C_x = (1 / (6*A)) * sum((x_i + x_{i+1}) * (x_i * y_{i+1} - x_{i+1} * y_i)) C_y = (1 / (6*A)) * sum((y_i + y_{i+1}) * (x_i * y_{i+1} - x_{i+1} * y_i)) where A is the polygon area.

close()[source]¶

Mark the polygon as closed in-place.

If the last point is nearly equal to the first (np.allclose), it is removed; otherwise the polygon is simply flagged as closed (the closing segment from the last point back to the first is implicit). Using np.allclose here is intentional: the caller has explicitly requested closure, so stripping a near-duplicate endpoint is the expected behaviour.

Returns:

Polygon: Self, for method chaining.

Return type:

Polygon

get_points()[source]¶

Get polygon points.

Returns:

np.ndarray: Point array of shape (n, 2) or (n, 3).

Return type:

ndarray

is_2d()[source]¶

Check if the polygon is 2D.

Returns:

bool: True if polygon is 2D, False if 3D.

Return type:

bool

is_closed()[source]¶

Check if the polygon is closed.

Returns:

bool: True if polygon is closed, False if open.

Return type:

bool

length()[source]¶

Compute total length of polygon path.

For closed polygons, includes the segment from last to first point.

Returns:

float: Total path length.

Return type:

float

n_points()[source]¶

Get number of points in polygon.

Returns:

int: Number of points.

Return type:

int

resample(n_points=100, n_iter=1, inplace=False)[source]¶

Resample polygon to have equidistant points.

Creates n_points that are approximately equidistantly spaced along the cumulative Euclidean distance. Uses linear interpolation.

Parameters:

n_pointsint, default=100: Number of points in resampled polygon. Must be at least 2.
n_iterint, default=1: Number of resampling iterations. Higher values (e.g., 3-5) provide better equidistant spacing. Must be at least 1.
inplacebool, default=False: If True, modify this polygon in-place. If False, return new polygon.

Returns:

Polygon: Resampled polygon. Returns self if inplace=True, new instance otherwise.

Parameters:

n_points (int)
n_iter (int)
inplace (bool)

Return type:

Polygon

smooth_laplace(n=1, lambda_=0.5, inplace=False)[source]¶

Smooth polygon using Laplace smoothing.

Applies iterative smoothing: p_new = (1-lambda)*p + lambda * M*p where M is the neighbor-averaging matrix.

Parameters:

nint, default=1: Number of smoothing iterations.
lambda_float, default=0.5: Diffusion speed parameter in range [0, 1].
inplacebool, default=False: If True, modify this polygon in-place. If False, return new polygon.

Returns:

Polygon: Smoothed polygon. Returns self if inplace=True, new instance otherwise.

Parameters:

n (int)
lambda_ (float)
inplace (bool)

Return type:

Polygon

smooth_taubin(n=1, lambda_=0.5, mu=-0.53, inplace=False)[source]¶

Smooth polygon using Taubin smoothing.

Alternates between shrinking (positive lambda) and expanding (negative mu) steps to reduce shrinkage while smoothing.

Parameters:

nint, default=1: Number of smoothing iterations.
lambda_float, default=0.5: Positive diffusion parameter for shrinking step.
mufloat, default=-0.53: Negative diffusion parameter for expanding step.
inplacebool, default=False: If True, modify this polygon in-place. If False, return new polygon.

Returns:

Polygon: Smoothed polygon. Returns self if inplace=True, new instance otherwise.

Parameters:

n (int)
lambda_ (float)
mu (float)
inplace (bool)

Return type:

Polygon