HDF file format

HDF / HDF5 is a hierarchical binary container: groups (folders), datasets (arrays), attributes (the sticky notes). It is the format NASA and a lot of science settled on when a CSV would not hold the cube. It is not how you open a MATLAB .mat. It is not a NIfTI ↔ DICOM conversion. It is not a PYCAD product.

If you meant MATLAB .mat → how to open MAT files (a later leftover; not rewritten here). If you meant VTK / ParaView datasets → VTK data format. If you meant DICOM → NIfTI → how to convert DICOM to NIfTI. If you meant the NIfTI / DICOM / STL hub → NIfTI / DICOM / STL converter guide.

Medical volumes more often travel as DICOM or NIfTI. HDF5 shows up when the same file also has to hold a table, a mask, run notes, and a cube that is larger than a 2 GB cap. This page is that container. It is not 685.

What is in the file

Self-describing means the units travel with the numbers. A colleague ten years later should not need a separate README to know the dataset is in millimetres. Chunking and compression (gzip and friends) are optional; they are why you can pull one slice of a terabyte file without mapping the whole thing. Parallel I/O is why an HPC job can have many ranks in the same file at once.

HDF4 versus HDF5

HDF started at NCSA in 1987. NASA picked it for EOS in the early 1990s after comparing a list of candidates; that decision is why you still trip over HDF4 in old satellite archives. HDF4’s hard stop was a 2 GB file and a rigid set of types. HDF5 (late 1990s) is a different format and a different API: effectively no file-size cap, user-defined types, one API, thread-safe, parallel I/O. The HDF Group (2008, non-profit) stewards the spec. New work is HDF5. HDF4 is an archive you open, not a format you start.

Read and write with h5py

In Python the usual binding is h5py: groups behave like dicts, datasets like NumPy arrays. pip install h5py numpy.

import h5py
import numpy as np

with h5py.File("my_first_hdf_file.h5", "w") as f:
    experiment = f.create_group("experiment_data")
    readings = np.random.rand(100, 3)
    dset = experiment.create_dataset("sensor_readings", data=readings)
    dset.attrs["units"] = "Volts"
    dset.attrs["sensor_model"] = "Model-X42"
    dset.attrs["timestamp"] = "2024-10-26T10:00:00Z"

with h5py.File("my_first_hdf_file.h5", "r") as f:
    data = f["/experiment_data/sensor_readings"][:]
    units = f["/experiment_data/sensor_readings"].attrs["units"]
    print(data.shape, units)

"w" overwrites. "a" opens without wiping. "r" is read-only. The [:] copies the whole dataset into RAM; a slice (dset[0:10, :]) is how you avoid that on a large cube. Path syntax is POSIX-like: /experiment_data/sensor_readings.

When HDF5, when not

• Use it for a large numeric cube, mixed objects in one file, or partial I/O. A 3-D volume plus its mask plus the run config is the usual scientific case.
• Do not use it as a replacement for DICOM in the clinic. The archive, the viewer, and the RIS speak DICOM. Conversion to NIfTI for research is 5714, not this page.
• CSV / JSON are fine for a flat table or a config. They are the wrong container for a 512³ float32.
• .mat is MATLAB’s container (modern .mat is itself HDF5 under the hood — that unpacking is the 425 leftover). Do not flatten this URL into that one.

To look without code: HDFView from The HDF Group, h5ls / h5dump on the CLI, ParaView, Panoply. MATLAB opens HDF5 natively.

What this page is not

• Not 685. NIfTI / DICOM / STL conversion already has a hub and how-tos. This is the container format.
• Not 425 / 7502. MAT files wait their own leftover pass.
• Not 5581. VTK is a visualization dataset, a different tree.
• Not a PYCAD HDF product. Outrank stills, first-person diary, and the homepage-as-CTA are gone. The h5py snippet stayed.

If an HDF5 cube has to be shown next to a DICOM study in a clinic app, that is the imaging piece. Case studies.