Core Functionality

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.Mesh from 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_ids to collect intersecting primitives
Using tf.gather_ids_within_distance for 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, face_labels = tf.boolean_union(mesh0, mesh1)
print(f"Union: {len(result_faces)} faces")

# Compute intersection
(result_faces, result_points), labels, face_labels = tf.boolean_intersection(mesh0, mesh1)
print(f"Intersection: {len(result_faces)} faces")

# Compute difference with intersection curves
(result_faces, result_points), labels, face_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.

Selects one signed half of an arrangement — e.g. "the part of mesh_a on the +normal side of mesh_b" — without going through a full boolean and without requiring the operands to be closed. Two perpendicular planes intersect along a line; the arrangement cuts each plane in half along that line; tf.sidedness_relations reports which other operand each component touches at the cut and which side it's on.

Features Showcased

tf.sidedness_relations: per-component sidedness against every other operand at the cuts
Vectorized selection over the returned OffsetBlockedArrays using flat .data + cumsum-on-.offsets
Lift per-component mask → per-face mask via np.isin + tf.reindex_by_mask

Example Code

import numpy as np
import trueform as tf

# Two perpendicular planes (XY and XZ).
faces_a, points_a = tf.make_plane_mesh(2.0, 2.0)
R = np.array([[1, 0,  0],
              [0, 0, -1],
              [0, 1,  0]], dtype=points_a.dtype)
points_b = points_a @ R.T
mesh_a = tf.Mesh(faces_a, points_a)
mesh_b = tf.Mesh(faces_a.copy(), points_b)

# Arrangement + sidedness relations.
(faces, points), tag_labels, _ = tf.mesh_arrangements([mesh_a, mesh_b])
arr = tf.Mesh(faces, points)
(tags, sides), (n_components, comp_labels) = tf.sidedness_relations(arr, tag_labels)

Vectorized Selection

The returned tags and sides are two OffsetBlockedArrays sharing the same offsets. Per-component "any-match" reduces to a flat-data predicate + prefix-sum at offsets — no Python loop over components:

# Element-wise: which entries match "tag == 1 (mesh_b), side == 0 (+normal)"?
matches = (tags.data == 1) & (sides.data == 0)

# Per-component count via cumsum + difference at offsets.
# Handles empty per-component blocks naturally (count = 0 → False).
csum = np.concatenate([[0], np.cumsum(matches)])
match_count = csum[tags.offsets[1:]] - csum[tags.offsets[:-1]]

# Restrict to components whose source is mesh_a (tag 0).
comp_src = np.empty(n_components, dtype=tag_labels.dtype)
comp_src[comp_labels] = tag_labels   # scatter — last write wins (single-source)
keep = (match_count > 0) & (comp_src == 0)
keep_components = np.where(keep)[0]

Sub-mesh Extraction

face_mask = np.isin(comp_labels, keep_components)
kept_faces, kept_points = tf.reindex_by_mask((faces, points), face_mask)

Sidedness Values

The integer values match the C++ tf::sidedness enum:

Value	Meaning
`0`	`on_positive_side` — component on operand's +normal side at the cut
`1`	`on_negative_side` — component on operand's -normal side at the cut
`2`	`on_boundary` — coplanar contact at the cut (degenerate)
`3`	`none` — selection-only sentinel, not produced by the predicate

The cumsum + offsets-difference pattern is the canonical way to do segmented reductions over an OffsetBlockedArray. np.add.reduceat doesn't handle empty segments correctly; cumsum + diff does (and works for any reduction, not just "any True").

Isocontours

Demonstrates extracting isocontours from scalar fields on meshes.

Features Showcased

Creating scalar fields with tf.distance
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(tf.Point(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.

Overview

Practical examples demonstrating trueform with Python.

Arrangements and Volumes

Building an arrangement from intersecting meshes, extracting closed bounded volumes, and selecting them by signed side of a knife.