pyvale.render.scenetools module

Spatial layout and multi object arrangement helpers for render scenes.

scene_arrange_circle(meshes, radius=100.0, plane='xy', center=array([0., 0., 0.]))

Place mesh centers evenly spaced around a circle.

Parameters:

• meshes (Sequence[Mesh3D]) – Collection of meshes to arrange in a circle.

• radius (float, optional) – Radius of the circle. Defaults to 100.0.

• plane (str, optional) – Circle plane ("xy", "xz", or "yz"). Defaults to "xy".

• center (np.ndarray, optional) – Center coordinates of the circle with shape (3,) and dtype float64. Defaults to (0.0, 0.0, 0.0).

Returns:

list[Mesh3D] – New list of circularly arranged meshes.

Raises:

ValueError – If plane is unsupported.

scene_arrange_grid(meshes, columns=3, spacing=array([0., 0.]), plane='xy', center=True)

Arrange meshes in a 2D planar grid with defined gaps between boxes.

Parameters:

• meshes (Sequence[Mesh3D]) – Collection of meshes to arrange in a grid.

• columns (int, optional) – Number of grid columns. Defaults to 3.

• spacing (np.ndarray, optional) – Gaps between bounding boxes with shape (2,) and dtype float64 representing (gap_u, gap_v). Defaults to (0.0, 0.0).

• plane (str, optional) – Grid arrangement plane ("xy", "xz", or "yz"). Defaults to "xy".

• center (bool, optional) – Whether to center the entire grid at the origin. Defaults to True.

Returns:

list[Mesh3D] – New list of grid arranged meshes.

Raises:

ValueError – If columns is not positive or plane is unsupported.

scene_arrange_line(meshes, axis=0, spacing=0.0)

Arrange meshes in a line with a constant gap between bounding boxes.

Parameters:

• meshes (Sequence[Mesh3D]) – Collection of meshes to arrange.

• axis (int, optional) – Spatial axis index along which to align meshes (0 for X, 1 for Y, 2 for Z). Defaults to 0.

• spacing (float, optional) – Clearance distance between successive bounding boxes. Defaults to 0.0.

Returns:

list[Mesh3D] – New list of arranged meshes.

scene_arrange_points(meshes, positions)

Move each mesh so its bounding box center lies at the matching target.

Parameters:

• meshes (Sequence[Mesh3D]) – Collection of meshes to arrange.

• positions (np.ndarray) – Array of target center positions with shape (num_meshes, 3) and dtype float64 representing (X, Y, Z) coordinates for each mesh.

Returns:

list[Mesh3D] – New list of repositioned meshes.

Raises:

ValueError – If the number of meshes does not match the number of positions.

scene_bounds(meshes)

Calculate the bounding box enclosing all meshes in a scene.

Parameters:

meshes (Sequence[Mesh3D]) – Collection of meshes to measure.

Returns:

tuple[np.ndarray, np.ndarray] – Tuple of (coord_min, coord_max) arrays, each with shape (3,) and dtype float64 representing (X, Y, Z) minimum and maximum extents of the enclosing bounding box.

scene_center(meshes)

Calculate the midpoint of the scene bounding box.

Parameters:

meshes (Sequence[Mesh3D]) – Collection of meshes.

Returns:

np.ndarray – Midpoint coordinates array with shape (3,) and dtype float64 representing (X, Y, Z) center of the scene.

scene_rotate(meshes, rotation, pivot=None)

Rotate all meshes around a shared pivot (default: scene center).

Parameters:

• meshes (Sequence[Mesh3D]) – Collection of meshes to rotate.

• rotation (scipy.spatial.transform.Rotation) – Spatial rotation to apply to all meshes.

• pivot (np.ndarray or None, optional) – Pivot center point array with shape (3,) and dtype float64. If None, defaults to the scene center.

Returns:

list[Mesh3D] – New list of rotated meshes.

scene_translate(meshes, translation)

Translate every mesh in a sequence by the same offset vector.

Parameters:

• meshes (Sequence[Mesh3D]) – Collection of meshes to translate.

• translation (np.ndarray) – Translation offset array with shape (3,) or (2,) and dtype float64 representing (dX, dY, dZ) offsets.

Returns:

list[Mesh3D] – New list of translated meshes.