Introduction
trueform is a Python library for real-time geometric processing. Spatial queries, mesh booleans, isocontours, topology — at interactive speed on million-polygon meshes. Robust on real-world inputs: non-manifold flaps, inconsistent geometry, the artifacts that pipelines accumulate. NumPy in, NumPy out. No new mesh types.
Research Foundation
Geometry pipelines accumulate defects. Sculpting, remeshing, format conversion—each step can introduce non-manifold flaps, inconsistencies, and surface artifacts. By the time geometry reaches your algorithm, it is rarely the ideal manifold most methods assume.
trueform is built around a simple idea: a mesh should be understood as an intended surface, observed through the noise of floating-point arithmetic and prior processing.
These defects are additive—they attach to the surface without redefining it. The underlying structure remains recoverable.
This perspective shapes the algorithms:
- Topological consistency. The intersection graph is reduced to its unique canonical form. The reduction diagram maps each intersection to its simplest representative in the ε-topology, ensuring consistency under floating-point uncertainty.
- Artifacts are modeled as independent noise. Geometric inconsistencies decompose locally across polygon regions; topological artifacts decompose globally across manifold edge-connected components—enabling robust classification of the intended structure.
The result is commutative correctness: operations on non-ideal meshes behave as if applied to the intended geometry. Chain operations freely and defer cleanup to the end.
Quick Tour
Here's how trueform enables complex geometric workflows with minimal code—working directly with numpy arrays, performing queries, and returning results ready for use:
import numpy as np
import trueform as tf
# Start with numpy arrays
points = np.array([
[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]
], dtype=np.float32)
faces = np.array([
[0, 1, 2], [0, 2, 3], [0, 3, 1], [1, 3, 2]
], dtype=np.int32)
# Create a mesh—that's it
mesh = tf.Mesh(faces, points)
Primitive queries work directly on geometry:
# Create geometric primitives
triangle = tf.Polygon([[0, 0, 0], [1, 0, 0], [0, 1, 0]])
segment = tf.Segment([[0, 0, 0], [1, 1, 1]])
ray = tf.Ray(origin=[0.2, 0.2, -1], direction=[0, 0, 1])
# Query relationships between primitives
dist2, pt_on_tri, pt_on_seg = tf.closest_metric_point_pair(triangle, segment)
# Ray intersection with primitive returns t or None
if (t := tf.ray_cast(ray, triangle)) is not None:
hit_point = ray.origin + t * np.array(ray.direction)
Topology is computed automatically when needed:
# Get boundary curves
paths, boundary_points = tf.boundary_curves(mesh)
# Access face adjacency (built on first use)
face_link = mesh.face_link
# Label connected components
num_components, labels = tf.label_connected_components(face_link)
components, component_label = tf.split_into_components(mesh, labels)
Spatial queries with automatic tree construction:
# Tree is built automatically on first spatial query
static_mesh = tf.Mesh(faces0, points0)
dynamic_mesh = tf.Mesh(faces1, points1)
# Attach transformation—operations use transformed pose without rebuild
dynamic_mesh.transformation = rotation_matrix
# Collision detection
does_intersect = tf.intersects(static_mesh, dynamic_mesh)
distance = tf.distance(static_mesh, dynamic_mesh)
# k-NN search
results = tf.neighbor_search(dynamic_mesh, query_point, k=5)
# Find all intersecting primitive pairs
pairs = tf.gather_intersecting_ids(static_mesh, dynamic_mesh)
# Find all primitive pairs within distance
pairs = tf.gather_ids_within_distance(static_mesh, dynamic_mesh, threshold=0.1)
# Compute intersection curves
paths, curve_points = tf.intersection_curves(static_mesh, dynamic_mesh)
Boolean operations return numpy arrays:
# Union, intersection, difference
(result_faces, result_points), labels = tf.boolean_union(static_mesh, dynamic_mesh)
# With intersection curves
(result_faces, result_points), labels, (paths, curve_points) = tf.boolean_union(
static_mesh, dynamic_mesh, return_curves=True
)
# Result is ready for visualization or further processing
result_mesh = tf.Mesh(result_faces, result_points)
Isobands extract regions from scalar fields:
# Create scalar field
plane = tf.Plane(normal=[0, 0, 1], offset=0.0)
scalars = tf.distance_field(mesh.points, plane)
# Extract isobands with boundary curves
(band_faces, band_points), labels, (paths, curve_points) = tf.isobands(
mesh, scalars, [-1.0, 0.0, 1.0], return_curves=True
)
Cleaning and reindexing maintain data integrity:
# Clean duplicates and degenerates
clean_faces, clean_points = tf.cleaned((faces, points))
# With index maps for attribute transfer
(clean_faces, clean_points), face_map, point_map = tf.cleaned(
(faces, points), return_index_map=True
)
# Filter by mask
mask = labels == 0
filtered_faces, filtered_points = tf.reindex_by_mask((faces, points), mask)
# Concatenate meshes
combined_faces, combined_points = tf.concatenated([
(faces0, points0),
(faces1, points1)
])
This is trueform from a bird's eye view. For comprehensive coverage of all features and usage patterns, explore the module documentation starting with Core.