`pycanha_core.gmm` — Core Geometric Classes#

These are the C++ geometric primitive and mesh classes.

Enumerations#

Primitives#

class pycanha_core.gmm.Triangle(*args, **kwargs)#

Bases: object

Triangular flat surface defined by three 3D vertices.

__init__(self, p1: numpy.ndarray[dtype=float64, shape=(3), order='C'], p2: numpy.ndarray[dtype=float64, shape=(3), order='C'], p3: numpy.ndarray[dtype=float64, shape=(3), order='C']) → None#: Create a triangle from three 3D vertex positions.

is_valid(self) → bool#: Whether the primitive geometry is valid.

normal_at_uv(self, uv: numpy.ndarray[dtype=float64, shape=(2), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Outward surface normal at a 2D parametric (uv) point.

property p1#: First vertex.

property p2#: Second vertex.

property p3#: Third vertex.

surface_area(self) → float#: Total surface area.

to_cartesian(self, uv: numpy.ndarray[dtype=float64, shape=(2), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Map a 2D parametric (uv) point back to 3D space.

to_uv(self, point: numpy.ndarray[dtype=float64, shape=(3), order='C']) → numpy.ndarray[dtype=float64, shape=(2), order='C']#: Project a 3D point onto the primitive’s 2D parametric (uv) space.

class pycanha_core.gmm.Rectangle(*args, **kwargs)#

Bases: object

Rectangular flat surface defined by three vertices (the fourth is derived): p1->p2 is one edge, p1->p3 the adjacent edge.

__init__(self, p1: numpy.ndarray[dtype=float64, shape=(3), order='C'], p2: numpy.ndarray[dtype=float64, shape=(3), order='C'], p3: numpy.ndarray[dtype=float64, shape=(3), order='C']) → None#: Create a rectangle from three corner positions.

is_valid(self) → bool#: Whether the primitive geometry is valid.

normal_at_uv(self, uv: numpy.ndarray[dtype=float64, shape=(2), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Outward surface normal at a 2D parametric (uv) point.

property p1#: Origin vertex.

property p2#: Second vertex (first edge from p1).

property p3#: Third vertex (second edge from p1).

surface_area(self) → float#: Total surface area.

to_cartesian(self, uv: numpy.ndarray[dtype=float64, shape=(2), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Map a 2D parametric (uv) point back to 3D space.

to_uv(self, point: numpy.ndarray[dtype=float64, shape=(3), order='C']) → numpy.ndarray[dtype=float64, shape=(2), order='C']#: Project a 3D point onto the primitive’s 2D parametric (uv) space.

class pycanha_core.gmm.Quadrilateral(*args, **kwargs)#

Bases: object

General quadrilateral surface defined by four vertices (may be non-planar).

__init__(self, p1: numpy.ndarray[dtype=float64, shape=(3), order='C'], p2: numpy.ndarray[dtype=float64, shape=(3), order='C'], p3: numpy.ndarray[dtype=float64, shape=(3), order='C'], p4: numpy.ndarray[dtype=float64, shape=(3), order='C']) → None#: Create a quadrilateral from four 3D vertex positions.

is_valid(self) → bool#: Whether the primitive geometry is valid.

normal_at_uv(self, uv: numpy.ndarray[dtype=float64, shape=(2), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Outward surface normal at a 2D parametric (uv) point.

property p1#: First vertex.

property p2#: Second vertex.

property p3#: Third vertex.

property p4#: Fourth vertex.

surface_area(self) → float#: Total surface area.

to_cartesian(self, uv: numpy.ndarray[dtype=float64, shape=(2), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Map a 2D parametric (uv) point back to 3D space.

to_uv(self, point: numpy.ndarray[dtype=float64, shape=(3), order='C']) → numpy.ndarray[dtype=float64, shape=(2), order='C']#: Project a 3D point onto the primitive’s 2D parametric (uv) space.

class pycanha_core.gmm.Cylinder(*args, **kwargs)#

Bases: object

Cylindrical surface segment defined by axis, radius, and angular extent.

__init__(self, p1: numpy.ndarray[dtype=float64, shape=(3), order='C'], p2: numpy.ndarray[dtype=float64, shape=(3), order='C'], p3: numpy.ndarray[dtype=float64, shape=(3), order='C'], radius: float, start_angle: float, end_angle: float) → None#: Create a cylinder from axis points, reference, radius, and angles.

property end_angle#: End angle [rad].

is_valid(self) → bool#: Whether the primitive geometry is valid.

normal_at_uv(self, uv: numpy.ndarray[dtype=float64, shape=(2), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Outward surface normal at a 2D parametric (uv) point.

property p1#: Base center position.

property p2#: Top center position.

property p3#: Reference point for the angle origin.

property radius#: Cylinder radius.

property start_angle#: Start angle [rad].

surface_area(self) → float#: Total surface area.

to_cartesian(self, uv: numpy.ndarray[dtype=float64, shape=(2), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Map a 2D parametric (uv) point back to 3D space.

to_uv(self, point: numpy.ndarray[dtype=float64, shape=(3), order='C']) → numpy.ndarray[dtype=float64, shape=(2), order='C']#: Project a 3D point onto the primitive’s 2D parametric (uv) space.

class pycanha_core.gmm.Disc(*args, **kwargs)#

Bases: object

Annular disc (flat ring) segment defined by center, normal, inner/outer radii, and angular extent.

__init__(self, p1: numpy.ndarray[dtype=float64, shape=(3), order='C'], p2: numpy.ndarray[dtype=float64, shape=(3), order='C'], p3: numpy.ndarray[dtype=float64, shape=(3), order='C'], inner_radius: float, outer_radius: float, start_angle: float, end_angle: float) → None#: Create a disc from center, normal ref, radii, and angles.

property end_angle#: End angle [rad].

property inner_radius#: Inner radius (0 for a full disc).

is_valid(self) → bool#: Whether the primitive geometry is valid.

normal_at_uv(self, uv: numpy.ndarray[dtype=float64, shape=(2), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Outward surface normal at a 2D parametric (uv) point.

property outer_radius#: Outer radius.

property p1#: Center position.

property p2#: Normal direction reference point.

property p3#: Reference point for the angle origin.

property start_angle#: Start angle [rad].

surface_area(self) → float#: Total surface area.

to_cartesian(self, uv: numpy.ndarray[dtype=float64, shape=(2), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Map a 2D parametric (uv) point back to 3D space.

to_uv(self, point: numpy.ndarray[dtype=float64, shape=(3), order='C']) → numpy.ndarray[dtype=float64, shape=(2), order='C']#: Project a 3D point onto the primitive’s 2D parametric (uv) space.

class pycanha_core.gmm.Cone(*args, **kwargs)#

Bases: object

Conical (frustum) surface segment defined by axis, two radii, and angular extent.

__init__(self, p1: numpy.ndarray[dtype=float64, shape=(3), order='C'], p2: numpy.ndarray[dtype=float64, shape=(3), order='C'], p3: numpy.ndarray[dtype=float64, shape=(3), order='C'], radius1: float, radius2: float, start_angle: float, end_angle: float) → None#: Create a cone from axis points, reference, radii, and angles.

property end_angle#: End angle [rad].

is_valid(self) → bool#: Whether the primitive geometry is valid.

normal_at_uv(self, uv: numpy.ndarray[dtype=float64, shape=(2), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Outward surface normal at a 2D parametric (uv) point.

property p1#: Base center position.

property p2#: Top center position.

property p3#: Reference point for the angle origin.

property radius1#: Radius at the base (p1 end).

property radius2#: Radius at the top (p2 end).

property start_angle#: Start angle [rad].

surface_area(self) → float#: Total surface area.

to_cartesian(self, uv: numpy.ndarray[dtype=float64, shape=(2), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Map a 2D parametric (uv) point back to 3D space.

to_uv(self, point: numpy.ndarray[dtype=float64, shape=(3), order='C']) → numpy.ndarray[dtype=float64, shape=(2), order='C']#: Project a 3D point onto the primitive’s 2D parametric (uv) space.

class pycanha_core.gmm.Sphere(*args, **kwargs)#

Bases: object

Spherical surface segment with optional base/apex truncation and angular extent.

__init__(self, p1: numpy.ndarray[dtype=float64, shape=(3), order='C'], p2: numpy.ndarray[dtype=float64, shape=(3), order='C'], p3: numpy.ndarray[dtype=float64, shape=(3), order='C'], radius: float, base_truncation: float, apex_truncation: float, start_angle: float, end_angle: float) → None#: Create a sphere segment from center, axis, reference, radius, truncations, and angular extent.

property apex_truncation#: Apex truncation (0 = no truncation).

property base_truncation#: Base truncation (0 = no truncation).

property end_angle#: End angle [rad].

is_valid(self) → bool#: Whether the primitive geometry is valid.

normal_at_uv(self, uv: numpy.ndarray[dtype=float64, shape=(2), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Outward surface normal at a 2D parametric (uv) point.

property p1#: Center position.

property p2#: Axis direction reference point.

property p3#: Reference point for the angle origin.

property radius#: Sphere radius.

property start_angle#: Start angle [rad].

surface_area(self) → float#: Total surface area.

to_cartesian(self, uv: numpy.ndarray[dtype=float64, shape=(2), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Map a 2D parametric (uv) point back to 3D space.

to_uv(self, point: numpy.ndarray[dtype=float64, shape=(3), order='C']) → numpy.ndarray[dtype=float64, shape=(2), order='C']#: Project a 3D point onto the primitive’s 2D parametric (uv) space.

Meshes#

class pycanha_core.gmm.ThermalMesh(*args, **kwargs)#

Bases: object

Per-primitive thermal discretization (UV cuts + per-side properties + tmm-node assignment).

__init__(self) → None#

__init__(self, dir1_mesh: collections.abc.Sequence[float], dir2_mesh: collections.abc.Sequence[float]) → None

Overloaded function.

__init__(self) -> None

Default unit square with one face pair.

__init__(self, dir1_mesh: collections.abc.Sequence[float], dir2_mesh: collections.abc.Sequence[float]) -> None

Build directly from the two UV cut vectors.

property dir1_mesh#: UV cut positions along parametric direction 1.

property dir2_mesh#: UV cut positions along parametric direction 2.

is_valid(self) → bool#: Whether the mesh definition is valid.

property node1_start#: Front-side base node number (-1 = no node).

property node1_step#: Front-side per-cell node increment.

property node2_start#: Back-side base node number (-1 = no node).

property node2_step#: Back-side per-cell node increment.

node_of(self, i: int, j: int, side: int) → int#: Node number for cell (i, j) on side 1 or 2.

property num_pair_faces#: (len(dir1_mesh) - 1) * (len(dir2_mesh) - 1) face pairs.

property side1_activity#: Front-side activity.

property side1_color#: Front-side color.

property side1_material#: Front-side bulk material (None if unassigned).

property side1_optical#: Front-side optical material (None if unassigned).

property side1_thick#: Front-side thickness [m].

property side2_activity#: Back-side activity.

property side2_color#: Back-side color.

property side2_material#: Back-side bulk material (None if unassigned).

property side2_optical#: Back-side optical material (None if unassigned).

property side2_thick#: Back-side thickness [m].

Transformations#

class pycanha_core.gmm.CoordinateTransformation(*args, **kwargs)#

Bases: object

Rigid 3D transformation (translation + 3x3 rotation matrix).

__init__(self) → None#

__init__(self, translation: numpy.ndarray[dtype=float64, shape=(3), order='C'], rotation: numpy.ndarray[dtype=float64, shape=(3, 3), order='F']) → None

Overloaded function.

__init__(self) -> None

Create an identity transformation.

__init__(self, translation: numpy.ndarray[dtype=float64, shape=(3), order='C'], rotation: numpy.ndarray[dtype=float64, shape=(3, 3), order='F']) -> None

Create from a translation vector and a 3x3 rotation matrix.

apply(self, point: numpy.ndarray[dtype=float64, shape=(3), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Apply the full transformation to a 3D point.

apply_normal(self, normal: numpy.ndarray[dtype=float64, shape=(3), order='C']) → numpy.ndarray[dtype=float64, shape=(3), order='C']#: Apply only the rotation to a 3D direction/normal.

compose(self, outer: pycanha_core.pycanha_core.gmm.CoordinateTransformation) → pycanha_core.pycanha_core.gmm.CoordinateTransformation#: Compose with an outer transformation (outer applied after this).

from_euler = <nanobind.nb_func object>#

from_rotation = <nanobind.nb_func object>#

from_translation = <nanobind.nb_func object>#

inverse(self) → pycanha_core.pycanha_core.gmm.CoordinateTransformation#: The inverse transformation.

is_identity(self) → bool#: Whether this is the identity transformation.

linear(self) → numpy.ndarray[dtype=float64, shape=(3, 3), order='F']#: The linear (rotation) part as a 3x3 matrix.

property rotation#: 3x3 rotation matrix.

property translation#: Translation vector [x, y, z].

Geometry hierarchy#

class pycanha_core.gmm.Geometry#

Bases: object

Abstract base of the scene tree (GeometryItem, GeometryGroup, GeometryGroupCutted).

__init__(*args, **kwargs)#

property children#: Immediate children (empty for a GeometryItem).

create_mesh(self) → None#: Force a rebuild of this object’s subtree mesh.

property id#: Ephemeral process-wide-unique runtime id (uint64).

property mesh#: Subtree mesh (TriMeshD) in the parent frame; lazily built.

property name#: Unique name within the model.

property owning_model#: The GeometryModel this object is registered with, or None.

property transform#: Coordinate transformation in the parent frame.

class pycanha_core.gmm.GeometryItem(*args, **kwargs)#

Bases: Geometry

A single meshable primitive plus its ThermalMesh (a scene-tree leaf).

__init__(self, name: str, primitive: pycanha_core.pycanha_core.gmm.Triangle | pycanha_core.pycanha_core.gmm.Rectangle | pycanha_core.pycanha_core.gmm.Quadrilateral | pycanha_core.pycanha_core.gmm.Disc | pycanha_core.pycanha_core.gmm.Cylinder | pycanha_core.pycanha_core.gmm.Cone | pycanha_core.pycanha_core.gmm.Sphere | pycanha_core.pycanha_core.gmm.Paraboloid | pycanha_core.pycanha_core.gmm.Cube, thermal_mesh: pycanha_core.pycanha_core.gmm.ThermalMesh, transform: pycanha_core.pycanha_core.gmm.CoordinateTransformation = <pycanha_core.pycanha_core.gmm.CoordinateTransformation object at 0x7605012bba30>) → None#: Create a geometry item.

property children#: Immediate children (empty for a GeometryItem).

create_mesh(self) → None#: Force a rebuild of this object’s subtree mesh.

property id#: Ephemeral process-wide-unique runtime id (uint64).

property mesh#: Subtree mesh (TriMeshD) in the parent frame; lazily built.

property mesh_options_override#: Per-item MeshOptions override (None to use model default).

property name#: Unique name within the model.

property owning_model#: The GeometryModel this object is registered with, or None.

property primitive#: The wrapped primitive.

property thermal_mesh#: The thermal mesh.

property transform#: Coordinate transformation in the parent frame.

class pycanha_core.gmm.GeometryGroup(*args, **kwargs)#

Bases: Geometry

A transform applied to a collection of child geometries.

__init__(self, name: str, children: collections.abc.Sequence[pycanha_core.pycanha_core.gmm.Geometry] = [], transform: pycanha_core.pycanha_core.gmm.CoordinateTransformation = <pycanha_core.pycanha_core.gmm.CoordinateTransformation object at 0x7605012b9930>) → None#: Create a geometry group.

add(self, child: pycanha_core.pycanha_core.gmm.Geometry) → None#: Append a child (rejects nullptr, registered, or duplicate nodes).

property children#: Immediate children (empty for a GeometryItem).

create_mesh(self) → None#: Force a rebuild of this object’s subtree mesh.

property id#: Ephemeral process-wide-unique runtime id (uint64).

property mesh#: Subtree mesh (TriMeshD) in the parent frame; lazily built.

property name#: Unique name within the model.

property owning_model#: The GeometryModel this object is registered with, or None.

remove_child(self, child: pycanha_core.pycanha_core.gmm.Geometry) → bool#: Remove a child; returns True if it was present.

property transform#: Coordinate transformation in the parent frame.

class pycanha_core.gmm.GeometryGroupCutted(*args, **kwargs)#

Bases: Geometry

Boolean-subtract group: every target is cut by the union of all cutters (each cutter must be a closed-solid GeometryItem).

__init__(self, name: str, targets: collections.abc.Sequence[pycanha_core.pycanha_core.gmm.Geometry], cutters: collections.abc.Sequence[pycanha_core.pycanha_core.gmm.GeometryItem], transform: pycanha_core.pycanha_core.gmm.CoordinateTransformation = <pycanha_core.pycanha_core.gmm.CoordinateTransformation object at 0x7605012ba330>) → None#: Create a cut group from targets and cutters.

property children#: Immediate children (empty for a GeometryItem).

create_mesh(self) → None#: Force a rebuild of this object’s subtree mesh.

cut_with(self, cutter: pycanha_core.pycanha_core.gmm.GeometryItem) → None#: Add another cutter (must be a closed-solid GeometryItem).

property cutters#: The cutter geometry items.

property id#: Ephemeral process-wide-unique runtime id (uint64).

property mesh#: Subtree mesh (TriMeshD) in the parent frame; lazily built.

property name#: Unique name within the model.

property owning_model#: The GeometryModel this object is registered with, or None.

property targets#: The target geometries being cut.

property transform#: Coordinate transformation in the parent frame.

class pycanha_core.gmm.GeometryModel(*args, **kwargs)#

Bases: object

Top-level scene container: registers geometry, resolves names, owns the world mesh.

__init__(self, name: str) → None#: Create a named geometry model.

add(self, object: pycanha_core.pycanha_core.gmm.Geometry, parent_name: str = '') → None#: Register an object (and its subtree) under parent_name (root when empty).

property children#: Immediate children of the root group.

children_recursive(self) → list[pycanha_core.pycanha_core.gmm.Geometry]#: All geometries in the tree (depth-first).

contains(self, name: str) → bool#

contains(self, object: pycanha_core.pycanha_core.gmm.Geometry) → bool

Overloaded function.

contains(self, name: str) -> bool

Whether a geometry with this name is registered.

contains(self, object: pycanha_core.pycanha_core.gmm.Geometry) -> bool

Whether this object is registered.

create_mesh(self) → None#: Force a full rebuild of the world mesh.

property default_mesh_options#: Default MeshOptions applied to items without an override.

faces_of_node(self, node_num: int) → list#: Face ids assigned to a node number (built at mesh build).

get(self, name: str) → pycanha_core.pycanha_core.gmm.Geometry#: Get a geometry by name (None if absent).

get_cut_group(self, name: str) → pycanha_core.pycanha_core.gmm.GeometryGroupCutted#: Get a GeometryGroupCutted by name (None if absent or wrong kind).

get_group(self, name: str) → pycanha_core.pycanha_core.gmm.GeometryGroup#: Get a GeometryGroup by name (None if absent or wrong kind).

get_item(self, name: str) → pycanha_core.pycanha_core.gmm.GeometryItem#: Get a GeometryItem by name (None if absent or wrong kind).

get_structure_version(self) → int#: Monotonic version bumped on every structural / content change.

invalidate_mesh(self) → None#: Mark the world mesh dirty without rebuilding.

property mesh#: World mesh as float32 (TriMeshF); lazily built and cached.

property name#: Model name.

notify_content_changed(self) → None#: Mark caches dirty after an external content edit.

remove(self, name: str) → None#

remove(self, object: pycanha_core.pycanha_core.gmm.Geometry) → None

Overloaded function.

remove(self, name: str) -> None

Remove a geometry (and its subtree) by name.

remove(self, object: pycanha_core.pycanha_core.gmm.Geometry) -> None

Remove a geometry (and its subtree).

rename(self, current_name: str, new_name: str) → None#: Rename a registered geometry.

reparent(self, name: str, new_parent_name: str) → None#: Move a geometry under a new parent group.

property root_group#: The root GeometryGroup.

property root_group_mesh#: Float64 root-group mesh (TriMeshD), before float32 cast.

pycanha_core.gmm — Core Geometric Classes#

Enumerations#

Primitives#

Meshes#

Transformations#

Geometry hierarchy#

Mesh utility functions#

`pycanha_core.gmm` — Core Geometric Classes#