neu_vol.piece¶

Read a box out of any source as a neu_lib.Piece, and write one back.

A piece carries its array with the frame saying where it is (voxel size and origin in nm), so a crop cannot lose its position on the way through:

piece = read_piece("crops.h5:/crop_01")                     # frame from the file
image = read_piece("s3://bucket/em", level=2, crop=piece)   # the SAME physical box
write_piece(cleaned, "crops_cleaned.h5")                    # ...and back out again

A crop given as another piece, or in nm, is converted through the target level’s own voxel size and origin, so it transfers between levels and between volumes. write_piece() writes an in-memory piece in the same layout pack_hdf5() uses, so neu-vol write can place either with no arguments.

Attributes¶

`DEFAULT_MAX_BYTES`
`logger`

Functions¶

`piece_name`(path[, dataset]) → str	What to call a piece read from `path`: `stem` or `stem/dataset`.
`read_piece`(src[, kind, level, crop, dataset, ...])	The voxels at `src`, with the frame that says where they are.
`write_piece`(piece, out, *[, dataset, dtype, truncate, ...]) → dict	Write a `neu_lib.Piece` to an HDF5 file, frame and position included.

Module Contents¶

neu_vol.piece.piece_name(path: str, dataset: str | None = None) → str¶

What to call a piece read from path: stem or stem/dataset.

Both halves, since crops from different files often share a dataset name and crops in one file share a stem, and a viewer keys layers by name.

The voxels at src, with the frame that says where they are.

src is PATH or PATH:/DATASET, the second selecting an array inside an HDF5 container (only a leading slash after the last colon counts, so s3:// is left alone). A spec mapping or an open backend= is accepted too.

crop is a box in whole voxels of the level read (((lo), (hi)) or the flat six), anything carrying bounds_nm such as another Piece, or {"nm": (lo, hi)}. A physical box is converted with this level’s own voxel size and origin and grown outward to whole voxels.

kind overrides what the source records; unrecorded, it stays None rather than being guessed from the dtype. voxel_size overrides the recorded scale and is required for a source that records none. dtype casts after the read, warning on a narrowing cast, which would silently wrap label ids.

The piece is named stem or stem/dataset after its source (piece_name()), unless name is given. max_bytes refuses a read larger than the cap, naming the size and a level that would fit; None lifts it. Store logging is filtered for the call.

neu_vol.piece.write_piece(piece, out: str, *, dataset: str | None = None, dtype: Any = None, truncate: bool = False, chunk: Sequence[int] | None = None, compression: str | None = 'gzip', overwrite: bool = False, dry_run: bool = False, voxel_size_field: str | None = None, offset_field: str | None = None, block_bytes: int | None = None) → dict¶

Write a neu_lib.Piece to an HDF5 file, frame and position included.

The inverse of read_piece():

piece = read_piece("crops.h5:/crop_01")
cleaned = piece.apply(dust).apply(dilate)
write_piece(cleaned, "crops_cleaned.h5")    # -> /crop_01, same frame

The piece supplies the voxel size, the voxel offset (piece.origin_voxel, which raises rather than rounding a non-whole origin), axes="zyx", units="nm" and its kind. dataset defaults to the last component of piece.name when it has one ("crops/crop_01" -> /crop_01), else DEFAULT_DATASET.

An existing file is added to when its recorded frame matches; a frame that disagrees, or a dataset name already in use without overwrite, is refused (check_hdf5_target()). Writing is blocked, so a lazy array streams. dry_run returns the plan without writing. A dtype too narrow for the values is refused unless truncate (check_fits()).

out must be a local path with an HDF5 extension: h5py has no object-store driver, and HDF5 files are recognised by name. neu-vol write <volume> --src <file> then places the piece with no offset argument.

neu_vol.piece.DEFAULT_MAX_BYTES = 4294967296¶

neu_vol.piece.logger¶