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,
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 inpoints;offsetsmarks where each one starts and ends. Seeoriented_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 + 1int32offsets intopoints. Point setiispoints[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
OBBMeasureTypemember.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
0to 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
offsetsback to the host to check it. This synchronizes the device, so passFalsewhen 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_shapesdevice arrays, where entryidescribes point setiexactly as fororiented_bounding_box().- Return type:
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(), ifoffsetsis not on the device ofpoints, ifoffsetsis notnum_shapes + 1non-decreasing offsets withinpointswith no empty point set, ifmax_points_per_shapeis not positive, or if the batch is too large for the scratch memory.TypeError – If
offsetsdoes not holdint32values.
- Parameters:
points (warp.array[warp.vec3])
offsets (warp.array[warp.int32])
measure_type (OBBMeasureType)
num_samples (int)
include_axis_aligned (bool)
include_pca (bool)
max_search_points (int | None)
num_refine_starts (int)
num_refine_iterations (int)
num_refine_samples (int)
num_spin_samples (int)
max_points_per_shape (int | None)
validate (bool)
device (DeviceLike | None)
- Return type: