Examples | PY
Core Functionality
Self-contained examples demonstrating primary features of trueform.
These examples demonstrate fundamental trueform workflows, from primitive queries to spatial acceleration and boolean operations.
Queries on Primitives
Demonstrates fundamental geometric queries between individual primitives.
Features Showcased
- Creating primitives (
tf.Polygon,tf.Segment,tf.Ray,tf.Point) - Boolean intersection tests with
tf.intersects - Finding closest points with
tf.closest_metric_point_pair - Ray casting with
tf.ray_cast
Example Code
import numpy as np
import trueform as tf
# Create primitives
triangle = tf.Polygon([[0, 0, 0], [1, 0, 0], [0, 1, 0]])
segment = tf.Segment([[2, 2, 0], [3, 3, 0]])
# Intersection test - segment is outside triangle
if not tf.intersects(triangle, segment):
dist2, pt_on_triangle, pt_on_segment = tf.closest_metric_point_pair(
triangle, segment
)
print(f"Distance: {np.sqrt(dist2)}")
# Ray casting
ray = tf.Ray(origin=[0.2, 0.2, -1], direction=[0, 0, 1])
if (t := tf.ray_cast(ray, triangle)) is not None:
hit_point = ray.origin + t * np.array(ray.direction)
print(f"Hit at t={t}")
Spatial Queries on Meshes
Demonstrates building spatial acceleration structures and querying meshes.
Features Showcased
- Creating
tf.Meshfrom numpy arrays - Building spatial tree with
mesh.build_tree() - Single nearest neighbor search with
tf.neighbor_search - k-NN search with
tf.neighbor_search(..., k=k) - Collision detection with
tf.intersects
Example Code
import numpy as np
import trueform as tf
# Create mesh from numpy arrays
faces = np.array([[0, 1, 2], [1, 3, 2]], dtype=np.int32)
points = np.array([
[0.0, 0.0, 0.0],
[1.0, 0.0, 0.0],
[0.0, 1.0, 0.0],
[1.0, 1.0, 0.0]
], dtype=np.float32)
mesh = tf.Mesh(faces, points)
# Build spatial tree (done automatically on first query, or explicitly)
mesh.build_tree()
# Single nearest neighbor search
query = tf.Point([0.1, 0.1, 0.1])
idx, dist2, closest_pt = tf.neighbor_search(mesh, query)
print(f"Nearest face: {idx}, distance: {np.sqrt(dist2)}")
print(f"Closest point: {closest_pt}")
# k-NN search
results = tf.neighbor_search(mesh, query, k=2)
for idx, dist2, closest_pt in results:
print(f"Face {idx} at distance {np.sqrt(dist2)}")
# Collision detection between meshes
other_mesh = tf.Mesh(faces, points + 0.5)
other_mesh.build_tree()
if tf.intersects(mesh, other_mesh):
print("Meshes intersect")
Collecting Intersecting Primitives
Demonstrates finding all primitives that satisfy a spatial predicate.
Features Showcased
- Using
tf.gather_intersecting_idsto collect intersecting primitives - Using
tf.gather_ids_within_distancefor proximity queries - Ray queries against meshes
Example Code
import numpy as np
import trueform as tf
# Create mesh
faces = np.array([[0, 1, 2], [1, 3, 2]], dtype=np.int32)
points = np.array([
[0.0, 0.0, 0.0],
[1.0, 0.0, 0.0],
[0.0, 1.0, 0.0],
[1.0, 1.0, 0.0]
], dtype=np.float32)
mesh = tf.Mesh(faces, points)
# Find all faces intersecting a point
pt = tf.Point([0.3, 0.3, 0.0])
ids = tf.gather_intersecting_ids(mesh, pt)
print(f"Point intersects faces: {ids}")
# Find all faces within distance of a point
pt_near = tf.Point([0.5, -0.1, 0.0])
ids = tf.gather_ids_within_distance(mesh, pt_near, distance=0.2)
print(f"Faces within distance: {ids}")
# Find all faces hit by a ray
ray = tf.Ray(origin=[0.3, 0.3, 1.0], direction=[0, 0, -1])
ids = tf.gather_intersecting_ids(mesh, ray)
print(f"Ray intersects faces: {ids}")
The spatial tree enables efficient broad-phase culling. Without it, these operations would require O(n) primitive tests.
Boolean Operations
Demonstrates mesh boolean operations (union, intersection, difference).
Features Showcased
- Building required topology structures
- Computing boolean union, intersection, difference
- Extracting intersection curves with
return_curves=True
Example Code
import numpy as np
import trueform as tf
def create_cube(center, size=1.0, dtype=np.float32):
"""Create a cube mesh"""
half = size / 2.0
cx, cy, cz = center
points = np.array([
[cx - half, cy - half, cz - half],
[cx + half, cy - half, cz - half],
[cx + half, cy + half, cz - half],
[cx - half, cy + half, cz - half],
[cx - half, cy - half, cz + half],
[cx + half, cy - half, cz + half],
[cx + half, cy + half, cz + half],
[cx - half, cy + half, cz + half],
], dtype=dtype)
faces = np.array([
[0, 1, 2], [0, 2, 3], # Bottom
[4, 7, 6], [4, 6, 5], # Top
[0, 5, 1], [0, 4, 5], # Front
[2, 7, 3], [2, 6, 7], # Back
[0, 3, 7], [0, 7, 4], # Left
[1, 6, 2], [1, 5, 6], # Right
], dtype=np.int32)
return tf.Mesh(faces, points)
# Create two overlapping cubes
mesh0 = create_cube(center=(0, 0, 0))
mesh1 = create_cube(center=(0.5, 0, 0))
# Build required structures for boolean operations
for mesh in [mesh0, mesh1]:
mesh.build_tree()
mesh.build_face_membership()
mesh.build_manifold_edge_link()
# Compute union
(result_faces, result_points), labels = tf.boolean_union(mesh0, mesh1)
print(f"Union: {len(result_faces)} faces")
# Compute intersection
(result_faces, result_points), labels = tf.boolean_intersection(mesh0, mesh1)
print(f"Intersection: {len(result_faces)} faces")
# Compute difference with intersection curves
(result_faces, result_points), labels, (paths, curve_points) = tf.boolean_difference(
mesh0, mesh1, return_curves=True
)
print(f"Difference: {len(result_faces)} faces, {len(paths)} curves")
Required topology structures are built automatically on first use. Prebuild with
build_tree(), build_face_membership(), and build_manifold_edge_link() to avoid the cost during the first query.Isocontours
Demonstrates extracting isocontours from scalar fields on meshes.
Features Showcased
- Creating scalar fields with
tf.distance_field - Extracting isocontours at threshold values
- Iterating over resulting curves
Example Code
import numpy as np
import trueform as tf
# Create mesh
faces = np.array([[0, 1, 2], [0, 2, 3]], dtype=np.int32)
points = np.array([
[0.0, 0.0, 0.0],
[1.0, 0.0, 0.0],
[1.0, 1.0, 0.0],
[0.0, 1.0, 0.0]
], dtype=np.float32)
mesh = tf.Mesh(faces, points)
# Create scalar field (signed distance from plane)
plane = tf.Plane(normal=[0, 0, 1], origin=[0, 0, 0.5])
scalar_field = tf.distance_field(mesh.points, plane)
# Extract isocontour at threshold
paths, curve_points = tf.isocontours(mesh, scalar_field, 0.0)
print(f"Found {len(paths)} curves")
# Iterate over curves
for i, path_ids in enumerate(paths):
pts = curve_points[path_ids]
print(f"Curve {i}: {len(pts)} points")
# Multiple thresholds
thresholds = np.array([-0.5, 0.0, 0.5], dtype=np.float32)
paths, curve_points = tf.isocontours(mesh, scalar_field, thresholds)
Transformations
Demonstrates applying transformations without rebuilding spatial trees.
Features Showcased
- Attaching transformation to mesh via
mesh.transformation - Queries use transformed geometry without tree rebuild
Example Code
import numpy as np
import trueform as tf
# Create mesh and build tree
faces = np.array([[0, 1, 2], [1, 3, 2]], dtype=np.int32)
points = np.array([
[0.0, 0.0, 0.0],
[1.0, 0.0, 0.0],
[0.0, 1.0, 0.0],
[1.0, 1.0, 0.0]
], dtype=np.float32)
mesh = tf.Mesh(faces, points)
mesh.build_tree()
# Create static mesh for collision
static_mesh = tf.Mesh(faces, points + 2.0)
static_mesh.build_tree()
# No collision initially
print(f"Initial collision: {tf.intersects(static_mesh, mesh)}")
# Apply transformation (tree is reused)
translation = np.eye(4, dtype=np.float32)
translation[0, 3] = 2.0 # Translate +2 in X
mesh.transformation = translation
# Now they collide
print(f"After translation: {tf.intersects(static_mesh, mesh)}")
Transformations enable real-time collision detection in interactive applications without the cost of rebuilding spatial trees on every frame.