from __future__ import annotations
import copy
from typing import TYPE_CHECKING, Any
import numpy as np
import numpy.typing as npt
from py3dtiles.exceptions import TilerException
from py3dtiles.typing import BoundingVolumeBoxDictType
from .bounding_volume import BoundingVolume
if TYPE_CHECKING:
from typing_extensions import Self
from .tile import Tile
# In order to prevent the appearance of ghost newline characters ("\n")
# when printing a numpy.array (mainly self._box in this file):
np.set_printoptions(linewidth=500)
[docs]
class BoundingVolumeBox(BoundingVolume[BoundingVolumeBoxDictType]):
"""
A box bounding volume as defined in the 3DTiles specifications i.e. an
array of 12 numbers that define an oriented bounding box:
- The first three elements define the x, y, and z values for the center of the box.
- The next three elements (with indices 3, 4, and 5) define the x axis
direction and half-length.
- The next three elements (with indices 6, 7, and 8) define the y axis
direction and half-length.
- The last three elements (indices 9, 10, and 11) define the z axis
direction and half-length.
Note that, by default, a box bounding volume doesn't need to be aligned
with the coordinate axis. Still in general, computing the box bounding
volume of two box bounding volumes won't necessarily yield a box that is
aligned with the coordinate axis (although this computation might require
some fitting algorithm e.g. the principal component analysis method.
Yet in sake of simplification (and numerical efficiency), when asked to
"add" (i.e. to find the enclosing box of) two (or more) box bounding
volumes this class resolves to compute the "canonical" fitting/enclosing
box i.e. a box that is parallel to the coordinate axis.
"""
def __init__(self) -> None:
super().__init__()
self._box: npt.NDArray[np.float64] | None = None
[docs]
@classmethod
def from_dict(cls, bounding_volume_box_dict: BoundingVolumeBoxDictType) -> Self:
"""
Construct a BoundingVolumeBox from a dict following the structure of a 3dtiles bounding volume
"""
bounding_volume_box = cls()
bounding_volume_box.set_from_list(bounding_volume_box_dict["box"])
bounding_volume_box.set_properties_from_dict(bounding_volume_box_dict)
return bounding_volume_box
[docs]
@classmethod
def from_points(cls, points: list[npt.NDArray[np.float64]]) -> BoundingVolumeBox:
"""
Construct a bounding box enclosing all the points.
Internally call `set_from_points`.
:return: a new instance of BoundingVolumeBox
"""
result = cls()
result.set_from_points(points)
return result
[docs]
@classmethod
def from_list(cls, box_list: npt.ArrayLike) -> BoundingVolumeBox:
"""
Construct a bounding box enclosing all the points.
Internally call `set_from_points`.
:return: a new instance of BoundingVolumeBox
"""
result = cls()
result.set_from_list(box_list)
return result
[docs]
def get_center(self) -> npt.NDArray[np.float64]:
if self._box is None:
raise AttributeError("Bounding Volume Box is not defined.")
return self._box[0:3]
[docs]
def translate(self, offset: npt.NDArray[np.float64]) -> None:
"""
Translate the box center with the given offset "vector"
:param offset: the 3D vector by which the box should be translated
"""
if self._box is None:
raise AttributeError("Bounding Volume Box is not defined.")
self._box[:3] += offset[:3]
[docs]
def set_from_list(self, box_list: npt.ArrayLike) -> None:
"""
Set the box from a list of coordinates closely matching the 3Dtiles spec.
:param box_list: An array of 12 numbers that define an oriented bounding box. The first three elements define the x, y, and z values for the center of the box. The next three elements (with indices 3, 4, and 5) define the x axis direction and half-length. The next three elements (indices 6, 7, and 8) define the y axis direction and half-length. The last three elements (indices 9, 10, and 11) define the z axis direction and half-length.
"""
box = np.array(box_list, dtype=np.float64)
valid, reason = BoundingVolumeBox.is_valid(box)
if not valid:
raise ValueError(reason)
self._box = box
[docs]
def set_from_points(self, points: list[npt.NDArray[np.float64]]) -> None:
"""
Make the current box only include a list of points. Note: the box limits are replaced, not extended.
:param points: An array of points
"""
box = BoundingVolumeBox.get_box_array_from_point(points)
valid, reason = BoundingVolumeBox.is_valid(box)
if not valid:
raise ValueError(reason)
self._box = box
[docs]
def set_from_mins_maxs(self, mins_maxs: npt.NDArray[np.float64]) -> None:
"""
Set the box from a min and a max.
:param mins_maxs: the array [x_min, y_min, z_min, x_max, y_max, z_max]
that is the boundaries of the box along each
coordinate axis
"""
self._box = BoundingVolumeBox.get_box_array_from_mins_maxs(mins_maxs)
[docs]
def get_corners(self) -> list[npt.NDArray[np.float64]]:
"""
:return: the corners (3D points) of the box as a list
"""
if self._box is None:
raise AttributeError("Bounding Volume Box is not defined.")
center, x_half_axis, y_half_axis, z_half_axis = self._box.reshape([-1, 3])
x_axis = x_half_axis * 2
y_axis = y_half_axis * 2
z_axis = z_half_axis * 2
# The eight cornering points of the box
origin = center - x_half_axis - y_half_axis - z_half_axis
ox = origin + x_axis
oy = origin + y_axis
oz = origin + z_axis
oxy = ox + y_axis
oxz = ox + z_axis
oyz = oy + z_axis
oxyz = oxy + z_axis
return [origin, ox, oy, oxy, oz, oxz, oyz, oxyz]
[docs]
def get_canonical_as_array(self) -> npt.NDArray[np.float64]:
"""
:return: the smallest enclosing box (as an array) that is parallel
to the coordinate axis
"""
return BoundingVolumeBox.get_box_array_from_point(self.get_corners())
[docs]
def add(self, other: BoundingVolume[Any]) -> None:
"""
Compute the 'canonical' bounding volume fitting this bounding volume
together with the added bounding volume. Again (refer above to the
class definition) the computed fitting bounding volume is generically
not the smallest one (due to its alignment with the coordinate axis).
:param other: another box bounding volume to be added with this one
"""
if not isinstance(other, BoundingVolumeBox):
raise NotImplementedError(
"The add method works only with BoundingVolumeBox"
)
if self._box is None:
# Then it is safe to overwrite
self._box = copy.deepcopy(other._box)
return
corners = self.get_corners() + other.get_corners()
self.set_from_points(corners)
[docs]
def sync_with_children(self, owner: Tile) -> None:
# We reset to some dummy state of this Bounding Volume Box so we
# can add up in place the boxes of the owner's children
# If there is no child, no modifications are done.
for child in owner.children:
if child.bounding_volume is None:
raise TilerException("Child should have a bounding volume.")
bounding_volume = copy.deepcopy(child.bounding_volume)
bounding_volume.transform(child.transform)
if not isinstance(bounding_volume, BoundingVolumeBox):
raise TilerException(
"All children must also have a box as bounding volume "
"if the parent has a bounding box"
)
self.add(bounding_volume)
[docs]
def to_dict(self) -> BoundingVolumeBoxDictType:
if self._box is None:
raise AttributeError("Bounding Volume Box is not defined.")
dict_data: BoundingVolumeBoxDictType = {"box": list(self._box)}
return self.add_root_properties_to_dict(dict_data)
[docs]
@staticmethod
def get_box_array_from_mins_maxs(
mins_maxs: npt.NDArray[np.float64],
) -> npt.NDArray[np.float64]:
"""
:param mins_maxs: the list [x_min, y_min, z_min, x_max, y_max, z_max]
that is the boundaries of the box along each
coordinate axis
:return: the smallest box (as an array, as opposed to a
BoundingVolumeBox instance) that encloses the given list of
(3D) points and that is parallel to the coordinate axis.
"""
x_min = mins_maxs[0]
x_max = mins_maxs[3]
y_min = mins_maxs[1]
y_max = mins_maxs[4]
z_min = mins_maxs[2]
z_max = mins_maxs[5]
new_center = np.array(
[(x_min + x_max) / 2, (y_min + y_max) / 2, (z_min + z_max) / 2]
)
new_x_half_axis = np.array([(x_max - x_min) / 2, 0, 0])
new_y_half_axis = np.array([0, (y_max - y_min) / 2, 0])
new_z_half_axis = np.array([0, 0, (z_max - z_min) / 2])
return np.concatenate(
(new_center, new_x_half_axis, new_y_half_axis, new_z_half_axis)
)
[docs]
@staticmethod
def get_box_array_from_point(
points: list[npt.NDArray[np.float64]],
) -> npt.NDArray[np.float64]:
"""
:param points: a list of 3D points
:return: the smallest box (as an array, as opposed to a
BoundingVolumeBox instance) that encloses the given list of
(3D) points and that is parallel to the coordinate axis.
"""
return BoundingVolumeBox.get_box_array_from_mins_maxs(
np.array(
[
min(c[0] for c in points),
min(c[1] for c in points),
min(c[2] for c in points),
max(c[0] for c in points),
max(c[1] for c in points),
max(c[2] for c in points),
]
)
)
[docs]
@staticmethod
def is_valid(box: npt.NDArray[np.float64]) -> tuple[bool, str]:
if box is None:
return False, "Bounding Volume Box is not defined."
if box.ndim != 1:
return False, "Bounding Volume Box has wrong dimensions."
if box.shape[0] != 12:
return False, "Warning: Bounding Volume Box must have 12 elements."
return True, ""