webknossos.geometry.bounding_box ¶

BoundingBox ¶

Bases: NDBoundingBox

An axis-aligned 3D bounding box with integer coordinates.

This class represents a axis-aligned cuboid in 3D space. The top-left coordinate is inclusive and the bottom-right coordinate is exclusive, defining a volume in space.

A small usage example:

from webknossos import BoundingBox

bbox_1 = BoundingBox((0, 0, 0), (100, 100, 100))
bbox_2 = BoundingBox((75, 75, 75), (100, 100, 100))

assert bbox_1.intersected_with(bbox_2).size == (25, 25, 25)

Attributes:

topleft (Vec3Int) –

Top-left corner coordinates (inclusive)
size (Vec3Int) –

Size of the bounding box in units of voxels for each dimension (width, height, depth)
axes (tuple[str, str, str]) –

Names of the coordinate axes, defaults to ("x", "y", "z")
index (Vec3Int) –

Index values for each dimension, defaults to (1, 2, 3)
bottomright (Vec3Int) –

Bottom-right corner coordinates (exclusive), computed from topleft + size
name (str | None) –

Optional name for the bounding box, defaults to "Unnamed Bounding Box"
is_visible (bool) –

Whether the bounding box should be visible, defaults to True
color (tuple[float, float, float, float] | None) –

Optional RGBA color values

axes `class-attribute` `instance-attribute` ¶

axes: tuple[str, str, str] = field(default=('x', 'y', 'z'))

bottomright `class-attribute` `instance-attribute` ¶

bottomright: Vec3Int = field(init=False)

bottomright_xyz `property` ¶

bottomright_xyz: Vec3Int

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

color `class-attribute` `instance-attribute` ¶

color: tuple[float, float, float, float] | None = None

index `class-attribute` `instance-attribute` ¶

index: Vec3Int = field(default=Vec3Int(1, 2, 3))

index_xyz `property` ¶

index_xyz: Vec3Int

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

is_visible `class-attribute` `instance-attribute` ¶

is_visible: bool = True

name `class-attribute` `instance-attribute` ¶

name: str | None = _DEFAULT_BBOX_NAME

ndim `property` ¶

ndim: int

The number of dimensions of the bounding box.

size `class-attribute` `instance-attribute` ¶

size: Vec3Int = field(converter=Vec3Int)

size_xyz `property` ¶

size_xyz: Vec3Int

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

topleft `class-attribute` `instance-attribute` ¶

topleft: Vec3Int = field(converter=Vec3Int)

topleft_xyz `property` ¶

topleft_xyz: Vec3Int

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

align_with_mag ¶

align_with_mag(mag: Mag | Vec3Int, ceil: bool = False) -> BoundingBox

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

Parameters:

mag (Mag) –

The mag to align with.
ceil (bool, default: False ) –

If true, the bounding box is enlarged when necessary. If false, it's shrunk when necessary.

Returns:

BoundingBox ( BoundingBox ) –

The aligned bounding box.

chunk ¶

chunk(chunk_shape: Vec3IntLike, chunk_border_alignments: Vec3IntLike | None = None) -> Generator[BoundingBox, None, None]

Decompose the bounding box into smaller chunks of size chunk_shape.

Parameters:

chunk_shape (Vec3IntLike) –

Size of chunks to decompose into. Each chunk will be at most this size.
chunk_border_alignments (Vec3IntLike | None, default: None ) –

If provided, all border coordinates between chunks will be divisible by these values.

Yields:

BoundingBox ( BoundingBox ) –

Smaller chunks of the original bounding box. Border chunks may be smaller than chunk_shape.

Raises:

AssertionError –

If chunk_border_alignments is provided and chunk_shape is not divisible by it.

Note

Border chunks may be smaller than chunk_shape
If chunk_border_alignments is provided, all border coordinates between chunks will be aligned to those values

contains ¶

contains(coord: Vec3IntLike | ndarray) -> bool

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

contains_bbox ¶

contains_bbox(inner_bbox: _T) -> bool

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

Parameters:

inner_bbox (NDBoundingBox) –

The bounding box to check.

Returns:

bool ( bool ) –

True if the bounding box is completely inside of the bounding box, False otherwise.

empty `classmethod` ¶

empty() -> BoundingBox

extended_by ¶

extended_by(other: _T) -> _T

Returns the smallest bounding box that contains both bounding boxes.

Parameters:

other (NDBoundingBox) –

The other bounding box to extend with.

Returns:

NDBoundingBox ( _T ) –

The smallest bounding box that contains both bounding boxes.

from_auto `classmethod` ¶

from_auto(obj: Union[BoundingBox, str, dict, list, tuple]) -> BoundingBox

from_checkpoint_name `classmethod` ¶

from_checkpoint_name(checkpoint_name: str) -> BoundingBox

This function extracts a bounding box in the format x_y_z_sx_sy_xz which is contained in a string.

from_config_dict `classmethod` ¶

from_config_dict(bbox: dict) -> BoundingBox

Creates a BoundingBox from a config-format dictionary.

Parameters:

bbox (Dict) –

Dictionary containing config-format bounding box data with keys 'topleft' and 'size'

Returns:

BoundingBox ( BoundingBox ) –

A new bounding box with the specified dimensions

from_csv `classmethod` ¶

from_csv(csv_bbox: str) -> BoundingBox

from_mag_to_mag1 ¶

from_mag_to_mag1(from_mag: Mag) -> _T

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

Parameters:

from_mag (Mag) –

The current magnification of the bounding box.

Returns:

NDBoundingBox ( _T ) –

The bounding box in the given magnification.

from_ndbbox `classmethod` ¶

from_ndbbox(bbox: NDBoundingBox) -> BoundingBox

from_points `classmethod` ¶

from_points(points: Iterable[Vec3IntLike]) -> BoundingBox

Returns a bounding box which is guaranteed to completely enclose all points in the input.

Parameters:

points (Iterable[Vec3IntLike]) –

Set of points to be bounded. Each point must be convertible to Vec3Int.

Returns:

BoundingBox ( BoundingBox ) –

A bounding box that is the minimum size needed to contain all input points.exactly containing all points.

from_tuple2 `classmethod` ¶

from_tuple2(tuple2: tuple[Vec3IntLike, Vec3IntLike]) -> BoundingBox

Creates a BoundingBox from a 2-tuple of coordinates.

Parameters:

tuple2 (tuple[Vec3IntLike, Vec3IntLike]) –

A tuple containing the topleft coordinates and size dimensions

Returns:

BoundingBox ( BoundingBox ) –

A new bounding box with the specified dimensions

from_tuple6 `classmethod` ¶

from_tuple6(tuple6: tuple[int, int, int, int, int, int]) -> BoundingBox

Creates a BoundingBox from a 6-tuple of coordinates.

Parameters:

tuple6 (tuple[int, int, int, int, int, int]) –

A tuple containing (x, y, z) coordinates followed by (width, height, depth) dimensions

Returns:

BoundingBox ( BoundingBox ) –

A new bounding box with the specified dimensions

from_wkw_dict `classmethod` ¶

from_wkw_dict(bbox: dict) -> BoundingBox

Creates a BoundingBox from a wkw-format dictionary.

Parameters:

bbox (Dict) –

Dictionary containing wkw-format bounding box data with keys 'topLeft', 'width', 'height', and 'depth'

Returns:

BoundingBox ( BoundingBox ) –

A new bounding box with the specified dimensions

get_bounds ¶

get_bounds(axis: str) -> tuple[int, int]

Returns the bounds of the given axis.

Parameters:

axis (str) –

The name of the axis to get the bounds for.

Returns:

tuple[int, int] –

tuple[int, int]: A tuple containing the top-left and bottom-right coordinates along the specified axis.

get_shape ¶

get_shape(axis_name: str) -> int

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

Parameters:

axis_name (str) –

The name of the axis to get the size for.

Returns:

int ( int ) –

The size of the bounding box along the specified axis.

group_boxes_with_aligned_mag `classmethod` ¶

group_boxes_with_aligned_mag(bounding_boxes: Iterable[NDBoundingBox], aligning_mag: Mag) -> dict[NDBoundingBox, list[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).

in_mag ¶

in_mag(mag: Mag) -> BoundingBox

Returns a new bounding box with coordinates scaled by the given magnification factor.

The method asserts that both topleft and bottomright coordinates are already properly aligned with the magnification factor. Use align_with_mag() first if needed.

Parameters:

mag (Mag) –

The magnification factor to scale coordinates by

Returns:

BoundingBox ( BoundingBox ) –

A new bounding box with coordinates divided by the magnification factor

Raises:

AssertionError –

If topleft or bottomright coordinates are not aligned with mag

intersected_with ¶

intersected_with(other: _T, dont_assert: bool = False) -> _T

Returns the intersection of two bounding boxes. If there is no intersection (resulting bounding box is empty) and dont_assert is False (default) the function raises an assertion error. If dont_assert is set to True this method returns an empty bounding box if there is no intersection.

Parameters:

other (NDBoundingBox) –

The other bounding box to intersect with.
dont_assert (bool, default: False ) –

If True, the method may return an empty bounding box. Default is False.

Returns:

NDBoundingBox ( _T ) –

The intersection of the two bounding boxes.

is_empty ¶

is_empty() -> bool

Checks if the bounding box has zero or negative size.

Tests if any dimension of the bounding box has zero or negative size.

Returns:

bool ( bool ) –

True if any dimension has zero or negative size, False otherwise.

offset ¶

offset(vector: Vec3IntLike) -> BoundingBox

Creates an offset copy of this bounding box by adding a vector to the topleft coordinate.

Generates a new bounding box with identical dimensions but translated by the given vector.

Parameters:

vector (Vec3IntLike) –

The vector to offset the bounding box by

Returns:

BoundingBox ( BoundingBox ) –

A new bounding box offset by the given vector

padded_with_margins ¶

padded_with_margins(margins_left: Vec3IntLike, margins_right: Vec3IntLike | None = None) -> _T

slice_array ¶

slice_array(array: ndarray) -> ndarray

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

to_checkpoint_name ¶

to_checkpoint_name() -> str

Converts the bounding box dimensions to a checkpoint name string.

Creates a string formatted as "x_y_z_width_height_depth" containing the bounding box coordinates and dimensions.

Returns:

str ( str ) –

A string in checkpoint name format containing the bounding box dimensions

to_config_dict ¶

to_config_dict() -> dict

Converts the bounding box to a config-format dictionary.

Creates a dictionary with config-format fields containing the bounding box dimensions.

Returns:

dict ( dict ) –

A dictionary with keys: - topleft: list[int] of (x,y,z) coordinates - size: list[int] of (width,height,depth) dimensions

to_csv ¶

to_csv() -> str

Converts the bounding box coordinates to a comma-separated string.

Creates a string containing the bounding box coordinates and dimensions in comma-separated format.

Returns:

str ( str ) –

A comma-separated string containing: - First three values: (x,y,z) coordinates of topleft - Last three values: (width,height,depth) dimensions

to_slices ¶

to_slices() -> tuple[slice, ...]

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

to_slices_xyz ¶

to_slices_xyz() -> tuple[slice, ...]

Returns a tuple of slices that corresponds to the bounding box in x, y, z and leaves all other axes one dimensional without offset.

to_tuple6 ¶

to_tuple6() -> tuple[int, int, int, int, int, int]

Converts the bounding box coordinates to a 6-tuple.

Creates a tuple containing the bounding box coordinates and dimensions.

Returns:

tuple[int, int, int, int, int, int] –

tuple[int, int, int, int, int, int]: A tuple containing: - First three values: (x,y,z) coordinates of topleft - Last three values: (width,height,depth) dimensions

to_wkw_dict ¶

to_wkw_dict() -> dict

Converts the bounding box to a wkw-format dictionary.

Creates a dictionary with wkw-format fields containing the bounding box dimensions.

Returns:

dict ( dict ) –

A dictionary with keys: - topLeft: list[int] of (x,y,z) coordinates - width: int width in x dimension - height: int height in y dimension - depth: int depth in z dimension

volume ¶

volume() -> int

Returns the volume of the bounding box.

with_bottomright ¶

with_bottomright(new_bottomright: VecIntLike) -> _T

Returns a new NDBoundingBox with an updated bottomright value.

Parameters:

new_bottomright (VecIntLike) –

The new bottom right corner coordinates.

Returns:

NDBoundingBox ( _T ) –

A new NDBoundingBox object with the updated bottom right corner.

with_bottomright_xyz ¶

with_bottomright_xyz(new_xyz: Vec3IntLike) -> _T

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

Parameters:

new_xyz (Vec3IntLike) –

The new x, y and z coordinates for the bottomright corner.

Returns:

NDBoundingBox ( _T ) –

A new NDBoundingBox object with the updated x, y and z coordinates of the bottomright corner.

with_bounds ¶

with_bounds(axis: str, new_topleft: int | None = None, new_size: int | None = None) -> _T

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

Parameters:

axis (str) –

The name of the axis to update.
new_topleft (int | None, default: None ) –

The new value for the top-left coordinate along the specified axis.
new_size (int | None, default: None ) –

The new size along the specified axis.

Returns:

NDBoundingBox ( _T ) –

A new NDBoundingBox object with updated bounds.

Raises:

ValueError –

If the given axis name does not exist.

with_bounds_x ¶

with_bounds_x(new_topleft_x: int | None = None, new_size_x: int | None = None) -> BoundingBox

Returns a copy of the bounding box with topleft.x optionally replaced and size.x optionally replaced.

with_bounds_y ¶

with_bounds_y(new_topleft_y: int | None = None, new_size_y: int | None = None) -> BoundingBox

Returns a copy of the bounding box with topleft.y optionally replaced and size.y optionally replaced.

with_bounds_z ¶

with_bounds_z(new_topleft_z: int | None = None, new_size_z: int | None = None) -> BoundingBox

Returns a copy of the bounding box with topleft.z optionally replaced and size.z optionally replaced.

with_color ¶

with_color(color: tuple[float, float, float, float]) -> _T

Returns a new instance of NDBoundingBox with the specified color.

Parameters:

color (tuple[float, float, float, float] | None) –

The color to set for the bounding box. The color should be specified as a tuple of four floats representing RGBA values.

Returns:

NDBoundingBox ( _T ) –

A new instance of NDBoundingBox with the specified color.

with_index ¶

with_index(new_index: VecIntLike) -> _T

Returns a new NDBoundingBox object with the specified index.

Parameters:

new_index (VecIntLike) –

The new axis order for the bounding box.

Returns:

NDBoundingBox ( _T ) –

A new NDBoundingBox object with the updated index.

with_index_xyz ¶

with_index_xyz(new_xyz: Vec3IntLike) -> _T

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

Parameters:

new_xyz (Vec3IntLike) –

The new x, y and z index for the bounding box.

Returns:

NDBoundingBox ( _T ) –

A new NDBoundingBox object with the updated x, y and z index.

with_is_visible ¶

with_is_visible(is_visible: bool) -> _T

Returns a new NDBoundingBox object with the specified visibility.

Parameters:

is_visible (bool) –

The visibility value to set.

Returns:

NDBoundingBox ( _T ) –

A new NDBoundingBox object with the updated visibility value.

with_name ¶

with_name(name: str | None) -> _T

Returns a new instance of NDBoundingBox with the specified name.

Parameters:

name (str | None) –

The name to assign to the new NDBoundingBox instance.

Returns:

NDBoundingBox ( _T ) –

A new instance of NDBoundingBox with the specified name.

with_size ¶

with_size(new_size: VecIntLike) -> _T

Returns a new NDBoundingBox object with the specified size.

Parameters:

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:

_T –

A new NDBoundingBox object with the specified size.

with_size_xyz ¶

with_size_xyz(new_xyz: Vec3IntLike) -> _T

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

Parameters:

new_xyz (Vec3IntLike) –

The new x, y and z size for the bounding box.

Returns:

NDBoundingBox ( _T ) –

A new NDBoundingBox object with the updated x, y and z size.

with_topleft ¶

with_topleft(new_topleft: VecIntLike) -> _T

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

Parameters:

new_topleft (VecIntLike) –

The new top left coordinates for the bounding box.

Returns:

NDBoundingBox ( _T ) –

A new NDBoundingBox object with the updated top left coordinates.

with_topleft_xyz ¶

with_topleft_xyz(new_xyz: Vec3IntLike) -> _T

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

Parameters:

new_xyz (Vec3IntLike) –

The new x, y and z coordinates for the topleft corner.

Returns:

NDBoundingBox ( _T ) –

A new NDBoundingBox object with the updated x, y and z coordinates of the topleft corner.

xyz_array_to_bbox_shape ¶

xyz_array_to_bbox_shape(data: ndarray) -> ndarray

Transforms data array with xyz axes to the shape of the bounding box. This is only possible for bboxes that are flat in all dimensions except xyz.

webknossos.geometry.bounding_box ¶

BoundingBox ¶

axes class-attribute instance-attribute ¶

bottomright class-attribute instance-attribute ¶

bottomright_xyz property ¶

color class-attribute instance-attribute ¶

index class-attribute instance-attribute ¶

index_xyz property ¶

is_visible class-attribute instance-attribute ¶

name class-attribute instance-attribute ¶

ndim property ¶

size class-attribute instance-attribute ¶

size_xyz property ¶

topleft class-attribute instance-attribute ¶

topleft_xyz property ¶

align_with_mag ¶

chunk ¶

contains ¶

contains_bbox ¶

empty classmethod ¶

extended_by ¶

from_auto classmethod ¶

from_checkpoint_name classmethod ¶

from_config_dict classmethod ¶

from_csv classmethod ¶

from_mag_to_mag1 ¶

from_ndbbox classmethod ¶

from_points classmethod ¶

from_tuple2 classmethod ¶

from_tuple6 classmethod ¶

from_wkw_dict classmethod ¶

get_bounds ¶

get_shape ¶

group_boxes_with_aligned_mag classmethod ¶

in_mag ¶

intersected_with ¶

is_empty ¶

offset ¶

padded_with_margins ¶

slice_array ¶

to_checkpoint_name ¶

to_config_dict ¶

to_csv ¶

to_slices ¶

to_slices_xyz ¶

to_tuple6 ¶

to_wkw_dict ¶

volume ¶

with_bottomright ¶

with_bottomright_xyz ¶

with_bounds ¶

with_bounds_x ¶

with_bounds_y ¶

with_bounds_z ¶

with_color ¶

with_index ¶

with_index_xyz ¶

with_is_visible ¶

with_name ¶

with_size ¶

with_size_xyz ¶

with_topleft ¶

with_topleft_xyz ¶

xyz_array_to_bbox_shape ¶

axes `class-attribute` `instance-attribute` ¶

bottomright `class-attribute` `instance-attribute` ¶

bottomright_xyz `property` ¶

color `class-attribute` `instance-attribute` ¶

index `class-attribute` `instance-attribute` ¶

index_xyz `property` ¶

is_visible `class-attribute` `instance-attribute` ¶

name `class-attribute` `instance-attribute` ¶

ndim `property` ¶

size `class-attribute` `instance-attribute` ¶

size_xyz `property` ¶

topleft `class-attribute` `instance-attribute` ¶

topleft_xyz `property` ¶

empty `classmethod` ¶

from_auto `classmethod` ¶

from_checkpoint_name `classmethod` ¶

from_config_dict `classmethod` ¶

from_csv `classmethod` ¶

from_ndbbox `classmethod` ¶

from_points `classmethod` ¶

from_tuple2 `classmethod` ¶

from_tuple6 `classmethod` ¶

from_wkw_dict `classmethod` ¶

group_boxes_with_aligned_mag `classmethod` ¶