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 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(Optional[str]) –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(Optional[Tuple[float, float, float, float]]) –Optional RGBA color values
class-attribute
instance-attribute
¶
axes: Tuple[str, str, str] = field(default=('x', 'y', 'z'))
property
¶
bottomright_xyz: Vec3Int
The bottomright corner of the bounding box regarding only x, y and z axis.
class-attribute
instance-attribute
¶
color: Optional[Tuple[float, float, float, float]] = None
property
¶
topleft_xyz: Vec3Int
The topleft corner of the bounding box regarding only x, y and z axis.
align_with_mag(mag: Union[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_shape: Vec3IntLike, chunk_border_alignments: Optional[Vec3IntLike] = 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(Optional[Vec3IntLike], 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(coord: Union[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(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.
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.
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.
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_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.
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.
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
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
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(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(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.
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(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(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() -> 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(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(margins_left: Vec3IntLike, margins_right: Optional[Vec3IntLike] = None) -> _T
slice_array(array: ndarray) -> ndarray
Returns a slice of the given array that corresponds to the bounding box.
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() -> 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() -> 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() -> Tuple[slice, ...]
Returns a tuple of slices that corresponds to the bounding box.
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() -> 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() -> 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
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(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(axis: str, new_topleft: Optional[int], new_size: Optional[int]) -> _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(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(_T) –A new NDBoundingBox object with updated bounds.
Raises:
-
ValueError–If the given axis name does not exist.
with_bounds_x(new_topleft_x: Optional[int] = None, new_size_x: Optional[int] = None) -> BoundingBox
Returns a copy of the bounding box with topleft.x optionally replaced and size.x optionally replaced.
with_bounds_y(new_topleft_y: Optional[int] = None, new_size_y: Optional[int] = None) -> BoundingBox
Returns a copy of the bounding box with topleft.y optionally replaced and size.y optionally replaced.
with_bounds_z(new_topleft_z: Optional[int] = None, new_size_z: Optional[int] = None) -> BoundingBox
Returns a copy of the bounding box with topleft.z optionally replaced and size.z optionally replaced.
with_color(color: Optional[Tuple[float, float, float, float]]) -> _T
Returns a new instance of NDBoundingBox with the specified color.
Parameters:
-
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(_T) –A new instance of NDBoundingBox with the specified color.
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(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(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(name: Optional[str]) -> _T
Returns a new instance of NDBoundingBox with the specified name.
Parameters:
-
name(Optional[str]) –The name to assign to the new
NDBoundingBoxinstance.
Returns:
-
NDBoundingBox(_T) –A new instance of
NDBoundingBoxwith the specified name.
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(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(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(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(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.
- Get Help
- Community Forums
- Email Support