medh5

The MEDH5 format engine. A .medh5 file is one subject at one or more timepoints, with every image, annotation, transform and curation record about them, in one self-describing HDF5 container. This crate is the canonical implementation of formats 1.0 and 1.1 (the specification, and 1.1 for the optional clinical profile): the data model, HDF5 I/O, validation, chunked access, compression, geometry and transforms, annotations, provenance, integrity — and, for 1.1, clinical events on a subject clock, strict prospective selection, and the task and cache contract training builds on.

It has two siblings, and all three read and write the same bytes:

• the Python package (pip install medh5), a thin layer over this crate that adds the NumPy, PyTorch, MONAI and converter integrations;
• the medh5 command line (medh5-cli), a native binary over this crate.

HDF5 and C-Blosc2 are built from source and linked statically (see medh5-sys), so a dependent crate needs no HDF5 installation. For an MSVC target, set CFLAGS_x86_64_pc_windows_msvc=-DNDEBUG (or the variable for your target): without it HDF5 keeps its assertions, and medh5-sys stops the build.

Write and read a sample

use medh5::array::NdArray;
use medh5::sample::{create, open_sample, GridOptions, ImageOptions};

fn main() -> medh5::Result<()> {
    let path = std::env::temp_dir().join("medh5-readme-case_0001.medh5");

    // A writer validates every call and commits atomically: a reader never
    // sees half a file, and a crash leaves the previous one intact.
    let ct = NdArray::from_vec(&[8, 16, 16], vec![0i16; 8 * 16 * 16])?;
    let mut w = create(&path, Some("case_0001"), Some("DEMO-0001"), "balanced", &[])?;
    w.add_grid("ct", &[8, 16, 16], &[2.0, 0.8, 0.8], GridOptions::default())?;
    w.add_image("CT", &ct, "ct", "CT", ImageOptions::default())?;
    let content_id = w.commit(true)?; // the Merkle root over every stored digest

    let sample = open_sample(&path)?;
    assert_eq!(sample.identity()?.subject_id, "DEMO-0001");
    assert_eq!(sample.content_id()?, content_id);
    let voxels = sample.image("CT")?.read(None, false, None)?;
    assert_eq!(voxels.shape(), [8, 16, 16]);
    assert!(sample.verify(None)?.ok());

    // The validator the writer is held to (§15); `strict` would also ask for a
    // de-identification record (W903).
    let report = medh5::validate::validate_file(&path, "integrity", None)?;
    assert!(report.ok(), "{:?}", report.codes());

    std::fs::remove_file(&path)?;
    Ok(())
}

Where things are

Errors are one Error type whose diagnostic code, when it has one, is the code the validator reports for the same defect (§15.2, 1.1 §11.2).