Geometry Data

Geometry Data#

GeometryData — output schema for the harmonic_geometry module.

All geometry-producing functions in this module return a single GeometryData, which carries:

  • a discriminator geom_type (one of GEOM_TYPES) describing the layout of coordinates and any auxiliary connectivity arrays,

  • the coordinates themselves (an ndarray or list of ndarray),

  • optional edges / faces for graph-, tree-, and mesh-shaped data,

  • optional weights (per-point or per-edge),

  • optional field_grid for scalar-field types,

  • a parameters snapshot of the inputs that produced the geometry,

  • and free-form metadata (geom-specific, e.g. lobe count or mode multiplicity).

The geom_type strings are the contract relied on by downstream renderers (Manim, Three.js, TouchDesigner, matplotlib). Shape conventions are documented inline below.

class GeometryData(geom_type: str, coordinates: ~numpy.ndarray | ~typing.List[~numpy.ndarray], edges: ~numpy.ndarray | None = None, faces: ~numpy.ndarray | None = None, weights: ~numpy.ndarray | None = None, field_grid: ~typing.Tuple[~numpy.ndarray, ...] | None = None, parameters: ~typing.Dict[str, ~typing.Any] = <factory>, metadata: ~typing.Dict[str, ~typing.Any] = <factory>)[source]#

Bases: object

Container for one piece of geometric output.

Parameters:

  • geom_type (str) – One of GEOM_TYPES. Describes the layout of coordinates and which optional fields are populated.

  • coordinates (ndarray or list of ndarray) – The primary geometric data. Exact shape depends on geom_type; see module docstring.

  • edges (ndarray, optional) – Integer index pairs of shape (E, 2) for graph and tree types. Indices are into coordinates along axis 0.

  • faces (ndarray, optional) – Integer triangle indices of shape (F, 3) for mesh_3d.

  • weights (ndarray, optional) – Per-point or per-edge scalar weights. Shape must be broadcast- compatible with the entity it annotates.

  • field_grid (tuple of ndarray, optional) – (X, Y) or (X, Y, Z) meshgrid arrays for field_2d / field_3d types.

  • parameters (dict) – Snapshot of the inputs that produced this geometry (e.g. the HarmonicInput fields). Free-form; serialized via pickle.

  • metadata (dict) – Geom-specific annotations (e.g. lobe count for Lissajous, mode multiplicity for Chladni). Free-form; serialized via pickle.

Notes

Files written by save() are pickle-backed. Do not load GeometryData files from untrusted sources.

geom_type: str#
coordinates: ndarray | List[ndarray]#
edges: ndarray | None = None#
faces: ndarray | None = None#
weights: ndarray | None = None#
field_grid: Tuple[ndarray, ...] | None = None#
parameters: Dict[str, Any]#
metadata: Dict[str, Any]#
save(path: str) → None[source]#

Persist to path as a numpy .npz file.

parameters and metadata are pickled into a 0-d object array. Lists of arrays (e.g. for curve_set_2d) are flattened with index suffixes so they round-trip through np.savez.

Loading is the inverse via load(). Because pickled data is used, only load files from sources you trust.

classmethod load(path: str) → GeometryData[source]#

Load a GeometryData previously written by save().

Only load files from trusted sources — parameters and metadata are unpickled.

Contents