Command line interface¶
Besides the main zea API documentation, zea provides a
command line interface (CLI) with two primary subcommands.
zea — main entry point¶
The zea command exposes two subcommands:
zea process --dataset <path> --config <config.yaml> [options] # batch beamform
zea app [--share] [--server_port PORT] # Gradio visualizer
zea¶
zea ultrasound toolbox.
usage: zea [-h] command ...
- -h, --help¶
show this help message and exit
zea app¶
usage: zea app [-h] [--share] [--server-port SERVER_PORT] [--device DEVICE]
- -h, --help¶
show this help message and exit
Create a public Gradio share link.
- --server-port <server_port>¶
Port for the Gradio server to listen on. Defaults to 7860.
- --device <device>¶
Compute device passed to init_device (e.g. ‘cpu’, ‘auto:1’).
zea process¶
usage: zea process [-h] --dataset DATASET --config CONFIG
[--save-dir SAVE_DIR] [--key KEY] [--n-frames N_FRAMES]
[--save-as SAVE_AS] [--keep-keys KEEP_KEYS [KEEP_KEYS ...]]
[--timings] [--num-threads NUM_THREADS]
[--revision REVISION] [--config-revision CONFIG_REVISION]
[--overwrite] [--keep-dynamic-range] [--device DEVICE]
- -h, --help¶
show this help message and exit
- --dataset <dataset>, -d <dataset>¶
Path/URI to the zea dataset (folder of HDF5 files or a single HDF5 file).
- --config <config>, -c <config>¶
Path to config.yaml for the beamforming pipeline.
- --save-dir <save_dir>¶
Directory where output files are written. Default: output/
- --key <key>¶
Data key to load from each file (e.g. data/raw_data, data/image/values).
- --n-frames <n_frames>¶
Maximum number of frames to process per file (all frames when omitted).
- --save-as <save_as>¶
Output format. One of: gif, mp4, hdf5.
- --keep-keys <keep_keys>¶
Pipeline output keys to forward to the next frame iteration.
- --timings¶
Record dataloader and pipeline timings and save to YAML files in save_dir.
- --num-threads <num_threads>¶
Number of threads used by the dataloader. Default is 16.
- --revision <revision>¶
HuggingFace revision for the dataset (branch, tag, or commit hash). Only used for hf:// paths.
- --config-revision <config_revision>¶
HuggingFace revision for the config (branch, tag, or commit hash). Defaults to –revision if omitted.
- --overwrite¶
Overwrite existing output files. Default is False.
- --keep-dynamic-range¶
Store pipeline output as-is (float32 dB) instead of converting to uint8. Only valid when –save-as hdf5.
- --device <device>¶
Compute device (‘cuda:0’, ‘cpu’, ‘auto:1’, …). Only relevant when running the beamformer pipeline.
Process dataset (standalone CLI)¶
The beamformer can also be invoked directly as a module (equivalent to zea process).
Both --dataset / -d and --config / -c are required; --save-dir is optional
(defaults to output/):
python -m zea.data.process¶
Beamform a zea dataset using a pipeline defined in a config YAML file. Processes frames sequentially to support temporal algorithms.
usage: python -m zea.data.process [-h] --dataset DATASET --config CONFIG
[--save-dir SAVE_DIR] [--key KEY]
[--n-frames N_FRAMES] [--save-as SAVE_AS]
[--keep-keys KEEP_KEYS [KEEP_KEYS ...]]
[--timings] [--num-threads NUM_THREADS]
[--revision REVISION]
[--config-revision CONFIG_REVISION]
[--overwrite] [--keep-dynamic-range]
[--device DEVICE]
- -h, --help¶
show this help message and exit
- --dataset <dataset>, -d <dataset>¶
Path/URI to the zea dataset (folder of HDF5 files or a single HDF5 file).
- --config <config>, -c <config>¶
Path to config.yaml for the beamforming pipeline.
- --save-dir <save_dir>¶
Directory where output files are written. Default: output/
- --key <key>¶
Data key to load from each file (e.g. data/raw_data, data/image/values).
- --n-frames <n_frames>¶
Maximum number of frames to process per file (all frames when omitted).
- --save-as <save_as>¶
Output format. One of: gif, mp4, hdf5.
- --keep-keys <keep_keys>¶
Pipeline output keys to forward to the next frame iteration.
- --timings¶
Record dataloader and pipeline timings and save to YAML files in save_dir.
- --num-threads <num_threads>¶
Number of threads used by the dataloader. Default is 16.
- --revision <revision>¶
HuggingFace revision for the dataset (branch, tag, or commit hash). Only used for hf:// paths.
- --config-revision <config_revision>¶
HuggingFace revision for the config (branch, tag, or commit hash). Defaults to –revision if omitted.
- --overwrite¶
Overwrite existing output files. Default is False.
- --keep-dynamic-range¶
Store pipeline output as-is (float32 dB) instead of converting to uint8. Only valid when –save-as hdf5.
- --device <device>¶
Compute device (‘cuda:0’, ‘cpu’, ‘auto:1’, …). Only relevant when running the beamformer pipeline.
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}
...
- -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]
[--batch BATCH]
[--convert_measurements]
[--convert_images]
[--max_files MAX_FILES] [--force]
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)
- --batch <batch>¶
Specify which BatchX directory to process, e.g. –batch=Batch2
- --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
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]
[--no_compression] [--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’).
- --no_compression¶
Disable compression when saving the zea dataset. By default, compression is enabled, which reduces disk space at the cost of increased conversion time.
- --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.
Data copying¶
python -m zea.data¶
Arguments for copying a zea.Folder to a new location.
usage: python -m zea.data [-h] --src STR --dst STR --key STR
[--mode {None,a,w,r+,x}]
- -h, --help¶
show this help message and exit
- --src¶
Source folder path. (required)
- --dst¶
Destination folder path. (required)
- --key¶
Key to access in the HDF5 files. (required)
- --mode¶
Default None lets Folder.copy auto-select the mode (‘a’ for a single key, ‘w’ when –key is ‘all’/’*’); passing ‘a’ would break the all/* case. (default: None)
Data file manipulation¶
python -m zea.data.file_operations¶
Manipulate zea data files.
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.
usage: python -m zea.data.file_operations [-h]
{sum,compound_frames,compound_transmits,resave,extract}
...
- -h, --help¶
show this help message and exit
python -m zea.data.file_operations compound_frames¶
usage: python -m zea.data.file_operations compound_frames [-h] [--overwrite]
input_path
output_path
- input_path¶
Input HDF5 file or folder.
- output_path¶
Output HDF5 file or folder.
- -h, --help¶
show this help message and exit
- --overwrite¶
Overwrite existing output file.
python -m zea.data.file_operations compound_transmits¶
usage: python -m zea.data.file_operations compound_transmits
[-h] [--overwrite] input_path output_path
- input_path¶
Input HDF5 file or folder.
- output_path¶
Output HDF5 file or folder.
- -h, --help¶
show this help message and exit
- --overwrite¶
Overwrite existing output file.
python -m zea.data.file_operations extract¶
usage: python -m zea.data.file_operations extract [-h]
[--transmits TRANSMITS [TRANSMITS ...]]
[--frames FRAMES [FRAMES ...]]
[--overwrite]
input_path output_path
- input_path¶
Input HDF5 file or folder.
- output_path¶
Output HDF5 file or folder.
- -h, --help¶
show this help message and exit
- --transmits <transmits>¶
Target transmits. Can be a list of integers or ranges (e.g. 0-3 7).
- --frames <frames>¶
Target frames. Can be a list of integers or ranges (e.g. 0-3 7).
- --overwrite¶
Overwrite existing output file.
python -m zea.data.file_operations resave¶
usage: python -m zea.data.file_operations resave [-h] [--overwrite]
[--chunk-frames]
[--disable-compression]
input_path output_path
- input_path¶
Input HDF5 file or folder.
- output_path¶
Output HDF5 file or folder.
- -h, --help¶
show this help message and exit
- --overwrite¶
Overwrite existing output file.
- --chunk-frames¶
Store the data datasets with HDF5 chunked storage, one frame per chunk.
- --disable-compression¶
Disable lzf compression for the datasets.
python -m zea.data.file_operations sum¶
usage: python -m zea.data.file_operations sum [-h] [--overwrite]
input_paths [input_paths ...]
output_path
- input_paths¶
Paths to the input files or folders.
- output_path¶
Output HDF5 file.
- -h, --help¶
show this help message and exit
- --overwrite¶
Overwrite existing output file.