API Reference¶

Reading, writing, converting¶

medvol.read ¶

read(path: PathLike, format: Optional[str] = None, policy: Optional[Policy] = None, reference=None, **options) -> Tuple[Image, Report]

The image in path and the report. Raises if path holds several images (use read_all).

medvol.read_all ¶

read_all(path: PathLike, format: Optional[str] = None, policy: Optional[Policy] = None, reference=None, **options) -> Tuple[List[Image], Report]

Every image in path (a DICOM directory can hold several stacks) and the report.

reference: for a DICOM RTSTRUCT, the referenced image series it is rasterised onto.

medvol.write ¶

write(image: Image, path: PathLike, format: Optional[str] = None, policy: Optional[Policy] = None, reference=None, **options) -> Report

Write image to path; the format comes from format or the extension.

reference: for a DICOM SEG, the referenced image series (directory, files or datasets).

medvol.convert.convert ¶

convert(source: PathLike, target: PathLike, source_format: Optional[str] = None, target_format: Optional[str] = None, policy: Optional[Policy] = None, **options) -> Report

Read source and write it to target; the report covers both steps.

medvol.inspect ¶

inspect(path: PathLike, format: Optional[str] = None, policy: Optional[Policy] = None, **options) -> str

A summary of the image(s) in path in the MLArray vocabulary.

medvol.reorient.reorient ¶

reorient(image: Image, target: str, report: Report = None) -> Image

image reoriented to the closest "LPS" or "RAS" layout (a new Image).

medvol.check_capabilities ¶

check_capabilities(image: Image, capabilities: Capabilities, report: Report, policy: Policy) -> None

Report (or raise for, with on_loss='error') what the target format cannot represent.

Image, policy and report¶

medvol.Image `dataclass` ¶

Image(array: ndarray, meta: Meta)

Stored values in their original dtype, in the array order meta.axes describes, plus metadata.

to_mlarray ¶

to_mlarray(**kwargs) -> MLArray

An in-memory MLArray of this image (layout options as for MLArray).

medvol.Policy `dataclass` ¶

Policy(nifti_form: str = 'nibabel', nifti_form_disagreement: str = 'warn', nifti_form_tolerance_mm: float = 0.001, nifti_no_codes: str = 'error', reorient: str = 'none', world_frame: str = 'dicom_patient', dicom_tilt: str = 'exact', dicom_irregular_spacing: str = 'error', dicom_stacks: str = 'split', dicom_rescale: str = 'error', vector_frame: str = 'from_file', on_loss: str = 'warn', layout: str = 'source')

Options of read, write and convert; the first option of each is the default.

nifti_form_tolerance_mm is the distance (in mm, over the image corners) above which qform and sform count as disagreeing.

from_options `classmethod` ¶

from_options(policy: Policy = None, **options: Any) -> Policy

A policy from keyword options, optionally on top of an existing policy.

medvol.Report `dataclass` ¶

Report(operation: str, format: str, path: Optional[str] = None, choices: Dict[str, Any] = dict(), warnings: List[str] = list(), dropped: List[str] = list())

choose ¶

choose(name: str, value: Any) -> None

Record a choice made by a policy or by the data.

drop ¶

drop(what: str, reason: str, on_loss: str = 'warn') -> None

Record something the target cannot represent; raise if on_loss is error.

history_entry ¶

history_entry(tool: str) -> Dict[str, Any]

The entry this report adds to an image's history.

medvol.LossError ¶

Bases: ValueError

Something cannot be represented in the target format and policy on_loss is error.

Plugins¶

medvol.plugins.base.FormatPlugin ¶

Bases: ABC

read `abstractmethod` ¶

read(path: PathLike, policy: Policy, **options) -> Tuple[List[Image], Report]

All images in path (DICOM can hold several stacks) and the report.

options are format-specific (e.g. the reference series of a DICOM RTSTRUCT).

sniff `abstractmethod` ¶

sniff(path: PathLike) -> float

Confidence 0..1 that path is in this format, from its content where possible.

write `abstractmethod` ¶

write(image: Image, path: PathLike, policy: Policy, **options) -> Report

Write image to path; options are format-specific (e.g. DICOM SEG reference).

medvol.plugins.base.Capabilities `dataclass` ¶

Capabilities(max_space_axes: int = 3, min_space_axes: int = 1, non_space_axes: FrozenSet[str] = frozenset(), max_ndim: int = 7, oblique: bool = True, shear: bool = True, label_table: bool = False, key_value: bool = False, dtypes: Optional[FrozenSet[str]] = None)

What a writer can represent; anything else is reported and dropped, or raises (on_loss).

medvol.plugins.base.FieldTable `dataclass` ¶

FieldTable(core_owned: FrozenSet[str] = frozenset(), data_dependent: FrozenSet[str] = frozenset())

Ownership of a format's header fields (spec section 4).

core-owned: always regenerated from the MLArray core on export;
data-dependent: kept while the source fingerprint matches, else recomputed or dropped;
everything else: verbatim.

medvol.registry.plugins ¶

plugins() -> Dict[str, FormatPlugin]

All registered plugins by name (loaded once).

medvol.registry.register ¶

register(plugin: FormatPlugin) -> None

Register a plugin at runtime (replaces a plugin of the same name).

medvol.registry.get ¶

get(name: str) -> FormatPlugin

DICOM helpers¶

medvol.plugins.dicom_seg.write_seg ¶

write_seg(image: Image, path: str, policy: Policy, reference=None) -> Report

A DICOM SEG of the label map image on the referenced series (spec 7.6).

reference (or medvol.write(..., reference=...)): the referenced image series as a directory, a list of files or of pydicom datasets. path is the output file (*.dcm) or a directory.

medvol.plugins.dicom_rtstruct.read_rtstruct ¶

read_rtstruct(path: PathLike, reference: PathLike, policy: Policy) -> Tuple[List[Image], Report]

The label map of every RTSTRUCT in path, rasterised onto the image series reference.

reference is read with the same policy (a directory or file(s) that medvol reads as DICOM); RTSTRUCTs in it are ignored. Returns (images, report).