neu_lib.grid¶

Aligning a box to a block grid, per axis, and the BBox type.

Which grid matters depends on the caller: a store’s chunks or shards (a partial write is a read-modify-write, and two concurrent partial writes into one chunk lose one of them), a pyramid’s cumulative downsampling factor, or the per-axis LCM of two chunkings. This module only does the integer arithmetic, independently per axis, because real grids are anisotropic: (1, 2, 2) pyramids and (128, 2048, 2048) chunks are both common.

Boxes are half-open, [lo, hi): a hi already on a block boundary stays there.

Attributes¶

MODES

Classes¶

BBox

A half-open box [lo, hi) with integer bounds, of any rank.

Functions¶

`align_box`(lo, hi, block[, mode]) → tuple[tuple[int, ...], tuple[int, ...]]	Align the half-open box `[lo, hi)` to the `block` grid, per axis.
`clamp_box`(lo, hi, extent) → tuple[tuple[int, ...], tuple[int, ...]]	Trim the box to `[0, extent)` per axis. An edge clamped to the end of the volume
`lcm_grid`(*grids) → tuple[int, ...]	Per-axis least common multiple of several block shapes: a box on this grid is on
`misaligned_axes`(lo, hi, block[, extent]) → list[int]	Axes where an edge of `[lo, hi)` falls inside a block.

Module Contents¶

class neu_lib.grid.BBox¶

A half-open box [lo, hi) with integer bounds, of any rank.

Frozen and hashable; every operation returns a new box. Axis order is the caller’s (the suite uses zyx).

aligned(block: Sequence[int], mode: str = 'outer') → BBox¶: align_box(), as a method.

clamped(extent: Sequence[int]) → BBox¶: clamp_box(), as a method. Raises if nothing is left, which usually means the box is in the wrong frame; use intersect() when no overlap is a valid answer.

contains(points: Any) → Any¶

Whether each point falls in [lo, hi).

A single point gives a bool; an (N, D) array gives a (N,) bool array.

classmethod empty(ndim: int = 3) → BBox¶: A box with zero extent on every axis — the identity for union().

classmethod from_points(points: Any) → BBox¶: The smallest box containing every point of an (N, D) array. hi is max + 1, so the box contains the extreme points. Raises on an empty set; use empty() for an empty box.

intersect(other: BBox) → BBox¶: The overlap, or an empty box at the origin when there is none.

is_empty() → bool¶

misaligned_axes(block: Sequence[int], extent: Sequence[int] | None = None) → list[int]¶: misaligned_axes(), as a method.

slices() → tuple[slice, ...]¶

translate(offset: Sequence[float]) → BBox¶: Move the box. A fractional offset is floored, like the grid arithmetic in this module, rather than truncated toward zero: a shift of -0.5 moves the box by -1, not by nothing.

union(other: BBox) → BBox¶: The smallest box containing both. An empty operand is ignored, so reduce(BBox.union, boxes, BBox.empty()) works.

property center: Any¶: The midpoint, as a float array. Not rounded: a box of odd extent has no integer centre.

hi: tuple[int, ...]¶

property hi_array: Any¶: hi as an int64 array.

lo: tuple[int, ...]¶

property lo_array: Any¶: lo as an int64 array.

property ndim: int¶

property shape: tuple[int, ...]¶

property size: int¶: Voxel count. Zero exactly when the box is empty.

neu_lib.grid.align_box(lo: Sequence[int], hi: Sequence[int], block: Sequence[int], mode: str = 'outer') → tuple[tuple[int, ...], tuple[int, ...]]¶

Align the half-open box [lo, hi) to the block grid, per axis.

outer floors lo and ceils hi, so no requested voxel is lost. It never fails.
inner ceils lo and floors hi, so the result lies inside the request.
nearest rounds both ends.
origin rounds lo and keeps the extent, for a fixed-size crop; hi is then generally off the grid.

Raises ValueError if an axis would be left empty (inner on a box spanning no whole block, nearest on one whose ends round together).

neu_lib.grid.clamp_box(lo: Sequence[int], hi: Sequence[int], extent: Sequence[int]) → tuple[tuple[int, ...], tuple[int, ...]]¶: Trim the box to [0, extent) per axis. An edge clamped to the end of the volume may fall off the grid, which is fine (see misaligned_axes()).

neu_lib.grid.lcm_grid(*grids: Sequence[int]) → tuple[int, ...]¶: Per-axis least common multiple of several block shapes: a box on this grid is on all of them, e.g. lcm_grid((128, 128, 128), (1, 2, 2)) == (128, 128, 128).

neu_lib.grid.misaligned_axes(lo: Sequence[int], hi: Sequence[int], block: Sequence[int], extent: Sequence[int] | None = None) → list[int]¶

Axes where an edge of [lo, hi) falls inside a block.

With extent given, an edge at the end of the volume counts as aligned: the final block is partial anyway, so there is no neighbouring data to read-modify-write.

neu_lib.grid.MODES = ('outer', 'inner', 'nearest', 'origin')¶