Training, evaluation and visualization

Run commands from the repository root after completing installation and resource setup. Select one GPU with CUDA_VISIBLE_DEVICES and use a new output directory for each run.

Training and checkpoints

Add --checkpoint to initialize model weights with a fresh optimizer:

CUDA_VISIBLE_DEVICES=0 uv run --no-sync python -m eghumannerf train \
    --checkpoint models/thu_fullsrdf.ckpt --train-subjects 0 --subjects 401 \
    --max-steps 10 --limit-val-batches 1 --output outputs/continued

Without --checkpoint, model training starts from initialization; the feature extractor and perceptual loss still use their pretrained ImageNet/VGG weights.

Use --resume with a checkpoint saved by this runner to restore model, optimizer and global step:

CUDA_VISIBLE_DEVICES=0 uv run --no-sync python -m eghumannerf train \
    --resume outputs/continued/last.ckpt --train-subjects 0 --subjects 401 \
    --max-steps 12 --limit-val-batches 1 --output outputs/resumed

--max-steps is the total step limit, including restored steps. This example continues from step 10 to step 12. Mid-epoch restoration restarts data loading rather than restoring the exact sampling cursor and random trajectory. --checkpoint and --resume are mutually exclusive.

Inspect a saved checkpoint with the inference command:

CUDA_VISIBLE_DEVICES=0 uv run --no-sync python -m eghumannerf infer \
    --checkpoint outputs/resumed/last.ckpt --subjects 401 --limit-val-batches 1 \
    --output outputs/resumed_inference

Evaluation options

infer and evaluate use the same rendering path. --limit-val-batches 1 selects a short run; omit the limit to process the configured split. --subjects selects THuman validation subjects. ZJU uses the subjects and cameras in config/experiment/zju_val.yaml.

The THuman metrics use the full image. ZJU provides both full-image and bounding-box metrics; keys ending in _b identify the bounding-box results. PIQ and the legacy skimage SSIM are separate metrics; see known issues for the latter.

Use repeated --set group.key=value arguments to override Hydra configuration values. The resolved configuration is saved with each run.

Outputs and logs

Path within the run directory	Contents
renders/	Input views, predictions, ground truth and comparison images
validation_samples.json	Per-batch names and per-image metrics
validation_summary.json	Aggregate metrics
resolved_config.yaml	Experiment configuration
training_steps.json, training_summary.json	Training diagnostics
last.ckpt	Saved training checkpoint

W&B runs offline; CSV and TensorBoard logs are written locally.

uv run --no-sync tensorboard --logdir outputs

Interactive result viewer

After running evaluation, generate an offline viewer for the saved images:

uv run --no-sync python scripts/build_review.py \
    --eval outputs/thuman_eval outputs/zju_eval \
    --output outputs/viewer

Open outputs/viewer/index.html in a browser. Add --train outputs/continued outputs/resumed to include training curves, or --video to export the first available ZJU subject/camera sequence.

Command reference and tests

uv run --no-sync python -m eghumannerf --help
uv run --no-sync python -m pytest -q