polytopax.ConvexHull

class polytopax.ConvexHull(vertices: ~jax.Array, faces: ~jax.Array | None = None, algorithm_info: dict[str, ~typing.Any] = <factory>)[source]

JAX-compatible ConvexHull class with object-oriented API.

This class provides a high-level interface for convex hull operations, including geometric queries, property computation, and transformations. It is designed to be compatible with JAX transformations (jit, grad, vmap).

vertices

Hull vertex coordinates with shape (n_vertices, dim)

Type:: jax.Array

faces

Face composition with shape (n_faces, vertices_per_face) [optional]

Type:: jax.Array | None

algorithm_info

Metadata about the computation algorithm

Type:: dict[str, Any]

_volume_cache

Cached volume value for performance

Type:: float | None

_surface_area_cache

Cached surface area value for performance

Type:: float | jax.Array | None

_centroid_cache

Cached centroid value for performance

Type:: jax.Array | None

Example

>>> import jax.numpy as jnp
>>> from polytopax import ConvexHull
>>> points = jnp.array([[0, 0], [1, 0], [0, 1], [1, 1]])
>>> hull = ConvexHull.from_points(points)
>>> print(f"Volume: {hull.volume():.4f}")
>>> print(f"Centroid: {hull.centroid()}")

__init__(vertices: ~jax.Array, faces: ~jax.Array | None = None, algorithm_info: dict[str, ~typing.Any] = <factory>) → None

Methods

`__init__`(vertices[, faces, algorithm_info])
`bounding_box`()	Compute axis-aligned bounding box.
`centroid`()	Compute hull centroid (with caching).
`contains`(point[, tolerance])	Test if point is inside hull.
`diameter`()	Compute hull diameter (maximum distance between vertices).
`distance_to`(point)	Compute distance from point to hull.
`from_dict`(data)	Create ConvexHull from dictionary representation.
`from_points`(points[, algorithm])	Create ConvexHull from point cloud.
`is_degenerate`([tolerance])	Check if hull is degenerate (lower-dimensional).
`rotate`(angle[, axis])	Rotate the convex hull (Phase 2 implementation).
`scale`(factor)	Scale the convex hull (Phase 2 implementation).
`summary`()	Get summary statistics of the hull.
`surface_area`()	Compute hull surface area (with caching).
`to_dict`()	Convert hull to dictionary representation.
`translate`(vector)	Translate the convex hull (Phase 2 implementation).
`vertices_array`()	Get vertices as JAX array.
`volume`([method])	Compute hull volume (with caching).

Attributes

`dimension`	Spatial dimension.
`faces`
`n_vertices`	Number of hull vertices.
`vertices`
`algorithm_info`

vertices: Array

faces: Array | None = None

algorithm_info: dict[str, Any]

__post_init__()[source]: Post-initialization processing.

classmethod from_points(points: Array, algorithm: str = 'approximate', **kwargs) → ConvexHull[source]

Create ConvexHull from point cloud.

Parameters:

points – Input point cloud with shape (n_points, dim)
algorithm – Hull computation algorithm (“approximate”)
**kwargs – Algorithm-specific parameters

Returns:

ConvexHull instance

Example

>>> points = jnp.random.normal(jax.random.PRNGKey(0), (50, 3))
>>> hull = ConvexHull.from_points(points, n_directions=100)

property n_vertices: int: Number of hull vertices.

property dimension: int: Spatial dimension.

volume(method: str = 'simplex_decomposition') → float | Array[source]

Compute hull volume (with caching).

Parameters:: method – Volume computation method
Returns:: Volume of the convex hull

surface_area() → float | Array[source]

Compute hull surface area (with caching).

Returns:: Surface area of the convex hull

contains(point: Array, tolerance: float = 1e-08) → bool[source]

Test if point is inside hull.

Parameters:

point – Point to test with shape (dim,)
tolerance – Numerical tolerance

Returns:

True if point is inside or on boundary

distance_to(point: Array) → float[source]

Compute distance from point to hull.

Parameters:: point – Point with shape (dim,)
Returns:: Signed distance (positive=outside, negative=inside)

centroid() → Array[source]

Compute hull centroid (with caching).

Returns:: Centroid coordinates

bounding_box() → tuple[Array, Array][source]

Compute axis-aligned bounding box.

Returns:: Tuple of (min_coords, max_coords)

diameter() → float[source]

Compute hull diameter (maximum distance between vertices).

Returns:: Maximum distance between any two vertices

is_degenerate(tolerance: float = 1e-10) → bool[source]

Check if hull is degenerate (lower-dimensional).

Parameters:: tolerance – Tolerance for degeneracy detection
Returns:: True if hull is degenerate

summary() → dict[str, Any][source]

Get summary statistics of the hull.

Returns:: Dictionary containing various hull properties

vertices_array() → Array[source]

Get vertices as JAX array.

Returns:: Vertex coordinates array

to_dict() → dict[str, Any][source]

Convert hull to dictionary representation.

Returns:: Dictionary representation suitable for serialization

classmethod from_dict(data: dict[str, Any]) → ConvexHull[source]

Create ConvexHull from dictionary representation.

Parameters:: data – Dictionary containing hull data
Returns:: ConvexHull instance

__repr__() → str[source]: String representation of ConvexHull.

__str__() → str[source]: Human-readable string representation.

scale(factor: float | Array) → ConvexHull[source]

Scale the convex hull (Phase 2 implementation).

Parameters:: factor – Scaling factor (scalar or per-dimension)
Returns:: New scaled ConvexHull instance

translate(vector: Array) → ConvexHull[source]

Translate the convex hull (Phase 2 implementation).

Parameters:: vector – Translation vector
Returns:: New translated ConvexHull instance

rotate(angle: float, axis: Array | None = None) → ConvexHull[source]

Rotate the convex hull (Phase 2 implementation).

Parameters:

angle – Rotation angle (radians)
axis – Rotation axis (3D only)

Returns:

New rotated ConvexHull instance

__init__(vertices: ~jax.Array, faces: ~jax.Array | None = None, algorithm_info: dict[str, ~typing.Any] = <factory>) → None