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
(Tuple[str, ...]
) – -
bottomright
(VecInt
) – -
bottomright_xyz
(Vec3Int
) –The bottomright corner of the bounding box regarding only x, y and z axis.
-
color
(Optional[Tuple[float, float, float, float]]
) – -
index
(VecInt
) – -
index_xyz
(Vec3Int
) –The index of x, y and z axis within the bounding box.
-
is_visible
(bool
) – -
name
(Optional[str]
) – -
size
(VecInt
) – -
size_xyz
(Vec3Int
) –The size of the bounding box regarding only x, y and z axis.
-
topleft
(VecInt
) – -
topleft_xyz
(Vec3Int
) –The topleft corner of the bounding box regarding only x, y and z axis.
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
topleft_xyz
property
¶
topleft_xyz: Vec3Int
The topleft corner of the bounding box regarding only x, y and z axis.
align_with_mag
¶
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.
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.
- Get Help
- Community Forums
- Email Support