Skip to content

webknossos.geometry.nd_bounding_box

Classes:

  • NDBoundingBox

    A generalized N-dimensional bounding box that can handle arbitrary dimensions.

NDBoundingBox

A generalized N-dimensional bounding box that can handle arbitrary dimensions.

The NDBoundingBox represents an N-dimensional rectangular region defined by its top-left corner coordinates and size. Each dimension has an associated axis name and index for ordering.

Parameters:

  • topleft

    The coordinates of the upper-left corner (inclusive)

  • size

    The size/extent in each dimension

  • axes

    The names of the axes/dimensions (e.g. "x", "y", "z", "t")

  • index

    The order/position of each axis, starting from 1 (0 is reserved for channels)

  • name

    Optional name for this bounding box

  • is_visible

    Whether this bounding box should be visible

  • color

    Optional RGBA color tuple (4 floats) for display

Examples:

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)
)
Note
  • The top-left coordinate is inclusive while bottom-right is exclusive
  • Each axis must have a unique index starting from 1
  • Index 0 is reserved for channel information

Methods:

  • align_with_mag

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

  • chunk

    Decompose the bounding box into smaller chunks of size chunk_shape.

  • contains

    Check whether a point is inside of the bounding box.

  • contains_bbox

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

  • extended_by

    Returns the smallest bounding box that contains both bounding boxes.

  • from_mag_to_mag1

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

  • from_wkw_dict

    Create an instance of NDBoundingBox from a dictionary representation.

  • get_bounds

    Returns the bounds of the given axis.

  • get_shape

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

  • group_boxes_with_aligned_mag

    Groups the given BoundingBox instances by aligning each

  • in_mag

    Returns the bounding box in the given mag.

  • intersected_with

    Returns the intersection of two bounding boxes.

  • is_empty

    Boolean check whether the boundung box is empty.

  • offset

    Returns a new NDBoundingBox object with the specified offset.

  • padded_with_margins
  • slice_array

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

  • to_checkpoint_name

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

  • to_config_dict

    Returns a dictionary representation of the bounding box.

  • to_slices

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

  • to_slices_xyz

    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_wkw_dict

    Converts the bounding box object to a json dictionary.

  • volume

    Returns the volume of the bounding box.

  • with_bottomright

    Returns a new NDBoundingBox with an updated bottomright value.

  • with_bottomright_xyz

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

  • with_bounds

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

  • with_color

    Returns a new instance of NDBoundingBox with the specified color.

  • with_index

    Returns a new NDBoundingBox object with the specified index.

  • with_index_xyz

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

  • with_is_visible

    Returns a new NDBoundingBox object with the specified visibility.

  • with_name

    Returns a new instance of NDBoundingBox with the specified name.

  • with_size

    Returns a new NDBoundingBox object with the specified size.

  • with_size_xyz

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

  • with_topleft

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

  • with_topleft_xyz

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

  • xyz_array_to_bbox_shape

    Transforms data array with xyz axes to the shape of the bounding box.

Attributes:

axes class-attribute instance-attribute

axes: Tuple[str, ...] = field(converter=str_tpl)

bottomright class-attribute instance-attribute

bottomright: VecInt = 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: Optional[Tuple[float, float, float, float]] = None

index class-attribute instance-attribute

index: VecInt = field(converter=int_tpl)

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: Optional[str] = _DEFAULT_BBOX_NAME

size class-attribute instance-attribute

size: VecInt = field(converter=int_tpl)

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: VecInt = field(converter=int_tpl)

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: Union[Mag, Vec3Int], ceil: bool = False) -> _T

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

Parameters:

  • mag (Union[Mag, Vec3Int]) –

    The magnification to align the bounding box to.

  • ceil (bool, default: False ) –

    If True, the bounding box is enlarged when necessary. If False, it's shrunk when necessary.

Returns:

  • NDBoundingBox ( _T ) –

    The aligned bounding box.

chunk

chunk(chunk_shape: VecIntLike, chunk_border_alignments: Optional[VecIntLike] = None) -> Generator[_T, None, None]

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.

Parameters:

  • chunk_shape (VecIntLike) –

    The size of the chunks to generate.

  • chunk_border_alignments (Optional[VecIntLike], default: None ) –

    The alignment of the chunk borders.

Yields:

  • _T

    Generator[NDBoundingBox]: A generator of the chunks.

contains

contains(coord: VecIntLike) -> bool

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

Parameters:

  • coord (VecIntLike) –

    The coordinates to check.

Returns:

  • bool ( bool ) –

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

contains_bbox

contains_bbox(inner_bbox: _T) -> bool

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

Parameters:

Returns:

  • bool ( bool ) –

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

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_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_wkw_dict classmethod

from_wkw_dict(bbox: Dict) -> NDBoundingBox

Create an instance of NDBoundingBox from a dictionary representation.

Parameters:

  • bbox (Dict) –

    The dictionary representation of the bounding box.

Returns:

  • NDBoundingBox ( NDBoundingBox ) –

    An instance of NDBoundingBox.

Raises:

  • AssertionError

    If additionalAxes are present but axisOrder is not provided.

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) -> _T

Returns the bounding box in the given mag.

Parameters:

  • mag (Mag) –

    The magnification to convert the bounding box to.

Returns:

  • NDBoundingBox ( _T ) –

    The bounding box in the given magnification.

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

Boolean check whether the boundung box is empty.

Returns:

  • bool ( bool ) –

    True if the bounding box is empty, False otherwise.

offset

offset(vector: VecIntLike) -> _T

Returns a new NDBoundingBox object with the specified offset.

Parameters:

  • vector (VecIntLike) –

    The offset to apply to the bounding box.

Returns:

  • NDBoundingBox ( _T ) –

    A new NDBoundingBox object with the specified offset.

padded_with_margins

padded_with_margins(margins_left: Vec3IntLike, margins_right: Optional[Vec3IntLike] = 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

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

Returns:

  • str ( str ) –

    A string representation of the bounding box.

to_config_dict

to_config_dict() -> dict

Returns a dictionary representation of the bounding box.

Returns:

  • dict ( dict ) –

    A dictionary representation of the bounding box.

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_wkw_dict

to_wkw_dict() -> dict

Converts the bounding box object to a json dictionary.

Returns:

  • dict ( dict ) –

    A json dictionary representing the bounding box.

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: 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_color

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

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: Optional[str]) -> _T

Returns a new instance of NDBoundingBox with the specified name.

Parameters:

  • name (Optional[str]) –

    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.