neu_vol.dvid¶

Addressing a DVID instance, and resolving which version of it you get.

Instance-type agnostic: it addresses an instance, resolves a ref to a node and records that node, for a labelmap, annotation or keyvalue alike, so neu-mark can use it without an array. The labelmap geometry and array view are in backends/dvid.py. Also here: fetching DVID ROIs as one positioned label array (roi_volume()).

A uuid may be a branch ref, which names a node that moves: resolve it once, in the driver (resolve_node()).

Attributes¶

`MISSING`
`ROI_BLOCK_VOXELS`
`ROI_INSTANCE`

Classes¶

RoiVolume

A combined ROI label array, positioned in nm.

Functions¶

`address`(spec) → tuple[str, str, str]	`(server, uuid, instance)` — the argument triple every neuclease call takes.
`available_rois`(spec) → list[str]	Every `roi` instance on this node.
`check_instance_type`(info, spec, *expected) → str	Require the instance to be one of `expected`, else raise. Returns its type.
`clear_node_cache`() → None	Drop memoized ref resolutions (tests, and any long-lived process).
`fetch_roi_ranges`(spec, rois, *[, processes]) → tuple[list[str], dict, dict]	`(names, ranges, boxes)`: the fetch half of building an ROI volume, one request
`instance_info`(spec) → dict	DVID's `/info` for this instance: one request, no backend opened.
`instance_type`(info) → str \| None	The instance's DVID type name — `labelmap`, `annotation`, `keyvalue`, …
`is_url`(location) → bool	True if this location names a DVID instance rather than a store.
`node_provenance`(spec, node) → dict	What a pull came from, for the record written beside the output.
`node_summary`(spec) → dict	Both candidate nodes for a ref: what it points at now, and the newest locked one.
`parse_url`(url) → dict[str, str]	`dvid://<server>/<uuid>/<instance>` -> the spec fields.
`resolve_node`(spec, *[, prefer_locked]) → dict	Resolve this spec's `uuid` ref to a concrete node, and say if it is locked.
`resolve_roi_set`(spec, rois) → list[str]	Validate an ROI name list against the node before fetching any of them.
`roi_frame`(box_lo_blocks, voxel_size_nm[, origin_nm]) → neu_lib.Frame	The `Frame` of an ROI array whose voxel `(0, 0, 0)` is block `box_lo`.
`roi_volume`(spec, rois, *, voxel_size_nm[, origin_nm, ...]) → RoiVolume	Fetch the named ROIs as one label array with its `Frame`.
`spec_url`(spec) → str	The `dvid://` URL for a spec — for messages and provenance.
`synced_instances`(info) → list[str]	Instances this one is synced to, from `Base.Syncs`.

Module Contents¶

class neu_vol.dvid.RoiVolume¶

A combined ROI label array, positioned in nm.

labels[z, y, x] == i means block (z, y, x) belongs to names[i - 1]; 0 is in none. Where ROIs intersect the one named later holds the voxel, and overlaps records each intersecting pair with its size in blocks.

mask(*names: str) → numpy.ndarray¶: Boolean array of the named ROIs (all of them when none are named).

frame: neu_lib.Frame¶

labels: numpy.ndarray¶

names: tuple[str, ...]¶

overlaps: tuple[tuple[str, str, int], ...] = ()¶

neu_vol.dvid.address(spec: Mapping[str, Any]) → tuple[str, str, str]¶: (server, uuid, instance) — the argument triple every neuclease call takes.

neu_vol.dvid.available_rois(spec: Mapping[str, Any]) → list[str]¶: Every roi instance on this node.

neu_vol.dvid.check_instance_type(info: Mapping[str, Any], spec: Mapping[str, Any], *expected: str) → str¶: Require the instance to be one of expected, else raise. Returns its type.

neu_vol.dvid.clear_node_cache() → None¶: Drop memoized ref resolutions (tests, and any long-lived process).

neu_vol.dvid.fetch_roi_ranges(spec: Mapping[str, Any], rois: Sequence[str], *, processes: int = 0) → tuple[list[str], dict, dict]¶: (names, ranges, boxes): the fetch half of building an ROI volume, one request per ROI, separate so the ranges can be unpacked more than once. boxes omits any ROI that holds no blocks.

neu_vol.dvid.instance_info(spec: Mapping[str, Any]) → dict¶: DVID’s /info for this instance: one request, no backend opened.

neu_vol.dvid.instance_type(info: Mapping[str, Any]) → str | None¶: The instance’s DVID type name — labelmap, annotation, keyvalue, …

neu_vol.dvid.is_url(location: Any) → bool¶: True if this location names a DVID instance rather than a store.

neu_vol.dvid.node_provenance(spec: Mapping[str, Any], node: Mapping[str, Any]) → dict¶

What a pull came from, for the record written beside the output.

The resolved uuid identifies the snapshot; requested keeps the ref as typed. The node’s DAG metadata is recorded too (DVID has no per-instance mutation id). Callers add fields describing their own read.

neu_vol.dvid.node_summary(spec: Mapping[str, Any]) → dict¶

Both candidate nodes for a ref: what it points at now, and the newest locked one.

Returns {"head": node, "locked": node | None, "locked_error": str | None}; locked is head when the ref already points at a locked node, and None when no locked node is reachable.

neu_vol.dvid.parse_url(url: str) → dict[str, str]¶

dvid://<server>/<uuid>/<instance> -> the spec fields.

Exactly three segments, split on / only:

server may carry a port (emdata3:8900); a bare host gets http:// from neuclease. Use the dvid+https:// scheme for a TLS server.
uuid may be a full or abbreviated uuid, or the uuid:branch form (93fdbc:main).
instance is the data instance name; the caller checks its type.

neu_vol.dvid.resolve_node(spec: Mapping[str, Any], *, prefer_locked: bool = False) → dict¶

Resolve this spec’s uuid ref to a concrete node, and say if it is locked.

A branch ref (93fdbc:main) resolves to the branch HEAD, which in a lock-and-spawn workflow is the open, still-mutable node. Resolve once, in the driver, and hand workers the concrete uuid: per-worker resolution could read two versions if HEAD moves mid-run.

prefer_locked walks back to the newest locked node with DVID’s ref~N syntax, which needs the repo:branch form. Returns {"ref", "uuid", "locked", "walked"}.

neu_vol.dvid.resolve_roi_set(spec: Mapping[str, Any], rois: Sequence[str]) → list[str]¶

Validate an ROI name list against the node before fetching any of them.

The order given is kept: it decides which ROI wins where two intersect.

neu_vol.dvid.roi_frame(box_lo_blocks: Sequence[int], voxel_size_nm: Sequence[float], origin_nm: Sequence[float] = (0.0, 0.0, 0.0)) → neu_lib.Frame¶

The Frame of an ROI array whose voxel (0, 0, 0) is block box_lo.

voxel_size_nm and origin_nm describe the scale-0 grid the node indexes, which DVID does not record.

neu_vol.dvid.roi_volume(spec: Mapping[str, Any], rois: Sequence[str], *, voxel_size_nm: Sequence[float], origin_nm: Sequence[float] = (0.0, 0.0, 0.0), processes: int = 0) → RoiVolume¶

Fetch the named ROIs as one label array with its Frame.

spec addresses any instance on the node (ROIs are per node). voxel_size_nm / origin_nm are the scale-0 grid’s (see roi_frame()). An ROI holding no blocks raises.

neu_vol.dvid.spec_url(spec: Mapping[str, Any]) → str¶: The dvid:// URL for a spec — for messages and provenance.

neu_vol.dvid.synced_instances(info: Mapping[str, Any]) → list[str]¶

Instances this one is synced to, from Base.Syncs.

An annotation instance answers /label/<id> only when synced to a labelmap, so callers check this before fetching per body.

neu_vol.dvid.MISSING = Multiline-String¶

Show Value

"""Talking to DVID needs the `neuclease` package, which is not installed here.

neuclease cannot be a pip dependency: it needs `libdvid-cpp`, `vigra` and `dvidutils`, which are conda-only on flyem-forge — and libdvid is load-bearing rather than incidental, since it is what inflates DVID's compressed label blocks. Install it into the environment instead:
    mamba install -n neu-env -c flyem-forge -c conda-forge neuclease"""

neu_vol.dvid.ROI_BLOCK_VOXELS = 32¶

neu_vol.dvid.ROI_INSTANCE = 'roi'¶