CLI Reference

Complete command-line interface for training, calibration, inference, and export.

Installation

# Create virtual environment

python -m venv .venv

.venv\Scripts\activate # Windows

# source .venv/bin/activate # Linux/Mac

# Basic install

pip install -e .

# With ONNX export support

pip install -e ".[export]"

# With ONNX runtime validation

pip install -e ".[export,export-validate]"

# Development tools (pytest, black, ruff)

pip install -e ".[dev]"

Requirements: Python 3.10+. Requires PyTorch >=2.6.0 (RCE fix) and Pillow >=10.3.0 (buffer overflow fix).

Debug Logging

All commands support --verbose or -v flag for debug logging:

rdn-woundseg --verbose train [options]

rdn-woundseg -v predict [options]

Commands

`rdn-woundseg train`

Train a new U-Net model from scratch. Saves best checkpoint as best_model_epoch{N}_{timestamp}.pth.

Example Usage

rdn-woundseg train \ --train-csv data/dataset_train.csv \ --test-csv data/dataset_test.csv \ --image-dir images --mask-dir masks \ --test-image-dir test_images --test-mask-dir test_masks \ --out outputs/base --epochs 15

Options

--train-csvPath to training dataset CSV

--test-csvPath to test dataset CSV

--image-dirDirectory containing training images

--mask-dirDirectory containing training masks

--test-image-dirDirectory containing test images

--test-mask-dirDirectory containing test masks

--outOutput directory for checkpoints

--epochsNumber of training epochs (default: 15)

`rdn-woundseg finetune`

Fine-tune an existing model checkpoint. Saves best checkpoint as best_model_finetune_epoch{N}_{timestamp}.pth.

Example Usage

rdn-woundseg finetune \ --train-csv data/dataset_train.csv \ --test-csv data/dataset_test.csv \ --image-dir images --mask-dir masks \ --test-image-dir test_images --test-mask-dir test_masks \ --base-ckpt outputs/base --out outputs/finetune --epochs 5

Options

--base-ckptPath to base checkpoint directory

--train-csvPath to training dataset CSV

--test-csvPath to test dataset CSV

--image-dirDirectory containing training images

--mask-dirDirectory containing training masks

--test-image-dirDirectory containing test images

--test-mask-dirDirectory containing test masks

--outOutput directory for fine-tuned model

--epochsNumber of fine-tuning epochs

`rdn-woundseg calibrate`

Find optimal operating threshold via grid search over Dice score. Outputs threshold_curve.png and best_threshold.txt.

Example Usage

rdn-woundseg calibrate \ --ckpt outputs/finetune \ --test-csv data/dataset_test.csv \ --test-image-dir test_images --test-mask-dir test_masks \ --out outputs/finetune --grid-step 0.05

Options

--ckptPath to model checkpoint

--test-csvPath to test dataset CSV

--test-image-dirDirectory with test images

--test-mask-dirDirectory with test masks

--outOutput directory for calibration results

--grid-stepStep size for threshold grid search (default: 0.05)

`rdn-woundseg analyze`

Bucket predictions into TP/FN/FP/TN and identify UNCERTAIN cases. Writes policy_lock.txt for deployment.

Example Usage

rdn-woundseg analyze \ --ckpt outputs/finetune \ --test-csv data/dataset_test.csv \ --test-image-dir test_images --test-mask-dir test_masks \ --out outputs/finetune \ --operating-threshold 0.55 \ --min-wound-area-px 50 \ --use-3state

Options

--ckptPath to model checkpoint

--test-csvPath to test dataset CSV

--test-image-dirDirectory with test images

--test-mask-dirDirectory with test masks

--outOutput directory for analysis results

--operating-thresholdOperating threshold (0.0-1.0)

--min-wound-area-pxMinimum connected pixels to count as wound

--use-3stateEnable 3-state classification (WOUND/NO_WOUND/UNCERTAIN)

`rdn-woundseg predict`

Run inference on images without ground truth. Outputs mask PNGs and predictions.json.

Example Usage

# Single image rdn-woundseg predict \ --input path/to/image.png \ --ckpt outputs/finetune \ --out outputs/predictions \ --operating-threshold 0.55 # Directory of images rdn-woundseg predict \ --input path/to/images/ \ --ckpt outputs/finetune \ --out outputs/predictions \ --save-probs # also save probability heatmaps

Options

--inputInput image file or directory

--ckptPath to model checkpoint

--outOutput directory for predictions

--operating-thresholdOperating threshold for classification

--save-probsSave probability heatmaps

`rdn-woundseg gallery`

Create image grids for TP/FN/FP/TN buckets showing input, ground truth, prediction, and probability heatmap.

Example Usage

rdn-woundseg gallery \ --ckpt outputs/finetune \ --test-csv data/dataset_test.csv \ --test-image-dir test_images --test-mask-dir test_masks \ --out outputs/galleries \ --operating-threshold 0.55 \ --max-per-bucket 16

Options

--ckptPath to model checkpoint

--test-csvPath to test dataset CSV

--test-image-dirDirectory with test images

--test-mask-dirDirectory with test masks

--outOutput directory for gallery images

--operating-thresholdOperating threshold for classification

--max-per-bucketMax examples per TP/FN/FP/TN bucket

`rdn-woundseg export`

Export trained model to ONNX format. Bundles policy_lock.txt and model_meta.json.

Example Usage

# Export with schema validation rdn-woundseg export \ --ckpt outputs/finetune \ --out outputs/export \ --validate # Export with full runtime validation rdn-woundseg export \ --ckpt outputs/finetune \ --out outputs/export \ --validate --validate-runtime # Export without policy rdn-woundseg export \ --ckpt outputs/finetune \ --out outputs/export \ --skip-policy

Options

--ckptPath to model checkpoint

--outOutput directory for ONNX model

--validateSchema validation (requires [export] install)

--validate-runtimeCompare ONNX vs PyTorch outputs (requires [export,export-validate])

--skip-policyExport without policy_lock.txt

ONNX Export Output

Output Files

model.onnxONNX model (outputs probabilities [0, 1])
model_meta.jsonInput normalization and layout metadata
policy_lock.txtDecision thresholds (unless --skip-policy)

Input/Output Spec

# Input

image: float32 [batch, 3, 256, 256]

# normalized (mean=0.5, std=0.5)

# Output

probability: float32 [batch, 1, 256, 256]

# values in [0, 1]

Policy Parameters

Parameter	Description
operating_threshold	Probability threshold for wound detection
min_wound_area_px	Minimum connected pixels to count as wound
use_3state	Enable UNCERTAIN state for ambiguous cases
near_miss_delta	Margin for near-miss classification
detect_threshold	Lower threshold for UNCERTAIN detection

The policy_lock.txt file persists these values for consistent inference across deployments.

Data Format

CSV files must contain a new_id column with filenames (e.g., image001.png). Images and masks are stored in separate directories with matching filenames.

Tip: Version dataset CSVs (e.g., dataset_test_v1.csv) when labels, splits, or preprocessing change to preserve experiment provenance.