neu_morpho.occupancy

Coarse-scale occupancy prefilter — skip empty blocks up front.

A small coarse-scale level is reduced to a boolean over the meshing block grid, so empty blocks are never read. With an allowlist, “occupied” means isin(coarse, allowlist).

Functions

occupied_blocks(occ_array_zyx, *, occ_voxel_size, ...) → set[tuple[int, int, int]]

Return the set of block indices (in the meshing grid) that are non-empty.

Module Contents

neu_morpho.occupancy.occupied_blocks(occ_array_zyx: numpy.ndarray, *, occ_voxel_size: Sequence[float], mesh_voxel_size: Sequence[float], block_shape: Sequence[int], grid_shape: Sequence[int], allowlist: set[int] | None = None, dilate: int = 0) → set[tuple[int, int, int]]

Return the set of block indices (in the meshing grid) that are non-empty.

occ_array_zyx is the whole coarse-scale segmentation (small). Physical voxel sizes map the coarse grid onto the meshing block grid; grid_shape is the number of blocks per axis at the meshing scale.

dilate grows the occupied set by N blocks in every direction. Use it: a coarse scale drops sparse tissue, and the miss does not shrink with finer scales, so an un-dilated filter silently skips blocks holding data. An extra block costs one read; a missed one costs a body. On a sparse volume of small objects, turn occupancy off altogether.

allowlist is discouraged here: small allowlisted bodies vanish at coarse scales. Prefer the default != 0 test and filter by allowlist inside the block.