warp.Bvh#

class warp.Bvh(*args, **kwargs)[source]#

__init__( lowers, uppers, constructor=None, groups=None, leaf_size=1, )[source]#

Class representing a bounding volume hierarchy.

Depending on which device the input bounds live, it can be either a CPU tree or a GPU tree.

id#: Unique identifier for this BVH object, can be passed to kernels.

device#: Device this object lives on, all buffers must live on the same device.

Parameters:

lowers (array) – Array of lower bounds of data type warp.vec3.
uppers (array) – Array of upper bounds of data type warp.vec3. lowers and uppers must live on the same device.
constructor (str | None) – The construction algorithm used to build the tree. Valid choices are "sah", "median", "lbvh", or None. When None, the default constructor will be used (see the note).
groups (array | None) – Optional array of group indices of data type warp.int32.
leaf_size (int) – The number of primitives (AABBs) stored in each leaf node. The optimal value depends on the primary use case. For intersection queries (e.g., AABB query), a small value like 1 (the default) is generally recommended for optimal performance. For closest point queries, a larger value like 4 or 8 can be more performant. This is an intrinsic parameter which does not impact the return value of the query method.

Note

Explanation of BVH constructors:

"sah": A CPU-based top-down constructor where the AABBs are split based on Surface Area Heuristics (SAH). Construction takes slightly longer than others but has the best query performance.
"median": A CPU-based top-down constructor where the AABBs are split based on the median of centroids of primitives in an AABB. This constructor is faster than SAH but offers inferior query performance.
"lbvh": A GPU-based bottom-up constructor which maximizes parallelism. Construction is very fast, especially for large models. Query performance is slightly slower than "sah".
None: The constructor will be automatically chosen based on the device where the tree lives. For a GPU tree, the "lbvh" constructor will be selected; for a CPU tree, the "sah" constructor will be selected.

All three constructors are supported for GPU trees. When a CPU-based constructor is selected for a GPU tree, bounds will be copied back to the CPU to run the CPU-based constructor. After construction, the CPU tree will be copied to the GPU.

Only "sah" and "median" are supported for CPU trees. If "lbvh" is selected for a CPU tree, a warning message will be issued, and the constructor will automatically fall back to "sah".

The leaf_size parameter controls the number of primitives (AABBs) stored in each leaf node of the BVH. This parameter can have a considerable impact on query performance, and the optimal value depends on the types of queries that will be performed:

For intersection queries (such as ray or AABB queries), smaller leaf_size values (e.g., 1) are generally preferred, as they reduce the number of unnecessary primitive checks and can improve traversal speed.
For closest point queries, larger leaf_size values (e.g., 4 or more) may be beneficial, as they allow more primitives to be checked together, potentially reducing traversal overhead.

The default value is 1, which is optimal for intersection queries. For use cases that involve both intersection and closest point queries (such as mesh queries), a moderate value (e.g., 4) may provide a good balance. Users are encouraged to experiment with this parameter to find the best value for their specific workload.

Concept of Grouped BVH:

A Grouped BVH extends the traditional Bounding Volume Hierarchy to efficiently handle multiple independent groups of objects—such as distinct environments in parallel robot simulations—within a single BVH structure.

In a standard BVH, all objects share one global tree, so queries must traverse the entire hierarchy and filter results in user space. Grouped BVH introduces a group identifier for each object and makes sure that objects from the same group occupy an entire subtree whose root can be quickly identified by calling bvh_get_group_root.

By starting traversal directly from a group’s root node, queries are confined to that group’s objects only, avoiding unnecessary intersection tests with other groups. This design significantly reduces query overhead for large multi-environment workloads, improves memory coherence, and eliminates the need for spatial separation between groups.

The grouped BVH thus allows Warp to perform environment-specific queries—such as collision detection, sensor simulation, or rendering—within a unified BVH framework, maintaining compatibility with existing APIs and near-identical performance for non-grouped use cases.

Methods

`__init__`(lowers, uppers[, constructor, ...])	Class representing a bounding volume hierarchy.
`rebuild`([constructor])	Rebuild the BVH hierarchy in place from the current `lowers`/`uppers` arrays.
`refit`()	Refit the BVH.

refit()[source]#

Refit the BVH.

This should be called after users modify the lowers or uppers arrays.

rebuild(constructor=None)[source]#

Rebuild the BVH hierarchy in place from the current lowers/uppers arrays.

This method does not allocate new memory; it reuses the existing BVH buffers.

Unlike refit(), which only tightens parent AABBs while preserving the existing tree topology, rebuild discards the old hierarchy and constructs a new one. Use this when primitive distributions change significantly (large deformations, insertions/removals, or reordered items), or when you want to switch construction algorithms.

Parameters:: constructor (str | None) – Construction algorithm to use. One of "sah", "median", "lbvh", or None. If None, the default is chosen based on the device (CPU → "sah", CUDA → "lbvh"). On CPU, "sah" and "median" are supported; requesting "lbvh" falls back to "sah" with a warning. On CUDA, in-place rebuild supports "lbvh" only; other values fall back to "lbvh" with a warning.

Notes

This method is CUDA graph-capture safe: previously captured graphs that include queries on this BVH remain valid after rebuild because buffers are reused.
If you need a CPU top-down constructor ("sah"/"median") for a GPU tree, create a new BVH via the class constructor instead.

Raises:: ValueError – If an unknown constructor is provided.
Parameters:: constructor (str | None)