neu_vol.source_metadata¶

Read coordinate metadata and the level-0 data location from a source volume.

convert uses this so voxel_size / offset need not be re-specified when the source carries them (OME-NGFF zarr groups, precomputed info, DVID, webknossos, an HDF5 file that records its own frame). Explicit arguments override what is read here; sources that record nothing return None.

Returned dict keys: data_spec (the array/scale spec to read), voxel_size / offset (z, y, x), units, spatial_axes, has_channels, kind.

Two tiers, differing in cost: the readers read one small metadata document each; describe() and existing_levels() additionally open every level, which on an object store costs about ten times as much (15.8 s against 1.4 s on an 8-level zarr).

Attributes¶

logger

Functions¶

`describe`(volume, *[, dataset, level]) → neu_vol.report.Description	Detected format, coordinate metadata and the levels actually present.
`existing_levels`(volume, fmt[, probe, dataset]) → dict[int, dict]	`{level: {"shape", "chunks", "read_chunks"}}` for the levels that open.
`level0_chunking`(described, location)	`(read chunk, write chunk)` of a described source's level 0, either possibly `None`.
`level_spec`(volume, fmt, level, *[, dataset]) → dict[str, Any]	The backend spec for one level of a multiscale volume.
`location_spec`(location, fmt, *[, dataset]) → dict[str, Any]	The backend spec addressing `location`, in the form `fmt` expects.
`read_level_voxel_sizes`(spec) → list[tuple[float, ...]] \| None	Each level's own voxel size, from the volume's metadata. `None` if absent.
`read_source_metadata`(spec) → dict \| None	Coordinate metadata and the level-0 `data_spec` for `spec`; `None` if absent.
`require_one_array`(described, location, op) → dict	`described` if it resolved a single array; otherwise an error naming the datasets.

Module Contents¶

neu_vol.source_metadata.describe(volume: str, *, dataset: str | None = None, level: int | None = None) → neu_vol.report.Description¶

Detected format, coordinate metadata and the levels actually present.

Returns a Description: a dict that also renders as the table neu-vol info prints, with .frame() giving the per-level rows as a DataFrame. level describes that source scale instead of level 0.

An HDF5 file or image stack has one level and may record no metadata, so meta can be None. An HDF5 file may hold several arrays:

datasets is {name: {"shape", "dtype", "chunks", <recorded frame>}} for every HDF5 file, and None for other formats;
dataset is the array the rest of the dict describes, or None;
with several arrays and none named, shape / dtype / meta / level_voxel_sizes are None and levels is empty; callers needing one array use require_one_array().

Raises FileNotFoundError if nothing at volume looks like a volume.

neu_vol.source_metadata.existing_levels(volume: str, fmt: str, probe: int = 12, *, dataset: str | None = None) → dict[int, dict]¶

{level: {"shape", "chunks", "read_chunks"}} for the levels that open.

Probes upward until a level fails to open, so it works on a conversion still in progress, whose group metadata is written last. A single-container format has only level 0. Chunking is read per level, since levels may be chunked differently; chunks is the write chunk (the shard, when sharded) and read_chunks the unit actually fetched.

neu_vol.source_metadata.level0_chunking(described: Mapping[str, Any], location: str)¶

(read chunk, write chunk) of a described source’s level 0, either possibly None.

describe() reports chunking only for levels it finds; a bare array has none, so its chunking is read from the array itself. The two differ when the level is sharded: the write chunk is the shard.

neu_vol.source_metadata.level_spec(volume: str, fmt: str, level: int, *, dataset: str | None = None) → dict[str, Any]¶

The backend spec for one level of a multiscale volume.

zarr v3 puts each level in its own subdirectory; precomputed, DVID and webknossos select one with scale_index. A single-container format has only level 0, and any other raises, since its backend would ignore scale_index and open level 0 anyway.

neu_vol.source_metadata.location_spec(location: str, fmt: str, *, dataset: str | None = None) → dict[str, Any]¶

The backend spec addressing location, in the form fmt expects.

Most formats take path; an image stack takes source (a directory or glob), HDF5 takes path plus the dataset inside the container, and DVID and webknossos take the fields of their URLs. Everything that turns a user-supplied location into a spec goes through here.

dataset names the array inside an HDF5 file. When omitted it is resolved by sole_dataset(), which raises, listing the candidates, unless the file holds exactly one. Ignored for every other format.

neu_vol.source_metadata.read_level_voxel_sizes(spec: Mapping[str, Any]) → list[tuple[float, ...]] | None¶

Each level’s own voxel size, from the volume’s metadata. None if absent.

Read per level, never derived from shape ratios (shapes are ceil-divided, so the ratio is inexact) or from 2**level (pyramids may be anisotropic). Finest-first, (z, y, x), spatial axes only.

neu_vol.source_metadata.read_source_metadata(spec: Mapping[str, Any]) → dict | None¶

Coordinate metadata and the level-0 data_spec for spec; None if absent.

See the module docstring for the keys. An image stack records no physical scale, so it always returns None.

neu_vol.source_metadata.require_one_array(described: Mapping[str, Any], location: str, op: str) → dict¶

described if it resolved a single array; otherwise an error naming the datasets.

For callers that go on to read the array, which would otherwise fail on a None shape from a multi-array HDF5 container.

neu_vol.source_metadata.logger¶