CLI & Scripts Overview

This section provides comprehensive guides for using PhysioTwin4D’s command-line tools to process medical imaging data. These tools are designed for medical imaging experts and physiological simulation researchers who need efficient, reproducible pipelines for extracting anatomic models from 3D medical images and building the personalized physiological digital twins derived from them.

How to Use These Resources

PhysioTwin4D exposes the same toolkit through three user-facing layers:

  • Workflows are Python classes that orchestrate complete processing pipelines. Use them when integrating PhysioTwin4D into Python applications or when you need programmatic control over inputs, outputs, and parameters.

  • CLIs are installed command-line wrappers around workflow classes. Use them for repeatable processing runs, batch jobs, and environment validation without writing Python glue code.

  • Tutorials are repository scripts that demonstrate each major workflow with concrete data preparation, commands, and expected outputs. Use them when first learning the toolkit or validating a local installation.

The experiments/ directory tracks prior and ongoing research experiments that helped define this toolkit. Those experiments are useful historical and design context, but they are not intended to be examples for users or developers. For supported usage patterns, start with the tutorials, CLIs, and workflow API documentation.

Target Audience

These CLI tools are intended for users with:

  • Strong medical image analysis expertise

  • Understanding of physiological simulation requirements

  • Modest Python experience for running scripts

  • Familiarity with command-line interfaces

If you are a Python developer looking to extend or integrate PhysioTwin4D into your applications, please refer to the Architecture Overview section.

Available Scripts

Current Scripts

Script

Description

Download Example Data

Download supported PhysioTwin4D example datasets

Heart Gated CT Processing

Process cardiac gated CT to animated heart models with physiological motion

convert_image_to_vtk (CLI)

Segment one 3D image and export anatomy-group VTK surfaces

convert_image_4d_to_3d (CLI)

Split a 4D medical image into a 3D time series using ITK readers

Create Statistical Model

Build a PCA statistical shape model from sample meshes aligned to a reference

Heart Model to Patient Registration

Register generic heart models to patient-specific imaging data and surface models

High-Resolution 4D CT Reconstruction

Reconstruct high-resolution 4D CT from time-series images and a reference

VTK to USD Conversion

Convert VTK anatomical models to USD format with material painting

Train a PhysicsNeMo Surrogate

Train a PhysicsNeMo mesh-stage surrogate from per-subject manifests

Predict With a Trained Surrogate

Predict motion with a trained surrogate, and rasterize deformation fields

visualize_pca_modes (CLI)

Render PCA model mode visualizations

Installation

All scripts are installed with the PhysioTwin4D package:

pip install physiotwin4d

After installation, scripts are available as command-line tools with the prefix physiotwin4d-:

physiotwin4d-convert-image-to-usd --help
physiotwin4d-download-data --help

General Workflow

All PhysioTwin4D scripts follow a similar pattern:

  1. Input Data: Provide medical image files (NRRD, NII, MHA formats)

  2. Configuration: Set processing parameters via command-line flags

  3. Processing Pipeline: Automated execution of segmentation, registration, and conversion

  4. Output Generation: USD files ready for Omniverse visualization

Typical Command Structure

physiotwin4d-<command> --help

Use each command’s --help output as the source of truth for required arguments and script-specific options.

Output Organization

Every script writes into the directory you give it, flat, with filenames prefixed by the project name where one applies:

output_directory/
├── <project_name>.dynamic_painted.usd     # animated USD, when produced
├── <project_name>.static_painted.usd
├── <project_name>.all_painted.usd
├── patient_surfaces.vtp                   # meshes, from the VTK workflows
├── patient_labelmap.mha                   # labelmaps and volumes
└── *.png                                  # screenshots, when requested

The tutorial scripts follow the same rule under tutorials/output/<tutorial_name>/.

Getting Help

Each script provides detailed help:

physiotwin4d-<script-name> --help

For troubleshooting and common issues, see Troubleshooting.

Next Steps