Command line interface

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

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

Top-level CLI with global arguments and subcommands.

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

-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}

-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)

Convert datasets

python -m zea.data.convert

Convert raw data to a zea dataset.

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

-h, --help

show this help message and exit

python -m zea.data.convert camus

usage: python -m zea.data.convert camus [-h] [--download]
                                        [--no_hyperthreading] [--upload]
                                        [--revision REVISION]
                                        [--reduced-dataset]
                                        src dst

src

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

dst

Destination folder path

-h, --help

show this help message and exit

--download

Download the CAMUS dataset from the server, will be saved to the –src path

--no_hyperthreading

Disable hyperthreading for multiprocessing

--upload

Upload the converted dataset to HuggingFace Hub (zeahub/camus or zeahub/camus-sample)

--revision <revision>

Revision branch to upload to on HuggingFace Hub. Required when –upload is set. Upload to ‘main’ is not allowed.

--reduced-dataset

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

python -m zea.data.convert cetus

usage: python -m zea.data.convert cetus [-h] [--download]
                                        [--no_hyperthreading] [--upload]
                                        [--revision REVISION]
                                        src dst

src

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

dst

Destination folder path

-h, --help

show this help message and exit

--download

Download the CETUS dataset from the server, will be saved to the –src path

--no_hyperthreading

Disable hyperthreading for multiprocessing

--upload

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

--revision <revision>

Revision branch to upload to on HuggingFace Hub. Required when –upload is set. Upload to ‘main’ is not allowed.

python -m zea.data.convert echonet

usage: python -m zea.data.convert echonet [-h] [--split_path SPLIT_PATH]
                                          [--no_hyperthreading]
                                          src dst

src

Source folder path

dst

Destination folder path

-h, --help

show this help message and exit

--split_path <split_path>

Path to the split.yaml file containing the dataset split if a split should be copied

--no_hyperthreading

Disable hyperthreading for multiprocessing

python -m zea.data.convert echonetlvh

usage: python -m zea.data.convert echonetlvh [-h] [--no_rejection]
                                             [--rejection_path REJECTION_PATH]
                                             [--convert_measurements]
                                             [--convert_images]
                                             [--max_files MAX_FILES] [--force]
                                             [--max_workers MAX_WORKERS]
                                             src dst

src

Source folder path

dst

Destination folder path

-h, --help

show this help message and exit

--no_rejection

Do not reject sequences in manual_rejections.txt

--rejection_path <rejection_path>

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

--convert_measurements

Only convert measurements CSV file

--convert_images

Only convert image files

--max_files <max_files>

Maximum number of files to process (for testing)

--force

Force recomputation even if parameters already exist

--max_workers <max_workers>

Maximum number of workers to use for precomputing cone parameters and dataloading.

python -m zea.data.convert echoxflow

usage: python -m zea.data.convert echoxflow [-h] [--croissant CROISSANT]
                                            [--min-frames MIN_FRAMES]
                                            [--min-fps MIN_FPS]
                                            [--limit LIMIT] [--overwrite]
                                            [--upload] [--revision REVISION]
                                            [--hf_repo_id HF_REPO_ID]
                                            src dst

src

EchoXFlow data root, e.g. /data/EchoXFlow/data

dst

Destination folder path

-h, --help

show this help message and exit

--croissant <croissant>

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

--min-frames <min_frames>

Minimum B-mode frame count.

--min-fps <min_fps>

Minimum frame rate (Hz).

--limit <limit>

Convert at most N recordings.

--overwrite

Overwrite existing output files.

--upload

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

--revision <revision>

Target branch on the Hub. Required when –upload is set; upload to ‘main’ is blocked.

--hf_repo_id <hf_repo_id>

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

python -m zea.data.convert picmus

usage: python -m zea.data.convert picmus [-h] [--download] [--upload]
                                         [--revision REVISION]
                                         src dst

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.

dst

Destination folder path

-h, --help

show this help message and exit

--download

Download both the main PICMUS dataset and the in-vivo partition from the PICMUS challenge website before converting.

--upload

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

--revision <revision>

Revision branch to upload to on HuggingFace Hub. Required when –upload is set. Upload to ‘main’ is not allowed.

python -m zea.data.convert verasonics

usage: python -m zea.data.convert verasonics [-h]
                                             [--frames FRAMES [FRAMES ...]]
                                             [--allow_accumulate]
                                             [--device DEVICE] [--upload]
                                             [--revision REVISION]
                                             [--hf_repo_id HF_REPO_ID]
                                             src dst

src

Source folder path

dst

Destination folder path

-h, --help

show this help message and exit

--frames <frames>

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.

--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.

--device <device>

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

--upload

Upload the converted dataset to HuggingFace Hub after conversion. Only for zea maintainers with push access to the repository.

--revision <revision>

Required when –upload is set. Upload to ‘main’ is not allowed.

--hf_repo_id <hf_repo_id>

HuggingFace repo ID for ownership checks and optional upload. Required if –upload is set.