Spatial utilities

Functions for spatial partitioning, bounding-box computation, fragment index arithmetic, and chunk coordinate manipulation. These are the internal building blocks used by the read/write functions; they are also useful for contributors implementing custom readers or geometry operations.

Chunking

Spatial chunk assignment and query utilities.

All functions are pure numpy — no store or encoding dependencies. Chunk assignment is vectorised: assign_chunks processes millions of vertices in one pass using np.floor and structured-array np.unique.

zarr_vectors.spatial.chunking.assign_bins(positions, bin_shape)

Assign each vertex to a supervoxel bin.

Identical to assign_chunks() but uses bin_shape instead of chunk_shape — produces a finer spatial grouping.

Parameters:

• positions (ndarray[tuple[Any, ...], dtype[floating]]) – (N, D) array of vertex positions.

• bin_shape (tuple[float, ...]) – Supervoxel edge lengths per dimension.

Returns:

Dict mapping bin_coords → (N_k,) array of vertex indices.

Return type:

dict[tuple[int, …], ndarray[tuple[Any, …], dtype[int64]]]

zarr_vectors.spatial.chunking.assign_chunks(positions, chunk_shape)

Assign each vertex to a spatial chunk.

Parameters:

• positions (ndarray[tuple[Any, ...], dtype[floating]]) – (N, D) array of vertex positions.

• chunk_shape (tuple[float, ...]) – Physical size per dimension. Length must equal D.

Returns:

Dict mapping chunk_coords → (N_k,) array of vertex indices belonging to that chunk. Indices are into the original positions array.

Raises:

ChunkingError – If dimensions are inconsistent.

Return type:

dict[tuple[int, …], ndarray[tuple[Any, …], dtype[int64]]]

zarr_vectors.spatial.chunking.bin_to_chunk(bin_coords, bins_per_chunk)

Map a bin coordinate to its parent chunk coordinate.

Parameters:

• bin_coords (tuple[int, ...]) – N-dimensional bin grid coordinate.

• bins_per_chunk (tuple[int, ...]) – Number of bins per chunk in each dimension.

Returns:

Chunk coordinate tuple.

Return type:

tuple[int, …]

zarr_vectors.spatial.chunking.bin_to_fragment_index(bin_coords, chunk_coords, bins_per_chunk)

Linearise an intra-chunk bin coordinate to a fragment index.

Uses row-major (C-order) linearisation within the chunk’s bin grid.

Parameters:

• bin_coords (tuple[int, ...]) – Global bin coordinate.

• chunk_coords (tuple[int, ...]) – Parent chunk coordinate.

• bins_per_chunk (tuple[int, ...]) – Bins per chunk per dimension.

Returns:

Integer fragment index within the chunk.

Return type:

int

zarr_vectors.spatial.chunking.bins_intersecting_bbox(bbox_min, bbox_max, bin_shape)

Return all bin coordinates that intersect a bounding box.

Finer-grained version of chunks_intersecting_bbox().

Parameters:

• bbox_min (ndarray[tuple[Any, ...], dtype[floating]]) – (D,) minimum corner.

• bbox_max (ndarray[tuple[Any, ...], dtype[floating]]) – (D,) maximum corner.

• bin_shape (tuple[float, ...]) – Supervoxel edge lengths.

Returns:

Sorted list of bin coordinate tuples.

Return type:

list[tuple[int, …]]

zarr_vectors.spatial.chunking.chunk_to_bin_range(chunk_coords, bins_per_chunk)

Return the range of bin coordinates within a chunk (inclusive).

Parameters:

• chunk_coords (tuple[int, ...]) – Chunk grid coordinate.

• bins_per_chunk (tuple[int, ...]) – Number of bins per chunk in each dimension.

Returns:

(min_bin_coords, max_bin_coords) — both inclusive.

Return type:

tuple[tuple[int, …], tuple[int, …]]

zarr_vectors.spatial.chunking.chunks_intersecting_bbox(bbox_min, bbox_max, chunk_shape)

Return all chunk coordinates that intersect a bounding box.

Parameters:

• bbox_min (ndarray[tuple[Any, ...], dtype[floating]]) – (D,) minimum corner of query box.

• bbox_max (ndarray[tuple[Any, ...], dtype[floating]]) – (D,) maximum corner of query box.

• chunk_shape (tuple[float, ...]) – Physical chunk size per dimension.

Returns:

Sorted list of chunk coordinate tuples.

Return type:

list[tuple[int, …]]

zarr_vectors.spatial.chunking.compute_bounds(positions)

Compute axis-aligned bounding box.

Parameters:

positions (ndarray[tuple[Any, ...], dtype[floating]]) – (N, D) array.

Returns:

(min_corner, max_corner) — each a (D,) float64 array.

Raises:

ChunkingError – If positions is empty.

Return type:

tuple[ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]]]

zarr_vectors.spatial.chunking.compute_chunk_coords(position, chunk_shape)

Compute chunk coordinates for a single position.

Parameters:

• position (ndarray[tuple[Any, ...], dtype[floating]]) – (D,) array.

• chunk_shape (tuple[float, ...]) – Physical size per dimension.

Returns:

Chunk coordinate tuple, e.g. (0, 1, 2).

Return type:

tuple[int, …]

zarr_vectors.spatial.chunking.compute_grid_shape(bounds, chunk_shape)

Compute number of chunks per dimension.

Parameters:

• bounds (tuple[ndarray[tuple[Any, ...], dtype[floating]], ndarray[tuple[Any, ...], dtype[floating]]]) – (min_corner, max_corner).

• chunk_shape (tuple[float, ...]) – Physical chunk size per dimension.

Returns:

Tuple of chunk counts per dimension. Each value is at least 1.

Return type:

tuple[int, …]

zarr_vectors.spatial.chunking.fragment_index_to_bin(fragment_index, chunk_coords, bins_per_chunk)

Convert a fragment index back to a global bin coordinate.

Inverse of bin_to_fragment_index().

Parameters:

• fragment_index (int) – Linearised fragment index within the chunk.

• chunk_coords (tuple[int, ...]) – Parent chunk coordinate.

• bins_per_chunk (tuple[int, ...]) – Bins per chunk per dimension.

Returns:

Global bin coordinate tuple.

Return type:

tuple[int, …]

zarr_vectors.spatial.chunking.group_bins_by_chunk(bin_assignments, bins_per_chunk)

Group bin assignments into chunks with linearised fragment indices.

Takes the output of assign_bins() and organises it by chunk. Each entry maps a fragment index (linearised bin position within the chunk) to the array of global vertex indices in that bin.

Parameters:

• bin_assignments (dict[tuple[int, ...], ndarray[tuple[Any, ...], dtype[int64]]]) – Output from assign_bins.

• bins_per_chunk (tuple[int, ...]) – Bins per chunk per dimension.

Returns:

{chunk_coords: {fragment_index: global_vertex_indices}}.

Return type:

dict[tuple[int, …], dict[int, ndarray[tuple[Any, …], dtype[int64]]]]

zarr_vectors.spatial.chunking.neighbouring_chunk_keys(key, *, halo=1, occupied_keys=None, include_self=False)

Return chunk keys within halo of key along every axis.

Pure integer-tuple work — no store I/O — so it composes with any chunk-key arity (3D, 4D when attribute-chunked, etc.).

Parameters:

• key (tuple[int, ...]) – The reference chunk coord.

• halo (int) – Maximum per-axis distance. halo=1 returns the (3^ndim - 1) chunks adjacent on at least one face, edge, or corner; halo=2 widens to a 5^ndim cube.

• occupied_keys (Iterable[tuple[int, ...]] | None) – If given, restrict the output to keys that actually exist in the store. Pass set(level.chunk_keys) to filter to occupied chunks.

• include_self (bool) – If True, include key itself in the output.

Returns:

Sorted list of unique ChunkCoords tuples.

Return type:

list[tuple[int, …]]

zarr_vectors.spatial.chunking.positions_in_bbox(positions, bbox_min, bbox_max)

Return indices of positions within a bounding box (inclusive).

Parameters:

• positions (ndarray[tuple[Any, ...], dtype[floating]]) – (N, D) array.

• bbox_min (ndarray[tuple[Any, ...], dtype[floating]]) – (D,) minimum corner.

• bbox_max (ndarray[tuple[Any, ...], dtype[floating]]) – (D,) maximum corner.

Returns:

(M,) array of indices where all coordinates are within [bbox_min, bbox_max].

Return type:

ndarray[tuple[Any, …], dtype[int64]]

Bounding box

fragment index