webknossos.geometry.nd_bounding_box ¶

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

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

ndim `property` ¶

ndim: int

The number of dimensions of the bounding box.

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:

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 ¶

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.

webknossos.geometry.nd_bounding_box ¶

NDBoundingBox ¶

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 ¶

extended_by ¶

from_mag_to_mag1 ¶

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_slices ¶

to_slices_xyz ¶

to_wkw_dict ¶

volume ¶

with_bottomright ¶

with_bottomright_xyz ¶

with_bounds ¶

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` ¶

from_wkw_dict `classmethod` ¶

group_boxes_with_aligned_mag `classmethod` ¶