pyvista.DataSetFilters.oriented_bounding_box

DataSetFilters.oriented_bounding_box(

box_style: Literal['frame', 'outline', 'face'] = 'face',

*,

axis_0_direction: VectorLike[float] | str | None = None,

axis_1_direction: VectorLike[float] | str | None = None,

axis_2_direction: VectorLike[float] | str | None = None,

frame_width: float = 0.1,

return_meta: bool = False,

as_composite: bool = True,

)

Return an oriented bounding box (OBB) for this dataset.

By default, the bounding box is a MultiBlock with six PolyData comprising the faces of a cube. The blocks are named and ordered as ('+X','-X','+Y','-Y','+Z','-Z').

The box can optionally be styled as an outline or frame.

Note

The names of the blocks of the returned MultiBlock correspond to the oriented box’s local axes, not the global x-y-z axes. E.g. the normal of the '+X' face of the returned box has the same direction as the box’s primary axis, and is not necessarily pointing in the +x direction (1, 0, 0).

Added in version 0.45.

Parameters:

box_style‘frame’ | ‘outline’ | ‘face’, default: ‘face’

Choose the style of the box. If 'face' (default), each face of the box is a single quad cell. If 'outline', the edges of each face are returned as line cells. If 'frame', the center portion of each face is removed to create a picture-frame style border with each face having four quads (one for each side of the frame). Use frame_width to control the size of the frame.

axis_0_directionVectorLike[float] | str, optional

Approximate direction vector of this mesh’s primary axis. If set, the first axis in the returned axes metadata is flipped such that it best aligns with the specified vector. Can be a vector or string specifying the axis by name (e.g. 'x' or '-x', etc.).

axis_1_directionVectorLike[float] | str, optional

Approximate direction vector of this mesh’s secondary axis. If set, the second axis in the returned axes metadata is flipped such that it best aligns with the specified vector. Can be a vector or string specifying the axis by name (e.g. 'x' or '-x', etc.).

axis_2_directionVectorLike[float] | str, optional

Approximate direction vector of this mesh’s third axis. If set, the third axis in the returned axes metadata is flipped such that it best aligns with the specified vector. Can be a vector or string specifying the axis by name (e.g. 'x' or '-x', etc.).

frame_widthfloat, optional

Set the width of the frame. Only has an effect if box_style is 'frame'. Values must be between 0.0 (minimal frame) and 1.0 (large frame). The frame is scaled to ensure it has a constant width.

return_metabool, default: False

If True, also returns the corner point and the three axes vectors defining the orientation of the box. The sign of the axes vectors can be controlled using the axis_#_direction arguments.

as_compositebool, default: True

Return the box as a pyvista.MultiBlock with six blocks: one for each face. Set this False to merge the output and return PolyData.

Returns:

pyvista.MultiBlock or pyvista.PolyData

MultiBlock with six named cube faces when as_composite=True and PolyData otherwise.

numpy.ndarray

The box’s corner point corresponding to the origin of its axes if return_meta=True.

numpy.ndarray

The box’s orthonormal axes vectors if return_meta=True.

See also

bounding_box

Similar filter for an axis-aligned bounding box (AABB).

align_xyz

Align a mesh to the world x-y-z axes. Used internally by this filter.

pyvista.Plotter.add_bounding_box

Add a bounding box to a scene.

pyvista.CubeFacesSource

Generate the faces of a cube. Used internally by this filter.

Examples

Create a bounding box for a dataset.

>>> import pyvista as pv
>>> from pyvista import examples
>>> mesh = examples.download_oblique_cone()
>>> box = mesh.oriented_bounding_box()

Plot the mesh and its bounding box.

>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(mesh, color='red')
>>> _ = pl.add_mesh(box, opacity=0.5)
>>> pl.show()

Static Scene

Interactive Scene

Return the metadata for the box.

>>> box, point, axes = mesh.oriented_bounding_box('outline', return_meta=True)

Use the metadata to plot the box’s axes using AxesAssembly. The assembly is aligned with the x-y-z axes and positioned at the origin by default. Create a transformation to scale, then rotate, then translate the assembly to the corner point of the box. The transpose of the axes is used as an inverted rotation matrix.

>>> scale = box.length / 4
>>> transform = pv.Transform().scale(scale).rotate(axes.T).translate(point)
>>> axes_assembly = pv.AxesAssembly(user_matrix=transform.matrix)

Plot the box and the axes.

>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(mesh)
>>> _ = pl.add_mesh(box, color='black', line_width=5)
>>> _ = pl.add_actor(axes_assembly)
>>> pl.show()

Static Scene

Interactive Scene

Note how the box’s z-axis is pointing from the cone’s tip to its base. If we want to flip this axis, we can “seed” its direction as the '-z' direction.

>>> box, _, axes = mesh.oriented_bounding_box(
...     'outline', axis_2_direction='-z', return_meta=True
... )
>>>

Plot the box and axes again. This time, use AxesAssemblySymmetric and position the axes in the center of the box.

>>> center = pv.merge(box).points.mean(axis=0)
>>> scale = box.length / 2
>>> transform = pv.Transform().scale(scale).rotate(axes.T).translate(center)
>>> axes_assembly = pv.AxesAssemblySymmetric(user_matrix=transform.matrix)

>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(mesh)
>>> _ = pl.add_mesh(box, color='black', line_width=5)
>>> _ = pl.add_actor(axes_assembly)
>>> pl.show()

Static Scene

Interactive Scene