geoparticle.base.Geometry

class Geometry(name: str | None = None, dimension: int | None = None)

Bases: object

Base class for geometry objects, providing utilities for vector transformations and coordinate management.

Shortest import: from geoparticle import Geometry

__init__(name: str | None = None, dimension: int | None = None)

Initialize a Geometry object with optional naming.

Parameters:

• name (str | None) – Optional name for the geometry. Defaults to a generated name based on the class name and counter.

• dimension (int | None) – Optional dimension of the geometry. Defaults to None.

Methods

__init__([name, dimension])	Initialize a Geometry object with optional naming.
check_overlap([tol])	Check if there are overlapping points in the geometry.
clip(keep, *[, plane_name, plane_normal, ...])	Clip geometry by a half-space defined by a named plane or an arbitrary plane.
coord2id(x, y, z)	Find the nearest vertex index/indices and its/their coordinates.
copy([name])	Create a deep copy of the geometry object.
equal(geo)	Check if two geometries are equal based on their coordinates.
get_and_delete(ids)	Extract points by their indices and remove them from the geometry.
get_counter()	Get the current value of the class-wide counter.
intersect(geometries[, rmax, inplace, name])	Keep points from self that are within rmax of at least one point in every other geometry.
load_from(other)	Copy coordinate arrays and dimension from another Geometry into this instance.
mirror(plane_name, plane_pos[, inplace, name])	Mirror the geometry across a principal plane.
plot([ax, ms, alpha])	Plot the geometry points in 2D.
rotate(angle_deg[, axis_direction, ...])	Rotate the geometry around a principal axis or a custom axis.
set_coord(xs, ys, zs)	Set the coordinates of the geometry, broadcasting scalars if necessary.
shift([x, y, z, inplace, name])	Translate the geometry by the given offsets.
stack(axis, n_axis, dl, dimension[, ...])	Stack a planar layer (self) along axis by repeating points at spacing dl.
subtract(geo2[, rmax, inplace, name])	Return points from self that are at least rmax away from any point in geo2.
union(geometries[, inplace, name])	Concatenate this geometry with others and return a new Geometry.

Attributes

counter
flatten_coords	Get the flattened array of coordinates.
matrix_coords	Get the coordinates as a 2D array.
size	Get the number of points in the geometry.

copy(name: str | None = None)

Create a deep copy of the geometry object.

Parameters:

name (str | None) – Optional name for the copied geometry. If None, the original name is retained.

Returns:

A new geometry object with the same attributes.

Return type:

Geometry

load_from(other: Geometry)

Copy coordinate arrays and dimension from another Geometry into this instance.

Parameters:

other (Geometry) – Source geometry.

Returns:

self for chaining.

Return type:

Geometry

Raises:

TypeError – If other is not a Geometry.

classmethod get_counter() → int

Get the current value of the class-wide counter.

Returns:

The current counter value.

Return type:

int

property size: int

Get the number of points in the geometry.

Returns:

The size of the geometry.

Return type:

int

property matrix_coords: ndarray

Get the coordinates as a 2D array.

Returns:

Array of shape (N, 3) with [x, y, z] coordinates.

Return type:

np.ndarray

property flatten_coords: ndarray

Get the flattened array of coordinates.

Returns:

Flattened array of [x, y, z] coordinates.

Return type:

np.ndarray

set_coord(xs, ys, zs)

Set the coordinates of the geometry, broadcasting scalars if necessary.

Parameters:

• xs – X-coordinates (scalar or array-like).

• ys – Y-coordinates (scalar or array-like).

• zs – Z-coordinates (scalar or array-like).

Returns:

The updated geometry object.

Return type:

Geometry

Raises:

• TypeError – If a scalar is provided without a size hint.

• ValueError – If the coordinate arrays have mismatched sizes.

shift(x=0.0, y=0.0, z=0.0, inplace: bool = False, name: str | None = None)

Translate the geometry by the given offsets.

Parameters:

• x (float) – Offset along the X-axis.

• y (float) – Offset along the Y-axis.

• z (float) – Offset along the Z-axis.

• inplace (bool) – If True, modify the geometry in place. Otherwise, return a new geometry.

• name (str | None) – Optional name for the resulting geometry. Cannot be given when inplace is True. If not given, the original name is used.

Returns:

New geometry if not inplace, otherwise None.

Return type:

Geometry | None

mirror(plane_name: str, plane_pos: float, inplace: bool = False, name: str | None = None)

Mirror the geometry across a principal plane.

Parameters:

• plane_name (str) – Name of the plane (‘YOZ’, ‘XOY’, or ‘XOZ’).

• plane_pos (float) – Position of the plane.

• inplace (bool) – If True, modify the geometry in place. Otherwise, return a new geometry.

• name (str | None) – Optional name for the resulting geometry. Cannot be given when inplace is True. If not given, the original name is used.

Returns:

New geometry if not inplace, otherwise None

Return type:

Geometry | None

Raises:

ValueError – If an invalid plane name is provided.

rotate(angle_deg: float, axis_direction: str | None = None, axis_point1: Sequence[float] | None = None, axis_point2: Sequence[float] | None = None, inplace: bool = False, name: str | None = None)

Rotate the geometry around a principal axis or a custom axis.

Rules:

• If axis_direction is provided, axis_point1 and axis_point2 must not be provided

• If axis_direction is None, both axis_point1 and axis_point2 must be provided

Parameters:

• angle_deg (float) – Rotation angle in degrees.

• axis_direction (str | None) – Principal axis (‘x’, ‘y’, or ‘z’).

• axis_point1 (Sequence[float] | None) – First point defining the custom axis.

• axis_point2 (Sequence[float] | None) – Second point defining the custom axis.

• inplace (bool) – If True, modify the geometry in place. Otherwise, return a new geometry.

• name (str | None) – Optional name for the resulting geometry. Cannot be given when inplace is True. If not given, the original name is used.

Returns:

A new geometry object after rotation, or None if inplace is True.

Return type:

Geometry | None

Raises:

ValueError – If invalid axis parameters are provided.

union(geometries: Geometry | Sequence[Geometry], inplace: bool = False, name: str | None = None)

Concatenate this geometry with others and return a new Geometry.

Parameters:

• geometries (Geometry | Sequence[Geometry]) – Other Geometry objects to union with.

• inplace (bool) – If True, modify the geometry in place. Otherwise, return a new geometry.

• name (str | None) – Optional name for the resulting geometry. Cannot be given when inplace is True. If not given, the original name is used.

Returns:

A new geometry object after union, or None if inplace is True.

Return type:

Geometry | None

__add__(other)

Return the union of this geometry with another.

Parameters:

other (Geometry) – Another geometry to union with.

Returns:

A new geometry object after union.

Return type:

Geometry

Raises:

NotImplementedError – If other is not a Geometry instance.

__iadd__(other)

Return the union of this geometry with another in-place.

Parameters:

other (Geometry) – Another geometry to union with.

Returns:

The updated geometry object (self) after the in-place union.

Return type:

Geometry

Raises:

NotImplementedError – If other is not a Geometry instance.

subtract(geo2: Geometry, rmax: float = 1e-05, inplace: bool = False, name: str | None = None)

Return points from self that are at least rmax away from any point in geo2.

Parameters:

• geo2 (Geometry) – Geometry to subtract from self.

• rmax (float) – Minimum distance to consider a point as not overlapping.

• inplace (bool) – If True, modify the geometry in place. Otherwise, return a new geometry.

• name (str | None) – Optional name for the resulting geometry. Cannot be given when inplace is True. If not given, the original name is used.

Returns:

A new geometry object after subtraction, or None if inplace is True.

Return type:

Geometry | None

intersect(geometries: Geometry | Sequence[Geometry], rmax: float = 1e-05, inplace: bool = False, name: str | None = None)

Keep points from self that are within rmax of at least one point in every other geometry.

Parameters:

• geometries (Geometry | Sequence[Geometry]) – Other Geometry objects to intersect with.

• rmax (float) – Maximum distance to consider points as intersecting.

• inplace (bool) – If True, modify the geometry in place. Otherwise, return a new geometry.

• name (str | None) – Optional name for the resulting geometry. Cannot be given when inplace is True. If not given, the original name is used.

Returns:

A new geometry object after intersection, or None if inplace is True.

Return type:

Geometry | None

stack(axis: str, n_axis: int, dl: float, dimension: int, inplace: bool = False, name: str | None = None)

Stack a planar layer (self) along axis by repeating points at spacing dl.

Parameters:

• axis (str) – Axis to stack along (‘x’, ‘y’, or ‘z’).

• n_axis (int) – Number of layers to stack. Positive for positive direction, negative for negative direction.

• dl (float) – Spacing between layers.

• dimension (int) – Dimension of the resulting geometry (2 or 3).

• inplace (bool) – If True, modify the geometry in place. Otherwise, return a new geometry.

• name (str | None) – Optional name for the resulting geometry. Cannot be given when inplace is True. If not given, the original name is used.

Returns:

A new geometry object after stacking, or None if inplace is True.

Return type:

Geometry | None

clip(keep: str, *, plane_name: str | None = None, plane_normal: Sequence[float] | ndarray | None = None, plane_point: Sequence[float] | ndarray | None = None, inplace: bool = False, name: str | None = None)

Clip geometry by a half-space defined by a named plane or an arbitrary plane.

Rules:

• If plane_name is given, plane_normal and plane_point must not be provided.

• If plane_name is not given, plane_normal and plane_point must both be provided.

Parameters:

• keep (str) – Side to keep (‘positive’ or ‘negative’).

• plane_name (str, optional) – Named plane (‘XOY’, ‘XOZ’, ‘YOZ’). Defaults to None.

• plane_normal (Sequence[float], optional) – Normal vector of the plane. Defaults to None.

• plane_point (Sequence[float], optional) – A point on the plane. Defaults to None.

• inplace (bool) – If True, modify the geometry in place. Otherwise, return a new geometry.

• name (str | None) – Optional name for the resulting geometry. Cannot be given when inplace is True. If not given, the original name is used.

Returns:

A new geometry object after clipping, or None if inplace is True.

Return type:

Geometry | None

Raises:

ValueError – If invalid arguments are provided.

get_and_delete(ids: ndarray)

Extract points by their indices and remove them from the geometry.

Parameters:

ids (np.ndarray) – Indices of points to extract.

Returns:

A new geometry object containing the extracted points.

Return type:

Geometry

coord2id(x: float, y: float, z: float)

Find the nearest vertex index/indices and its/their coordinates.

Parameters:

• x (float) – X-coordinate of the query point.

• y (float) – Y-coordinate of the query point.

• z (float) – Z-coordinate of the query point.

Returns:

Index/Indices of the nearest vertex/vertices and its/their coordinates.

Return type:

tuple

equal(geo: Geometry)

Check if two geometries are equal based on their coordinates.

Parameters:

geo (Geometry) – Another geometry to compare with.

Returns:

True if the geometries are equal, False otherwise.

Return type:

bool

__eq__(other)

Check if two geometries are equal using the equal method.

Parameters:

other (Geometry) – Another geometry to compare with.

Returns:

True if the geometries are equal, False otherwise.

Return type:

bool

Raises:

NotImplementedError – If other is not a Geometry instance.

check_overlap(tol: float = 1e-10)

Check if there are overlapping points in the geometry. Find two nearest points and see if their distance is less than tol.

Parameters:

tol (float) – Tolerance distance to consider points as overlapping.

plot(ax=None, ms=None, alpha=None, **scatter_kwargs)

Plot the geometry points in 2D.

Parameters:

• ax – Matplotlib Axes object to plot on. If None, a new figure and axes are created.

• **scatter_kwargs – Additional keyword arguments for the scatter plot.

• ms – Marker size.

• alpha – Transparency level of the points.

counter = 0