neu_vol.detect¶

Which format a location holds, and whether a precomputed scale actually stores data.

Detection reads marker objects (info, zarr.json, .zarray) and URL schemes, never volume data. The exceptions are O(1) chunk-existence probes: CloudVolume writes .gz-suffixed chunk keys, which read as zeros unless detected, and an info may declare scales that were never written.

Attributes¶

`FORMAT_MARKERS`
`PRECOMPUTED_GZ`
`SINGLE_LEVEL_FORMATS`
`logger`

Functions¶

`detect_backend`(location) → str \| None	Detect a source's format from its marker file (no data read).
`detect_file_backend`(location) → str \| None	`hdf5` or `image_stack` for a local file, glob or directory of slices.
`finest_populated_scale`(location, scales) → int \| None	Index into `scales` of the finest one that actually holds data, or `None`.
`other_format_markers`(location, fmt) → list[str]	Markers of volume formats other than `fmt` already present at `location`.
`precomputed_chunks_are_gzipped`(location, scales) → bool	True if these precomputed scales' chunk objects are `.gz`-suffixed.
`require_chunked_volume`(fmt, location, op) → str	`fmt` if it is a chunked multiscale volume; a useful error if it is not.
`require_populated_scale`(spec, *[, op]) → None	Raise if `spec` names a precomputed scale this volume never wrote.
`scale_holds_data`(location, scale) → bool	Whether a precomputed scale stores any chunk: conclusive, like `scale_is_empty()`.
`scale_is_empty`(location, scale) → bool	True if this precomputed scale's prefix holds no chunk object at all.
`scale_stores_chunks`(location, scale) → bool	True if this precomputed scale's origin chunk object is stored, under either suffix.

Module Contents¶

neu_vol.detect.detect_backend(location: str | Mapping[str, Any]) → str | None¶

Detect a source’s format from its marker file (no data read).

info -> neuroglancer-precomputed; zarr.json -> zarr v3; .zarray/.zgroup -> zarr v2; a dvid:// URL -> dvid; wk:// -> webknossos; a mapped-view descriptor -> mapped. Returns None if none match.

Precomputed whose chunks are .gz-suffixed reports PRECOMPUTED_GZ instead, so callers fail loudly rather than reading zeros.

A marker always wins: hdf5 and image_stack have no marker and are recognised by detect_file_backend() only after every marker probe has missed.

neu_vol.detect.detect_file_backend(location: str | Mapping[str, Any]) → str | None¶

hdf5 or image_stack for a local file, glob or directory of slices.

Neither has a marker object, so detection uses the name plus one stat, and runs only after every marker probe has missed:

a glob is an image stack;
a file is judged by extension; an unknown one returns None;
a directory must actually contain a slice, so a typo is not mistaken for an empty stack.

Local paths only: neither reader has an object-store driver.

neu_vol.detect.finest_populated_scale(location: str | Mapping[str, Any], scales: Sequence[Mapping[str, Any]]) → int | None¶

Index into scales of the finest one that actually holds data, or None.

An info may declare scales that were never written; such a scale opens, reports its declared extent, and reads as the fill value everywhere. Three tiers, cheapest first:

Probe origin chunks finest-first. An ordinary volume answers on the first check.
If a coarser scale has an origin chunk and finer ones do not, the finer ones are either unwritten or sparse at the origin; scale_holds_data() decides.
If no scale has an origin chunk, apply scale_holds_data() to every scale, finest-first: a volume can be sparse at the origin of all its scales.

neu_vol.detect.other_format_markers(location: str | Mapping[str, Any], fmt: str) → list[str]¶

Markers of volume formats other than fmt already present at location.

Creating a volume writes only its own marker, so a precomputed volume made where a zarr one lives leaves info and zarr.json side by side, and detection then never reaches the zarr.

neu_vol.detect.precomputed_chunks_are_gzipped(location: str | Mapping[str, Any], scales: Mapping[str, Any] | Sequence[Mapping[str, Any]]) → bool¶

True if these precomputed scales’ chunk objects are .gz-suffixed.

CloudVolume gzips chunks and appends .gz to the key; tensorstore asks for the unsuffixed key and reads the fill value, so every block comes back as zeros.

scales is one entry of info["scales"] or several in preference order. Each scale’s origin chunk is probed by name first (two existence checks), and only if no scale answers is a prefix listed, scale by scale in the order given. A listing is never bounded by its limit — it enumerates the whole prefix — so detect_backend() passes the scales coarsest-first, keeping any listing on the smallest prefix.

neu_vol.detect.require_chunked_volume(fmt: str, location: str, op: str) → str¶

fmt if it is a chunked multiscale volume; a useful error if it is not.

Called by the ops that rewrite a volume in place. Without it an HDF5 file or image stack fails deep inside an occupancy listing that finds no chunk keys, which reads as “no data” rather than “not that kind of volume”.

neu_vol.detect.require_populated_scale(spec: Mapping[str, Any], *, op: str = 'convert') → None¶

Raise if spec names a precomputed scale this volume never wrote.

Reading an unwritten scale fails silently: every block is the fill value and the output is a correct-looking volume of zeros. This raises only on conclusive evidence — the scale’s prefix holds no chunk while another scale’s does — because a sparse volume may legitimately store nothing at the origin.

neu_vol.detect.scale_holds_data(location: str | Mapping[str, Any], scale: Mapping[str, Any]) → bool¶

Whether a precomputed scale stores any chunk: conclusive, like scale_is_empty().

Probes the origin chunk, then up to eight more predictable chunk keys (either suffix), and lists the prefix only if all of them miss, since a listing enumerates every object of a dense scale.

neu_vol.detect.scale_is_empty(location: str | Mapping[str, Any], scale: Mapping[str, Any]) → bool¶

True if this precomputed scale’s prefix holds no chunk object at all.

The conclusive form of scale_stores_chunks(), at the cost of a listing. Cheap when the scale was never written (its prefix is empty); expensive on a sparse volume whose origin is background, where the whole prefix is enumerated.

neu_vol.detect.scale_stores_chunks(location: str | Mapping[str, Any], scale: Mapping[str, Any]) → bool¶

True if this precomputed scale’s origin chunk object is stored, under either suffix.

A True is evidence of a written scale; a False is not proof of an empty one, since a sparse volume may store nothing at its origin.

neu_vol.detect.FORMAT_MARKERS¶

neu_vol.detect.PRECOMPUTED_GZ = 'neuroglancer_precomputed_gz'¶

neu_vol.detect.SINGLE_LEVEL_FORMATS¶

neu_vol.detect.logger¶