Skip to content

webknossos.geometry.nd_bounding_box

def str_tpl(str_list: Iterable[str]) -> Tuple[str, ...]:
def int_tpl( vec_int_like: Union[webknossos.geometry.vec_int.VecInt, Tuple[int, ...], numpy.ndarray, Iterable[int]]) -> webknossos.geometry.vec_int.VecInt:
class NDBoundingBox:

The NDBoundingBox class is a generalized version of the 3-dimensional BoundingBox class. It is designed to represent bounding boxes in any number of dimensions.

The bounding box is characterized by its top-left corner, the size of the box, the names of the axes for each dimension, and the index (or order) of the axes. Each axis must have a unique index, starting from 1 (index 0 is reserved for channel information).

The top-left coordinate is inclusive, while the bottom-right coordinate is exclusive.

Here's a brief example of how to use it:

# Create a 2D bounding box
bbox_1 = NDBoundingBox(
    top_left=(0, 0),
    size=(100, 100),
    axes=("x", "y"),
    index=(1,2)
)

# Create a 4D bounding box
bbox_2 = NDBoundingBox(
    top_left=(75, 75, 75, 0),
    size=(100, 100, 100, 20),
    axes=("x", "y", "z", "t"),
    index=(2,3,4,1)
)
NDBoundingBox( topleft: Union[webknossos.geometry.vec_int.VecInt, Tuple[int, ...], numpy.ndarray, Iterable[int]], size: Union[webknossos.geometry.vec_int.VecInt, Tuple[int, ...], numpy.ndarray, Iterable[int]], axes: Iterable[str], index: Union[webknossos.geometry.vec_int.VecInt, Tuple[int, ...], numpy.ndarray, Iterable[int]], name: Union[str, NoneType] = 'Unnamed Bounding Box', is_visible: bool = True, color: Union[Tuple[float, float, float, float], NoneType] = None)

Method generated by attrs for class NDBoundingBox.

axes: Tuple[str, ...]
name: Union[str, NoneType]
is_visible: bool
color: Union[Tuple[float, float, float, float], NoneType]
def with_name(self: ~_T, name: Union[str, NoneType]) -> ~_T:

Returns a new instance of NDBoundingBox with the specified name.

Args:

  • name (Optional[str]): The name to assign to the new NDBoundingBox instance.

Returns:

  • NDBoundingBox: A new instance of NDBoundingBox with the specified name.
def with_topleft( self: ~_T, new_topleft: Union[webknossos.geometry.vec_int.VecInt, Tuple[int, ...], numpy.ndarray, Iterable[int]]) -> ~_T:

Returns a new NDBoundingBox object with the specified top left coordinates.

Args:

  • new_topleft (VecIntLike): The new top left coordinates for the bounding box.

Returns:

  • NDBoundingBox: A new NDBoundingBox object with the updated top left coordinates.
def with_size( self: ~_T, new_size: Union[webknossos.geometry.vec_int.VecInt, Tuple[int, ...], numpy.ndarray, Iterable[int]]) -> ~_T:

Returns a new NDBoundingBox object with the specified size.

Args:

  • new_size (VecIntLike): The new size of the bounding box. Can be a VecInt or any object that can be converted to a VecInt.

Returns:

  • A new NDBoundingBox object with the specified size.
def with_index( self: ~_T, new_index: Union[webknossos.geometry.vec_int.VecInt, Tuple[int, ...], numpy.ndarray, Iterable[int]]) -> ~_T:

Returns a new NDBoundingBox object with the specified index.

Args:

  • new_index (VecIntLike): The new axis order for the bounding box.

Returns:

  • NDBoundingBox: A new NDBoundingBox object with the updated index.
def with_bottomright( self: ~_T, new_bottomright: Union[webknossos.geometry.vec_int.VecInt, Tuple[int, ...], numpy.ndarray, Iterable[int]]) -> ~_T:

Returns a new NDBoundingBox with an updated bottomright value.

Args:

  • new_bottomright (VecIntLike): The new bottom right corner coordinates.

Returns:

  • NDBoundingBox: A new NDBoundingBox object with the updated bottom right corner.
def with_is_visible(self: ~_T, is_visible: bool) -> ~_T:

Returns a new NDBoundingBox object with the specified visibility.

Args:

  • is_visible (bool): The visibility value to set.

Returns:

  • NDBoundingBox: A new NDBoundingBox object with the updated visibility value.
def with_color( self: ~_T, color: Union[Tuple[float, float, float, float], NoneType]) -> ~_T:

Returns a new instance of NDBoundingBox with the specified color.

Args:

  • color (Optional[Tuple[float, float, float, float]]): The color to set for the bounding box. The color should be specified as a tuple of four floats representing RGBA values.

Returns:

  • NDBoundingBox: A new instance of NDBoundingBox with the specified color.
def with_bounds( self: ~_T, axis: str, new_topleft: Union[int, NoneType], new_size: Union[int, NoneType]) -> ~_T:

Returns a new NDBoundingBox object with updated bounds along the specified axis.

Args:

  • axis (str): The name of the axis to update.
  • new_topleft (Optional[int]): The new value for the top-left coordinate along the specified axis.
  • new_size (Optional[int]): The new size along the specified axis.

Returns:

  • NDBoundingBox: A new NDBoundingBox object with updated bounds.

Raises:

  • ValueError: If the given axis name does not exist.
def get_bounds(self, axis: str) -> Tuple[int, int]:

Returns the bounds of the given axis.

Args:

  • axis (str): The name of the axis to get the bounds for.

Returns:

  • Tuple[int, int]: A tuple containing the top-left and bottom-right coordinates along the specified axis.
@classmethod
def group_boxes_with_aligned_mag( cls, bounding_boxes: collections.abc.Iterable[webknossos.geometry.nd_bounding_box.NDBoundingBox], aligning_mag: webknossos.geometry.mag.Mag) -> dict[webknossos.geometry.nd_bounding_box.NDBoundingBox, list[webknossos.geometry.nd_bounding_box.NDBoundingBox]]:

Groups the given BoundingBox instances by aligning each bbox to the given mag and using that as the key. For example, bounding boxes of size 2563 could be grouped into the corresponding 10243 chunks to which they belong by using aligning_mag = Mag(1024).

@classmethod
def from_wkw_dict(cls, bbox: Dict) -> webknossos.geometry.nd_bounding_box.NDBoundingBox:

Create an instance of NDBoundingBox from a dictionary representation.

Args:

  • bbox (Dict): The dictionary representation of the bounding box.

Returns:

  • NDBoundingBox: An instance of NDBoundingBox.

Raises:

  • AssertionError: If additionalAxes are present but axisOrder is not provided.
def to_wkw_dict(self) -> dict:

Converts the bounding box object to a json dictionary.

Returns:

  • dict: A json dictionary representing the bounding box.
def to_config_dict(self) -> dict:

Returns a dictionary representation of the bounding box.

Returns:

  • dict: A dictionary representation of the bounding box.
def to_checkpoint_name(self) -> str:

Returns a string representation of the bounding box that can be used as a checkpoint name.

Returns:

  • str: A string representation of the bounding box.
def get_shape(self, axis_name: str) -> int:

Returns the size of the bounding box along the specified axis.

Args:

  • axis_name (str): The name of the axis to get the size for.

Returns:

  • int: The size of the bounding box along the specified axis.
topleft_xyz: webknossos.geometry.vec3_int.Vec3Int

The topleft corner of the bounding box regarding only x, y and z axis.

size_xyz: webknossos.geometry.vec3_int.Vec3Int

The size of the bounding box regarding only x, y and z axis.

bottomright_xyz: webknossos.geometry.vec3_int.Vec3Int

The bottomright corner of the bounding box regarding only x, y and z axis.

index_xyz: webknossos.geometry.vec3_int.Vec3Int

The index of x, y and z axis within the bounding box.

def with_topleft_xyz( self: ~_T, new_xyz: Union[webknossos.geometry.vec3_int.Vec3Int, Tuple[int, int, int], numpy.ndarray, Iterable[int]]) -> ~_T:

Returns a new NDBoundingBox object with changed x, y and z coordinates of the topleft corner.

Args:

  • new_xyz (Vec3IntLike): The new x, y and z coordinates for the topleft corner.

Returns:

  • NDBoundingBox: A new NDBoundingBox object with the updated x, y and z coordinates of the topleft corner.
def with_size_xyz( self: ~_T, new_xyz: Union[webknossos.geometry.vec3_int.Vec3Int, Tuple[int, int, int], numpy.ndarray, Iterable[int]]) -> ~_T:

Returns a new NDBoundingBox object with changed x, y and z size.

Args:

  • new_xyz (Vec3IntLike): The new x, y and z size for the bounding box.

Returns:

  • NDBoundingBox: A new NDBoundingBox object with the updated x, y and z size.
def with_bottomright_xyz( self: ~_T, new_xyz: Union[webknossos.geometry.vec3_int.Vec3Int, Tuple[int, int, int], numpy.ndarray, Iterable[int]]) -> ~_T:

Returns a new NDBoundingBox object with changed x, y and z coordinates of the bottomright corner.

Args:

  • new_xyz (Vec3IntLike): The new x, y and z coordinates for the bottomright corner.

Returns:

  • NDBoundingBox: A new NDBoundingBox object with the updated x, y and z coordinates of the bottomright corner.
def with_index_xyz( self: ~_T, new_xyz: Union[webknossos.geometry.vec3_int.Vec3Int, Tuple[int, int, int], numpy.ndarray, Iterable[int]]) -> ~_T:

Returns a new NDBoundingBox object with changed x, y and z index.

Args:

  • new_xyz (Vec3IntLike): The new x, y and z index for the bounding box.

Returns:

  • NDBoundingBox: A new NDBoundingBox object with the updated x, y and z index.
def padded_with_margins( self, margins_left: Union[webknossos.geometry.vec_int.VecInt, Tuple[int, ...], numpy.ndarray, Iterable[int]], margins_right: Union[webknossos.geometry.vec_int.VecInt, Tuple[int, ...], numpy.ndarray, Iterable[int], NoneType] = None) -> webknossos.geometry.nd_bounding_box.NDBoundingBox:
def intersected_with(self: ~_T, other: ~_T, dont_assert: bool = False) -> ~_T:

Returns the intersection of two bounding boxes.

If dont_assert is set to False, this method may return empty bounding boxes (size == (0, 0, 0))

Args:

  • other (NDBoundingBox): The other bounding box to intersect with.
  • dont_assert (bool): If True, the method may return empty bounding boxes.

Returns:

  • NDBoundingBox: The intersection of the two bounding boxes.
def extended_by(self: ~_T, other: ~_T) -> ~_T:

Returns the smallest bounding box that contains both bounding boxes.

Args:

  • other (NDBoundingBox): The other bounding box to extend with.

Returns:

  • NDBoundingBox: The smallest bounding box that contains both bounding boxes.
def is_empty(self) -> bool:

Boolean check whether the boundung box is empty.

Returns:

  • bool: True if the bounding box is empty, False otherwise.
def in_mag(self: ~_T, mag: webknossos.geometry.mag.Mag) -> ~_T:

Returns the bounding box in the given mag.

Args:

  • mag (Mag): The magnification to convert the bounding box to.

Returns:

  • NDBoundingBox: The bounding box in the given magnification.
def from_mag_to_mag1(self: ~_T, from_mag: webknossos.geometry.mag.Mag) -> ~_T:

Returns the bounging box in the finest magnification (Mag(1)).

Args:

  • from_mag (Mag): The current magnification of the bounding box.

Returns:

  • NDBoundingBox: The bounding box in the given magnification.
def align_with_mag( self: ~_T, mag: Union[webknossos.geometry.mag.Mag, webknossos.geometry.vec3_int.Vec3Int], ceil: bool = False) -> ~_T:

Rounds the bounding box, so that both topleft and bottomright are divisible by mag.

Args:

  • mag (Union[Mag, Vec3Int]): The magnification to align the bounding box to.
  • ceil (bool): If True, the bounding box is enlarged when necessary. If False, it's shrinked when necessary.

Returns:

  • NDBoundingBox: The aligned bounding box.
def contains( self, coord: Union[webknossos.geometry.vec_int.VecInt, Tuple[int, ...], numpy.ndarray, Iterable[int]]) -> bool:

Check whether a point is inside of the bounding box. Note that the point may have float coordinates in the ndarray case

Args:

  • coord (VecIntLike): The coordinates to check.

Returns:

  • bool: True if the point is inside of the bounding box, False otherwise.
def contains_bbox(self: ~_T, inner_bbox: ~_T) -> bool:

Check whether a bounding box is completely inside of the bounding box.

Args:

  • inner_bbox (NDBoundingBox): The bounding box to check.

Returns:

  • bool: True if the bounding box is completely inside of the bounding box, False otherwise.
def chunk( self: ~_T, chunk_shape: Union[webknossos.geometry.vec_int.VecInt, Tuple[int, ...], numpy.ndarray, Iterable[int]], chunk_border_alignments: Union[webknossos.geometry.vec_int.VecInt, Tuple[int, ...], numpy.ndarray, Iterable[int], NoneType] = None) -> Generator[~_T, NoneType, NoneType]:

Decompose the bounding box into smaller chunks of size chunk_shape.

Chunks at the border of the bounding box might be smaller than chunk_shape. If chunk_border_alignment is set, all border coordinates between two chunks will be divisible by that value.

Args:

  • chunk_shape (VecIntLike): The size of the chunks to generate.
  • chunk_border_alignments (Optional[VecIntLike]): The alignment of the chunk borders.

Yields:

  • Generator[NDBoundingBox]: A generator of the chunks.
def volume(self) -> int:

Returns the volume of the bounding box.

def slice_array(self, array: numpy.ndarray) -> numpy.ndarray:

Returns a slice of the given array that corresponds to the bounding box.

def to_slices(self) -> Tuple[slice, ...]:

Returns a tuple of slices that corresponds to the bounding box.

def offset( self: ~_T, vector: Union[webknossos.geometry.vec_int.VecInt, Tuple[int, ...], numpy.ndarray, Iterable[int]]) -> ~_T:

Returns a new NDBoundingBox object with the specified offset.

Args:

  • vector (VecIntLike): The offset to apply to the bounding box.

Returns:

  • NDBoundingBox: A new NDBoundingBox object with the specified offset.