zea.data.convert.picmus¶

Convert the PICMUS database to the zea format.

PICMUS (Plane-wave Imaging Challenge in Medical UltraSound) is a public dataset released for the IEEE International Ultrasonics Symposium 2016 (IUS 2016, Tours, France). It contains simulated, experimental, and in-vivo plane-wave ultrasound acquisitions captured with a Verasonics Vantage system and L11-4v probe, designed for benchmarking image reconstruction algorithms.

The dataset comprises three partitions:

Simulation - Synthetic contrast-speckle and resolution phantoms (IQ data).
Experimental - Physical phantom measurements (IQ and RF data).
In-vivo - Carotid artery acquisitions (IQ data).

License

The datasets and code provided on PICMUS are free of use. The only request is to refer properly to PICMUS - The Plane Wave Imaging Challenge in Medical UltraSound and quote the proceeding paper.

Reference

H. Liebgott, A. Rodriguez-Molares, F. Cervenansky, J. D’hooge and O. Bernard. Plane-Wave Imaging Challenge in Medical Ultrasound. 2016 IEEE International Ultrasonics Symposium (IUS), Tours, France, 2016, pp. 1-4. DOI: 10.1109/ULTSYM.2016.7728908

Links

PICMUS Challenge website
Download page
Dataset on Hugging Face (simulation and experimental partitions only; in-vivo is not yet uploaded)

Usage

python -m zea.data.convert picmus ./raw ./output --download
python -m zea.data.convert picmus ./raw ./output

Functions

`convert`(source_path, output_path[, overwrite])	Convert and write a single PICMUS HDF5 file to the zea format.
`convert_picmus`(args)	Convert PICMUS HDF5 files to the zea dataset format.
`download_picmus`(destination)	Download the PICMUS main dataset and in-vivo partition.
`upload_picmus`(output_folder, revision)	Upload the converted PICMUS dataset to a HuggingFace Hub revision branch.

zea.data.convert.picmus.convert(source_path, output_path, overwrite=False)[source]¶

Convert and write a single PICMUS HDF5 file to the zea format.

The subject type ("simulation", "phantom", or "human") is inferred automatically from the source file path.

Parameters:

source_path (str, pathlike) – Path to the original PICMUS HDF5 file.
output_path (str, pathlike) – Path for the output zea HDF5 file.
overwrite (bool, optional) – If True, overwrite any existing output file. Defaults to False.

zea.data.convert.picmus.convert_picmus(args)[source]¶

Convert PICMUS HDF5 files to the zea dataset format.

Processes all matching files found in the source directory (and optionally the in-vivo partition), preserving the relative directory structure under the destination. Each converted file is placed in its own sub-directory named after the file stem, which is required by the zea dataset format.

Usage:

# Download and convert everything (main + in-vivo)
python -m zea.data.convert picmus <src> <dst> --download

# Convert from manually extracted archives
python -m zea.data.convert picmus <src> <dst>

Parameters:

args (argparse.Namespace) –

An object with the following attributes.

src (str or Path): Working directory. When --download is given, both archives are downloaded here. Otherwise this must contain archive_to_download/ (or picmus.zip) and optionally an in_vivo/ sub-directory.
dst (str or Path): Output directory. Converted files are written here, preserving relative paths. Created if absent; existing files are skipped.
download (bool, optional): If True, automatically download the main dataset and the in-vivo partition before converting.

Note

Only files whose names end in iq.hdf5 or rf.hdf5 (and do not contain img) are converted; all others are skipped.
Without --download, an in_vivo/ sub-directory found next to the main data directory is automatically included.

zea.data.convert.picmus.download_picmus(destination)[source]¶

Download the PICMUS main dataset and in-vivo partition.

Downloads archive_to_download.zip (simulation + experimental data) and in_vivo.zip from the PICMUS challenge website and extracts both archives into destination.

Parameters:: destination (str | Path) – Directory where the archives will be downloaded and extracted. Will be created if it does not exist.
Return type:: tuple[Path, Path]
Returns:: A tuple (main_dir, invivo_dir) where main_dir is the path to the extracted main dataset and invivo_dir is the path to the extracted in-vivo dataset.

zea.data.convert.picmus.upload_picmus(output_folder, revision)[source]¶

Upload the converted PICMUS dataset to a HuggingFace Hub revision branch.

Only for zea maintainers with push access to the repository. Upload to main is blocked; merge the revision branch into main manually after verifying the upload.

Parameters:

output_folder (str | Path) – Root folder containing the converted HDF5 files.
revision (str) – Target branch name on the Hub (must not be "main").

Return type:

None