lagrange.raycasting¶

Classes¶

`BuildQuality`	BVH construction quality level.
`CastMode`	Ray-casting direction mode.
`FallbackMode`	Fallback mode for vertices without a ray hit.
`ProjectMode`	Main projection mode.
`RayCaster`	A ray caster built on top of Embree.
`SceneFlags`	Flags for configuring the Embree scene.

Functions¶

`project`(…)	Project query points onto a source mesh.
`project_closest_point`(…)	Project query points onto a source mesh by closest-point interpolation.
`project_closest_vertex`(…)	Project query points onto a source mesh by closest-vertex snapping.
`project_directional`(…)	Project query points onto a source mesh along a prescribed direction.

Module Contents¶

class lagrange.raycasting.BuildQuality(*args, **kwds)¶

Bases: enum.Enum

BVH construction quality level.

High = 2¶: Slowest build time, highest BVH quality.

Low = 0¶: Fastest build time, lowest BVH quality.

Medium = 1¶: Moderate build time and BVH quality.

class lagrange.raycasting.CastMode(*args, **kwds)¶

Bases: enum.Enum

Ray-casting direction mode.

BothWays = 1¶: Cast forward and backward.

OneWay = 0¶: Cast forward only.

class lagrange.raycasting.FallbackMode(*args, **kwds)¶

Bases: enum.Enum

Fallback mode for vertices without a ray hit.

ClosestPoint = 2¶: Interpolate from the closest surface point.

ClosestVertex = 1¶: Copy from the closest vertex.

Constant = 0¶: Fill with a constant value.

class lagrange.raycasting.ProjectMode(*args, **kwds)¶

Bases: enum.Enum

Main projection mode.

ClosestPoint = 1¶: Interpolate from the closest surface point.

ClosestVertex = 0¶: Copy from the closest vertex.

RayCasting = 2¶: Project along a prescribed direction.

class lagrange.raycasting.RayCaster(scene_flags=4, build_quality=BuildQuality.Medium)¶

A ray caster built on top of Embree.

This class manages an Embree BVH scene for efficient spatial queries. In the Python API it is exposed purely as a caching object: build the scene once, then pass it to the various project_* functions to avoid rebuilding the BVH on every call.

Example:

caster = lagrange.raycasting.RayCaster()
caster.add_mesh(source)
caster.commit_updates()

lagrange.raycasting.project_closest_point(
    source, target, attribute_ids=[attr_id], project_vertices=False,
    ray_caster=caster)
lagrange.raycasting.project_closest_vertex(
    source, target, attribute_ids=[attr_id], project_vertices=False,
    ray_caster=caster)

Parameters:

scene_flags (int)
build_quality (BuildQuality)

add_instance(mesh_index, transform)¶

Add an instance of an existing mesh with a given transform.

Parameters:

mesh_index (int) – Index of the source mesh (returned by add_mesh()).
transform (Annotated[numpy.typing.NDArray[numpy.float32], dict(shape=(4, 4), order='F')]) – 4×4 affine transformation matrix (float32).

Returns:

Local instance index relative to the source mesh.

Return type:

int

add_mesh(mesh, transform=...)¶

Add a triangle mesh to the scene.

The mesh is moved into the ray caster. Call commit_updates() after adding all meshes.

By default a single instance with an identity transform is created. Pass None to add the mesh without any instance (use add_instance() to create instances later).

Parameters:

mesh (lagrange.core.SurfaceMesh) – Triangle mesh.
transform (Annotated[numpy.typing.NDArray[numpy.float32], dict(shape=(4, 4), order='F')] | None) – 4×4 affine transformation matrix (float32), or None to add the mesh without creating an instance.

Returns:

Index of the source mesh in the scene.

Return type:

int

add_scene(simple_scene)¶

Add all meshes and instances from a SimpleScene.

Parameters:: simple_scene (lagrange.scene.SimpleScene3D) – Scene containing meshes and their instances.
Return type:: None

commit_updates()¶

Rebuild the BVH after adding or modifying meshes.

Must be called before any query or project function.

Return type:: None

get_transform(mesh_index, instance_index)¶

Get the affine transform of a mesh instance.

Parameters:

mesh_index (int) – Index of the source mesh.
instance_index (int) – Local instance index.

Returns:

4×4 affine transformation matrix (float32).

Return type:

Annotated[numpy.typing.NDArray[numpy.float32], dict(shape=(4, 4), order=’F’)]

get_visibility(mesh_index, instance_index)¶

Get the visibility flag of a mesh instance.

Parameters:

mesh_index (int) – Index of the source mesh.
instance_index (int) – Local instance index.

Returns:

True if the instance is visible.

Return type:

bool

update_mesh(mesh_index, mesh)¶

Replace a mesh in the scene.

All instances of the old mesh will reference the new mesh.

Parameters:

mesh_index (int) – Index of the mesh to replace.
mesh (lagrange.core.SurfaceMesh) – New triangle mesh.

Return type:

None

update_transform(mesh_index, instance_index, transform)¶

Update the affine transform of a mesh instance.

Parameters:

mesh_index (int) – Index of the source mesh.
instance_index (int) – Local instance index.
transform (Annotated[numpy.typing.NDArray[numpy.float32], dict(shape=(4, 4), order='F')]) – New 4×4 affine transformation matrix (float32).

Return type:

None

update_vertices(mesh_index, mesh)¶

Notify that vertices of a mesh have been modified.

The number and order of vertices must not change.

Parameters:

mesh_index (int) – Index of the mesh whose vertices changed.
mesh (lagrange.core.SurfaceMesh) – The modified mesh with updated vertex positions.

Return type:

None

update_visibility(mesh_index, instance_index, visible)¶

Update the visibility of a mesh instance.

Parameters:

mesh_index (int) – Index of the source mesh.
instance_index (int) – Local instance index.
visible (bool) – True to make visible, False to hide.

Return type:

None

class lagrange.raycasting.SceneFlags¶

Bases: enum.IntEnum

Flags for configuring the Embree scene.

Compact = 2¶: Compact BVH layout.

Dynamic = 1¶: Scene will be updated frequently.

Empty = 0¶: No special behavior.

Filter = 8¶: Enable user-defined filters.

Robust = 4¶: Robust BVH traversal.

lagrange.raycasting.project(source: lagrange.core.SurfaceMesh, target: lagrange.core.SurfaceMesh, attribute_ids: collections.abc.Sequence[int] = [], project_vertices: bool = True, project_mode: ProjectMode = ProjectMode.ClosestPoint, direction: object | None = None, cast_mode: CastMode = CastMode.BothWays, fallback_mode: FallbackMode = FallbackMode.Constant, default_value: float = 0.0, ray_caster: RayCaster | None = None) → None¶

lagrange.raycasting.project(source: lagrange.core.SurfaceMesh, points: Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=None, 3, order='C', device='cpu')], project_mode: ProjectMode, direction: Annotated[numpy.typing.NDArray[numpy.float32], dict(shape=3, order='C')] | Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=None, 3, order='C', device='cpu')] | None = None, cast_mode: CastMode = CastMode.BothWays, fallback_mode: FallbackMode = FallbackMode.Constant, default_value: float = 0.0, ray_caster: RayCaster | None = None) → Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=None, 3, order='C', device='cpu')]

Project query points onto a source mesh.

Parameters:

source – Source triangle mesh.
points – (N, 3) NumPy array of query point positions (float64). Modified in place to store the projected positions.
project_mode – Projection mode (default: ProjectMode.ClosestPoint).
direction – Ray direction. Can be a 3D vector, or a numpy array of shape (N, 3) for per-vertex directions. Only used with ProjectMode.RayCasting.
cast_mode – Forward-only or both directions (only used with ProjectMode.RayCasting).
fallback_mode – Fallback for missed vertices (only used with ProjectMode.RayCasting).
default_value – Fill value for FallbackMode.Constant (default: 0).
ray_caster – Optional pre-built RayCaster for caching.

Returns:

(N, 3) NumPy array of projected positions (float64).

lagrange.raycasting.project_closest_point(source: lagrange.core.SurfaceMesh, target: lagrange.core.SurfaceMesh, attribute_ids: collections.abc.Sequence[int] = [], project_vertices: bool = True, ray_caster: RayCaster | None = None) → None¶

lagrange.raycasting.project_closest_point(source: lagrange.core.SurfaceMesh, points: Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=None, 3, order='C', device='cpu')], ray_caster: RayCaster | None = None) → Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=None, 3, order='C', device='cpu')]

Project query points onto a source mesh by closest-point interpolation.

For each query point, the closest point on the source mesh surface is found.

Parameters:

source – Source triangle mesh.
points – (N, 3) NumPy array of query point positions (float64). Modified in place to store the projected positions.
ray_caster – Optional pre-built RayCaster for caching.

Returns:

(N, 3) NumPy array of projected positions (float64).

lagrange.raycasting.project_closest_vertex(source: lagrange.core.SurfaceMesh, target: lagrange.core.SurfaceMesh, attribute_ids: collections.abc.Sequence[int] = [], project_vertices: bool = True, ray_caster: RayCaster | None = None) → None¶

lagrange.raycasting.project_closest_vertex(source: lagrange.core.SurfaceMesh, points: Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=None, 3, order='C', device='cpu')], ray_caster: RayCaster | None = None) → Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=None, 3, order='C', device='cpu')]

Project query points onto a source mesh by closest-vertex snapping.

For each query point, the closest surface point is found and snapped to the nearest source vertex.

Parameters:

source – Source triangle mesh.
points – (N, 3) NumPy array of query point positions (float64). Modified in place to store the projected positions.
ray_caster – Optional pre-built RayCaster for caching.

Returns:

(N, 3) NumPy array of projected positions (float64).

lagrange.raycasting.project_directional(source: lagrange.core.SurfaceMesh, target: lagrange.core.SurfaceMesh, attribute_ids: collections.abc.Sequence[int] = [], project_vertices: bool = True, direction: object | None = None, cast_mode: CastMode = CastMode.BothWays, fallback_mode: FallbackMode = FallbackMode.Constant, default_value: float = 0.0, ray_caster: RayCaster | None = None) → None¶

lagrange.raycasting.project_directional(source: lagrange.core.SurfaceMesh, points: Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=None, 3, order='C', device='cpu')], direction: Annotated[numpy.typing.NDArray[numpy.float32], dict(shape=3, order='C')] | Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=None, 3, order='C', device='cpu')], cast_mode: CastMode = CastMode.BothWays, fallback_mode: FallbackMode = FallbackMode.Constant, default_value: float = 0.0, ray_caster: RayCaster | None = None) → Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=None, 3, order='C', device='cpu')]

Project query points onto a source mesh along a prescribed direction.

For each query point, a ray is cast in the given direction. If it hits the source mesh, vertex positions are set from the hit.

Parameters:

source – Source triangle mesh.
points – (N, 3) NumPy array of query point positions (float64). Modified in place to store the projected positions.
direction – Ray direction. Can be a 3D vector, or a numpy array of shape (N, 3) for per-vertex directions,
cast_mode – Forward-only or both directions (default: CastMode.BothWays).
fallback_mode – Fallback for missed vertices (default: FallbackMode.Constant).
default_value – Fill value for FallbackMode.Constant (default: 0).
ray_caster – Optional pre-built RayCaster for caching.

Returns:

(N, 3) NumPy array of projected positions (float64).