Command line interface

Besides the main zea API documentation, zea provides a command line interface (CLI) with four primary subcommands (process, app, data, convert).

Note that is very new functionality, and might change in future releases. Please report any issues you encounter.

zea process --dataset <path> --config <config.yaml> [options]  # batch beamform a dataset
zea app [--share] [--server-port PORT]                         # launch the Gradio visualizer
zea data <operation> [options]                                 # manipulate zea data files
zea convert <dataset> <src> <dst> [options]                    # convert raw datasets to zea

zea

Top-level CLI with global arguments and subcommands.

usage: zea [-h] [--device STR] {process,app,data,convert}

-h, --help

show this help message and exit

--device STR

Compute device passed to init_device (e.g. ‘cpu’, ‘auto:1’). (default: auto:1)

zea process

Arguments for beamforming a zea dataset.

usage: zea process [-h] -d STR -c STR [-o PATH] [--key STR] [--n-frames {None}|INT] [--save-as {gif,mp4,hdf5}] [--keep-keys [STR [STR ...]]] [--timings | --no-timings] [--num-threads INT] [--revision {None}|STR] [--config-revision {None}|STR] [--overwrite | --no-overwrite] [--keep-dynamic-range | --no-keep-dynamic-range]

-h, --help

show this help message and exit

-d STR, --dataset STR

Path/URI to the zea dataset (folder of HDF5 files or a single HDF5 file). (required)

-c STR, --config STR

Path to config.yaml for the beamforming pipeline. (required)

-o PATH, --save-dir PATH

Directory where output files are written. Default: output/ (default: output)

--key STR

Data key to load from each file (e.g. data/raw_data, data/image/values). (default: data/raw_data)

--n-frames {None}|INT

Maximum number of frames to process per file (all frames when omitted). (default: None)

--save-as {gif,mp4,hdf5}

Output format. One of: gif, mp4, hdf5. (default: gif)

--keep-keys [STR [STR ...]]

List of pipeline output keys to forward to the next frame iteration. (default: maxval)

--timings, --no-timings

Record dataloader and pipeline timings and save to YAML files in save_dir. (default: False)

--num-threads INT

Number of threads for the dataloader. Default: 16. (default: 16)

--revision {None}|STR

HuggingFace revision for the dataset (branch, tag, or commit hash). Only used for hf:// paths. (default: None)

--config-revision {None}|STR

HuggingFace revision for the config (branch, tag, or commit hash). Defaults to –revision if omitted. (default: None)

--overwrite, --no-overwrite

Overwrite existing output files. Default: False. (default: False)

--keep-dynamic-range, --no-keep-dynamic-range

Store pipeline output as-is (float32 dB) instead of converting to uint8. Only valid when –save-as hdf5. (default: False)

zea app

Arguments for the interactive Gradio dataset visualizer.

usage: zea app [-h] [--share | --no-share] [--server-port {None}|INT]

-h, --help

show this help message and exit

--share, --no-share

Create a public Gradio share link. (default: False)

--server-port {None}|INT

Port for the Gradio server to listen on. If None, will search for an available port starting at 7860. Defaults to None. (default: None)

zea data

Manipulate zea data files (sum, compound, resave, extract, summary, copy).

All operations accept files; folder inputs are also supported. For file-to-file operations, each zea file in the input folder is processed and written to a mirrored path in the output folder. Inputs also accept hf:// paths (a single file or a folder in a Hugging Face dataset repo); outputs must be local paths.

usage: zea data [-h] {sum,compound_frames,compound_transmits,resave,extract,summary,copy,decode_hadamard,sa_to_virtual_focus}

-h, --help

show this help message and exit

zea data sum

Sum the raw data of multiple files or folders.

usage: zea data sum [-h] --output-path STR [--overwrite | --no-overwrite] [[STR [STR ...]]]

-h, --help

show this help message and exit

input-paths

Paths to the input files or folders. Also accepts ‘hf://’ paths. (default: )

--output-path STR

Output HDF5 file. Passed as --output-path because the inputs are variadic. (required)

--overwrite, --no-overwrite

Overwrite existing output file. (default: False)

zea data compound_frames

Compound frames to increase SNR.

usage: zea data compound_frames [-h] [--overwrite | --no-overwrite] STR STR

-h, --help

show this help message and exit

input-path

Input HDF5 file or folder. Also accepts an ‘hf://’ path. (required)

output-path

Output HDF5 file or folder. (required)

--overwrite, --no-overwrite

Overwrite existing output file. (default: False)

zea data compound_transmits

Compound transmits to increase SNR.

usage: zea data compound_transmits [-h] [--overwrite | --no-overwrite] STR STR

-h, --help

show this help message and exit

input-path

Input HDF5 file or folder. Also accepts an ‘hf://’ path. (required)

output-path

Output HDF5 file or folder. (required)

--overwrite, --no-overwrite

Overwrite existing output file. (default: False)

zea data resave

Resave a file to change format version.

usage: zea data resave [-h] [--overwrite | --no-overwrite] [--chunk-axes [STR [STR ...]]] STR STR

-h, --help

show this help message and exit

input-path

Input HDF5 file or folder. Also accepts an ‘hf://’ path. (required)

output-path

Output HDF5 file or folder. (required)

--overwrite, --no-overwrite

Overwrite existing output file. (default: False)

--chunk-axes [STR [STR ...]]

Dimension names to chunk with HDF5 chunk size 1 (others stored at full extent), so partial/streamed reads fetch only the requested frames. Defaults to one chunk per frame, mirroring zea.data.spec.DEFAULT_CHUNK_AXES (default: n_frames)

zea data extract

Extract subset of frames or transmits.

usage: zea data extract [-h] [--transmits [STR [STR ...]]] [--frames [STR [STR ...]]] [--overwrite | --no-overwrite] STR STR

-h, --help

show this help message and exit

input-path

Input HDF5 file or folder. Also accepts an ‘hf://’ path. (required)

output-path

Output HDF5 file or folder. (required)

--transmits [STR [STR ...]]

Target transmits. Can be a list of integers or ranges (e.g. 0-3 7). (default: all)

--frames [STR [STR ...]]

Target frames. Can be a list of integers or ranges (e.g. 0-3 7). (default: all)

--overwrite, --no-overwrite

Overwrite existing output file. (default: False)

zea data summary

Print a summary of a zea data file to the console.

usage: zea data summary [-h] STR

-h, --help

show this help message and exit

input-path

Input HDF5 file. Also accepts an ‘hf://’ path. (required)

zea data copy

Copy zea files or folders to a new location.

You can specify a data key to copy only a subset of the data. If the destination file already exists, you can specify a mode to control how the data is written (append, overwrite, etc.).

usage: zea data copy [-h] --key STR [--mode {None,a,w,r+,x}] STR STR

-h, --help

show this help message and exit

src

Source file or folder path. Also accepts an ‘hf://’ path. (required)

dst

Destination folder path. (required)

--key STR

Key to access in the HDF5 files. (required)

--mode {None,a,w,r+,x}

HDF5 file mode for the destination files. Defaults to auto-selection. (default: None)

zea data decode_hadamard

Decode Hadamard-encoded data in a zea file or folder.

usage: zea data decode_hadamard [-h] [--overwrite | --no-overwrite] PATH PATH

-h, --help

show this help message and exit

input-path

Input HDF5 file or folder. (required)

output-path

Output HDF5 file or folder. (required)

--overwrite, --no-overwrite

Overwrite existing output file. (default: False)

zea data sa_to_virtual_focus

Convert a synthetic aperture dataset to a virtual focus dataset.

usage: zea data sa_to_virtual_focus [-h] [--polar-angle-deg FLOAT] [--azimuth-angle-deg FLOAT] [--focus-distance FLOAT] [--transmit-origin FLOAT FLOAT FLOAT] [--tx-apodization STR] [--overwrite | --no-overwrite] PATH PATH

-h, --help

show this help message and exit

input-path

Input HDF5 file or folder. (required)

output-path

Output HDF5 file or folder. (required)

--polar-angle-deg FLOAT

Polar angle for the virtual focus. (default: 0.0)

--azimuth-angle-deg FLOAT

Azimuth angle for the virtual focus. (default: 0.0)

--focus-distance FLOAT

Focus distance for the virtual focus. (default: inf)

--transmit-origin FLOAT FLOAT FLOAT

Origin of the transmit. (default: 0.0 0.0 0.0)

--tx-apodization STR

Type of transmit apodization to apply. (default: kaiser)

--overwrite, --no-overwrite

Overwrite existing output file. (default: False)

zea convert

Convert raw open-source ultrasound datasets to the zea format.

Pick a dataset subcommand and provide the source and destination folders:

zea convert camus ./raw ./output --download
zea convert echonet ./raw ./output
zea convert echoxflow ./raw ./output

Run zea convert <dataset> --help for the per-dataset options.

usage: zea convert [-h] {echonet,echonetlvh,camus,cetus,picmus,verasonics,echoxflow}

-h, --help

show this help message and exit

zea convert echonet

Convert Echonet dataset.

usage: zea convert echonet [-h] [--split-path {None}|PATH] [--no-hyperthreading | --no-no-hyperthreading] PATH PATH

-h, --help

show this help message and exit

src

Source folder path. (required)

dst

Destination folder path. (required)

--split-path {None}|PATH

Path to the split.yaml file containing the dataset split if a split should be copied. (default: None)

--no-hyperthreading, --no-no-hyperthreading

Disable hyperthreading for multiprocessing. (default: False)

zea convert echonetlvh

Convert EchonetLVH dataset.

usage: zea convert echonetlvh [-h] [--no-rejection | --no-no-rejection] [--rejection-path {None}|PATH] [--convert-measurements | --no-convert-measurements] [--convert-images | --no-convert-images] [--max-files {None}|INT] [--force | --no-force] [--max-workers INT] PATH PATH

-h, --help

show this help message and exit

src

Source folder path. (required)

dst

Destination folder path. (required)

--no-rejection, --no-no-rejection

Do not reject sequences in manual_rejections.txt. (default: False)

--rejection-path {None}|PATH

Path to custom rejection txt file (defaults to manual_rejections.txt from zea). (default: None)

--convert-measurements, --no-convert-measurements

Only convert measurements CSV file. (default: False)

--convert-images, --no-convert-images

Only convert image files. (default: False)

--max-files {None}|INT

Maximum number of files to process (for testing). (default: None)

--force, --no-force

Force recomputation even if parameters already exist. (default: False)

--max-workers INT

Maximum number of workers to use for precomputing cone parameters and dataloading. (default: 4)

zea convert camus

Convert CAMUS dataset.

usage: zea convert camus [-h] [--download | --no-download] [--no-hyperthreading | --no-no-hyperthreading] [--upload | --no-upload] [--revision {None}|STR] [--reduced-dataset | --no-reduced-dataset] PATH PATH

-h, --help

show this help message and exit

src

Source folder path, should contain either manually downloaded dataset or will be target location for automated download with the –download flag. (required)

dst

Destination folder path. (required)

--download, --no-download

Download the CAMUS dataset from the server, will be saved to the –src path. (default: False)

--no-hyperthreading, --no-no-hyperthreading

Disable hyperthreading for multiprocessing. (default: False)

--upload, --no-upload

Upload the converted dataset to HuggingFace Hub (zeahub/camus or zeahub/camus-sample). (default: False)

--revision {None}|STR

Revision branch to upload to on HuggingFace Hub. Required when –upload is set. Upload to ‘main’ is not allowed. (default: None)

--reduced-dataset, --no-reduced-dataset

Only convert and upload a small hardcoded sample subset (camus-sample). (default: False)

zea convert cetus

Convert CETUS dataset.

usage: zea convert cetus [-h] [--download | --no-download] [--no-hyperthreading | --no-no-hyperthreading] [--upload | --no-upload] [--revision {None}|STR] PATH PATH

-h, --help

show this help message and exit

src

Source folder path, should contain either manually downloaded dataset or will be target location for automated download with the –download flag. (required)

dst

Destination folder path. (required)

--download, --no-download

Download the CETUS dataset from the server, will be saved to the –src path. (default: False)

--no-hyperthreading, --no-no-hyperthreading

Disable hyperthreading for multiprocessing. (default: False)

--upload, --no-upload

Upload the converted dataset to HuggingFace Hub (zeahub/cetus-miccai-2014). (default: False)

--revision {None}|STR

Revision branch to upload to on HuggingFace Hub. Required when –upload is set. Upload to ‘main’ is not allowed. (default: None)

zea convert picmus

Convert PICMUS dataset.

usage: zea convert picmus [-h] [--download | --no-download] [--upload | --no-upload] [--revision {None}|STR] PATH PATH

-h, --help

show this help message and exit

src

Source folder path. Should contain either a manually downloaded and extracted archive (archive_to_download/ or picmus.zip) or will be used as the download target when –download is given. An ‘in_vivo/’ sub-directory, if present, is automatically included. (required)

dst

Destination folder path. (required)

--download, --no-download

Download both the main PICMUS dataset and the in-vivo partition from the PICMUS challenge website before converting. (default: False)

--upload, --no-upload

Upload the converted dataset to HuggingFace Hub (zeahub/picmus). (default: False)

--revision {None}|STR

Revision branch to upload to on HuggingFace Hub. Required when –upload is set. Upload to ‘main’ is not allowed. (default: None)

zea convert verasonics

Convert Verasonics data to zea dataset.

usage: zea convert verasonics [-h] [--frames {None}|{[STR [STR ...]]}] [--allow-accumulate | --no-allow-accumulate] [--device STR] [--upload | --no-upload] [--revision {None}|STR] [--hf-repo-id STR] PATH PATH

-h, --help

show this help message and exit

src

Source folder path. (required)

dst

Destination folder path. (required)

--frames {None}|{[STR [STR ...]]}

The frames to add to the file. This can be a list of integers, a range of integers (e.g. 4-8), or ‘all’. Defaults to ‘all’, unless specified in a convert.yaml file. (default: None)

--allow-accumulate, --no-allow-accumulate

Sometimes, some transmits are already accumulated on the Verasonics system (e.g. harmonic imaging through pulse inversion). In this case, the mode in the Receive structure is set to 1 (accumulate). If this flag is set, such files will be processed. Otherwise, an error is raised when such a mode is detected. (default: False)

--device STR

Device to use for conversion (e.g., ‘cpu’ or ‘gpu:0’). (default: cpu)

--upload, --no-upload

Upload the converted dataset to HuggingFace Hub after conversion. Only for zea maintainers with push access to the repository. (default: False)

--revision {None}|STR

Required when –upload is set. Upload to ‘main’ is not allowed. (default: None)

--hf-repo-id STR

HuggingFace repo ID for ownership checks and optional upload. Required if –upload is set. (default: ‘’)

zea convert echoxflow

Convert EchoXFlow dataset.

usage: zea convert echoxflow [-h] [--croissant {None}|STR] [--min-frames INT] [--min-fps FLOAT] [--limit {None}|INT] [--overwrite | --no-overwrite] [--upload | --no-upload] [--revision {None}|STR] [--hf-repo-id STR] STR STR

-h, --help

show this help message and exit

src

EchoXFlow data root, e.g. /data/EchoXFlow/data (required)

dst

Destination folder path. (required)

--croissant {None}|STR

Path to croissant.json (default: <src>/croissant.json). (default: None)

--min-frames INT

Minimum B-mode frame count. (default: 10)

--min-fps FLOAT

Minimum frame rate (Hz). (default: 30.0)

--limit {None}|INT

Convert at most N recordings. (default: None)

--overwrite, --no-overwrite

Overwrite existing output files. (default: False)

--upload, --no-upload

Upload the converted dataset to HuggingFace Hub (zeahub/echoxflow). (default: False)

--revision {None}|STR

Target branch on the Hub. Required when –upload is set; upload to ‘main’ is blocked. (default: None)

--hf-repo-id STR

HuggingFace repo id for ownership checks and optional upload (default: zeahub/echoxflow). (default: ‘’)