Add Docker build/run environment and simplify README for release

- Dockerfile: build the full PanDORA env on CUDA 11.7 (torch 2.0.1+cu117,
  pinned via a global PIP_CONSTRAINT so nothing upgrades torch to a
  driver-incompatible CUDA build), tiny-cuda-nn v1.6, pyequilib 0.5.6,
  numpy<2, viser 0.0.16, and Blender. Removes the unused COLMAP/SfM stack,
  caps compile parallelism (MAKE_JOBS), and sets PYTHONPATH for lantern_scripts.
- docker/build_and_run.sh: build the image (tunable CUDA_VERSION/MAKE_JOBS)
  and run the pipeline or an interactive GPU shell, mounting the repo + data.
- docker/run_pandora_pipeline.sh: fixed two-stage PanDORA training pipeline.
- docker/download_scenes.sh: download PanDORA dataset scenes by name.
- README.md: rewrite as a simple 4-step Docker quick start; point advanced
  users to README-pandora.md / README-hdrnerfacto.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
MrKarimiDandClaude Opus 4.8 committed 2026-08-02 15:31:38 -04:00
1 parent 287f56176b
commit 0197bd32ed
5 files changed
+480 -357

No files matched your search

+86
View File
@@ -0,0 +1,86 @@
#!/usr/bin/env bash
#
# Build the PanDORA docker image and run the fixed two-stage training pipeline
# inside it, with GPU access and the repo + dataset mounted at runtime.
#
# Usage:
# docker/build_and_run.sh [--rebuild] [--shell]
#
# --rebuild Rebuild the image from scratch (docker build --no-cache).
# --shell Drop into an interactive shell instead of running the pipeline.
#
# Common environment overrides:
# DATA_ROOT Host dir mounted to /data (default below)
# DATASET_DIR Container path to a *_ns scene (default below, under /data)
# STEP1_ITERS / STEP2_ITERS Lower for a quick smoke test.
set -euo pipefail
# --- Configuration -----------------------------------------------------------
IMAGE="${IMAGE:-pandora:latest}"
# Repo root = parent of this script's directory.
REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
# Host data directory that holds the processed scenes; mounted to /data.
DATA_ROOT="${DATA_ROOT:-/home-local2/${USER}.extra.nobkp/nerfstudio_ds}"
# Container-side path to the scene to train on (lives under /data).
DATASET_DIR="${DATASET_DIR:-/data/sample_scene/sample_scene_ns/}"
SHM_SIZE="${SHM_SIZE:-12gb}"
REBUILD=0
RUN_SHELL=0
for arg in "$@"; do
case "$arg" in
--rebuild) REBUILD=1 ;;
--shell) RUN_SHELL=1 ;;
-h|--help)
sed -n '2,20p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
exit 0 ;;
*) echo "Unknown argument: $arg" >&2; exit 1 ;;
esac
done
# --- Build -------------------------------------------------------------------
# Parallel compile jobs for the from-source builds (ceres/colmap/tcnn). Keep
# modest to avoid GCC OOM/segfault on the heavy Ceres template files; raise on
# high-RAM machines, e.g. MAKE_JOBS=8 docker/build_and_run.sh.
MAKE_JOBS="${MAKE_JOBS:-4}"
# CUDA toolkit version for the base image + torch/tcnn build. Must be <= the max
# CUDA version your host NVIDIA driver supports (see `nvidia-smi`). Default 11.7.1
# (torch 2.0.1+cu117) matches the known-working env and runs on older drivers
# (r450+). torch 2.0.1 also ships cu118 wheels if your driver is newer.
CUDA_VERSION="${CUDA_VERSION:-11.7.1}"
BUILD_ARGS=(-t "$IMAGE" -f "$REPO/Dockerfile"
--build-arg MAKE_JOBS="$MAKE_JOBS"
--build-arg CUDA_VERSION="$CUDA_VERSION"
"$REPO")
if [ "$REBUILD" -eq 1 ]; then
echo ">> Rebuilding image '$IMAGE' from scratch (--no-cache)..."
docker build --no-cache "${BUILD_ARGS[@]}"
else
echo ">> Building image '$IMAGE' (cached)..."
docker build "${BUILD_ARGS[@]}"
fi
# --- Run ---------------------------------------------------------------------
# Mount the repo onto the same path the image installed it editable (-e .), so
# the live code is used and the editable install stays valid.
DOCKER_RUN=(
docker run --rm -it
--gpus all
--shm-size="$SHM_SIZE"
-v "$REPO":/home/user/nerfstudio
-v "$DATA_ROOT":/data
-e DATASET_DIR="$DATASET_DIR"
-e EXPERIMENT_NAME="${EXPERIMENT_NAME:-pandora}"
-e STEP1_ITERS="${STEP1_ITERS:-60000}"
-e STEP2_ITERS="${STEP2_ITERS:-120000}"
-w /home/user/nerfstudio
"$IMAGE"
)
if [ "$RUN_SHELL" -eq 1 ]; then
echo ">> Launching interactive shell in '$IMAGE'..."
exec "${DOCKER_RUN[@]}" bash
else
echo ">> Running PanDORA pipeline in '$IMAGE' on DATASET_DIR=$DATASET_DIR ..."
exec "${DOCKER_RUN[@]}" bash docker/run_pandora_pipeline.sh
fi
+132
View File
@@ -0,0 +1,132 @@
#!/usr/bin/env bash
#
# Download PanDORA dataset scenes by name.
# Scenes are hosted as individual ZIP archives (~5 GB each) at:
# https://hdrdb-public.s3.valeria.science/pandora/<scene>.zip
# See: https://lvsn.github.io/pandora/dataset/index.html
#
# Usage:
# docker/download_scenes.sh <scene> [<scene> ...]
# docker/download_scenes.sh all
# docker/download_scenes.sh --list
#
# Options:
# --dest DIR Destination directory (default: $DATA_ROOT or /data)
# --keep-zip Keep the downloaded .zip after extracting (default: delete)
# --force Re-download / re-extract even if already present
# --list Print the available scene names and exit
#
# Downloads are resumable (curl -C -), so re-running continues an interrupted
# download. Extraction is skipped if the scene is already present unless --force.
set -euo pipefail
BASE_URL="https://hdrdb-public.s3.valeria.science/pandora"
# The 14 available scenes (exact zip basenames).
SCENES=(
auditorium
auditorium_dark
basement
blue_bedroom
classroom_no_windows
classroom_windows
clubhouse
coffee_room
lab_office
living_room
lobby
meeting_room
office
small_office
)
DEST="${DATA_ROOT:-/data}"
KEEP_ZIP=0
FORCE=0
REQUESTED=()
is_valid_scene() {
local s="$1"
for known in "${SCENES[@]}"; do
[ "$known" = "$s" ] && return 0
done
return 1
}
print_list() {
echo "Available PanDORA scenes (${#SCENES[@]}):"
for s in "${SCENES[@]}"; do echo " - $s"; done
}
# --- Parse arguments ---------------------------------------------------------
while [ $# -gt 0 ]; do
case "$1" in
--dest) DEST="$2"; shift 2 ;;
--keep-zip) KEEP_ZIP=1; shift ;;
--force) FORCE=1; shift ;;
--list) print_list; exit 0 ;;
-h|--help) sed -n '2,25p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
all) REQUESTED=("${SCENES[@]}"); shift ;;
-*) echo "Unknown option: $1" >&2; exit 1 ;;
*) REQUESTED+=("$1"); shift ;;
esac
done
if [ ${#REQUESTED[@]} -eq 0 ]; then
echo "ERROR: no scene(s) specified." >&2
echo >&2
print_list >&2
echo >&2
echo "Example: docker/download_scenes.sh meeting_room coffee_room" >&2
exit 1
fi
# Validate all requested names up front.
for s in "${REQUESTED[@]}"; do
if ! is_valid_scene "$s"; then
echo "ERROR: unknown scene '$s'." >&2
echo >&2
print_list >&2
exit 1
fi
done
mkdir -p "$DEST"
# --- Download + extract ------------------------------------------------------
for scene in "${REQUESTED[@]}"; do
marker="$DEST/.$scene.done"
zip="$DEST/$scene.zip"
url="$BASE_URL/$scene.zip"
echo "=================================================================="
echo "Scene: $scene"
echo " URL : $url"
echo " Dest: $DEST"
echo "=================================================================="
if [ -f "$marker" ] && [ "$FORCE" -eq 0 ]; then
echo "Already downloaded and extracted (marker $marker exists); skipping."
echo "Use --force to re-download."
continue
fi
echo "Downloading (resumable)..."
curl -L -f --retry 5 --retry-delay 5 -C - -o "$zip" "$url"
echo "Extracting..."
unzip -q -o "$zip" -d "$DEST"
touch "$marker"
if [ "$KEEP_ZIP" -eq 0 ]; then
echo "Removing archive $zip (use --keep-zip to keep)..."
rm -f "$zip"
fi
echo "Done: $scene"
done
echo "=================================================================="
echo "All requested scenes are ready under: $DEST"
echo "=================================================================="
+80
View File
@@ -0,0 +1,80 @@
#!/usr/bin/env bash
#
# Fixed PanDORA two-stage training pipeline (README "Option A").
# Runs inside the PanDORA docker image, but also works in an interactive shell.
#
# step 1 (lantern_steps 1) -> align_fast_to_well.py -> step 2 (lantern_steps 2)
#
# The dataset is provided via the DATASET_DIR env var (a processed *_ns scene).
# Deterministic --experiment-name / --timestamp make the step-1 outputs a known
# path that the align + step-2 commands can reference.
set -euo pipefail
# Make the repo root importable so `lantern_scripts` (used by nerfstudio's lantern
# processors/config) resolves even if PYTHONPATH isn't already set in the env.
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
export PYTHONPATH="${REPO_ROOT}:${PYTHONPATH:-}"
# --- Configuration (override via environment) --------------------------------
# Processed nerfstudio scene directory (contains transforms.json, images/, ...).
DATASET_DIR="${DATASET_DIR:-/data/sample_scene/sample_scene_ns/}"
EXPERIMENT_NAME="${EXPERIMENT_NAME:-pandora}"
# Iteration counts (lower these for a quick smoke test, e.g. STEP1_ITERS=200).
STEP1_ITERS="${STEP1_ITERS:-60000}"
STEP2_ITERS="${STEP2_ITERS:-120000}"
NUM_IMAGES_TO_SAMPLE="${NUM_IMAGES_TO_SAMPLE:-1800}"
STEP1_OUT="outputs/${EXPERIMENT_NAME}/PanDORA/step_1"
STEP2_OUT="outputs/${EXPERIMENT_NAME}/PanDORA/step_2"
if [ ! -d "$DATASET_DIR" ]; then
echo "ERROR: DATASET_DIR does not exist: $DATASET_DIR"
echo "Set DATASET_DIR to a processed nerfstudio scene (a *_ns directory)."
exit 1
fi
echo "=================================================================="
echo "PanDORA two-stage training"
echo " DATASET_DIR = $DATASET_DIR"
echo " EXPERIMENT_NAME = $EXPERIMENT_NAME"
echo " step 1 iters = $STEP1_ITERS -> $STEP1_OUT"
echo " step 2 iters = $STEP2_ITERS -> $STEP2_OUT"
echo "=================================================================="
# --- Step 1: train on two exposures (lantern step 1) -------------------------
echo "[1/3] Training PanDORA step 1..."
ns-train PanDORA \
--data "$DATASET_DIR" \
--experiment-name "$EXPERIMENT_NAME" \
--timestamp step_1 \
--output-dir outputs \
--pipeline.datamanager.train-num-images-to-sample-from "$NUM_IMAGES_TO_SAMPLE" \
--pipeline.model.lantern_steps 1 \
--pipeline.datamanager.pixel-sampler.lantern_steps 1 \
--max-num-iterations "$STEP1_ITERS" \
--viewer.quit-on-train-completion True
# --- Step 2a: align fast exposure to well exposure ---------------------------
echo "[2/3] Aligning fast exposure to well exposure..."
python lantern_scripts/align_fast_to_well.py \
--input_dir "$DATASET_DIR" \
--config "$STEP1_OUT/config.yml"
# --- Step 2b: train on aligned two exposures (lantern step 2) ----------------
echo "[3/3] Training PanDORA step 2..."
ns-train PanDORA \
--data "$DATASET_DIR" \
--experiment-name "$EXPERIMENT_NAME" \
--timestamp step_2 \
--output-dir outputs \
--pipeline.datamanager.train-num-images-to-sample-from "$NUM_IMAGES_TO_SAMPLE" \
--pipeline.model.lantern_steps 2 \
--pipeline.datamanager.pixel-sampler.lantern_steps 2 \
--pipeline.model.apply_mu_law False \
--load-dir "$STEP1_OUT/nerfstudio_models" \
--max-num-iterations "$STEP2_ITERS" \
--viewer.quit-on-train-completion True
echo "=================================================================="
echo "Done. Final model: $STEP2_OUT"
echo "=================================================================="