lapy.Polygon

class lapy.Polygon(points, closed=False)

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. For closed polygons, the last point should not duplicate the first point.

closedbool, default=False

If True, treats the path as a closed polygon. If False, treats it as an open polyline.

Attributes

points	(np.ndarray) Polygon vertex coordinates, shape (n_points, d).
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.
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.

Examples

>>> import numpy as np
>>> from lapy.polygon import Polygon
>>> # Create a 2D closed polygon (square)
>>> square = np.array([[0, 0], [1, 0], [1, 1], [0, 1]])
>>> poly = Polygon(square, closed=True)
>>> poly.is_2d()
True
>>> poly.length()
4.0
>>> # Create a 3D open path
>>> path_3d = np.array([[0, 0, 0], [1, 0, 0], [1, 1, 0], [1, 1, 1]])
>>> poly3d = Polygon(path_3d, closed=False)
>>> poly3d.is_2d()
False

area()

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.

centroid()

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,).

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.

get_points()

Get polygon points.

Returns:

np.ndarray

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

is_2d()

Check if the polygon is 2D.

Returns:

bool

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

is_closed()

Check if the polygon is closed.

Returns:

bool

True if polygon is closed, False if open.

length()

Compute total length of polygon path.

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

Returns:

float

Total path length.

n_points()

Get number of points in polygon.

Returns:

int

Number of points.

resample(n_points=100, n_iter=1, inplace=False)

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.

smooth_laplace(n=1, lambda_=0.5, inplace=False)

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.

smooth_taubin(n=1, lambda_=0.5, mu=-0.53, inplace=False)

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.