warp.geometry.oriented_bounding_boxes#

warp.geometry.oriented_bounding_boxes(
points,
offsets,
measure_type=OBBMeasureType.VOLUME,
num_samples=4096,
*,
include_axis_aligned=True,
include_pca=True,
max_search_points=None,
num_refine_starts=_OBB_REFINE_STARTS,
num_refine_iterations=_OBB_REFINE_ITERATIONS,
num_refine_samples=_OBB_REFINE_SAMPLES,
num_spin_samples=_OBB_SPIN_SAMPLES,
max_points_per_shape=None,
validate=True,
device=None,
)[source]#

Approximate an oriented bounding box (OBB) of each of several point sets in one pass.

Equivalent to calling oriented_bounding_box() on every point set, but all point sets share each kernel launch, so the cost of many small point sets is no longer dominated by launch overhead. The point sets are stored back to back in points; offsets marks where each one starts and ends. See oriented_bounding_box() for the search that is run on each point set and for the meaning of the shared search parameters.

Parameters:
  • points (warp.array[warp.vec3]) – Array of point positions of type warp.vec3, holding every point set one after another.

  • offsets (warp.array[warp.int32]) – Array of num_shapes + 1 int32 offsets into points. Point set i is points[offsets[i]:offsets[i + 1]], so the offsets must be non-decreasing, and every point set must contain at least one point.

  • measure_type (OBBMeasureType) – Quantity to minimize, as an OBBMeasureType member.

  • num_samples (int) – Number of candidate orientations to sample from the spiral for each point set.

  • include_axis_aligned (bool) – Whether to also evaluate the identity rotation.

  • include_pca (bool) – Whether to also evaluate the principal axes of each point set.

  • max_search_points (int | None) – Upper bound on how many points of each point set are used to score candidate orientations, or None (the default) to score over every point. A cap bounds the cost of fitting very large point sets but can change which orientation is chosen. Each box is re-measured over all of its points either way.

  • num_refine_starts (int) – Number of distinct candidate orientations that are refined, each from a different basin of the search space. Refining several avoids committing to a sampled orientation that is not near the best one.

  • num_refine_iterations (int) – Number of coarse-to-fine refinement rounds after the initial search.

  • num_refine_samples (int) – Number of orientations probed per refinement round around each start.

  • num_spin_samples (int) – Number of angles probed about each of the box’s three axes in each of three final spin rounds (coarse to fine) around each start. Spinning about an axis keeps a box face that is flush with a face of the point set’s convex hull flush, so this settles the box onto the best such position. Pass 0 to skip the spin rounds.

  • max_points_per_shape (int | None) – Optional upper bound on the size of any one point set, used only to size the launches. Supplying it avoids over-provisioning threads when every point set is small. Results do not depend on it.

  • validate (bool) – Whether to read offsets back to the host to check it. This synchronizes the device, so pass False when the offsets are known to be valid, which also makes the call capturable in a CUDA graph. Validation is skipped during graph capture regardless. Without validation, a point set that is empty yields a box with non-finite extents instead of an error.

  • device (DeviceLike | None) – Device on which to run. Defaults to the device of points.

Returns:

A tuple (transform, extents, measure) of length-num_shapes device arrays, where entry i describes point set i exactly as for oriented_bounding_box().

Return type:

tuple[wp.array, wp.array, wp.array]

Note

The cost of the search is proportional to the total number of points. Replacing each point set with its convex hull vertices, or with any other subset that is known to contain every hull vertex, leaves every box unchanged and lowers the cost in proportion to the number of points removed; see oriented_bounding_box().

Scratch memory grows with num_shapes * max(num_samples, num_refine_starts * num_refine_samples, 3 * num_refine_starts * num_spin_samples). For a very large number of shapes, call this function on groups of them.

Raises:
  • ValueError – If a search parameter is out of range as for oriented_bounding_box(), if offsets is not on the device of points, if offsets is not num_shapes + 1 non-decreasing offsets within points with no empty point set, if max_points_per_shape is not positive, or if the batch is too large for the scratch memory.

  • TypeError – If offsets does not hold int32 values.

Parameters:
Return type:

tuple[wp.array, wp.array, wp.array]