Deploy to HuggingFace Spaces

.flake8

@@ -0,0 +1,3 @@
+[flake8]
+max-line-length = 100
+ignore = E203 E741 W503 E731

.gitattributes

@@ -0,0 +1,6 @@
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.webm filter=lfs diff=lfs merge=lfs -text

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,81 @@
+# Copyright (c) Delanoe Pirard / Aedelon
+# Licensed under the Apache License, Version 2.0
+
+name: Bug Report
+description: Report a bug in awesome-depth-anything-3
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting! Please fill out the form below.
+
+        **Note**: For issues with the model itself (accuracy, artifacts), please report to the [upstream repository](https://github.com/ByteDance-Seed/Depth-Anything-3/issues).
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: What happened? What did you expect to happen?
+      placeholder: Describe the bug...
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal code or steps to reproduce the issue
+      placeholder: |
+        ```python
+        from depth_anything_3.api import DepthAnything3
+        model = DepthAnything3.from_pretrained("depth-anything/DA3-LARGE")
+        # ...
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Error Traceback
+      description: Full error message and traceback
+      render: shell
+      placeholder: Paste the full traceback here...
+
+  - type: input
+    id: version
+    attributes:
+      label: Package Version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: device
+    attributes:
+      label: Device
+      options:
+        - CUDA (NVIDIA GPU)
+        - MPS (Apple Silicon)
+        - CPU
+    validations:
+      required: true
+
+  - type: input
+    id: pytorch
+    attributes:
+      label: PyTorch Version
+      placeholder: "2.9.0"
+
+  - type: input
+    id: python
+    attributes:
+      label: Python Version
+      placeholder: "3.11"
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      placeholder: "macOS 14.0 / Ubuntu 22.04 / Windows 11"

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Upstream Repository
+    url: https://github.com/ByteDance-Seed/Depth-Anything-3/issues
+    about: For issues with the model architecture, accuracy, or training
+  - name: Discussions
+    url: https://github.com/Aedelon/awesome-depth-anything-3/discussions
+    about: Ask questions or share ideas

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,61 @@
+# Copyright (c) Delanoe Pirard / Aedelon
+# Licensed under the Apache License, Version 2.0
+
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for your suggestion!
+
+        **Note**: For model/architecture changes, please suggest to the [upstream repository](https://github.com/ByteDance-Seed/Depth-Anything-3/issues).
+        This fork focuses on optimization, deployment, and developer experience.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Use Case
+      description: What problem does this solve? What are you trying to do?
+      placeholder: I'm trying to...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How would you like it to work?
+      placeholder: It would be great if...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any other approaches you've considered?
+      placeholder: I also thought about...
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Category
+      options:
+        - Performance optimization
+        - CLI improvement
+        - API enhancement
+        - Documentation
+        - Testing
+        - CI/CD
+        - Other
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I would be willing to submit a PR for this feature

.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+# Copyright (c) Delanoe Pirard / Aedelon
+# Licensed under the Apache License, Version 2.0
+
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint with ruff
+        run: uv run ruff check src/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --tb=short -x
+        env:
+          PYTORCH_ENABLE_MPS_FALLBACK: "1"
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for hatch-vcs
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Build package
+        run: uv build
+
+      - name: Check package
+        run: uvx twine check dist/*

.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+# Copyright (c) Delanoe Pirard / Aedelon
+# Licensed under the Apache License, Version 2.0
+
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for hatch-vcs version
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Uses trusted publishing (OIDC) - no API token needed
+        # Configure at: https://pypi.org/manage/project/awesome-depth-anything-3/settings/publishing/

.gitignore

@@ -0,0 +1,63 @@
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+workspace/
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Test/coverage
+.coverage
+.pytest_cache/
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# Jupyter notebooks
+.ipynb_checkpoints/
+
+# IDE
+.vscode/
+.idea/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Project-specific
+gallery*/
+debug*/
+DA3HF*/
+gradio_workspace/
+eval_workspace/
+FILTER*/
+input_images*/
+*.gradio/
+.gradio/
+src/debug_main.py
+temp*.png
+/outputs
+
+# Model weights and large files
+*.pt
+*.pth
+*.ckpt
+*.safetensors
+!assets/**/*.pt
+
+# Logs
+*.log
+logs/

.pre-commit-config.yaml

@@ -0,0 +1,59 @@
+repos:
+  - repo: 'https://github.com/pre-commit/pre-commit-hooks'
+    rev: v4.5.0
+    hooks:
+      - id: check-added-large-files
+        args:
+          - '--maxkb=125'
+      - id: check-ast
+      - id: check-executables-have-shebangs
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-toml
+      - id: check-yaml
+      - id: debug-statements
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: no-commit-to-branch
+        args:
+          - '--branch'
+          - 'master'
+      - id: pretty-format-json
+        exclude: '.*\.ipynb$'
+        args:
+          - '--autofix'
+          - '--indent'
+          - '4'
+      - id: trailing-whitespace
+        args:
+          - '--markdown-linebreak-ext=md'
+  - repo: 'https://github.com/pycqa/isort'
+    rev: 5.13.2
+    hooks:
+      - id: isort
+        args:
+          - '--settings-file'
+          - 'pyproject.toml'
+          - '--filter-files'
+  - repo: 'https://github.com/asottile/pyupgrade'
+    rev: v3.15.2
+    hooks:
+      - id: pyupgrade
+        args: [--py38-plus, --keep-runtime-typing]
+  - repo: 'https://github.com/psf/black.git'
+    rev: 24.3.0
+    hooks:
+      - id: black
+        args:
+          - '--config=pyproject.toml'
+  - repo: 'https://github.com/PyCQA/flake8'
+    rev: 7.0.0
+    hooks:
+      - id: flake8
+        args:
+          - '--config=.flake8'
+  - repo: 'https://github.com/myint/autoflake'
+    rev: v1.4
+    hooks:
+      - id: autoflake
+        args: [ '--remove-all-unused-imports', '--recursive', '--remove-unused-variables', '--in-place']

BENCHMARKS.md

@@ -0,0 +1,217 @@
+# Benchmark Results
+
+Performance benchmarks comparing **awesome-depth-anything-3** (optimized fork) against the vanilla upstream implementation.
+
+> **Test Environment**: Apple Silicon (M-series), PyTorch 2.9.0
+> **Models**: da3-small, da3-base, da3-large, da3-giant
+
+---
+
+## Quick Summary
+
+| Feature | Improvement |
+|---------|-------------|
+| Model Loading (cached) | **200x faster** (0.8s → 0.005s) |
+| Inference (MPS, batch 4) | **1.14x faster** |
+| Cold Load Time | **1.7x faster** |
+| Memory Efficiency | Adaptive batching prevents OOM |
+
+---
+
+## 1. Awesome vs Upstream Comparison
+
+Direct comparison between this optimized fork and the original upstream repository.
+
+### MPS (Apple Silicon GPU)
+
+| Batch Size | Upstream | Awesome | Speedup | Notes |
+|------------|----------|---------|---------|-------|
+| 1 | 3.47 img/s | 3.50 img/s | 1.01x | Minimal overhead |
+| 2 | 3.64 img/s | 3.83 img/s | 1.05x | Batching benefits |
+| **4** | 3.32 img/s | 3.78 img/s | **1.14x** | Best improvement |
+
+#### Model Loading Performance
+
+| Metric | Upstream | Awesome | Speedup |
+|--------|----------|---------|---------|
+| Cold Load | 1.28s | 0.77s | **1.7x** |
+| Cached Load | N/A | 0.005s | **~200x** |
+
+The model caching system is the standout feature - after the first load, subsequent loads are essentially instant.
+
+### CPU
+
+| Batch Size | Upstream | Awesome | Speedup |
+|------------|----------|---------|---------|
+| 1 | 0.27 img/s | 0.31 img/s | 1.13x |
+| 2 | 0.24 img/s | 0.24 img/s | 1.00x |
+| 4 | 0.17 img/s | 0.16 img/s | 0.95x |
+
+> **Note**: CPU performance is similar between versions since GPU-specific optimizations don't apply. The slight regression at batch 4 is within measurement noise.
+
+---
+
+## 2. Model Performance by Size
+
+Throughput benchmarks on MPS (Apple Silicon) with 1280x720 input images.
+
+| Model | Parameters | Batch 1 | Batch 4 | Best Config |
+|-------|------------|---------|---------|-------------|
+| **da3-small** | ~25M | 22.2 img/s | 27.2 img/s | B=4 SDPA |
+| **da3-base** | ~100M | 10.7 img/s | 11.6 img/s | B=4 SDPA |
+| **da3-large** | ~335M | 3.8 img/s | 3.8 img/s | B=1-2 |
+| **da3-giant** | ~1.1B | 1.6 img/s | 1.2 img/s | B=1 |
+
+### Latency (single image)
+
+| Model | MPS | CPU | MPS Speedup |
+|-------|-----|-----|-------------|
+| da3-small | 45 ms | ~3,500 ms | ~78x |
+| da3-base | 94 ms | ~7,000 ms | ~74x |
+| da3-large | 265 ms | ~3,900 ms | ~15x |
+| da3-giant | 618 ms | N/A | - |
+
+---
+
+## 3. Preprocessing Pipeline
+
+### Strategy: Hybrid CPU/GPU
+
+On Apple Silicon, **CPU preprocessing is faster** than GPU (Kornia) due to optimized OpenCV/Accelerate routines. The overhead of MPS kernel launches exceeds the benefit for image transforms.
+
+| Resolution | CPU Time | GPU Time | Winner |
+|------------|----------|----------|--------|
+| 640x480 | 6.0 ms | N/A | CPU |
+| 1920x1080 | 18.7 ms | N/A | CPU |
+| 3840x2160 | 57.0 ms | N/A | CPU |
+
+> **Design Decision**: GPU preprocessing is automatically disabled on MPS. The GPU is reserved for model inference where it provides 15-78x speedup.
+
+### CUDA (NVIDIA)
+
+On CUDA, GPU preprocessing with NVJPEG provides significant benefits for JPEG decoding directly to GPU memory, eliminating CPU→GPU transfer overhead.
+
+---
+
+## 4. Attention Mechanisms
+
+Comparison between SDPA (Scaled Dot-Product Attention / Flash Attention) and manual attention implementation.
+
+### Per-Layer Performance
+
+| Config | SDPA | Manual | Speedup |
+|--------|------|--------|---------|
+| ViT-L 518px (MPS) | 2.21 ms | 1.86 ms | 0.8x |
+| ViT-L 1024px (MPS) | 9.91 ms | 5.87 ms | 0.6x |
+| ViT-L 518px (CPU) | 3.75 ms | 4.96 ms | 1.3x |
+| ViT-L 1024px (CPU) | 11.73 ms | 16.85 ms | 1.4x |
+
+> **Insight**: On MPS, manual attention is faster for ViT due to MPS's SDPA implementation overhead. On CPU, SDPA benefits from optimized BLAS operations.
+
+### End-to-End Impact
+
+| Model | SDPA | Manual | Best |
+|-------|------|--------|------|
+| da3-small | 21.8 img/s | 22.2 img/s | Manual |
+| da3-base | 9.8 img/s | 10.7 img/s | Manual |
+| da3-large | 3.8 img/s | 3.7 img/s | SDPA |
+| da3-giant | 1.6 img/s | 1.6 img/s | Tie |
+
+---
+
+## 5. Adaptive Batching
+
+The adaptive batching system dynamically adjusts batch size based on available GPU memory.
+
+### Test: 20 images with da3-large on MPS
+
+| Strategy | Total Time | Throughput | Batches Used |
+|----------|------------|------------|--------------|
+| Fixed B=1 | 5,612 ms | 3.6 img/s | [1,1,1...] |
+| Fixed B=2 | 5,514 ms | **3.6 img/s** | [2,2,2...] |
+| Fixed B=4 | 8,305 ms | 2.4 img/s | [4,4,4,4,4] |
+| Adaptive 85% | 5,637 ms | 3.5 img/s | [4,4,4...] |
+
+> **Recommendation**: For MPS with da3-large, fixed batch size of 2 provides optimal throughput. Adaptive batching is more valuable for:
+> - Variable input sizes
+> - Unknown GPU memory constraints
+> - Preventing OOM errors on smaller GPUs
+
+---
+
+## 6. Cross-Device Comparison
+
+### Inference Throughput (da3-large, batch=1)
+
+```
+MPS (Apple Silicon)  ███████████████��████████████████████████  3.7 img/s
+CPU                  ███                                       0.3 img/s
+```
+
+**MPS provides ~12x speedup over CPU** for da3-large inference.
+
+### Attention Layer (ViT-L 518px, SDPA)
+
+```
+MPS   ████████████████████████  2.40 ms
+CPU   ███████████████████████████████████████  3.75 ms
+```
+
+---
+
+## 7. Optimization Recommendations
+
+### For Apple Silicon (MPS)
+
+1. **Use model caching** - 200x faster subsequent loads
+2. **Batch size 2-4** for da3-small/base, **batch 1-2** for da3-large/giant
+3. **Let CPU handle preprocessing** - it's faster than MPS for image transforms
+4. **SDPA vs Manual**: Both are similar; SDPA slightly better for larger models
+
+### For NVIDIA CUDA
+
+1. **Enable GPU preprocessing** with NVJPEG for JPEG inputs
+2. **Use SDPA** (Flash Attention) - significant speedup
+3. **Larger batch sizes** benefit more from GPU parallelism
+4. **Adaptive batching** to maximize VRAM utilization
+
+### For CPU-only
+
+1. **Use smallest viable model** (da3-small: 22x faster than da3-giant)
+2. **Batch size 1** is optimal (memory bandwidth limited)
+3. **SDPA provides 1.3-1.4x speedup** on CPU
+
+---
+
+## Running Benchmarks
+
+```bash
+# Quick benchmark (fewer iterations)
+uv run python benchmarks/full_benchmark.py --quick
+
+# Full benchmark on specific device
+uv run python benchmarks/full_benchmark.py --device mps
+uv run python benchmarks/full_benchmark.py --device cuda
+uv run python benchmarks/full_benchmark.py --device cpu
+
+# Compare against upstream (requires upstream repo)
+uv run python benchmarks/comparative_benchmark.py --device all
+
+# Skip specific tests
+uv run python benchmarks/full_benchmark.py --skip-batching
+```
+
+---
+
+## Methodology
+
+- **Warmup**: 2 inference passes before timing
+- **Runs**: 3-5 iterations per configuration
+- **Synchronization**: `torch.mps.synchronize()` / `torch.cuda.synchronize()` for accurate GPU timing
+- **Memory cleanup**: `gc.collect()` + cache clearing between tests
+- **Input**: Synthetic 1280x720 RGB images (consistent across tests)
+
+---
+
+*Benchmarks last updated: December 2024*
+*Hardware: Apple Silicon (M-series) | Software: PyTorch 2.9.0*

CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-12-03
+
+### Added
+
+- **Model Caching**: ~200x faster model loading after first use via `ModelCache` singleton
+- **Adaptive Batching**: Automatic batch size optimization based on available GPU memory
+  - `batch_inference()` method with `batch_size="auto"` option
+  - `get_optimal_batch_size()` for memory-aware batch sizing
+- **CLI Batching Options**: `--batch-size`, `--max-batch-size`, `--target-memory-utilization`
+- **Apple Silicon Optimizations**: Smart CPU/GPU preprocessing selection for MPS
+- **GPU Preprocessing**: Kornia-based GPU preprocessing with NVJPEG support on CUDA
+- **Comprehensive Benchmarks**: Performance comparison scripts and documentation
+- **PyPI Package**: Published as `awesome-depth-anything-3`
+- **CI/CD**: GitHub Actions for testing, linting, and PyPI publishing
+- **HF Spaces Demo**: Interactive Gradio demo on Hugging Face
+- **Colab Tutorial**: Interactive notebook with examples
+
+### Changed
+
+- Package renamed from `depth-anything-3` to `awesome-depth-anything-3`
+- Improved error handling in CLI commands
+- Better logging with configurable levels
+
+### Credits
+
+This package is an optimized fork of [Depth Anything 3](https://github.com/ByteDance-Seed/Depth-Anything-3)
+by ByteDance. All model architecture and weights are their work. See README for full attribution.

CONTRIBUTING.md

@@ -0,0 +1,114 @@
+# Contributing to awesome-depth-anything-3
+
+Thank you for your interest in contributing! This document provides guidelines for contributing to this project.
+
+## Important Note
+
+This is an **optimized fork** of [Depth Anything 3](https://github.com/ByteDance-Seed/Depth-Anything-3) by ByteDance.
+
+- **Model/architecture changes** should be proposed to the [upstream repository](https://github.com/ByteDance-Seed/Depth-Anything-3)
+- **Optimization/deployment improvements** are welcome here
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/Aedelon/awesome-depth-anything-3.git
+cd awesome-depth-anything-3
+
+# Install with development dependencies (using uv)
+uv sync --extra dev
+
+# Or with pip
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+uv run pytest tests/ -v
+
+# Run specific test file
+uv run pytest tests/test_adaptive_batching.py -v
+
+# Run with coverage
+uv run pytest tests/ --cov=src/depth_anything_3
+```
+
+## Code Style
+
+We use `ruff` for linting and formatting:
+
+```bash
+# Check for issues
+uv run ruff check src/
+
+# Auto-fix issues
+uv run ruff check src/ --fix
+
+# Format code
+uv run ruff format src/
+```
+
+## Pre-commit Hooks
+
+We recommend using pre-commit hooks:
+
+```bash
+uv run pre-commit install
+uv run pre-commit run --all-files
+```
+
+## Pull Request Process
+
+1. **Fork** the repository
+2. **Create a branch** for your feature (`git checkout -b feature/amazing-feature`)
+3. **Make your changes** with clear, descriptive commits
+4. **Run tests** and linting
+5. **Update documentation** if needed
+6. **Push** to your fork and **open a Pull Request**
+
+### PR Guidelines
+
+- Keep PRs focused on a single change
+- Include tests for new functionality
+- Update CHANGELOG.md for user-facing changes
+- Ensure CI passes before requesting review
+
+## Types of Contributions Welcome
+
+### Highly Welcome
+
+- Performance optimizations
+- Bug fixes
+- Documentation improvements
+- Test coverage improvements
+- CI/CD improvements
+- Device compatibility (CUDA, MPS, CPU)
+
+### Discuss First
+
+- New CLI commands
+- API changes
+- New dependencies
+
+### Redirect to Upstream
+
+- Model architecture changes
+- Training code changes
+- New model variants
+
+## Reporting Issues
+
+When reporting bugs, please include:
+
+- Python version
+- PyTorch version
+- Device type (CUDA/MPS/CPU)
+- Minimal reproduction code
+- Full error traceback
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the Apache License 2.0.

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on
+      the same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 The Depth Anything 3 Team
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -0,0 +1,418 @@
+---
+title: Awesome Depth Anything 3
+emoji: 🌊
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 5.50.0
+app_file: app.py
+pinned: false
+license: apache-2.0
+short_description: Metric 3D reconstruction from images/video
+---
+
+<div align="center">
+
+# Awesome Depth Anything 3
+
+**Optimized fork of Depth Anything 3 with production-ready features**
+
+[![PyPI](https://img.shields.io/pypi/v/awesome-depth-anything-3)](https://pypi.org/project/awesome-depth-anything-3/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
+[![Tests](https://github.com/Aedelon/awesome-depth-anything-3/actions/workflows/ci.yml/badge.svg)](https://github.com/Aedelon/awesome-depth-anything-3/actions)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Aedelon/awesome-depth-anything-3/blob/main/notebooks/da3_tutorial.ipynb)
+[![HF Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/Aedelon/awesome-depth-anything-3)
+
+[Demo](https://huggingface.co/spaces/Aedelon/awesome-depth-anything-3) · [Tutorial](notebooks/da3_tutorial.ipynb) · [Benchmarks](BENCHMARKS.md) · [Original Paper](https://arxiv.org/abs/2511.10647)
+
+</div>
+
+---
+
+> **This is an optimized fork** of [Depth Anything 3](https://github.com/ByteDance-Seed/Depth-Anything-3) by ByteDance.
+> All credit for the model architecture, training, and research goes to the original authors (see [Credits](#-credits) below).
+> This fork focuses on **production optimization, developer experience, and ease of deployment**.
+
+## 🚀 What's New in This Fork
+
+| Feature | Description |
+|---------|-------------|
+| **Model Caching** | ~200x faster model loading after first use |
+| **Adaptive Batching** | Automatic batch size optimization based on GPU memory |
+| **PyPI Package** | `pip install awesome-depth-anything-3` |
+| **CLI Improvements** | Batch processing options, better error handling |
+| **Apple Silicon Optimized** | Smart CPU/GPU preprocessing for best MPS performance |
+| **Comprehensive Benchmarks** | Detailed performance analysis across devices |
+
+### Performance Improvements
+
+| Metric | Upstream | This Fork | Improvement |
+|--------|----------|-----------|-------------|
+| Cached model load | ~1s | ~5ms | **200x faster** |
+| Batch 4 inference (MPS) | 3.32 img/s | 3.78 img/s | **1.14x faster** |
+| Cold model load | 1.28s | 0.77s | **1.7x faster** |
+
+---
+
+<div align="center">
+
+## Original Depth Anything 3
+
+<h3>Recovering the Visual Space from Any Views</h3>
+
+[**Haotong Lin**](https://haotongl.github.io/)<sup>&ast;</sup> · [**Sili Chen**](https://github.com/SiliChen321)<sup>&ast;</sup> · [**Jun Hao Liew**](https://liewjunhao.github.io/)<sup>&ast;</sup> · [**Donny Y. Chen**](https://donydchen.github.io)<sup>&ast;</sup> · [**Zhenyu Li**](https://zhyever.github.io/) · [**Guang Shi**](https://scholar.google.com/citations?user=MjXxWbUAAAAJ&hl=en) · [**Jiashi Feng**](https://scholar.google.com.sg/citations?user=Q8iay0gAAAAJ&hl=en)
+<br>
+[**Bingyi Kang**](https://bingykang.github.io/)<sup>&ast;&dagger;</sup>
+
+&dagger;project lead&emsp;&ast;Equal Contribution
+
+<a href="https://arxiv.org/abs/2511.10647"><img src='https://img.shields.io/badge/arXiv-Depth Anything 3-red' alt='Paper PDF'></a>
+<a href='https://depth-anything-3.github.io'><img src='https://img.shields.io/badge/Project_Page-Depth Anything 3-green' alt='Project Page'></a>
+<a href='https://huggingface.co/spaces/depth-anything/Depth-Anything-3'><img src='https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Official Demo-blue'></a>
+
+</div>
+
+This work presents **Depth Anything 3 (DA3)**, a model that predicts spatially consistent geometry from
+arbitrary visual inputs, with or without known camera poses.
+In pursuit of minimal modeling, DA3 yields two key insights:
+- 💎 A **single plain transformer** (e.g., vanilla DINO encoder) is sufficient as a backbone without architectural specialization,
+- ✨ A singular **depth-ray representation** obviates the need for complex multi-task learning.
+
+🏆 DA3 significantly outperforms
+[DA2](https://github.com/DepthAnything/Depth-Anything-V2) for monocular depth estimation,
+and [VGGT](https://github.com/facebookresearch/vggt) for multi-view depth estimation and pose estimation.
+All models are trained exclusively on **public academic datasets**.
+
+<!-- <p align="center">
+  <img src="assets/images/da3_teaser.png" alt="Depth Anything 3" width="100%">
+</p> -->
+<p align="center">
+  <img src="assets/images/demo320-2.gif" alt="Depth Anything 3 - Left" width="70%">
+</p>
+<p align="center">
+  <img src="assets/images/da3_radar.png" alt="Depth Anything 3" width="100%">
+</p>
+
+
+## 📰 News
+- **30-11-2025:** Add [`use_ray_pose`](#use-ray-pose) and [`ref_view_strategy`](docs/funcs/ref_view_strategy.md) (reference view selection for multi-view inputs).   
+- **25-11-2025:** Add [Awesome DA3 Projects](#-awesome-da3-projects), a community-driven section featuring DA3-based applications.
+- **14-11-2025:** Paper, project page, code and models are all released.
+
+## ✨ Highlights
+
+### 🏆 Model Zoo
+We release three series of models, each tailored for specific use cases in visual geometry.
+
+- 🌟 **DA3 Main Series** (`DA3-Giant`, `DA3-Large`, `DA3-Base`, `DA3-Small`) These are our flagship foundation models, trained with a unified depth-ray representation. By varying the input configuration, a single model can perform a wide range of tasks:
+  + 🌊 **Monocular Depth Estimation**: Predicts a depth map from a single RGB image.
+  + 🌊 **Multi-View Depth Estimation**: Generates consistent depth maps from multiple images for high-quality fusion.
+  + 🎯 **Pose-Conditioned Depth Estimation**: Achieves superior depth consistency when camera poses are provided as input.
+  + 📷 **Camera Pose Estimation**:  Estimates camera extrinsics and intrinsics from one or more images.
+  + 🟡 **3D Gaussian Estimation**: Directly predicts 3D Gaussians, enabling high-fidelity novel view synthesis.
+
+- 📐 **DA3 Metric Series** (`DA3Metric-Large`) A specialized model fine-tuned for metric depth estimation in monocular settings, ideal for applications requiring real-world scale.
+
+- 🔍 **DA3 Monocular Series** (`DA3Mono-Large`). A dedicated model for high-quality relative monocular depth estimation. Unlike disparity-based models (e.g.,  [Depth Anything 2](https://github.com/DepthAnything/Depth-Anything-V2)), it directly predicts depth, resulting in superior geometric accuracy.
+
+🔗 Leveraging these available models, we developed a **nested series** (`DA3Nested-Giant-Large`). This series combines a any-view giant model with a metric model to reconstruct visual geometry at a real-world metric scale.
+
+### 🛠️ Codebase Features
+Our repository is designed to be a powerful and user-friendly toolkit for both practical application and future research.
+- 🎨 **Interactive Web UI & Gallery**: Visualize model outputs and compare results with an easy-to-use Gradio-based web interface.
+- ⚡ **Flexible Command-Line Interface (CLI)**: Powerful and scriptable CLI for batch processing and integration into custom workflows.
+- 💾 **Multiple Export Formats**: Save your results in various formats, including `glb`, `npz`, depth images, `ply`, 3DGS videos, etc, to seamlessly connect with other tools.
+- 🔧 **Extensible and Modular Design**: The codebase is structured to facilitate future research and the integration of new models or functionalities.
+
+
+<!-- ### 🎯 Visual Geometry Benchmark
+We introduce a new benchmark to rigorously evaluate geometry prediction models on three key tasks: pose estimation, 3D reconstruction, and visual rendering (novel view synthesis) quality.
+
+- 🔄 **Broad Model Compatibility**: Our benchmark is designed to be versatile, supporting the evaluation of various models, including both monocular and multi-view depth estimation approaches.
+- 🔬 **Robust Evaluation Pipeline**: We provide a standardized pipeline featuring RANSAC-based pose alignment, TSDF fusion for dense reconstruction, and a principled view selection strategy for novel view synthesis.
+- 📊 **Standardized Metrics**: Performance is measured using established metrics: AUC for pose accuracy, F1-score and Chamfer Distance for reconstruction, and PSNR/SSIM/LPIPS for rendering quality.
+- 🌍 **Diverse and Challenging Datasets**: The benchmark spans a wide range of scenes from datasets like HiRoom, ETH3D, DTU, 7Scenes, ScanNet++, DL3DV, Tanks and Temples, and MegaDepth. -->
+
+
+## 🚀 Quick Start
+
+### 📦 Installation
+
+```bash
+# From PyPI (recommended)
+pip install awesome-depth-anything-3
+
+# With Gradio web UI
+pip install awesome-depth-anything-3[app]
+
+# With CUDA optimizations (xformers + gsplat)
+pip install awesome-depth-anything-3[cuda]
+
+# Everything
+pip install awesome-depth-anything-3[all]
+```
+
+<details>
+<summary><b>Development installation</b></summary>
+
+```bash
+git clone https://github.com/Aedelon/awesome-depth-anything-3.git
+cd awesome-depth-anything-3
+pip install -e ".[dev]"
+
+# Optional: 3D Gaussian Splatting head
+pip install --no-build-isolation git+https://github.com/nerfstudio-project/gsplat.git@0b4dddf
+```
+</details>
+
+For detailed model information, please refer to the [Model Cards](#-model-cards) section below.
+
+### 💻 Basic Usage
+
+```python
+import glob, os, torch
+from depth_anything_3.api import DepthAnything3
+device = torch.device("cuda")
+model = DepthAnything3.from_pretrained("depth-anything/DA3NESTED-GIANT-LARGE")
+model = model.to(device=device)
+example_path = "assets/examples/SOH"
+images = sorted(glob.glob(os.path.join(example_path, "*.png")))
+prediction = model.inference(
+    images,
+)
+# prediction.processed_images : [N, H, W, 3] uint8   array
+print(prediction.processed_images.shape)
+# prediction.depth            : [N, H, W]    float32 array
+print(prediction.depth.shape)  
+# prediction.conf             : [N, H, W]    float32 array
+print(prediction.conf.shape)  
+# prediction.extrinsics       : [N, 3, 4]    float32 array # opencv w2c or colmap format
+print(prediction.extrinsics.shape)
+# prediction.intrinsics       : [N, 3, 3]    float32 array
+print(prediction.intrinsics.shape)
+```
+
+```bash
+
+export MODEL_DIR=depth-anything/DA3NESTED-GIANT-LARGE
+# This can be a Hugging Face repository or a local directory
+# If you encounter network issues, consider using the following mirror: export HF_ENDPOINT=https://hf-mirror.com
+# Alternatively, you can download the model directly from Hugging Face
+export GALLERY_DIR=workspace/gallery
+mkdir -p $GALLERY_DIR
+
+# CLI auto mode with backend reuse
+da3 backend --model-dir ${MODEL_DIR} --gallery-dir ${GALLERY_DIR} # Cache model to gpu
+da3 auto assets/examples/SOH \
+    --export-format glb \
+    --export-dir ${GALLERY_DIR}/TEST_BACKEND/SOH \
+    --use-backend
+
+# CLI video processing with feature visualization
+da3 video assets/examples/robot_unitree.mp4 \
+    --fps 15 \
+    --use-backend \
+    --export-dir ${GALLERY_DIR}/TEST_BACKEND/robo \
+    --export-format glb-feat_vis \
+    --feat-vis-fps 15 \
+    --process-res-method lower_bound_resize \
+    --export-feat "11,21,31"
+
+# CLI auto mode without backend reuse
+da3 auto assets/examples/SOH \
+    --export-format glb \
+    --export-dir ${GALLERY_DIR}/TEST_CLI/SOH \
+    --model-dir ${MODEL_DIR}
+
+```
+
+The model architecture is defined in [`DepthAnything3Net`](src/depth_anything_3/model/da3.py), and specified with a Yaml config file located at [`src/depth_anything_3/configs`](src/depth_anything_3/configs). The input and output processing are handled by [`DepthAnything3`](src/depth_anything_3/api.py). To customize the model architecture, simply create a new config file (*e.g.*, `path/to/new/config`) as:
+
+```yaml
+__object__:
+  path: depth_anything_3.model.da3
+  name: DepthAnything3Net
+  args: as_params
+
+net:
+  __object__:
+    path: depth_anything_3.model.dinov2.dinov2
+    name: DinoV2
+    args: as_params
+
+  name: vitb
+  out_layers: [5, 7, 9, 11]
+  alt_start: 4
+  qknorm_start: 4
+  rope_start: 4
+  cat_token: True
+
+head:
+  __object__:
+    path: depth_anything_3.model.dualdpt
+    name: DualDPT
+    args: as_params
+
+  dim_in: &head_dim_in 1536
+  output_dim: 2
+  features: &head_features 128
+  out_channels: &head_out_channels [96, 192, 384, 768]
+```
+
+Then, the model can be created with the following code snippet.
+```python
+from depth_anything_3.cfg import create_object, load_config
+
+Model = create_object(load_config("path/to/new/config"))
+```
+
+
+
+## 📚 Useful Documentation
+
+- 🖥️ [Command Line Interface](docs/CLI.md)
+- 📑 [Python API](docs/API.md)
+<!-- - 🏁 [Visual Geometry Benchmark](docs/BENCHMARK.md) -->
+
+## 🗂️ Model Cards
+
+Generally, you should observe that DA3-LARGE achieves comparable results to VGGT.
+
+The Nested series uses an Any-view model to estimate pose and depth, and a monocular metric depth estimator for scaling. 
+
+| 🗃️ Model Name                  | 📏 Params | 📊 Rel. Depth | 📷 Pose Est. | 🧭 Pose Cond. | 🎨 GS | 📐 Met. Depth | ☁️ Sky Seg | 📄 License     |
+|-------------------------------|-----------|---------------|--------------|---------------|-------|---------------|-----------|----------------|
+| **Nested** | | | | | | | | |
+| [DA3NESTED-GIANT-LARGE](https://huggingface.co/depth-anything/DA3NESTED-GIANT-LARGE)  | 1.40B     | ✅             | ✅            | ✅             | ✅     | ✅             | ✅         | CC BY-NC 4.0   |
+| **Any-view Model** | | | | | | | | |
+| [DA3-GIANT](https://huggingface.co/depth-anything/DA3-GIANT)                     | 1.15B     | ✅             | ✅            | ✅             | ✅     |               |           | CC BY-NC 4.0   |
+| [DA3-LARGE](https://huggingface.co/depth-anything/DA3-LARGE)                     | 0.35B     | ✅             | ✅            | ✅             |       |               |           | CC BY-NC 4.0     |
+| [DA3-BASE](https://huggingface.co/depth-anything/DA3-BASE)                     | 0.12B     | ✅             | ✅            | ✅             |       |               |           | Apache 2.0     |
+| [DA3-SMALL](https://huggingface.co/depth-anything/DA3-SMALL)                     | 0.08B     | ✅             | ✅            | ✅             |       |               |           | Apache 2.0     |
+|                               |           |               |              |               |               |       |           |                |
+| **Monocular Metric Depth** | | | | | | | | |
+| [DA3METRIC-LARGE](https://huggingface.co/depth-anything/DA3METRIC-LARGE)              | 0.35B     | ✅             |              |               |       | ✅             | ✅         | Apache 2.0     |
+|                               |           |               |              |               |               |       |           |                |
+| **Monocular Depth** | | | | | | | | |
+| [DA3MONO-LARGE](https://huggingface.co/depth-anything/DA3MONO-LARGE)                | 0.35B     | ✅             |              |               |               |       | ✅         | Apache 2.0     |
+
+
+## ⚡ Performance Benchmarks
+
+Inference throughput measured on Apple Silicon (MPS) with PyTorch 2.9.0. For detailed benchmarks, see [BENCHMARKS.md](BENCHMARKS.md).
+
+### Apple Silicon (MPS) - Batch Size 1
+
+| Model | Latency | Throughput |
+|-------|---------|------------|
+| DA3-Small | 46 ms | **22 img/s** |
+| DA3-Base | 93 ms | **11 img/s** |
+| DA3-Large | 265 ms | **3.8 img/s** |
+| DA3-Giant | 618 ms | **1.6 img/s** |
+
+### Cross-Device Comparison (DA3-Large)
+
+| Device | Throughput | vs CPU |
+|--------|------------|--------|
+| CPU | 0.3 img/s | 1.0x |
+| Apple Silicon (MPS) | 3.8 img/s | **13x** |
+| NVIDIA L4 (CUDA) | 10.3 img/s | **34x** |
+
+### Batch Processing
+
+```python
+from depth_anything_3.api import DepthAnything3
+
+model = DepthAnything3.from_pretrained("depth-anything/DA3-LARGE")
+
+# Adaptive batching (recommended for large image sets)
+results = model.batch_inference(
+    images=image_paths,
+    batch_size="auto",  # Automatically selects optimal batch size
+    target_memory_utilization=0.85,
+)
+
+# Fixed batch size
+results = model.batch_inference(
+    images=image_paths,
+    batch_size=4,
+)
+```
+
+> See [BENCHMARKS.md](BENCHMARKS.md) for comprehensive benchmarks including preprocessing, attention mechanisms, and adaptive batching strategies.
+
+
+## ❓ FAQ
+
+- **Monocular Metric Depth**: To obtain metric depth in meters from `DA3METRIC-LARGE`, use `metric_depth = focal * net_output / 300.`, where `focal` is the focal length in pixels (typically the average of fx and fy from the camera intrinsic matrix K). Note that the output from `DA3NESTED-GIANT-LARGE` is already in meters.
+
+- <a id="use-ray-pose"></a>**Ray Head (`use_ray_pose`)**:  Our API and CLI support `use_ray_pose` arg, which means that the model will derive camera pose from ray head, which is generally slightly slower, but more accurate. Note that the default is `False` for faster inference speed. 
+  <details>
+  <summary>AUC3 Results for DA3NESTED-GIANT-LARGE</summary>
+  
+  | Model | HiRoom | ETH3D | DTU | 7Scenes | ScanNet++ | 
+  |-------|------|-------|-----|---------|-----------|
+  | `ray_head` | 84.4 | 52.6 | 93.9 | 29.5 | 89.4 |
+  | `cam_head` | 80.3 | 48.4 | 94.1 | 28.5 | 85.0 |
+
+  </details>
+
+
+
+
+- **Older GPUs without XFormers support**: See [Issue #11](https://github.com/ByteDance-Seed/Depth-Anything-3/issues/11). Thanks to [@S-Mahoney](https://github.com/S-Mahoney) for the solution!
+
+
+## 🏢 Awesome DA3 Projects
+
+A community-curated list of Depth Anything 3 integrations across 3D tools, creative pipelines, robotics, and web/VR viewers, including but not limited to these. You are welcome to submit your DA3-based project via PR, and we will review and feature it if applicable.
+
+- [DA3-blender](https://github.com/xy-gao/DA3-blender): Blender addon for DA3-based 3D reconstruction from a set of images. 
+
+- [ComfyUI-DepthAnythingV3](https://github.com/PozzettiAndrea/ComfyUI-DepthAnythingV3): ComfyUI nodes for Depth Anything 3, supporting single/multi-view and video-consistent depth with optional point‑cloud export.
+
+- [DA3-ROS2-Wrapper](https://github.com/GerdsenAI/GerdsenAI-Depth-Anything-3-ROS2-Wrapper): Real-time DA3 depth in ROS2 with multi-camera support. 
+
+- [VideoDepthViewer3D](https://github.com/amariichi/VideoDepthViewer3D): Streaming videos with DA3 metric depth to a Three.js/WebXR 3D viewer for VR/stereo playback.
+
+
+## 📝 Credits
+
+### Original Authors
+
+This package is built on top of **Depth Anything 3**, created by the ByteDance Seed team:
+
+- [Haotong Lin](https://haotongl.github.io/), [Sili Chen](https://github.com/SiliChen321), [Jun Hao Liew](https://liewjunhao.github.io/), [Donny Y. Chen](https://donydchen.github.io), [Zhenyu Li](https://zhyever.github.io/), [Guang Shi](https://scholar.google.com/citations?user=MjXxWbUAAAAJ), [Jiashi Feng](https://scholar.google.com.sg/citations?user=Q8iay0gAAAAJ), [Bingyi Kang](https://bingykang.github.io/)
+
+All model weights, architecture, and core algorithms are their work. This fork only adds production optimizations and deployment tooling.
+
+### Fork Maintainer
+
+This optimized fork is maintained by [Delanoe Pirard (Aedelon)](https://github.com/Aedelon).
+
+Contributions:
+- Model caching system
+- Adaptive batching
+- Apple Silicon (MPS) optimizations
+- PyPI packaging and CI/CD
+- Comprehensive benchmarking
+
+### Citation
+
+If you use Depth Anything 3 in your research, please cite the original paper:
+
+```bibtex
+@article{depthanything3,
+  title={Depth Anything 3: Recovering the visual space from any views},
+  author={Haotong Lin and Sili Chen and Jun Hao Liew and Donny Y. Chen and Zhenyu Li and Guang Shi and Jiashi Feng and Bingyi Kang},
+  journal={arXiv preprint arXiv:2511.10647},
+  year={2025}
+}
+```
+
+If you specifically use features from this fork (caching, batching, MPS optimizations), you may additionally reference:
+
+```
+awesome-depth-anything-3: https://github.com/Aedelon/awesome-depth-anything-3
+```

README.md.original

@@ -0,0 +1,405 @@
+<div align="center">
+
+# Awesome Depth Anything 3
+
+**Optimized fork of Depth Anything 3 with production-ready features**
+
+[![PyPI](https://img.shields.io/pypi/v/awesome-depth-anything-3)](https://pypi.org/project/awesome-depth-anything-3/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
+[![Tests](https://github.com/Aedelon/awesome-depth-anything-3/actions/workflows/ci.yml/badge.svg)](https://github.com/Aedelon/awesome-depth-anything-3/actions)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Aedelon/awesome-depth-anything-3/blob/main/notebooks/da3_tutorial.ipynb)
+[![HF Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/Aedelon/awesome-depth-anything-3)
+
+[Demo](https://huggingface.co/spaces/Aedelon/awesome-depth-anything-3) · [Tutorial](notebooks/da3_tutorial.ipynb) · [Benchmarks](BENCHMARKS.md) · [Original Paper](https://arxiv.org/abs/2511.10647)
+
+</div>
+
+---
+
+> **This is an optimized fork** of [Depth Anything 3](https://github.com/ByteDance-Seed/Depth-Anything-3) by ByteDance.
+> All credit for the model architecture, training, and research goes to the original authors (see [Credits](#-credits) below).
+> This fork focuses on **production optimization, developer experience, and ease of deployment**.
+
+## 🚀 What's New in This Fork
+
+| Feature | Description |
+|---------|-------------|
+| **Model Caching** | ~200x faster model loading after first use |
+| **Adaptive Batching** | Automatic batch size optimization based on GPU memory |
+| **PyPI Package** | `pip install awesome-depth-anything-3` |
+| **CLI Improvements** | Batch processing options, better error handling |
+| **Apple Silicon Optimized** | Smart CPU/GPU preprocessing for best MPS performance |
+| **Comprehensive Benchmarks** | Detailed performance analysis across devices |
+
+### Performance Improvements
+
+| Metric | Upstream | This Fork | Improvement |
+|--------|----------|-----------|-------------|
+| Cached model load | ~1s | ~5ms | **200x faster** |
+| Batch 4 inference (MPS) | 3.32 img/s | 3.78 img/s | **1.14x faster** |
+| Cold model load | 1.28s | 0.77s | **1.7x faster** |
+
+---
+
+<div align="center">
+
+## Original Depth Anything 3
+
+<h3>Recovering the Visual Space from Any Views</h3>
+
+[**Haotong Lin**](https://haotongl.github.io/)<sup>&ast;</sup> · [**Sili Chen**](https://github.com/SiliChen321)<sup>&ast;</sup> · [**Jun Hao Liew**](https://liewjunhao.github.io/)<sup>&ast;</sup> · [**Donny Y. Chen**](https://donydchen.github.io)<sup>&ast;</sup> · [**Zhenyu Li**](https://zhyever.github.io/) · [**Guang Shi**](https://scholar.google.com/citations?user=MjXxWbUAAAAJ&hl=en) · [**Jiashi Feng**](https://scholar.google.com.sg/citations?user=Q8iay0gAAAAJ&hl=en)
+<br>
+[**Bingyi Kang**](https://bingykang.github.io/)<sup>&ast;&dagger;</sup>
+
+&dagger;project lead&emsp;&ast;Equal Contribution
+
+<a href="https://arxiv.org/abs/2511.10647"><img src='https://img.shields.io/badge/arXiv-Depth Anything 3-red' alt='Paper PDF'></a>
+<a href='https://depth-anything-3.github.io'><img src='https://img.shields.io/badge/Project_Page-Depth Anything 3-green' alt='Project Page'></a>
+<a href='https://huggingface.co/spaces/depth-anything/Depth-Anything-3'><img src='https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Official Demo-blue'></a>
+
+</div>
+
+This work presents **Depth Anything 3 (DA3)**, a model that predicts spatially consistent geometry from
+arbitrary visual inputs, with or without known camera poses.
+In pursuit of minimal modeling, DA3 yields two key insights:
+- 💎 A **single plain transformer** (e.g., vanilla DINO encoder) is sufficient as a backbone without architectural specialization,
+- ✨ A singular **depth-ray representation** obviates the need for complex multi-task learning.
+
+🏆 DA3 significantly outperforms
+[DA2](https://github.com/DepthAnything/Depth-Anything-V2) for monocular depth estimation,
+and [VGGT](https://github.com/facebookresearch/vggt) for multi-view depth estimation and pose estimation.
+All models are trained exclusively on **public academic datasets**.
+
+<!-- <p align="center">
+  <img src="assets/images/da3_teaser.png" alt="Depth Anything 3" width="100%">
+</p> -->
+<p align="center">
+  <img src="assets/images/demo320-2.gif" alt="Depth Anything 3 - Left" width="70%">
+</p>
+<p align="center">
+  <img src="assets/images/da3_radar.png" alt="Depth Anything 3" width="100%">
+</p>
+
+
+## 📰 News
+- **30-11-2025:** Add [`use_ray_pose`](#use-ray-pose) and [`ref_view_strategy`](docs/funcs/ref_view_strategy.md) (reference view selection for multi-view inputs).   
+- **25-11-2025:** Add [Awesome DA3 Projects](#-awesome-da3-projects), a community-driven section featuring DA3-based applications.
+- **14-11-2025:** Paper, project page, code and models are all released.
+
+## ✨ Highlights
+
+### 🏆 Model Zoo
+We release three series of models, each tailored for specific use cases in visual geometry.
+
+- 🌟 **DA3 Main Series** (`DA3-Giant`, `DA3-Large`, `DA3-Base`, `DA3-Small`) These are our flagship foundation models, trained with a unified depth-ray representation. By varying the input configuration, a single model can perform a wide range of tasks:
+  + 🌊 **Monocular Depth Estimation**: Predicts a depth map from a single RGB image.
+  + 🌊 **Multi-View Depth Estimation**: Generates consistent depth maps from multiple images for high-quality fusion.
+  + 🎯 **Pose-Conditioned Depth Estimation**: Achieves superior depth consistency when camera poses are provided as input.
+  + 📷 **Camera Pose Estimation**:  Estimates camera extrinsics and intrinsics from one or more images.
+  + 🟡 **3D Gaussian Estimation**: Directly predicts 3D Gaussians, enabling high-fidelity novel view synthesis.
+
+- 📐 **DA3 Metric Series** (`DA3Metric-Large`) A specialized model fine-tuned for metric depth estimation in monocular settings, ideal for applications requiring real-world scale.
+
+- 🔍 **DA3 Monocular Series** (`DA3Mono-Large`). A dedicated model for high-quality relative monocular depth estimation. Unlike disparity-based models (e.g.,  [Depth Anything 2](https://github.com/DepthAnything/Depth-Anything-V2)), it directly predicts depth, resulting in superior geometric accuracy.
+
+🔗 Leveraging these available models, we developed a **nested series** (`DA3Nested-Giant-Large`). This series combines a any-view giant model with a metric model to reconstruct visual geometry at a real-world metric scale.
+
+### 🛠️ Codebase Features
+Our repository is designed to be a powerful and user-friendly toolkit for both practical application and future research.
+- 🎨 **Interactive Web UI & Gallery**: Visualize model outputs and compare results with an easy-to-use Gradio-based web interface.
+- ⚡ **Flexible Command-Line Interface (CLI)**: Powerful and scriptable CLI for batch processing and integration into custom workflows.
+- 💾 **Multiple Export Formats**: Save your results in various formats, including `glb`, `npz`, depth images, `ply`, 3DGS videos, etc, to seamlessly connect with other tools.
+- 🔧 **Extensible and Modular Design**: The codebase is structured to facilitate future research and the integration of new models or functionalities.
+
+
+<!-- ### 🎯 Visual Geometry Benchmark
+We introduce a new benchmark to rigorously evaluate geometry prediction models on three key tasks: pose estimation, 3D reconstruction, and visual rendering (novel view synthesis) quality.
+
+- 🔄 **Broad Model Compatibility**: Our benchmark is designed to be versatile, supporting the evaluation of various models, including both monocular and multi-view depth estimation approaches.
+- 🔬 **Robust Evaluation Pipeline**: We provide a standardized pipeline featuring RANSAC-based pose alignment, TSDF fusion for dense reconstruction, and a principled view selection strategy for novel view synthesis.
+- 📊 **Standardized Metrics**: Performance is measured using established metrics: AUC for pose accuracy, F1-score and Chamfer Distance for reconstruction, and PSNR/SSIM/LPIPS for rendering quality.
+- 🌍 **Diverse and Challenging Datasets**: The benchmark spans a wide range of scenes from datasets like HiRoom, ETH3D, DTU, 7Scenes, ScanNet++, DL3DV, Tanks and Temples, and MegaDepth. -->
+
+
+## 🚀 Quick Start
+
+### 📦 Installation
+
+```bash
+# From PyPI (recommended)
+pip install awesome-depth-anything-3
+
+# With Gradio web UI
+pip install awesome-depth-anything-3[app]
+
+# With CUDA optimizations (xformers + gsplat)
+pip install awesome-depth-anything-3[cuda]
+
+# Everything
+pip install awesome-depth-anything-3[all]
+```
+
+<details>
+<summary><b>Development installation</b></summary>
+
+```bash
+git clone https://github.com/Aedelon/awesome-depth-anything-3.git
+cd awesome-depth-anything-3
+pip install -e ".[dev]"
+
+# Optional: 3D Gaussian Splatting head
+pip install --no-build-isolation git+https://github.com/nerfstudio-project/gsplat.git@0b4dddf
+```
+</details>
+
+For detailed model information, please refer to the [Model Cards](#-model-cards) section below.
+
+### 💻 Basic Usage
+
+```python
+import glob, os, torch
+from depth_anything_3.api import DepthAnything3
+device = torch.device("cuda")
+model = DepthAnything3.from_pretrained("depth-anything/DA3NESTED-GIANT-LARGE")
+model = model.to(device=device)
+example_path = "assets/examples/SOH"
+images = sorted(glob.glob(os.path.join(example_path, "*.png")))
+prediction = model.inference(
+    images,
+)
+# prediction.processed_images : [N, H, W, 3] uint8   array
+print(prediction.processed_images.shape)
+# prediction.depth            : [N, H, W]    float32 array
+print(prediction.depth.shape)  
+# prediction.conf             : [N, H, W]    float32 array
+print(prediction.conf.shape)  
+# prediction.extrinsics       : [N, 3, 4]    float32 array # opencv w2c or colmap format
+print(prediction.extrinsics.shape)
+# prediction.intrinsics       : [N, 3, 3]    float32 array
+print(prediction.intrinsics.shape)
+```
+
+```bash
+
+export MODEL_DIR=depth-anything/DA3NESTED-GIANT-LARGE
+# This can be a Hugging Face repository or a local directory
+# If you encounter network issues, consider using the following mirror: export HF_ENDPOINT=https://hf-mirror.com
+# Alternatively, you can download the model directly from Hugging Face
+export GALLERY_DIR=workspace/gallery
+mkdir -p $GALLERY_DIR
+
+# CLI auto mode with backend reuse
+da3 backend --model-dir ${MODEL_DIR} --gallery-dir ${GALLERY_DIR} # Cache model to gpu
+da3 auto assets/examples/SOH \
+    --export-format glb \
+    --export-dir ${GALLERY_DIR}/TEST_BACKEND/SOH \
+    --use-backend
+
+# CLI video processing with feature visualization
+da3 video assets/examples/robot_unitree.mp4 \
+    --fps 15 \
+    --use-backend \
+    --export-dir ${GALLERY_DIR}/TEST_BACKEND/robo \
+    --export-format glb-feat_vis \
+    --feat-vis-fps 15 \
+    --process-res-method lower_bound_resize \
+    --export-feat "11,21,31"
+
+# CLI auto mode without backend reuse
+da3 auto assets/examples/SOH \
+    --export-format glb \
+    --export-dir ${GALLERY_DIR}/TEST_CLI/SOH \
+    --model-dir ${MODEL_DIR}
+
+```
+
+The model architecture is defined in [`DepthAnything3Net`](src/depth_anything_3/model/da3.py), and specified with a Yaml config file located at [`src/depth_anything_3/configs`](src/depth_anything_3/configs). The input and output processing are handled by [`DepthAnything3`](src/depth_anything_3/api.py). To customize the model architecture, simply create a new config file (*e.g.*, `path/to/new/config`) as:
+
+```yaml
+__object__:
+  path: depth_anything_3.model.da3
+  name: DepthAnything3Net
+  args: as_params
+
+net:
+  __object__:
+    path: depth_anything_3.model.dinov2.dinov2
+    name: DinoV2
+    args: as_params
+
+  name: vitb
+  out_layers: [5, 7, 9, 11]
+  alt_start: 4
+  qknorm_start: 4
+  rope_start: 4
+  cat_token: True
+
+head:
+  __object__:
+    path: depth_anything_3.model.dualdpt
+    name: DualDPT
+    args: as_params
+
+  dim_in: &head_dim_in 1536
+  output_dim: 2
+  features: &head_features 128
+  out_channels: &head_out_channels [96, 192, 384, 768]
+```
+
+Then, the model can be created with the following code snippet.
+```python
+from depth_anything_3.cfg import create_object, load_config
+
+Model = create_object(load_config("path/to/new/config"))
+```
+
+
+
+## 📚 Useful Documentation
+
+- 🖥️ [Command Line Interface](docs/CLI.md)
+- 📑 [Python API](docs/API.md)
+<!-- - 🏁 [Visual Geometry Benchmark](docs/BENCHMARK.md) -->
+
+## 🗂️ Model Cards
+
+Generally, you should observe that DA3-LARGE achieves comparable results to VGGT.
+
+The Nested series uses an Any-view model to estimate pose and depth, and a monocular metric depth estimator for scaling. 
+
+| 🗃️ Model Name                  | 📏 Params | 📊 Rel. Depth | 📷 Pose Est. | 🧭 Pose Cond. | 🎨 GS | 📐 Met. Depth | ☁️ Sky Seg | 📄 License     |
+|-------------------------------|-----------|---------------|--------------|---------------|-------|---------------|-----------|----------------|
+| **Nested** | | | | | | | | |
+| [DA3NESTED-GIANT-LARGE](https://huggingface.co/depth-anything/DA3NESTED-GIANT-LARGE)  | 1.40B     | ✅             | ✅            | ✅             | ✅     | ✅             | ✅         | CC BY-NC 4.0   |
+| **Any-view Model** | | | | | | | | |
+| [DA3-GIANT](https://huggingface.co/depth-anything/DA3-GIANT)                     | 1.15B     | ✅             | ✅            | ✅             | ✅     |               |           | CC BY-NC 4.0   |
+| [DA3-LARGE](https://huggingface.co/depth-anything/DA3-LARGE)                     | 0.35B     | ✅             | ✅            | ✅             |       |               |           | CC BY-NC 4.0     |
+| [DA3-BASE](https://huggingface.co/depth-anything/DA3-BASE)                     | 0.12B     | ✅             | ✅            | ✅             |       |               |           | Apache 2.0     |
+| [DA3-SMALL](https://huggingface.co/depth-anything/DA3-SMALL)                     | 0.08B     | ✅             | ✅            | ✅             |       |               |           | Apache 2.0     |
+|                               |           |               |              |               |               |       |           |                |
+| **Monocular Metric Depth** | | | | | | | | |
+| [DA3METRIC-LARGE](https://huggingface.co/depth-anything/DA3METRIC-LARGE)              | 0.35B     | ✅             |              |               |       | ✅             | ✅         | Apache 2.0     |
+|                               |           |               |              |               |               |       |           |                |
+| **Monocular Depth** | | | | | | | | |
+| [DA3MONO-LARGE](https://huggingface.co/depth-anything/DA3MONO-LARGE)                | 0.35B     | ✅             |              |               |               |       | ✅         | Apache 2.0     |
+
+
+## ⚡ Performance Benchmarks
+
+Inference throughput measured on Apple Silicon (MPS) with PyTorch 2.9.0. For detailed benchmarks, see [BENCHMARKS.md](BENCHMARKS.md).
+
+### Apple Silicon (MPS) - Batch Size 1
+
+| Model | Latency | Throughput |
+|-------|---------|------------|
+| DA3-Small | 46 ms | **22 img/s** |
+| DA3-Base | 93 ms | **11 img/s** |
+| DA3-Large | 265 ms | **3.8 img/s** |
+| DA3-Giant | 618 ms | **1.6 img/s** |
+
+### Cross-Device Comparison (DA3-Large)
+
+| Device | Throughput | vs CPU |
+|--------|------------|--------|
+| CPU | 0.3 img/s | 1.0x |
+| Apple Silicon (MPS) | 3.8 img/s | **13x** |
+| NVIDIA L4 (CUDA) | 10.3 img/s | **34x** |
+
+### Batch Processing
+
+```python
+from depth_anything_3.api import DepthAnything3
+
+model = DepthAnything3.from_pretrained("depth-anything/DA3-LARGE")
+
+# Adaptive batching (recommended for large image sets)
+results = model.batch_inference(
+    images=image_paths,
+    batch_size="auto",  # Automatically selects optimal batch size
+    target_memory_utilization=0.85,
+)
+
+# Fixed batch size
+results = model.batch_inference(
+    images=image_paths,
+    batch_size=4,
+)
+```
+
+> See [BENCHMARKS.md](BENCHMARKS.md) for comprehensive benchmarks including preprocessing, attention mechanisms, and adaptive batching strategies.
+
+
+## ❓ FAQ
+
+- **Monocular Metric Depth**: To obtain metric depth in meters from `DA3METRIC-LARGE`, use `metric_depth = focal * net_output / 300.`, where `focal` is the focal length in pixels (typically the average of fx and fy from the camera intrinsic matrix K). Note that the output from `DA3NESTED-GIANT-LARGE` is already in meters.
+
+- <a id="use-ray-pose"></a>**Ray Head (`use_ray_pose`)**:  Our API and CLI support `use_ray_pose` arg, which means that the model will derive camera pose from ray head, which is generally slightly slower, but more accurate. Note that the default is `False` for faster inference speed. 
+  <details>
+  <summary>AUC3 Results for DA3NESTED-GIANT-LARGE</summary>
+  
+  | Model | HiRoom | ETH3D | DTU | 7Scenes | ScanNet++ | 
+  |-------|------|-------|-----|---------|-----------|
+  | `ray_head` | 84.4 | 52.6 | 93.9 | 29.5 | 89.4 |
+  | `cam_head` | 80.3 | 48.4 | 94.1 | 28.5 | 85.0 |
+
+  </details>
+
+
+
+
+- **Older GPUs without XFormers support**: See [Issue #11](https://github.com/ByteDance-Seed/Depth-Anything-3/issues/11). Thanks to [@S-Mahoney](https://github.com/S-Mahoney) for the solution!
+
+
+## 🏢 Awesome DA3 Projects
+
+A community-curated list of Depth Anything 3 integrations across 3D tools, creative pipelines, robotics, and web/VR viewers, including but not limited to these. You are welcome to submit your DA3-based project via PR, and we will review and feature it if applicable.
+
+- [DA3-blender](https://github.com/xy-gao/DA3-blender): Blender addon for DA3-based 3D reconstruction from a set of images. 
+
+- [ComfyUI-DepthAnythingV3](https://github.com/PozzettiAndrea/ComfyUI-DepthAnythingV3): ComfyUI nodes for Depth Anything 3, supporting single/multi-view and video-consistent depth with optional point‑cloud export.
+
+- [DA3-ROS2-Wrapper](https://github.com/GerdsenAI/GerdsenAI-Depth-Anything-3-ROS2-Wrapper): Real-time DA3 depth in ROS2 with multi-camera support. 
+
+- [VideoDepthViewer3D](https://github.com/amariichi/VideoDepthViewer3D): Streaming videos with DA3 metric depth to a Three.js/WebXR 3D viewer for VR/stereo playback.
+
+
+## 📝 Credits
+
+### Original Authors
+
+This package is built on top of **Depth Anything 3**, created by the ByteDance Seed team:
+
+- [Haotong Lin](https://haotongl.github.io/), [Sili Chen](https://github.com/SiliChen321), [Jun Hao Liew](https://liewjunhao.github.io/), [Donny Y. Chen](https://donydchen.github.io), [Zhenyu Li](https://zhyever.github.io/), [Guang Shi](https://scholar.google.com/citations?user=MjXxWbUAAAAJ), [Jiashi Feng](https://scholar.google.com.sg/citations?user=Q8iay0gAAAAJ), [Bingyi Kang](https://bingykang.github.io/)
+
+All model weights, architecture, and core algorithms are their work. This fork only adds production optimizations and deployment tooling.
+
+### Fork Maintainer
+
+This optimized fork is maintained by [Delanoe Pirard (Aedelon)](https://github.com/Aedelon).
+
+Contributions:
+- Model caching system
+- Adaptive batching
+- Apple Silicon (MPS) optimizations
+- PyPI packaging and CI/CD
+- Comprehensive benchmarking
+
+### Citation
+
+If you use Depth Anything 3 in your research, please cite the original paper:
+
+```bibtex
+@article{depthanything3,
+  title={Depth Anything 3: Recovering the visual space from any views},
+  author={Haotong Lin and Sili Chen and Jun Hao Liew and Donny Y. Chen and Zhenyu Li and Guang Shi and Jiashi Feng and Bingyi Kang},
+  journal={arXiv preprint arXiv:2511.10647},
+  year={2025}
+}
+```
+
+If you specifically use features from this fork (caching, batching, MPS optimizations), you may additionally reference:
+
+```
+awesome-depth-anything-3: https://github.com/Aedelon/awesome-depth-anything-3
+```

app.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+# Copyright (c) Delanoe Pirard / Aedelon
+# Licensed under the Apache License, Version 2.0
+"""
+Hugging Face Spaces entry point for awesome-depth-anything-3.
+
+This file is the main entry point for the HF Spaces deployment.
+It launches the Gradio web interface with optimized settings for cloud deployment.
+"""
+
+import os
+import tempfile
+
+# Disable analytics and configure for HF Spaces
+os.environ["GRADIO_ANALYTICS_ENABLED"] = "False"
+os.environ["DA3_LOG_LEVEL"] = "WARNING"
+
+from depth_anything_3.app.gradio_app import DepthAnything3App
+
+
+def main():
+    """Launch the Gradio app for HF Spaces."""
+    # Use DA3-LARGE for good balance of quality and speed
+    workspace_dir = "/tmp/workspace"
+    gallery_dir = "/tmp/gallery"
+
+    # Create directories
+    os.makedirs(workspace_dir, exist_ok=True)
+    os.makedirs(gallery_dir, exist_ok=True)
+
+    app = DepthAnything3App(
+        model_dir="depth-anything/DA3-LARGE",
+        workspace_dir=workspace_dir,
+        gallery_dir=gallery_dir,
+    )
+
+    demo = app.create_app()
+
+    # Build allowed paths for Gradio file access
+    allowed_paths = [
+        os.getcwd(),
+        tempfile.gettempdir(),
+        workspace_dir,
+        gallery_dir,
+        "/tmp",
+    ]
+
+    # Launch for HF Spaces (theme/css already set in create_app via gr.Blocks())
+    demo.queue(max_size=10).launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=True,
+        show_error=True,
+        allowed_paths=allowed_paths,
+    )
+
+
+if __name__ == "__main__":
+    main()

assets/examples/robot_unitree.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:99bc274f7613a665c6135085fe01691ebfaa9033101319071f37c550ab21d1ea
+size 1964268

benchmarks/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Delanoe Pirard / Aedelon
+# Licensed under the Apache License, Version 2.0
+"""Benchmark scripts for Depth Anything 3."""

benchmarks/comparative_benchmark.py

@@ -0,0 +1,436 @@
+#!/usr/bin/env python3
+# Copyright (c) Delanoe Pirard / Aedelon
+# Licensed under the Apache License, Version 2.0
+"""
+Comparative Benchmark: awesome-depth-anything-3 vs upstream (vanilla)
+
+Compares performance between the optimized fork and the original upstream.
+
+Usage:
+    python benchmarks/comparative_benchmark.py --device mps
+    python benchmarks/comparative_benchmark.py --device cuda
+    python benchmarks/comparative_benchmark.py --device all
+    python benchmarks/comparative_benchmark.py --quick
+"""
+
+import argparse
+import contextlib
+import gc
+import io
+import logging
+import os
+import shutil
+import sys
+import time
+import warnings
+
+# Suppress ALL logging before any imports
+logging.disable(logging.CRITICAL)
+os.environ["DA3_LOG_LEVEL"] = "CRITICAL"
+os.environ["PYTHONWARNINGS"] = "ignore"
+warnings.filterwarnings("ignore")
+
+import numpy as np
+import torch
+from PIL import Image
+
+# Suppress all loggers
+logging.getLogger("depth_anything_3").disabled = True
+logging.getLogger("dinov2").disabled = True
+logging.getLogger().setLevel(logging.CRITICAL)
+
+
+@contextlib.contextmanager
+def suppress_output():
+    """Context manager to suppress stdout and stderr."""
+    with contextlib.redirect_stdout(io.StringIO()), \
+         contextlib.redirect_stderr(io.StringIO()):
+        # Also suppress all loggers again
+        logging.disable(logging.CRITICAL)
+        yield
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+AWESOME_REPO = "/Users/aedelon/Workspace/awesome-depth-anything-3"
+UPSTREAM_REPO = "/Users/aedelon/Workspace/depth-anything-3-upstream"
+MODEL_NAME = "da3-large"
+
+
+# ============================================================================
+# UTILITIES
+# ============================================================================
+
+def cleanup():
+    gc.collect()
+    if torch.cuda.is_available():
+        torch.cuda.empty_cache()
+        torch.cuda.reset_peak_memory_stats()
+    if torch.backends.mps.is_available():
+        torch.mps.empty_cache()
+
+
+def sync_device(device):
+    if device.type == "cuda":
+        torch.cuda.synchronize()
+    elif device.type == "mps":
+        torch.mps.synchronize()
+
+
+def clear_modules():
+    """Clear depth_anything_3 from sys.modules."""
+    to_remove = [k for k in sys.modules.keys() if "depth_anything_3" in k]
+    for k in to_remove:
+        del sys.modules[k]
+
+
+def suppress_logging():
+    """Suppress all logging after module import."""
+    logging.disable(logging.CRITICAL)
+    try:
+        from depth_anything_3.utils.logger import logger
+        logger.level = 100
+    except:
+        pass
+
+
+def get_available_devices():
+    """Get available devices."""
+    devices = [torch.device("cpu")]
+    if torch.backends.mps.is_available():
+        devices.append(torch.device("mps"))
+    if torch.cuda.is_available():
+        devices.append(torch.device("cuda"))
+    return devices
+
+
+def get_device_name(device):
+    if device.type == "cuda":
+        return torch.cuda.get_device_name(device)
+    elif device.type == "mps":
+        return "Apple Silicon (MPS)"
+    return "CPU"
+
+
+# ============================================================================
+# BENCHMARK: UPSTREAM (VANILLA)
+# ============================================================================
+
+def benchmark_upstream(device, pil_images, process_res=504, runs=3):
+    """Benchmark upstream/vanilla depth-anything-3."""
+
+    # Setup path
+    clear_modules()
+    upstream_src = os.path.join(UPSTREAM_REPO, "src")
+    if upstream_src in sys.path:
+        sys.path.remove(upstream_src)
+    sys.path.insert(0, upstream_src)
+
+    with suppress_output():
+        from depth_anything_3.api import DepthAnything3
+        suppress_logging()
+
+        cleanup()
+
+        # Cold load
+        start = time.perf_counter()
+        model = DepthAnything3(model_name=MODEL_NAME)
+        model = model.to(device)
+        model.eval()
+        cold_load_time = time.perf_counter() - start
+
+        # Warmup
+        for _ in range(2):
+            model.inference(pil_images[:1], process_res=process_res)
+        sync_device(device)
+        cleanup()
+
+        # Benchmark inference
+        times = []
+        for _ in range(runs):
+            cleanup()
+            sync_device(device)
+            start = time.perf_counter()
+            model.inference(pil_images, process_res=process_res)
+            sync_device(device)
+            times.append(time.perf_counter() - start)
+
+        avg_time = np.mean(times)
+        std_time = np.std(times)
+        throughput = len(pil_images) / avg_time
+
+        del model
+        cleanup()
+
+    # Cleanup path
+    sys.path.remove(upstream_src)
+    clear_modules()
+
+    return {
+        "cold_load": cold_load_time,
+        "inference_time": avg_time,
+        "inference_std": std_time,
+        "throughput": throughput,
+    }
+
+
+# ============================================================================
+# BENCHMARK: AWESOME (OPTIMIZED)
+# ============================================================================
+
+def benchmark_awesome(device, pil_images, process_res=504, runs=3, use_cache=True):
+    """Benchmark awesome (optimized) depth-anything-3."""
+
+    # Setup path
+    clear_modules()
+    awesome_src = os.path.join(AWESOME_REPO, "src")
+    if awesome_src in sys.path:
+        sys.path.remove(awesome_src)
+    sys.path.insert(0, awesome_src)
+
+    with suppress_output():
+        from depth_anything_3.api import DepthAnything3
+        from depth_anything_3.cache import get_model_cache
+        suppress_logging()
+
+        # Clear cache if testing cold load
+        if not use_cache:
+            cache = get_model_cache()
+            cache.clear()
+
+        cleanup()
+
+        # Cold/warm load
+        start = time.perf_counter()
+        model = DepthAnything3(model_name=MODEL_NAME, device=device, use_cache=use_cache)
+        load_time = time.perf_counter() - start
+
+        # For cache test, do a second load
+        cached_load_time = None
+        if use_cache:
+            del model
+            cleanup()
+            start = time.perf_counter()
+            model = DepthAnything3(model_name=MODEL_NAME, device=device, use_cache=True)
+            cached_load_time = time.perf_counter() - start
+
+        # Warmup
+        for _ in range(2):
+            model.inference(pil_images[:1], process_res=process_res)
+        sync_device(device)
+        cleanup()
+
+        # Benchmark inference
+        times = []
+        for _ in range(runs):
+            cleanup()
+            sync_device(device)
+            start = time.perf_counter()
+            model.inference(pil_images, process_res=process_res)
+            sync_device(device)
+            times.append(time.perf_counter() - start)
+
+        avg_time = np.mean(times)
+        std_time = np.std(times)
+        throughput = len(pil_images) / avg_time
+
+        del model
+        cleanup()
+
+    # Cleanup path
+    sys.path.remove(awesome_src)
+    clear_modules()
+
+    return {
+        "cold_load": load_time,
+        "cached_load": cached_load_time,
+        "inference_time": avg_time,
+        "inference_std": std_time,
+        "throughput": throughput,
+    }
+
+
+# ============================================================================
+# MAIN
+# ============================================================================
+
+def run_comparison(device, batch_sizes, process_res=504, runs=3):
+    """Run comparison for a specific device."""
+
+    results = {}
+    temp_dir = "temp_compare"
+    os.makedirs(temp_dir, exist_ok=True)
+
+    try:
+        # Create test images
+        max_batch = max(batch_sizes)
+        pil_images = []
+        for i in range(max_batch):
+            img = Image.new("RGB", (1280, 720), color=(100 + i*10, 150, 200))
+            pil_images.append(img)
+
+        for batch_size in batch_sizes:
+            test_images = pil_images[:batch_size]
+            results[batch_size] = {}
+
+            print(f"\n  Batch size: {batch_size}")
+            print(f"  {'-'*50}")
+
+            # Upstream
+            print(f"  Testing UPSTREAM (vanilla)...", end=" ", flush=True)
+            try:
+                upstream = benchmark_upstream(device, test_images, process_res, runs)
+                results[batch_size]["upstream"] = upstream
+                print(f"{upstream['throughput']:.2f} img/s")
+            except Exception as e:
+                print(f"ERROR: {e}")
+                results[batch_size]["upstream"] = None
+
+            # Awesome (no cache - fair comparison)
+            print(f"  Testing AWESOME (no cache)...", end=" ", flush=True)
+            try:
+                awesome_nc = benchmark_awesome(device, test_images, process_res, runs, use_cache=False)
+                results[batch_size]["awesome_nocache"] = awesome_nc
+                print(f"{awesome_nc['throughput']:.2f} img/s")
+            except Exception as e:
+                print(f"ERROR: {e}")
+                results[batch_size]["awesome_nocache"] = None
+
+            # Awesome (with cache)
+            print(f"  Testing AWESOME (cached)...", end=" ", flush=True)
+            try:
+                awesome_c = benchmark_awesome(device, test_images, process_res, runs, use_cache=True)
+                results[batch_size]["awesome_cached"] = awesome_c
+                print(f"{awesome_c['throughput']:.2f} img/s")
+            except Exception as e:
+                print(f"ERROR: {e}")
+                results[batch_size]["awesome_cached"] = None
+
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+    return results
+
+
+def print_results_table(results, device):
+    """Print formatted results table."""
+
+    print(f"\n{'='*70}")
+    print(f" RESULTS: {device.type.upper()}")
+    print(f"{'='*70}")
+
+    # Header
+    print(f"\n{'Batch':<8} {'Metric':<18} {'Upstream':<12} {'Awesome':<12} {'Speedup':<10}")
+    print("-" * 60)
+
+    for batch_size, data in sorted(results.items()):
+        upstream = data.get("upstream")
+        awesome = data.get("awesome_nocache") or data.get("awesome_cached")
+
+        if not upstream or not awesome:
+            continue
+
+        # Inference throughput
+        u_thr = upstream["throughput"]
+        a_thr = awesome["throughput"]
+        speedup = a_thr / u_thr if u_thr > 0 else 0
+        print(f"{batch_size:<8} {'Throughput (img/s)':<18} {u_thr:<12.2f} {a_thr:<12.2f} {speedup:<10.2f}x")
+
+        # Inference time
+        u_time = upstream["inference_time"] * 1000
+        a_time = awesome["inference_time"] * 1000
+        speedup = u_time / a_time if a_time > 0 else 0
+        print(f"{'':<8} {'Latency (ms)':<18} {u_time:<12.1f} {a_time:<12.1f} {speedup:<10.2f}x")
+
+        # Cold load time
+        u_load = upstream["cold_load"]
+        a_load = awesome["cold_load"]
+        speedup = u_load / a_load if a_load > 0 else 0
+        print(f"{'':<8} {'Cold load (s)':<18} {u_load:<12.2f} {a_load:<12.2f} {speedup:<10.2f}x")
+
+        # Cached load (awesome only)
+        cached = data.get("awesome_cached")
+        if cached and cached.get("cached_load"):
+            c_load = cached["cached_load"]
+            speedup = u_load / c_load if c_load > 0 else 0
+            print(f"{'':<8} {'Cached load (s)':<18} {'-':<12} {c_load:<12.3f} {speedup:<10.1f}x")
+
+        print()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Comparative Benchmark: Awesome vs Upstream")
+    parser.add_argument("--device", "-d", type=str, default="auto",
+                       choices=["auto", "cpu", "mps", "cuda", "all"],
+                       help="Device to benchmark")
+    parser.add_argument("--batch-sizes", type=int, nargs="+", default=[1, 2, 4],
+                       help="Batch sizes to test")
+    parser.add_argument("--runs", type=int, default=3, help="Number of runs per test")
+    parser.add_argument("--quick", action="store_true", help="Quick mode (fewer runs)")
+    args = parser.parse_args()
+
+    if args.quick:
+        args.batch_sizes = [1, 2]
+        args.runs = 2
+
+    # Determine devices
+    available = get_available_devices()
+    if args.device == "auto":
+        devices = [available[-1]]
+    elif args.device == "all":
+        devices = available
+    else:
+        requested = torch.device(args.device)
+        if requested in available:
+            devices = [requested]
+        else:
+            print(f"Device '{args.device}' not available. Available: {[d.type for d in available]}")
+            return
+
+    # Header
+    print("\n" + "=" * 70)
+    print(" COMPARATIVE BENCHMARK: AWESOME vs UPSTREAM (VANILLA)")
+    print("=" * 70)
+    print(f" Model: {MODEL_NAME}")
+    print(f" PyTorch: {torch.__version__}")
+    print(f" Batch sizes: {args.batch_sizes}")
+    print(f" Runs per test: {args.runs}")
+    print(f" Devices: {[d.type.upper() for d in devices]}")
+    for d in available:
+        status = "✓" if d in devices else "○"
+        print(f"   {status} {d.type.upper()}: {get_device_name(d)}")
+    print("=" * 70)
+
+    all_results = {}
+
+    for device in devices:
+        print(f"\n{'#'*70}")
+        print(f" DEVICE: {device.type.upper()} ({get_device_name(device)})")
+        print(f"{'#'*70}")
+
+        results = run_comparison(device, args.batch_sizes, runs=args.runs)
+        all_results[device.type] = results
+        print_results_table(results, device)
+
+    # Final summary
+    print("\n" + "=" * 70)
+    print(" SUMMARY")
+    print("=" * 70)
+
+    for device_type, results in all_results.items():
+        print(f"\n {device_type.upper()}:")
+
+        for batch_size, data in sorted(results.items()):
+            upstream = data.get("upstream")
+            awesome = data.get("awesome_nocache")
+
+            if upstream and awesome:
+                speedup = awesome["throughput"] / upstream["throughput"]
+                print(f"   Batch {batch_size}: {speedup:.2f}x faster inference")
+
+    print("\n" + "=" * 70 + "\n")
+
+
+if __name__ == "__main__":
+    main()

benchmarks/flash_attention_benchmark.py

@@ -0,0 +1,488 @@
+#!/usr/bin/env python3
+# Copyright (c) Delanoe Pirard / Aedelon - Apache 2.0
+"""
+Flash Attention Benchmark for Depth Anything 3.
+
+Provides clear performance comparison with tables and analysis.
+
+Usage:
+    python benchmarks/flash_attention_benchmark.py
+    python benchmarks/flash_attention_benchmark.py --detailed
+"""
+
+import argparse
+import gc
+import os
+import sys
+import time
+from dataclasses import dataclass
+
+import torch
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from depth_anything_3.model.dinov2.layers import (
+    FLASH_ATTN_AVAILABLE,
+    FLASH_ATTN_VERSION,
+    Attention,
+)
+
+
+@dataclass
+class BenchmarkConfig:
+    """Configuration for a benchmark test case."""
+
+    name: str
+    seq_len: int
+    batch_size: int
+    embed_dim: int
+    num_heads: int
+    image_size: str  # Description of corresponding image size
+
+    @property
+    def description(self):
+        return f"{self.name} ({self.image_size})"
+
+
+# Depth Anything 3 model configurations
+DA3_CONFIGS = {
+    "vitb": {"embed_dim": 768, "num_heads": 12, "depth": 12},
+    "vitl": {"embed_dim": 1024, "num_heads": 16, "depth": 24},
+    "vitg": {"embed_dim": 1536, "num_heads": 24, "depth": 40},
+}
+
+
+def get_device_info():
+    """Get device information."""
+    if torch.cuda.is_available():
+        device = torch.device("cuda")
+        device_name = torch.cuda.get_device_name()
+        memory_gb = torch.cuda.get_device_properties(0).total_memory / 1024**3
+        compute_cap = torch.cuda.get_device_capability()
+        return {
+            "type": "cuda",
+            "device": device,
+            "name": device_name,
+            "memory_gb": memory_gb,
+            "compute_capability": f"{compute_cap[0]}.{compute_cap[1]}",
+        }
+    elif torch.backends.mps.is_available():
+        return {
+            "type": "mps",
+            "device": torch.device("mps"),
+            "name": "Apple Silicon",
+            "memory_gb": None,
+            "compute_capability": None,
+        }
+    else:
+        return {
+            "type": "cpu",
+            "device": torch.device("cpu"),
+            "name": "CPU",
+            "memory_gb": None,
+            "compute_capability": None,
+        }
+
+
+def benchmark_attention(attn_module, x, warmup=5, runs=20):
+    """Run benchmark for a single attention module."""
+    device = x.device
+
+    # Warmup
+    with torch.no_grad():
+        for _ in range(warmup):
+            _ = attn_module(x)
+    if device.type == "cuda":
+        torch.cuda.synchronize()
+
+    # Reset memory tracking
+    if device.type == "cuda":
+        torch.cuda.reset_peak_memory_stats()
+
+    # Benchmark
+    times = []
+    with torch.no_grad():
+        for _ in range(runs):
+            if device.type == "cuda":
+                torch.cuda.synchronize()
+            start = time.perf_counter()
+            _ = attn_module(x)
+            if device.type == "cuda":
+                torch.cuda.synchronize()
+            times.append((time.perf_counter() - start) * 1000)
+
+    # Memory
+    peak_mem_mb = 0
+    if device.type == "cuda":
+        peak_mem_mb = torch.cuda.max_memory_allocated() / 1024 / 1024
+
+    times_tensor = torch.tensor(times)
+    return {
+        "mean_ms": times_tensor.mean().item(),
+        "std_ms": times_tensor.std().item(),
+        "min_ms": times_tensor.min().item(),
+        "peak_mem_mb": peak_mem_mb,
+    }
+
+
+def print_header():
+    """Print benchmark header."""
+    print("\n" + "=" * 80)
+    print(" " * 20 + "FLASH ATTENTION BENCHMARK - DEPTH ANYTHING 3")
+    print("=" * 80 + "\n")
+
+
+def get_sdpa_backend_info():
+    """Get info about which SDPA backend is being used."""
+    info = {}
+    if torch.cuda.is_available():
+        from torch.backends.cuda import (
+            flash_sdp_enabled,
+            mem_efficient_sdp_enabled,
+            math_sdp_enabled,
+        )
+        info["flash_sdp"] = flash_sdp_enabled()
+        info["mem_efficient_sdp"] = mem_efficient_sdp_enabled()
+        info["math_sdp"] = math_sdp_enabled()
+    return info
+
+
+def print_device_info(device_info):
+    """Print device information."""
+    print("📊 HARDWARE CONFIGURATION")
+    print("─" * 80)
+    print(f"  Device Type      : {device_info['type'].upper()}")
+    print(f"  Device Name      : {device_info['name']}")
+    if device_info["memory_gb"]:
+        print(f"  Memory           : {device_info['memory_gb']:.1f} GB")
+    if device_info["compute_capability"]:
+        print(f"  Compute Cap.     : {device_info['compute_capability']}")
+        cc = float(device_info["compute_capability"])
+        if cc >= 7.5:
+            print(f"                     ✅ Flash Attention supported (≥7.5)")
+        else:
+            print(f"                     ❌ Flash Attention requires ≥7.5")
+
+    # SDPA backend info
+    sdpa_info = get_sdpa_backend_info()
+    if sdpa_info:
+        print(f"\n  PyTorch SDPA Backends:")
+        print(f"    Flash SDP      : {'✅ Enabled' if sdpa_info.get('flash_sdp') else '❌ Disabled'}")
+        print(f"    MemEfficient   : {'✅ Enabled' if sdpa_info.get('mem_efficient_sdp') else '❌ Disabled'}")
+        print(f"    Math SDP       : {'✅ Enabled' if sdpa_info.get('math_sdp') else '❌ Disabled'}")
+
+        if sdpa_info.get('flash_sdp'):
+            print(f"\n  ⚡ PyTorch SDPA uses Flash Attention internally!")
+            print(f"     (No need for flash-attn package with PyTorch >= 2.2)")
+
+    print(f"\n  flash-attn pkg   : {'✅ Installed v' + FLASH_ATTN_VERSION if FLASH_ATTN_AVAILABLE else '❌ Not installed (optional)'}")
+    print()
+
+
+def print_table_header():
+    """Print benchmark table header."""
+    print(
+        "┌──────────────────────────┬──────────────┬──────────────┬──────────────┬────────────┐"
+    )
+    print(
+        "│ Configuration            │ flash_attn   │ sdpa         │ manual       │ Speedup    │"
+    )
+    print(
+        "├──────────────────────────┼──────────────┼──────────────┼──────────────┼────────────┤"
+    )
+
+
+def print_table_row(config_desc, results, baseline="sdpa"):
+    """Print a benchmark result row."""
+    backends = ["flash_attn", "sdpa", "manual"]
+
+    # Format times
+    time_strs = []
+    for backend in backends:
+        if backend in results and results[backend]:
+            time_ms = results[backend]["mean_ms"]
+            time_strs.append(f"{time_ms:6.2f} ms")
+        else:
+            time_strs.append("     N/A")
+
+    # Calculate speedup
+    speedup_str = "      -"
+    if "flash_attn" in results and results["flash_attn"] and baseline in results:
+        if results[baseline]:
+            speedup = results[baseline]["mean_ms"] / results["flash_attn"]["mean_ms"]
+            speedup_str = f"  {speedup:.2f}x ⚡" if speedup > 1.1 else f"  {speedup:.2f}x"
+
+    print(
+        f"│ {config_desc:24s} │ {time_strs[0]:12s} │ {time_strs[1]:12s} │ {time_strs[2]:12s} │ {speedup_str:10s} │"
+    )
+
+
+def print_table_footer():
+    """Print benchmark table footer."""
+    print(
+        "└──────────────────────────┴──────────────┴──────────────┴──────────────┴────────────┘"
+    )
+
+
+def print_model_analysis(model_name, config, results, num_layers):
+    """Print detailed analysis for a specific model."""
+    if "flash_attn" not in results or not results["flash_attn"]:
+        return
+
+    flash_time = results["flash_attn"]["mean_ms"]
+    sdpa_time = results["sdpa"]["mean_ms"] if "sdpa" in results else flash_time
+
+    speedup = sdpa_time / flash_time
+    time_saved_per_layer = (sdpa_time - flash_time) / num_layers
+    total_time_saved = time_saved_per_layer * num_layers
+
+    print(f"\n  📈 {model_name} Analysis:")
+    print(f"     • Attention time per layer: {flash_time:.2f} ms (flash) vs {sdpa_time:.2f} ms (sdpa)")
+    print(f"     • Time saved per layer: {time_saved_per_layer:.2f} ms")
+    print(f"     • Total time saved ({num_layers} layers): {total_time_saved:.1f} ms")
+    print(f"     • Speedup: {speedup:.2f}x on attention")
+
+    # Estimate full inference impact
+    # Attention is ~15-20% of total inference time
+    attn_fraction = 0.175
+    overall_speedup = 1 / (1 - attn_fraction + attn_fraction / speedup)
+    overall_improvement = (1 - 1 / overall_speedup) * 100
+
+    print(
+        f"     • Estimated full inference speedup: {overall_speedup:.2f}x (~{overall_improvement:.1f}% faster)"
+    )
+
+
+def run_benchmark(test_configs, backends, warmup=5, runs=20, detailed=False):
+    """Run complete benchmark suite."""
+    device_info = get_device_info()
+    device = device_info["device"]
+    dtype = torch.float16 if device.type == "cuda" else torch.float32
+
+    print_header()
+    print_device_info(device_info)
+
+    # Filter backends based on availability
+    available_backends = []
+    if FLASH_ATTN_AVAILABLE and device.type == "cuda":
+        available_backends.append("flash_attn")
+    available_backends.append("sdpa")
+    if detailed:
+        available_backends.append("manual")
+
+    all_results = {}
+
+    # Run benchmarks by model
+    for model_name, model_config in DA3_CONFIGS.items():
+        print(f"\n🔬 MODEL: {model_name.upper()} (dim={model_config['embed_dim']}, heads={model_config['num_heads']}, depth={model_config['depth']})")
+        print("─" * 80)
+        print_table_header()
+
+        model_results = {}
+
+        for test_config in test_configs:
+            # Adjust config for this model
+            config = BenchmarkConfig(
+                name=test_config.name,
+                seq_len=test_config.seq_len,
+                batch_size=test_config.batch_size,
+                embed_dim=model_config["embed_dim"],
+                num_heads=model_config["num_heads"],
+                image_size=test_config.image_size,
+            )
+
+            x = torch.randn(
+                config.batch_size, config.seq_len, config.embed_dim, device=device, dtype=dtype
+            )
+
+            results = {}
+            for backend in available_backends:
+                gc.collect()
+                if device.type == "cuda":
+                    torch.cuda.empty_cache()
+
+                try:
+                    attn = Attention(
+                        dim=config.embed_dim,
+                        num_heads=config.num_heads,
+                        attn_backend=backend,
+                    ).to(device, dtype)
+                    attn.eval()
+
+                    result = benchmark_attention(attn, x, warmup=warmup, runs=runs)
+                    results[backend] = result
+
+                    del attn
+                except Exception as e:
+                    results[backend] = None
+                    if detailed:
+                        print(f"    {backend} failed: {e}")
+
+            model_results[config.name] = results
+            print_table_row(config.description, results)
+
+        print_table_footer()
+
+        # Analysis for this model
+        if detailed and model_results:
+            # Use medium config for analysis
+            medium_key = next(
+                (k for k in model_results.keys() if "1024" in k.lower() or "medium" in k.lower()),
+                list(model_results.keys())[0],
+            )
+            print_model_analysis(
+                model_name.upper(),
+                test_configs[0],
+                model_results[medium_key],
+                model_config["depth"],
+            )
+
+        all_results[model_name] = model_results
+
+    # Final summary
+    print("\n" + "=" * 80)
+    print("📋 SUMMARY & RECOMMENDATIONS")
+    print("=" * 80)
+
+    sdpa_info = get_sdpa_backend_info()
+
+    if device.type == "cuda":
+        # Check if PyTorch SDPA has Flash enabled
+        if sdpa_info.get('flash_sdp'):
+            print("\n✅ Flash Attention is ACTIVE via PyTorch SDPA!")
+            print("\n   Your setup:")
+            print(f"   • PyTorch {torch.__version__} with native Flash Attention")
+            print("   • SDPA backend: Flash SDP ⚡")
+            print("   • No additional packages needed!")
+            print("\n   Benefits you're already getting:")
+            print("   • 2-4x faster attention vs manual implementation")
+            print("   • Memory-efficient attention computation")
+            print("   • Automatic kernel selection per input size")
+
+            if FLASH_ATTN_AVAILABLE:
+                print(f"\n   ℹ️  flash-attn v{FLASH_ATTN_VERSION} also installed")
+                print("      (May provide slight additional optimization in some cases)")
+            else:
+                print("\n   ℹ️  flash-attn package: Not needed!")
+                print("      PyTorch >= 2.2 includes Flash Attention natively.")
+
+        elif FLASH_ATTN_AVAILABLE:
+            print("\n✅ Flash Attention is ACTIVE via flash-attn package")
+            print(f"\n   Using flash-attn v{FLASH_ATTN_VERSION}")
+            print("\n   Benefits:")
+            print("   • 2-3x faster attention computation")
+            print("   • ~15-25% overall inference speedup")
+            print("   • Lower memory usage")
+
+        else:
+            print("\n⚠️  Flash Attention not available")
+            print("\n   Options to enable:")
+            print("   1. Upgrade PyTorch to >= 2.2 (recommended)")
+            print("   2. Install flash-attn: pip install flash-attn --no-build-isolation")
+
+    elif device.type == "mps":
+        print("\n📱 Apple Silicon (MPS) detected")
+        print("\n   • Flash Attention not available for MPS")
+        print("   • PyTorch SDPA uses optimized Metal kernels")
+        print("   • Already running at optimal speed for your hardware")
+
+    else:
+        print("\n💻 CPU detected")
+        print("\n   • Consider using GPU for faster inference")
+        print("   • Flash Attention is CUDA-only")
+
+    # Print SDPA vs Manual speedup summary
+    print("\n" + "─" * 80)
+    print("⚡ PERFORMANCE COMPARISON")
+    print("─" * 80)
+    print("\n   SDPA vs Manual attention speedup (per layer):")
+
+    for model_name, model_results in all_results.items():
+        if model_results:
+            # Get XLarge config results for most impact
+            xlarge_key = next((k for k in model_results.keys() if "xlarge" in k.lower()), list(model_results.keys())[-1])
+            if xlarge_key in model_results:
+                res = model_results[xlarge_key]
+                if res.get("sdpa") and res.get("manual"):
+                    speedup = res["manual"]["mean_ms"] / res["sdpa"]["mean_ms"]
+                    print(f"   • {model_name.upper():6s}: {speedup:.1f}x faster (sdpa: {res['sdpa']['mean_ms']:.2f}ms vs manual: {res['manual']['mean_ms']:.2f}ms)")
+
+    print("\n" + "=" * 80)
+    print()
+
+    return all_results
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Flash Attention benchmark for DA3")
+    parser.add_argument(
+        "--detailed",
+        action="store_true",
+        help="Show detailed analysis and include manual backend",
+    )
+    parser.add_argument(
+        "--warmup",
+        type=int,
+        default=5,
+        help="Warmup iterations (default: 5)",
+    )
+    parser.add_argument(
+        "--runs",
+        type=int,
+        default=20,
+        help="Benchmark runs (default: 20)",
+    )
+
+    args = parser.parse_args()
+
+    # Test configurations based on common image sizes
+    test_configs = [
+        BenchmarkConfig(
+            name="Small",
+            seq_len=256,
+            batch_size=1,
+            embed_dim=768,  # Will be overridden per model
+            num_heads=12,  # Will be overridden per model
+            image_size="392px image",
+        ),
+        BenchmarkConfig(
+            name="Medium",
+            seq_len=529,
+            batch_size=1,
+            embed_dim=768,
+            num_heads=12,
+            image_size="518px image",
+        ),
+        BenchmarkConfig(
+            name="Large",
+            seq_len=1024,
+            batch_size=1,
+            embed_dim=768,
+            num_heads=12,
+            image_size="742px image",
+        ),
+        BenchmarkConfig(
+            name="XLarge",
+            seq_len=1369,
+            batch_size=1,
+            embed_dim=768,
+            num_heads=12,
+            image_size="1024px image",
+        ),
+    ]
+
+    backends = ["flash_attn", "sdpa"]
+    if args.detailed:
+        backends.append("manual")
+
+    run_benchmark(
+        test_configs=test_configs,
+        backends=backends,
+        warmup=args.warmup,
+        runs=args.runs,
+        detailed=args.detailed,
+    )
+
+
+if __name__ == "__main__":
+    main()

benchmarks/full_benchmark.py

@@ -0,0 +1,696 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025 Delanoe Pirard / Aedelon - Apache 2.0
+"""
+Full Benchmark Suite for Depth Anything 3
+
+Tests ALL optimization combinations for each device (CPU, MPS, CUDA).
+
+Optimizations tested:
+- Preprocessing: CPU (PIL) vs GPU (NVJPEG on CUDA)
+- Attention: SDPA (Flash Attention) vs Manual
+
+Usage:
+    python benchmarks/full_benchmark.py              # Best device only
+    python benchmarks/full_benchmark.py -d all       # All devices
+    python benchmarks/full_benchmark.py -d cuda      # CUDA only
+    python benchmarks/full_benchmark.py --quick      # Quick mode
+"""
+
+import argparse
+import gc
+import logging
+import os
+import shutil
+import sys
+import time
+import warnings
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+# Suppress ALL logging before any imports
+logging.disable(logging.CRITICAL)
+os.environ["DA3_LOG_LEVEL"] = "ERROR"
+warnings.filterwarnings("ignore")
+
+import numpy as np
+import torch
+from PIL import Image
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+# Suppress depth_anything_3 logger specifically
+logging.getLogger("depth_anything_3").disabled = True
+logging.getLogger("dinov2").disabled = True
+
+
+# ============================================================================
+# STYLES
+# ============================================================================
+
+class Style:
+    CYAN = "\033[96m"
+    GREEN = "\033[92m"
+    YELLOW = "\033[93m"
+    RED = "\033[91m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    RESET = "\033[0m"
+
+
+def colored(text, color, bold=False):
+    prefix = Style.BOLD if bold else ""
+    return f"{prefix}{color}{text}{Style.RESET}"
+
+
+# ============================================================================
+# UTILITIES
+# ============================================================================
+
+def cleanup():
+    gc.collect()
+    if torch.cuda.is_available():
+        torch.cuda.empty_cache()
+        torch.cuda.reset_peak_memory_stats()
+    if torch.backends.mps.is_available():
+        torch.mps.empty_cache()
+
+
+def sync_device(device):
+    if device.type == "cuda":
+        torch.cuda.synchronize()
+    elif device.type == "mps":
+        torch.mps.synchronize()
+
+
+def get_available_devices() -> List[torch.device]:
+    """Get all available devices for benchmarking."""
+    devices = [torch.device("cpu")]
+    if torch.backends.mps.is_available():
+        devices.append(torch.device("mps"))
+    if torch.cuda.is_available():
+        devices.append(torch.device("cuda"))
+    return devices
+
+
+def get_device_name(device: torch.device) -> str:
+    """Get human-readable device name."""
+    if device.type == "cuda":
+        return torch.cuda.get_device_name(device)
+    elif device.type == "mps":
+        return "Apple Silicon (MPS)"
+    else:
+        import platform
+        return f"CPU ({platform.processor() or 'Unknown'})"
+
+
+# ============================================================================
+# DATA CLASSES
+# ============================================================================
+
+@dataclass
+class BenchmarkResult:
+    """Single benchmark result."""
+    mean_ms: float
+    std_ms: float
+    fps: float
+
+    @classmethod
+    def from_times(cls, times: List[float], batch_size: int = 1):
+        mean_ms = np.mean(times)
+        std_ms = np.std(times)
+        fps = 1000 / mean_ms * batch_size
+        return cls(mean_ms=mean_ms, std_ms=std_ms, fps=fps)
+
+
+@dataclass
+class OptimizationConfig:
+    """Configuration for a specific optimization combination."""
+    name: str
+    preprocessing: str  # "cpu" or "gpu"
+    attention: str      # "sdpa" or "manual"
+    description: str
+
+    @property
+    def short_name(self) -> str:
+        prep = "GPU" if self.preprocessing == "gpu" else "CPU"
+        attn = "SDPA" if self.attention == "sdpa" else "Manual"
+        return f"{prep}+{attn}"
+
+
+# ============================================================================
+# BENCHMARK FUNCTIONS
+# ============================================================================
+
+def get_optimization_configs(device: torch.device) -> List[OptimizationConfig]:
+    """Get all valid optimization configurations for a device."""
+    configs = []
+
+    if device.type == "cuda":
+        # CUDA: All 4 combinations
+        configs = [
+            OptimizationConfig("gpu_sdpa", "gpu", "sdpa", "GPU Decode (NVJPEG) + SDPA (Flash)"),
+            OptimizationConfig("gpu_manual", "gpu", "manual", "GPU Decode (NVJPEG) + Manual Attn"),
+            OptimizationConfig("cpu_sdpa", "cpu", "sdpa", "CPU Decode (PIL) + SDPA (Flash)"),
+            OptimizationConfig("cpu_manual", "cpu", "manual", "CPU Decode (PIL) + Manual Attn"),
+        ]
+    elif device.type == "mps":
+        # MPS: CPU preprocessing is better, 2 combinations
+        configs = [
+            OptimizationConfig("cpu_sdpa", "cpu", "sdpa", "CPU Decode (PIL) + SDPA"),
+            OptimizationConfig("cpu_manual", "cpu", "manual", "CPU Decode (PIL) + Manual Attn"),
+        ]
+    else:
+        # CPU: 2 combinations
+        configs = [
+            OptimizationConfig("cpu_sdpa", "cpu", "sdpa", "SDPA Attention"),
+            OptimizationConfig("cpu_manual", "cpu", "manual", "Manual Attention"),
+        ]
+
+    return configs
+
+
+def benchmark_preprocessing_detailed(device: torch.device, runs: int = 5) -> Dict:
+    """Benchmark preprocessing in detail."""
+    from depth_anything_3.utils.io.input_processor import InputProcessor
+    from depth_anything_3.utils.io.gpu_input_processor import GPUInputProcessor
+
+    results = {}
+    temp_dir = "temp_bench_preproc"
+
+    sizes = [
+        ("720p", 1280, 720),
+        ("1080p", 1920, 1080),
+        ("4K", 3840, 2160),
+    ]
+
+    os.makedirs(temp_dir, exist_ok=True)
+
+    try:
+        cpu_proc = InputProcessor()
+        gpu_proc = None
+        if device.type == "cuda":
+            gpu_proc = GPUInputProcessor(device=device)
+
+        for name, w, h in sizes:
+            results[name] = {}
+
+            # Create test files
+            files = []
+            pil_imgs = []
+            for i in range(4):
+                img = Image.new("RGB", (w, h), color=(100 + i*10, 150, 200))
+                fpath = f"{temp_dir}/{name}_{i}.jpg"
+                img.save(fpath, quality=95)
+                files.append(fpath)
+                pil_imgs.append(img.copy())
+
+            # CPU benchmark
+            cleanup()
+            for _ in range(2):
+                cpu_proc(image=pil_imgs, process_res=518, num_workers=8)
+
+            times = []
+            for _ in range(runs):
+                start = time.perf_counter()
+                cpu_proc(image=pil_imgs, process_res=518, num_workers=8)
+                times.append((time.perf_counter() - start) * 1000)
+            results[name]["cpu"] = BenchmarkResult.from_times(times, batch_size=4)
+
+            # GPU benchmark (NVJPEG for CUDA)
+            if gpu_proc and gpu_proc.use_gpu:
+                cleanup()
+                for _ in range(2):
+                    gpu_proc(image=files, process_res=518, num_workers=1)
+                sync_device(device)
+
+                times = []
+                for _ in range(runs):
+                    sync_device(device)
+                    start = time.perf_counter()
+                    gpu_proc(image=files, process_res=518, num_workers=1)
+                    sync_device(device)
+                    times.append((time.perf_counter() - start) * 1000)
+                results[name]["gpu"] = BenchmarkResult.from_times(times, batch_size=4)
+
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+    return results
+
+
+def benchmark_attention_detailed(device: torch.device, runs: int = 10) -> Dict:
+    """Benchmark attention backends in detail."""
+    from depth_anything_3.model.dinov2.layers import Attention
+
+    results = {}
+    dtype = torch.float16 if device.type == "cuda" else torch.float32
+
+    configs = [
+        ("ViT-S (518px)", 384, 6, 529),
+        ("ViT-L (518px)", 1024, 16, 529),
+        ("ViT-L (770px)", 1024, 16, 1156),
+    ]
+
+    for name, dim, heads, seq_len in configs:
+        results[name] = {}
+        x = torch.randn(1, seq_len, dim, device=device, dtype=dtype)
+
+        for backend in ["sdpa", "manual"]:
+            cleanup()
+            attn = Attention(dim=dim, num_heads=heads, attn_backend=backend).to(device, dtype)
+            attn.eval()
+
+            # Warmup
+            with torch.no_grad():
+                for _ in range(3):
+                    attn(x)
+            sync_device(device)
+
+            # Benchmark
+            times = []
+            with torch.no_grad():
+                for _ in range(runs):
+                    sync_device(device)
+                    start = time.perf_counter()
+                    attn(x)
+                    sync_device(device)
+                    times.append((time.perf_counter() - start) * 1000)
+
+            results[name][backend] = BenchmarkResult.from_times(times)
+            del attn
+
+    return results
+
+
+def benchmark_inference_matrix(
+    device: torch.device,
+    models: List[str],
+    runs: int = 3,
+) -> Dict:
+    """Benchmark all optimization combinations for inference."""
+    from depth_anything_3.api import DepthAnything3
+
+    results = {}
+    temp_dir = "temp_bench_infer"
+    configs = get_optimization_configs(device)
+
+    os.makedirs(temp_dir, exist_ok=True)
+
+    # Create test images (720p)
+    img_paths = []
+    pil_imgs = []
+    for i in range(4):
+        img = Image.new("RGB", (1280, 720), color=(100 + i*20, 150, 200))
+        path = f"{temp_dir}/test_{i}.jpg"
+        img.save(path, quality=95)
+        img_paths.append(path)
+        pil_imgs.append(img.copy())
+
+    try:
+        for model_name in models:
+            results[model_name] = {}
+
+            for config in configs:
+                cleanup()
+
+                # Set attention backend
+                os.environ["DA3_ATTENTION_BACKEND"] = config.attention
+
+                # Load model fresh (to apply attention backend)
+                model = DepthAnything3(
+                    model_name=model_name,
+                    device=device,
+                    use_cache=False,
+                )
+
+                # Choose input based on preprocessing
+                if config.preprocessing == "gpu" and device.type == "cuda":
+                    test_input = img_paths[:1]  # File paths for NVJPEG
+                else:
+                    test_input = pil_imgs[:1]   # PIL for CPU preprocessing
+
+                # Warmup
+                for _ in range(3):
+                    model.inference(test_input, process_res=518)
+                sync_device(device)
+
+                # Benchmark
+                times = []
+                for _ in range(runs):
+                    sync_device(device)
+                    start = time.perf_counter()
+                    model.inference(test_input, process_res=518)
+                    sync_device(device)
+                    times.append((time.perf_counter() - start) * 1000)
+
+                results[model_name][config.name] = {
+                    "result": BenchmarkResult.from_times(times, batch_size=1),
+                    "config": config,
+                }
+
+                del model
+                cleanup()
+
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+    return results
+
+
+# ============================================================================
+# DISPLAY FUNCTIONS
+# ============================================================================
+
+def print_header(title: str):
+    """Print section header."""
+    print()
+    print(colored("═" * 70, Style.CYAN))
+    print(colored("║", Style.CYAN) + colored(f" {title}", Style.BOLD).center(77) + colored("║", Style.CYAN))
+    print(colored("═" * 70, Style.CYAN))
+
+
+def print_subheader(title: str):
+    """Print subsection header."""
+    print()
+    print(colored(f"▶ {title}", Style.YELLOW, bold=True))
+    print(colored("─" * 70, Style.DIM))
+
+
+def format_speedup(speedup: float) -> str:
+    """Format speedup with color."""
+    if speedup >= 1.5:
+        return colored(f"{speedup:.2f}x", Style.GREEN, bold=True)
+    elif speedup >= 1.1:
+        return colored(f"{speedup:.2f}x", Style.GREEN)
+    elif speedup >= 0.95:
+        return f"{speedup:.2f}x"
+    else:
+        return colored(f"{speedup:.2f}x", Style.RED)
+
+
+def print_preprocessing_results(results: Dict, device: torch.device):
+    """Print preprocessing benchmark results."""
+    print_subheader("PREPROCESSING (4 images batch)")
+
+    has_gpu = any("gpu" in r for r in results.values())
+
+    if has_gpu:
+        print(f"  {'Resolution':<12} {'CPU (PIL)':<14} {'GPU (NVJPEG)':<14} {'Speedup':<10}")
+        print(f"  {'-'*50}")
+
+        for name, data in results.items():
+            cpu_ms = data["cpu"].mean_ms
+            if "gpu" in data:
+                gpu_ms = data["gpu"].mean_ms
+                speedup = cpu_ms / gpu_ms
+                print(f"  {name:<12} {cpu_ms:>8.1f} ms    {gpu_ms:>8.1f} ms    {format_speedup(speedup)}")
+            else:
+                print(f"  {name:<12} {cpu_ms:>8.1f} ms    {'N/A':<14}")
+    else:
+        print(f"  {'Resolution':<12} {'CPU (PIL)':<14}")
+        print(f"  {'-'*30}")
+        for name, data in results.items():
+            cpu_ms = data["cpu"].mean_ms
+            print(f"  {name:<12} {cpu_ms:>8.1f} ms")
+
+    # Summary
+    if has_gpu:
+        speedups = []
+        for data in results.values():
+            if "gpu" in data:
+                speedups.append(data["cpu"].mean_ms / data["gpu"].mean_ms)
+        if speedups:
+            avg = np.mean(speedups)
+            print()
+            print(f"  {colored('→', Style.GREEN)} GPU preprocessing avg {colored(f'{avg:.1f}x', Style.GREEN, bold=True)} faster")
+
+
+def print_attention_results(results: Dict, device: torch.device):
+    """Print attention benchmark results."""
+    print_subheader("ATTENTION (per layer forward pass)")
+
+    print(f"  {'Config':<18} {'SDPA':<12} {'Manual':<12} {'Speedup':<10}")
+    print(f"  {'-'*52}")
+
+    for name, data in results.items():
+        sdpa_ms = data["sdpa"].mean_ms
+        manual_ms = data["manual"].mean_ms
+        speedup = manual_ms / sdpa_ms
+        print(f"  {name:<18} {sdpa_ms:>6.3f} ms    {manual_ms:>6.3f} ms    {format_speedup(speedup)}")
+
+    # Summary
+    speedups = [d["manual"].mean_ms / d["sdpa"].mean_ms for d in results.values()]
+    avg = np.mean(speedups)
+    print()
+    print(f"  {colored('→', Style.GREEN)} SDPA avg {colored(f'{avg:.1f}x', Style.GREEN, bold=True)} faster than manual")
+
+    # Check Flash SDP
+    if device.type == "cuda":
+        from torch.backends.cuda import flash_sdp_enabled
+        if flash_sdp_enabled():
+            print(f"  {colored('→', Style.GREEN)} Flash Attention: {colored('ENABLED', Style.GREEN, bold=True)} (PyTorch native)")
+
+
+def print_inference_matrix(results: Dict, device: torch.device):
+    """Print inference benchmark matrix."""
+    print_subheader("END-TO-END INFERENCE (720p input, batch=1)")
+
+    configs = get_optimization_configs(device)
+
+    # Header
+    header = f"  {'Model':<12}"
+    for cfg in configs:
+        header += f" {cfg.short_name:<14}"
+    header += " Best"
+    print(header)
+    print(f"  {'-'*(14 + 15*len(configs) + 6)}")
+
+    # Results per model
+    for model_name, model_results in results.items():
+        row = f"  {model_name:<12}"
+
+        best_fps = 0
+        best_config = None
+        worst_fps = float('inf')
+
+        for cfg in configs:
+            if cfg.name in model_results:
+                result = model_results[cfg.name]["result"]
+                fps = result.fps
+                row += f" {fps:>6.1f} img/s  "
+
+                if fps > best_fps:
+                    best_fps = fps
+                    best_config = cfg
+                if fps < worst_fps:
+                    worst_fps = fps
+            else:
+                row += f" {'N/A':<14}"
+
+        # Best indicator
+        if best_config:
+            row += f" {colored(best_config.short_name, Style.GREEN, bold=True)}"
+
+        print(row)
+
+    # Summary
+    print()
+    print(f"  {Style.DIM}Legend: GPU=NVJPEG decode, CPU=PIL decode, SDPA=Flash Attention{Style.RESET}")
+
+
+def print_device_summary(
+    device: torch.device,
+    preproc_results: Dict,
+    attn_results: Dict,
+    infer_results: Dict,
+):
+    """Print summary for a device."""
+    print()
+    print(colored("─" * 70, Style.CYAN))
+    print(colored(f" {device.type.upper()} - OPTIMIZATION SUMMARY", Style.BOLD))
+    print(colored("─" * 70, Style.CYAN))
+
+    # Best configuration
+    if infer_results:
+        print()
+        print(f"  {colored('Best configuration per model:', Style.CYAN)}")
+
+        for model_name, model_results in infer_results.items():
+            if not model_results:
+                continue
+
+            best_name = max(model_results.keys(), key=lambda k: model_results[k]["result"].fps)
+            best = model_results[best_name]
+            worst_name = min(model_results.keys(), key=lambda k: model_results[k]["result"].fps)
+            worst = model_results[worst_name]
+
+            speedup = best["result"].fps / worst["result"].fps if worst["result"].fps > 0 else 1
+
+            print(f"    {model_name:<12} {colored(best['config'].description, Style.GREEN)}")
+            print(f"    {'':<12} {best['result'].fps:.1f} img/s ({speedup:.1f}x vs worst)")
+
+    # Recommendations
+    print()
+    print(f"  {colored('Recommendations:', Style.CYAN)}")
+
+    if device.type == "cuda":
+        print(f"    ✓ Use {colored('GPU preprocessing (NVJPEG)', Style.GREEN)} for file inputs")
+        print(f"    ✓ {colored('SDPA (Flash Attention)', Style.GREEN)} is enabled by default")
+        print(f"    ✓ Pass file paths (not PIL images) to leverage NVJPEG")
+    elif device.type == "mps":
+        print(f"    ✓ Use {colored('CPU preprocessing', Style.GREEN)} (faster than GPU on MPS)")
+        print(f"    ✓ {colored('SDPA', Style.GREEN)} provides moderate speedup")
+    else:
+        print(f"    ✓ {colored('SDPA', Style.GREEN)} provides speedup over manual attention")
+        print(f"    ○ Consider using GPU (CUDA/MPS) for better performance")
+
+
+# ============================================================================
+# MAIN
+# ============================================================================
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="DA3 Full Benchmark - Test all optimization combinations",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python benchmarks/full_benchmark.py              # Best device only
+  python benchmarks/full_benchmark.py -d all       # All devices
+  python benchmarks/full_benchmark.py -d cuda      # CUDA only
+  python benchmarks/full_benchmark.py --quick      # Quick mode (fewer runs)
+  python benchmarks/full_benchmark.py --models da3-small da3-large
+        """
+    )
+    parser.add_argument("--quick", action="store_true", help="Quick mode (fewer runs)")
+    parser.add_argument("--skip-preprocessing", action="store_true", help="Skip preprocessing benchmark")
+    parser.add_argument("--skip-attention", action="store_true", help="Skip attention benchmark")
+    parser.add_argument("--skip-inference", action="store_true", help="Skip inference benchmark")
+    parser.add_argument("-d", "--device", type=str, default="auto",
+                       choices=["auto", "cpu", "mps", "cuda", "all"],
+                       help="Device to benchmark (default: auto)")
+    parser.add_argument("--models", nargs="+", default=None,
+                       help="Models to benchmark (default: all)")
+    args = parser.parse_args()
+
+    # Configure runs
+    runs_preproc = 3 if args.quick else 5
+    runs_attn = 5 if args.quick else 10
+    runs_infer = 2 if args.quick else 4
+
+    # Determine models
+    if args.models:
+        models = args.models
+    elif args.quick:
+        models = ["da3-small", "da3-large"]
+    else:
+        models = ["da3-small", "da3-base", "da3-large"]
+
+    # Determine devices
+    available_devices = get_available_devices()
+    if args.device == "auto":
+        devices_to_test = [available_devices[-1]]  # Best available
+    elif args.device == "all":
+        devices_to_test = available_devices
+    else:
+        requested = torch.device(args.device)
+        if requested in available_devices:
+            devices_to_test = [requested]
+        else:
+            print(f"Error: Device '{args.device}' not available.")
+            print(f"Available: {[d.type for d in available_devices]}")
+            return
+
+    # Main header
+    print()
+    print(colored("╔" + "═" * 68 + "╗", Style.CYAN))
+    print(colored("║", Style.CYAN) + colored(" DEPTH ANYTHING 3 - FULL BENCHMARK", Style.BOLD).center(77) + colored("║", Style.CYAN))
+    print(colored("║", Style.CYAN) + colored(" All Optimization Combinations", Style.DIM).center(77) + colored("║", Style.CYAN))
+    print(colored("╚" + "═" * 68 + "╝", Style.CYAN))
+
+    print(f"\n  {Style.DIM}PyTorch{Style.RESET}  : {colored(torch.__version__, Style.CYAN)}")
+    print(f"  {Style.DIM}Models{Style.RESET}   : {colored(', '.join(models), Style.CYAN)}")
+    print(f"  {Style.DIM}Mode{Style.RESET}     : {colored('Quick' if args.quick else 'Full', Style.CYAN)}")
+
+    print(f"\n  {Style.DIM}Available devices:{Style.RESET}")
+    for d in available_devices:
+        status = colored("●", Style.GREEN) if d in devices_to_test else colored("○", Style.DIM)
+        print(f"    {status} {d.type.upper():<6} {get_device_name(d)}")
+
+    all_results = {}
+
+    # Run benchmarks for each device
+    for device in devices_to_test:
+        device_name = get_device_name(device)
+        all_results[device.type] = {}
+
+        print_header(f"{device.type.upper()} - {device_name}")
+
+        # 1. Preprocessing
+        preproc_results = {}
+        if not args.skip_preprocessing and device.type != "cpu":
+            preproc_results = benchmark_preprocessing_detailed(device, runs=runs_preproc)
+            all_results[device.type]["preprocessing"] = preproc_results
+            print_preprocessing_results(preproc_results, device)
+        elif device.type == "cpu":
+            print_subheader("PREPROCESSING")
+            print(f"  {Style.DIM}Skipped (CPU only - no GPU comparison){Style.RESET}")
+
+        # 2. Attention
+        attn_results = {}
+        if not args.skip_attention:
+            attn_results = benchmark_attention_detailed(device, runs=runs_attn)
+            all_results[device.type]["attention"] = attn_results
+            print_attention_results(attn_results, device)
+
+        # 3. Inference Matrix
+        infer_results = {}
+        if not args.skip_inference:
+            infer_results = benchmark_inference_matrix(device, models, runs=runs_infer)
+            all_results[device.type]["inference"] = infer_results
+            print_inference_matrix(infer_results, device)
+
+        # Device Summary
+        print_device_summary(device, preproc_results, attn_results, infer_results)
+
+        cleanup()
+
+    # Cross-device comparison
+    if len(devices_to_test) > 1 and not args.skip_inference:
+        print_header("CROSS-DEVICE COMPARISON")
+
+        # Find common model
+        common_model = models[-1]  # Usually largest tested
+
+        print()
+        print(f"  {colored(f'{common_model} (best config per device):', Style.CYAN)}")
+        print(f"  {'Device':<10} {'Config':<30} {'Performance':<15}")
+        print(f"  {'-'*55}")
+
+        base_fps = None
+        for device in devices_to_test:
+            if device.type in all_results and "inference" in all_results[device.type]:
+                infer = all_results[device.type]["inference"].get(common_model, {})
+                if infer:
+                    best_name = max(infer.keys(), key=lambda k: infer[k]["result"].fps)
+                    best = infer[best_name]
+                    fps = best["result"].fps
+
+                    if base_fps is None:
+                        base_fps = fps
+
+                    speedup = fps / base_fps if base_fps else 1
+                    speedup_str = f"({speedup:.1f}x)" if device != devices_to_test[0] else "(baseline)"
+
+                    print(f"  {device.type.upper():<10} {best['config'].description:<30} {fps:>5.1f} img/s {speedup_str}")
+
+    # Final summary
+    print()
+    print(colored("═" * 70, Style.CYAN))
+    print(colored("║", Style.CYAN) + colored(" BENCHMARK COMPLETE", Style.BOLD).center(77) + colored("║", Style.CYAN))
+    print(colored("═" * 70, Style.CYAN))
+    print()
+
+
+if __name__ == "__main__":
+    main()

benchmarks/gpu_preprocessing_benchmark.py

@@ -0,0 +1,363 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025 Delanoe Pirard
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+GPU Preprocessing Benchmark
+
+Compares CPU vs GPU preprocessing performance across different image sizes.
+Measures:
+- Preprocessing time only
+- Total inference time (preprocessing + model forward)
+- Memory usage
+- Speedup percentages
+"""
+
+import time
+from typing import List, Tuple
+
+import numpy as np
+import torch
+from PIL import Image
+
+from depth_anything_3.utils.io.input_processor import InputProcessor
+from depth_anything_3.utils.io.gpu_input_processor import GPUInputProcessor
+
+
+import os
+import shutil
+
+def create_test_files(sizes: List[Tuple[int, int]], count: int = 4, temp_dir: str = "temp_bench_imgs") -> Tuple[List[List[str]], str]:
+    """Create test image files on disk.
+
+    Args:
+        sizes: List of (width, height) tuples
+        count: Number of images per size
+        temp_dir: Directory to save images
+
+    Returns:
+        List of image path batches, one per size
+        Path to temp directory
+    """
+    if os.path.exists(temp_dir):
+        shutil.rmtree(temp_dir)
+    os.makedirs(temp_dir)
+
+    batches = []
+    for w, h, _ in sizes:
+        batch = []
+        for i in range(count):
+            img = Image.new("RGB", (w, h), color=(i * 50, 100, 150))
+            fname = f"{temp_dir}/{w}x{h}_{i}.jpg"
+            img.save(fname, quality=95, subsampling=0)
+            batch.append(fname)
+        batches.append(batch)
+    return batches, temp_dir
+
+def benchmark_gpu_decode_files(
+    processor,
+    image_paths: List[str],
+    process_res: int = 504,
+    warmup_runs: int = 2,
+    benchmark_runs: int = 10,
+    num_workers: int = 8,
+) -> float:
+    """Benchmark GPU decoding (from file path)."""
+    # Warmup
+    for _ in range(warmup_runs):
+        processor(
+            image=image_paths,
+            process_res=process_res,
+            process_res_method="upper_bound_resize",
+            num_workers=num_workers,
+        )
+
+    # Benchmark
+    times = []
+    for _ in range(benchmark_runs):
+        if hasattr(processor, 'device') and processor.device.type == "cuda":
+            torch.cuda.synchronize()
+
+        start = time.perf_counter()
+        # Pass file paths directly to GPUInputProcessor
+        tensor, _, _ = processor(
+            image=image_paths,
+            process_res=process_res,
+            process_res_method="upper_bound_resize",
+            num_workers=num_workers,
+        )
+
+        if hasattr(processor, 'device') and processor.device.type == "cuda":
+            torch.cuda.synchronize()
+
+        elapsed = time.perf_counter() - start
+        times.append(elapsed)
+
+    return np.mean(times)
+
+def create_test_images(sizes: List[Tuple[int, int]], count: int = 4) -> List[List[Image.Image]]:
+    """Create test images for each size.
+
+    Args:
+        sizes: List of (width, height) tuples
+        count: Number of images per size
+
+    Returns:
+        List of image batches, one per size
+    """
+    batches = []
+    for w, h in sizes:
+        batch = [Image.new("RGB", (w, h), color=(i * 50, 100, 150)) for i in range(count)]
+        batches.append(batch)
+    return batches
+
+
+def benchmark_hybrid(
+    processor,
+    images: List[Image.Image],
+    process_res: int = 504,
+    warmup_runs: int = 2,
+    benchmark_runs: int = 10,
+    num_workers: int = 8,
+    device=torch.device("cuda")
+) -> float:
+    """Benchmark hybrid preprocessing (CPU resize -> GPU normalize)."""
+    
+    # Warmup
+    for _ in range(warmup_runs):
+        imgs_cpu, _, _ = processor(
+            image=images,
+            process_res=process_res,
+            process_res_method="upper_bound_resize",
+            num_workers=num_workers,
+            perform_normalization=False
+        )
+        imgs_gpu = imgs_cpu.to(device, non_blocking=True).float() / 255.0
+        _ = InputProcessor.normalize_tensor(imgs_gpu, mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])
+
+    # Benchmark
+    times = []
+    for _ in range(benchmark_runs):
+        if device.type == "cuda":
+            torch.cuda.synchronize()
+            
+        start = time.perf_counter()
+        
+        # 1. CPU Preprocessing (uint8)
+        imgs_cpu, _, _ = processor(
+            image=images,
+            process_res=process_res,
+            process_res_method="upper_bound_resize",
+            num_workers=num_workers,
+            perform_normalization=False
+        )
+        
+        # 2. Transfer + Normalize
+        imgs_gpu = imgs_cpu.to(device, non_blocking=True).float() / 255.0
+        _ = InputProcessor.normalize_tensor(imgs_gpu, mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])
+
+        if device.type == "cuda":
+            torch.cuda.synchronize()
+            
+        elapsed = time.perf_counter() - start
+        times.append(elapsed)
+        
+    return np.mean(times)
+
+def benchmark_preprocessing(
+    processor,
+    images: List[Image.Image],
+    process_res: int = 504,
+    warmup_runs: int = 2,
+    benchmark_runs: int = 10,
+    num_workers: int = 8,
+) -> float:
+    """Benchmark preprocessing performance.
+
+    Args:
+        processor: InputProcessor or GPUInputProcessor instance
+        images: List of test images
+        process_res: Processing resolution
+        warmup_runs: Number of warmup runs to discard
+        benchmark_runs: Number of benchmark runs to average
+        num_workers: Number of parallel workers (for CPU processor)
+
+    Returns:
+        Average preprocessing time in seconds
+    """
+    # Warmup
+    for _ in range(warmup_runs):
+        processor(
+            image=images,
+            process_res=process_res,
+            process_res_method="upper_bound_resize",
+            num_workers=num_workers,
+        )
+
+    # Benchmark
+    times = []
+    for _ in range(benchmark_runs):
+        if hasattr(processor, 'device') and processor.device.type == "cuda":
+            torch.cuda.synchronize()
+
+        start = time.perf_counter()
+        tensor, _, _ = processor(
+            image=images,
+            process_res=process_res,
+            process_res_method="upper_bound_resize",
+            num_workers=num_workers,
+        )
+
+        if hasattr(processor, 'device') and processor.device.type == "cuda":
+            torch.cuda.synchronize()
+
+        elapsed = time.perf_counter() - start
+        times.append(elapsed)
+
+    return np.mean(times)
+
+
+def print_results_table(results: List[dict]):
+    """Pretty print benchmark results as table."""
+    print("\n" + "=" * 140)
+    print("GPU PREPROCESSING BENCHMARK RESULTS")
+    print("=" * 140)
+    print(f"{'Image Size':<15} {'CPU Time':<12} {'GPU Time':<12} {'Hybrid Time':<12} {'GPU Decode':<12} {'Best Method':<15}")
+    print("-" * 140)
+
+    for result in results:
+        size_str = f"{result['width']}x{result['height']}"
+        cpu_time = f"{result['cpu_time']*1000:.2f} ms"
+        gpu_time = f"{result['gpu_time']*1000:.2f} ms"
+        hybrid_time = f"{result['hybrid_time']*1000:.2f} ms"
+        gpu_decode_time = f"{result['gpu_decode_time']*1000:.2f} ms"
+        
+        times = [result['cpu_time'], result['gpu_time'], result['hybrid_time'], result['gpu_decode_time']]
+        labels = ["CPU", "GPU", "Hybrid", "GPU Decode"]
+        best_idx = np.argmin(times)
+        best = labels[best_idx]
+
+        print(f"{size_str:<15} {cpu_time:<12} {gpu_time:<12} {hybrid_time:<12} {gpu_decode_time:<12} {best:<15}")
+
+    print("=" * 140 + "\n")
+
+
+def main():
+    """Run comprehensive benchmark."""
+    print("\n" + "=" * 100)
+    print("INITIALIZING GPU PREPROCESSING BENCHMARK")
+    print("=" * 100)
+
+    # Check GPU availability
+    if torch.cuda.is_available():
+        device_name = "cuda"
+        device_info = torch.cuda.get_device_name(0)
+        print(f"✓ GPU Device: {device_info}")
+        print("✓ GPU preprocessing: ENABLED (NVJPEG + Kornia)")
+    elif torch.backends.mps.is_available():
+        device_name = "mps"
+        device_info = "Apple MPS"
+        print(f"✓ GPU Device: {device_info}")
+        print("ℹ GPU preprocessing: DISABLED on MPS (CPU is faster on Apple Silicon)")
+        print("  → GPUInputProcessor will use CPU path automatically")
+        print("  → GPU reserved for model inference (5-10x speedup there)")
+    else:
+        print("✗ No GPU available - benchmark will show CPU vs CPU (no speedup expected)")
+        device_name = "cpu"
+        device_info = "CPU only"
+
+    device = torch.device(device_name)
+
+    # Create processors
+    cpu_proc = InputProcessor()
+    gpu_proc = GPUInputProcessor(device=device_name)
+    print(f"✓ Processors initialized: CPU vs {device_name.upper()}")
+
+    # Test configurations
+    # Format: (width, height, description)
+    test_sizes = [
+        (640, 480, "Small (VGA)"),
+        (1280, 720, "Medium (HD)"),
+        (1920, 1080, "Large (Full HD)"),
+        (3840, 2160, "XLarge (4K)"),
+    ]
+
+    process_res = 504
+    num_images = 4
+    num_workers = 8
+
+    print(f"✓ Test config: {num_images} images per batch, process_res={process_res}, num_workers={num_workers}")
+    print(f"✓ Testing {len(test_sizes)} image sizes: {', '.join([desc for _, _, desc in test_sizes])}")
+
+    # Create test images
+    print("\nGenerating test images (PIL & Files)...")
+    image_batches_pil = create_test_images([(w, h) for w, h, _ in test_sizes], count=num_images)
+    image_batches_files, temp_dir = create_test_files(test_sizes, count=num_images)
+    print("✓ Test images generated")
+
+    # Run benchmarks
+    print("\nRunning benchmarks (this may take a minute)...\n")
+    results = []
+
+    try:
+        for (w, h, desc), imgs_pil, imgs_files in zip(test_sizes, image_batches_pil, image_batches_files):
+            print(f"Benchmarking {desc} ({w}x{h})...", end=" ", flush=True)
+
+            cpu_time = benchmark_preprocessing(cpu_proc, imgs_pil, process_res, num_workers=num_workers)
+            gpu_time = benchmark_preprocessing(gpu_proc, imgs_pil, process_res, num_workers=num_workers)
+            hybrid_time = benchmark_hybrid(cpu_proc, imgs_pil, process_res, num_workers=num_workers, device=device)
+            
+            # GPU Decode uses file paths
+            gpu_decode_time = benchmark_gpu_decode_files(gpu_proc, imgs_files, process_res, num_workers=num_workers)
+
+            results.append({
+                'width': w,
+                'height': h,
+                'description': desc,
+                'cpu_time': cpu_time,
+                'gpu_time': gpu_time,
+                'hybrid_time': hybrid_time,
+                'gpu_decode_time': gpu_decode_time
+            })
+            
+            best_time = min(cpu_time, gpu_time, hybrid_time, gpu_decode_time)
+            if best_time == gpu_decode_time:
+                win = "GPU Decode"
+            elif best_time == hybrid_time:
+                win = "Hybrid"
+            elif best_time == gpu_time:
+                win = "GPU"
+            else:
+                win = "CPU"
+
+            print(f"✓ Best: {win}")
+
+        # Print results table
+        print_results_table(results)
+
+        # Memory info (CUDA only)
+        if device_name == "cuda":
+            print("\nGPU Memory Usage:")
+            print(f"  Allocated: {torch.cuda.memory_allocated(0) / 1024**2:.1f} MB")
+            print(f"  Cached: {torch.cuda.memory_reserved(0) / 1024**2:.1f} MB")
+    
+    finally:
+        # Cleanup
+        if os.path.exists(temp_dir):
+            shutil.rmtree(temp_dir)
+            print(f"\n✓ Cleaned up temp directory: {temp_dir}")
+
+if __name__ == "__main__":
+    main()
+

docs/API.md

@@ -0,0 +1,465 @@
+# 📚 DepthAnything3 API Documentation
+
+## 📑 Table of Contents
+
+1. [📖 Overview](#overview)
+2. [💡 Usage Examples](#usage-examples)
+3. [🔧 Core API](#core-api)
+   - [DepthAnything3 Class](#depthanything3-class)
+   - [inference() Method](#inference-method)
+4. [⚙️ Parameters](#parameters)
+   - [Input Parameters](#input-parameters)
+   - [Pose Alignment Parameters](#pose-alignment-parameters)
+   - [Feature Export Parameters](#feature-export-parameters)
+   - [Rendering Parameters](#rendering-parameters)
+   - [Processing Parameters](#processing-parameters)
+   - [Export Parameters](#export-parameters)
+5. [📤 Export Formats](#export-formats)
+6. [↩️ Return Value](#return-value)
+
+## 📖 Overview
+
+This documentation provides comprehensive API reference for DepthAnything3, including usage examples, parameter specifications, export formats, and advanced features. It covers both basic pose and depth estimation workflows and advanced pose-conditioned processing with multiple export capabilities.
+
+## 💡 Usage Examples
+
+Here are quick examples to get you started:
+
+### 🚀 Basic Depth Estimation
+```python
+from depth_anything_3.api import DepthAnything3
+
+# Initialize and run inference
+model = DepthAnything3.from_pretrained("depth-anything/DA3NESTED-GIANT-LARGE").to("cuda")
+prediction = model.inference(["image1.jpg", "image2.jpg"])
+```
+
+### 📷 Pose-Conditioned Depth Estimation
+```python
+import numpy as np
+
+# With camera parameters for better consistency
+prediction = model.inference(
+    image=["image1.jpg", "image2.jpg"],
+    extrinsics=extrinsics_array,  # (N, 4, 4)
+    intrinsics=intrinsics_array   # (N, 3, 3)
+)
+```
+
+### 📤 Export Results
+```python
+# Export depth data and 3D visualization
+prediction = model.inference(
+    image=image_paths,
+    export_dir="./output",
+    export_format="mini_npz-glb"
+)
+```
+
+### 🔍 Feature Extraction
+```python
+# Export intermediate features from specific layers
+prediction = model.inference(
+    image=image_paths,
+    export_dir="./output",
+    export_format="feat_vis",
+    export_feat_layers=[0, 1, 2]  # Export features from layers 0, 1, 2
+)
+```
+
+### ✨ Advanced Export with Gaussian Splatting
+```python
+# Export multiple formats including Gaussian Splatting
+# Note: infer_gs=True requires da3-giant or da3nested-giant-large model
+model = DepthAnything3(model_name="da3-giant").to("cuda")
+
+prediction = model.inference(
+    image=image_paths,
+    extrinsics=extrinsics_array,
+    intrinsics=intrinsics_array,
+    export_dir="./output",
+    export_format="npz-glb-gs_ply-gs_video",
+    align_to_input_ext_scale=True,
+    infer_gs=True,  # Required for gs_ply and gs_video exports
+)
+```
+
+### 🎨 Advanced Export with Feature Visualization
+```python
+# Export with intermediate feature visualization
+prediction = model.inference(
+    image=image_paths,
+    export_dir="./output",
+    export_format="mini_npz-glb-depth_vis-feat_vis",
+    export_feat_layers=[0, 5, 10, 15, 20],
+    feat_vis_fps=30,
+)
+```
+
+### 📐 Using Ray-Based Pose Estimation
+```python
+# Use ray-based pose estimation instead of camera decoder
+prediction = model.inference(
+    image=image_paths,
+    export_dir="./output",
+    export_format="glb",
+    use_ray_pose=True,  # Enable ray-based pose estimation
+)
+```
+
+### 🎯 Reference View Selection
+```python
+# For multi-view inputs, automatically select the best reference view
+prediction = model.inference(
+    image=image_paths,
+    ref_view_strategy="saddle_balanced",  # Default: balanced selection
+)
+
+# For video sequences, use middle frame as reference
+prediction = model.inference(
+    image=video_frames,
+    ref_view_strategy="middle",  # Good for temporally ordered inputs
+)
+```
+
+## 🔧 Core API
+
+### 🔨 DepthAnything3 Class
+
+The main API class that provides depth estimation capabilities with optional pose conditioning.
+
+#### 🎯 Initialization
+
+```python
+from depth_anything_3 import DepthAnything3
+
+# Initialize the model with a model name
+model = DepthAnything3(model_name="da3-large")
+model = model.to("cuda")  # Move to GPU
+```
+
+**Parameters:**
+- `model_name` (str, default: "da3-large"): The name of the model preset to use.
+  - **Available models:**
+    - 🦾 `"da3-giant"` - 1.15B params, any-view model with GS support
+    - ⭐ `"da3-large"` - 0.35B params, any-view model (recommended for most use cases)
+    - 📦 `"da3-base"` - 0.12B params, any-view model
+    - 🪶 `"da3-small"` - 0.08B params, any-view model
+    - 👁️ `"da3mono-large"` - 0.35B params, monocular depth only
+    - 📏 `"da3metric-large"` - 0.35B params, metric depth with sky segmentation
+    - 🎯 `"da3nested-giant-large"` - 1.40B params, nested model with all features
+
+### 🚀 inference() Method
+
+The primary inference method that processes images and returns depth predictions.
+
+```python
+prediction = model.inference(
+    image=image_list,
+    extrinsics=extrinsics_array,      # Optional
+    intrinsics=intrinsics_array,      # Optional
+    align_to_input_ext_scale=True,   # Whether to align predicted poses to input scale
+    infer_gs=True,                   # Enable Gaussian branch for gs exports
+    use_ray_pose=False,              # Use ray-based pose estimation instead of camera decoder
+    ref_view_strategy="saddle_balanced",  # Reference view selection strategy
+    render_exts=render_extrinsics,    # Optional renders for gs_video
+    render_ixts=render_intrinsics,    # Optional renders for gs_video
+    render_hw=(height, width),        # Optional renders for gs_video
+    process_res=504,
+    process_res_method="upper_bound_resize",
+    export_dir="output_directory",    # Optional
+    export_format="mini_npz",
+    export_feat_layers=[],            # List of layer indices to export features from
+    conf_thresh_percentile=40.0,      # Confidence threshold percentile for depth map in GLB export
+    num_max_points=1_000_000,         # Maximum number of points to export in GLB export
+    show_cameras=True,                # Whether to show cameras in GLB export
+    feat_vis_fps=15,                  # Frames per second for feature visualization in feat_vis export
+    export_kwargs={}                  # Optional, additional arguments to export functions. export_format:key:val, see 'Parameters/Export Parameters' for details
+)
+```
+
+## ⚙️ Parameters
+
+### 📸 Input Parameters
+
+#### `image` (required)
+- **Type**: `List[Union[np.ndarray, Image.Image, str]]`
+- **Description**: List of input images. Can be numpy arrays, PIL Images, or file paths.
+- **Example**:
+  ```python
+  # From file paths
+  image = ["image1.jpg", "image2.jpg", "image3.jpg"]
+
+  # From numpy arrays
+  image = [np.array(img1), np.array(img2)]
+
+  # From PIL Images
+  image = [Image.open("image1.jpg"), Image.open("image2.jpg")]
+  ```
+
+#### `extrinsics` (optional)
+- **Type**: `Optional[np.ndarray]`
+- **Shape**: `(N, 4, 4)` where N is the number of input images
+- **Description**: Camera extrinsic matrices (world-to-camera transformation). When provided, enables pose-conditioned depth estimation mode.
+- **Note**: If not provided, the model operates in standard depth estimation mode.
+
+#### `intrinsics` (optional)
+- **Type**: `Optional[np.ndarray]`
+- **Shape**: `(N, 3, 3)` where N is the number of input images
+- **Description**: Camera intrinsic matrices containing focal length and principal point information. When provided, enables pose-conditioned depth estimation mode.
+
+### 🎯 Pose Alignment Parameters
+
+#### `align_to_input_ext_scale` (default: True)
+- **Type**: `bool`
+- **Description**: When True the predicted extrinsics are replaced with the input
+  ones and the depth maps are rescaled to match their metric scale. When False the
+  function returns the internally aligned poses computed via Umeyama alignment.
+
+#### `infer_gs` (default: False)
+- **Type**: `bool`
+- **Description**: Enable Gaussian Splatting branch for gaussian splatting exports. Required when using `gs_ply` or `gs_video` export formats.
+
+#### `use_ray_pose` (default: False)
+- **Type**: `bool`
+- **Description**: Use ray-based pose estimation instead of camera decoder for pose prediction. When True, the model uses ray prediction heads to estimate camera poses; when False, it uses the camera decoder approach.
+
+#### `ref_view_strategy` (default: "saddle_balanced")
+- **Type**: `str`
+- **Description**: Strategy for selecting the reference view from multiple input views. Options: `"first"`, `"middle"`, `"saddle_balanced"`, `"saddle_sim_range"`. Only applied when number of views ≥ 3. See [detailed documentation](funcs/ref_view_strategy.md) for strategy comparisons.
+- **Available strategies**:
+  - `"saddle_balanced"`: Selects view with balanced features across multiple metrics (recommended default)
+  - `"saddle_sim_range"`: Selects view with largest similarity range
+  - `"first"`: Always uses first view (not recommended, equivalent to no reordering for views < 3)
+  - `"middle"`: Uses middle view (recommended for video sequences)
+
+### 🔍 Feature Export Parameters
+
+#### `export_feat_layers` (default: [])
+- **Type**: `List[int]`
+- **Description**: List of layer indices to export intermediate features from. Features are stored in the `aux` dictionary of the Prediction object with keys like `feat_layer_0`, `feat_layer_1`, etc.
+
+### 🎥 Rendering Parameters
+
+These arguments are only used when exporting Gaussian-splatting videos (include
+`"gs_video"` in `export_format`). They describe an auxiliary camera trajectory
+with ``M`` views.
+
+#### `render_exts` (optional)
+- **Type**: `Optional[np.ndarray]`
+- **Shape**: `(M, 4, 4)`
+- **Description**: Camera extrinsics for the synthesized trajectory. If omitted,
+  the exporter falls back to the predicted poses.
+
+#### `render_ixts` (optional)
+- **Type**: `Optional[np.ndarray]`
+- **Shape**: `(M, 3, 3)`
+- **Description**: Camera intrinsics for each rendered frame. Leave `None` to
+  reuse the input intrinsics.
+
+#### `render_hw` (optional)
+- **Type**: `Optional[Tuple[int, int]]`
+- **Description**: Explicit output resolution `(height, width)` for the rendered
+  frames. Defaults to the input resolution when not provided.
+
+### ⚡ Processing Parameters
+
+#### `process_res` (default: 504)
+- **Type**: `int`
+- **Description**: Base resolution for processing. The model will resize images to this resolution for inference.
+
+#### `process_res_method` (default: "upper_bound_resize")
+- **Type**: `str`
+- **Description**: Method for resizing images to the target resolution.
+- **Options**:
+  - `"upper_bound_resize"`: Resize so that the specified dimension (504) becomes the longer side
+  - `"lower_bound_resize"`: Resize so that the specified dimension (504) becomes the shorter side
+- **Example**:
+  - Input: 1200×1600 → Output: 378×504 (with `process_res=504`, `process_res_method="upper_bound_resize"`)
+  - Input: 504×672 → Output: 504×672 (no change needed)
+
+### 📦 Export Parameters
+
+#### `export_dir` (optional)
+- **Type**: `Optional[str]`
+- **Description**: Directory path where exported files will be saved. If not provided, no files will be exported.
+
+#### `export_format` (default: "mini_npz")
+- **Type**: `str`
+- **Description**: Format for exporting results. Supports multiple formats separated by `-`.
+- **Example**: `"mini_npz-glb"` exports both mini_npz and glb formats.
+
+#### 🌐 GLB Export Parameters
+
+These parameters are passed directly to the `inference()` method and only apply when `export_format` includes `"glb"`.
+
+##### `conf_thresh_percentile` (default: 40.0)
+- **Type**: `float`
+- **Description**: Lower percentile for adaptive confidence threshold. Points below this confidence percentile will be filtered out from the point cloud.
+
+##### `num_max_points` (default: 1,000,000)
+- **Type**: `int`
+- **Description**: Maximum number of points in the exported point cloud. If the point cloud exceeds this limit, it will be downsampled.
+
+##### `show_cameras` (default: True)
+- **Type**: `bool`
+- **Description**: Whether to include camera wireframes in the exported GLB file for visualization.
+
+#### 🎨 Feature Visualization Parameters
+
+These parameters are passed directly to the `inference()` method and only apply when `export_format` includes `"feat_vis"`.
+
+##### `feat_vis_fps` (default: 15)
+- **Type**: `int`
+- **Description**: Frame rate for the output video when visualizing features across multiple images.
+
+#### ✨🎥 3DGS and 3DGS Video Parameters
+
+These parameters are passed directly to the `inference()` method and only apply when `export_format` includes `"gs_ply"` or `"gs_video"`.
+
+##### `export_kwargs` (default: `{}`)
+- Type: `dict[str, dict[str, Any]]`
+- Description: Per-format extra arguments passed to export functions, mainly for `"gs_ply"` and `"gs_video"`.
+  - Access pattern: `export_kwargs[export_format][key] = value`
+  - Example:
+    ```python
+    {
+        "gs_ply": {
+            "gs_views_interval": 1,
+        },
+        "gs_video": {
+            "trj_mode": "interpolate_smooth",
+            "chunk_size": 1,
+            "vis_depth": None,
+        },
+    }
+    ```
+
+## 📤 Export Formats
+
+The API supports multiple export formats for different use cases:
+
+### 📊 `mini_npz`
+- **Description**: Minimal NPZ format containing essential data
+- **Contents**: `depth`, `conf`, `exts`, `ixts`
+- **Use case**: Lightweight storage for depth data with camera parameters
+
+### 📦 `npz`
+- **Description**: Full NPZ format with comprehensive data
+- **Contents**: `depth`, `conf`, `exts`, `ixts`, `image`, etc.
+- **Use case**: Complete data export for advanced processing
+
+### 🌐 `glb`
+- **Description**: 3D visualization format with point cloud and camera poses
+- **Contents**:
+  - Point cloud with colors from original images
+  - Camera wireframes for visualization
+  - Confidence-based filtering and downsampling
+- **Use case**: 3D visualization, inspection, and analysis
+- **Features**:
+  - Automatic sky depth handling
+  - Confidence threshold filtering
+  - Background filtering (black/white)
+  - Scene scale normalization
+- **Parameters** (passed via `inference()` method directly):
+  - `conf_thresh_percentile` (float, default: 40.0): Lower percentile for adaptive confidence threshold. Points below this confidence percentile will be filtered out.
+  - `num_max_points` (int, default: 1,000,000): Maximum number of points in the exported point cloud. If exceeded, points will be downsampled.
+  - `show_cameras` (bool, default: True): Whether to include camera wireframes in the exported GLB file for visualization.
+
+### ✨ `gs_ply`
+- **Description**: Gaussian Splatting point cloud format
+- **Contents**: 3DGS data in PLY format. Compatible with standard 3DGS viewers such as [SuperSplat](https://superspl.at/editor) (recommended), [SPARK](https://sparkjs.dev/viewer/).
+- **Use case**: Gaussian Splatting reconstruction
+- **Requirements**: Must set `infer_gs=True` when calling `inference()`. Only supported by `da3-giant` and `da3nested-giant-large` models.
+- **Additional configs**, provided via `export_kwargs` (see [Export Parameters](#export-parameters)):
+  - `gs_views_interval`: Export to 3DGS every N views, default: `1`.
+
+### 🎥 `gs_video`
+- **Description**: Rasterized 3DGS to obtain videos
+- **Contents**: A video of 3DGS-rasterized views using either provided viewpoints or a predefined camera trajectory.
+- **Use case**: Video rendering for Gaussian Splatting
+- **Requirements**: Must set `infer_gs=True` when calling `inference()`. Only supported by `da3-giant` and `da3nested-giant-large` models.
+- **Note**: Can optionally use `render_exts`, `render_ixts`, and `render_hw` parameters in `inference()` method to specify novel viewpoints.
+- **Additional configs**, provided via `export_kwargs` (see [Export Parameters](#export-parameters)):
+  - `extrinsics`: Optional world-to-camera poses for novel views. Falls back to the predicted poses of input views if not provided. (Alternatively, use `render_exts` parameter in `inference()`)
+  - `intrinsics`: Optional camera intrinsics for novel views. Falls back to the predicted intrinsics of input views if not provided. (Alternatively, use `render_ixts` parameter in `inference()`)
+  - `out_image_hw`: Optional output resolution `H x W`. Falls back to input resolution if not provided. (Alternatively, use `render_hw` parameter in `inference()`)
+  - `chunk_size`: Number of views rasterized per batch. Default: `8`.
+  - `trj_mode`: Predefined camera trajectory for novel-view rendering.
+  - `color_mode`: Same as `render_mode` in [gsplat](https://docs.gsplat.studio/main/apis/rasterization.html#gsplat.rasterization).
+  - `vis_depth`: How depth is combined with RGB. Default: `hcat` (horizontal concatenation).
+  - `enable_tqdm`: Whether to display a tqdm progress bar during rendering.
+  - `output_name`: File name of the rendered video.
+  - `video_quality`: Video quality to save. Default: `high`.
+    - `high`: High quality video (default)
+    - `medium`: Medium quality video (balance of storage space and quality)
+    - `low`: Low quality video (fewer storage space)
+
+### 🔍 `feat_vis`
+- **Description**: Feature visualization format
+- **Contents**: PCA-visualized intermediate features from specified layers
+- **Use case**: Model interpretability and feature analysis
+- **Note**: Requires `export_feat_layers` to be specified
+- **Parameters** (passed via `inference()` method directly):
+  - `feat_vis_fps` (int, default: 15): Frame rate for the output video when visualizing features across multiple images.
+
+### 🎨 `depth_vis`
+- **Description**: Depth visualization format
+- **Contents**: Color-coded depth maps alongside original images
+- **Use case**: Visual inspection of depth estimation quality
+
+### 🔗 Multiple Format Export
+You can export multiple formats simultaneously by separating them with `-`:
+
+```python
+# Export both mini_npz and glb formats
+export_format = "mini_npz-glb"
+
+# Export multiple formats
+export_format = "npz-glb-gs_ply"
+```
+
+## ↩️ Return Value
+
+The `inference()` method returns a `Prediction` object with the following attributes:
+
+### 📊 Core Outputs
+
+- **depth**: `np.ndarray` - Estimated depth maps with shape `(N, H, W)` where N is the number of images, H is height, and W is width.
+- **conf**: `np.ndarray` - Confidence maps with shape `(N, H, W)` indicating prediction reliability (optional, depends on model).
+
+### 📷 Camera Parameters
+
+- **extrinsics**: `np.ndarray` - Camera extrinsic matrices with shape `(N, 3, 4)` representing world-to-camera transformations. Only present if camera poses were estimated or provided as input.
+- **intrinsics**: `np.ndarray` - Camera intrinsic matrices with shape `(N, 3, 3)` containing focal length and principal point information. Only present if poses were estimated or provided as input.
+
+### 🎁 Additional Outputs
+
+- **processed_images**: `np.ndarray` - Preprocessed input images with shape `(N, H, W, 3)` in RGB format (0-255 uint8).
+- **aux**: `dict` - Auxiliary outputs including:
+  - `feat_layer_X`: Intermediate features from layer X (if `export_feat_layers` was specified)
+  - `gaussians`: 3D Gaussian Splats data (if `infer_gs=True`)
+
+### 💻 Usage Example
+
+```python
+prediction = model.inference(image=["img1.jpg", "img2.jpg"])
+
+# Access depth maps
+depth_maps = prediction.depth  # shape: (2, H, W)
+
+# Access confidence
+if hasattr(prediction, 'conf'):
+    confidence = prediction.conf
+
+# Access camera parameters (if available)
+if hasattr(prediction, 'extrinsics'):
+    camera_poses = prediction.extrinsics  # shape: (2, 4, 4)
+
+if hasattr(prediction, 'intrinsics'):
+    camera_intrinsics = prediction.intrinsics  # shape: (2, 3, 3)
+
+# Access intermediate features (if export_feat_layers was set)
+if hasattr(prediction, 'aux') and 'feat_layer_0' in prediction.aux:
+    features = prediction.aux['feat_layer_0']
+```

docs/CLI.md

@@ -0,0 +1,654 @@
+# 🚀 Depth Anything 3 Command Line Interface
+
+## 📋 Table of Contents
+
+- [📖 Overview](#overview)
+- [⚡ Quick Start](#quick-start)
+- [📚 Command Reference](#command-reference)
+  - [🤖 auto - Auto Mode](#auto---auto-mode)
+  - [🖼️ image - Single Image Processing](#image---single-image-processing)
+  - [🗂️ images - Image Directory Processing](#images---image-directory-processing)
+  - [🎬 video - Video Processing](#video---video-processing)
+  - [📐 colmap - COLMAP Dataset Processing](#colmap---colmap-dataset-processing)
+  - [🔧 backend - Backend Service](#backend---backend-service)
+  - [🎨 gradio - Gradio Application](#gradio---gradio-application)
+  - [🖼️ gallery - Gallery Server](#gallery---gallery-server)
+- [⚙️ Parameter Details](#parameter-details)
+- [💡 Usage Examples](#usage-examples)
+
+## 📖 Overview
+
+The Depth Anything 3 CLI provides a comprehensive command-line toolkit supporting image depth estimation, video processing, COLMAP dataset handling, and web applications.
+
+The backend service enables cache model to GPU so that we do not need to reload model for each command.
+
+## ⚡ Quick Start
+
+The CLI can run fully offline or connect to the backend for cached weights and task scheduling:
+
+```bash
+# 🔧 Start backend service (optional, keeps model resident in GPU memory)
+da3 backend --model-dir depth-anything/DA3NESTED-GIANT-LARGE
+
+# 🚀 Use auto mode to process input
+da3 auto path/to/input --export-dir ./workspace/scene001
+
+# ♻️ Reuse backend for next job
+da3 auto path/to/video.mp4 \
+    --export-dir ./workspace/scene002 \
+    --use-backend \
+    --backend-url http://localhost:8008
+```
+
+Each export directory contains `scene.glb`, `scene.jpg`, and optional extras such as `depth_vis/` or `gs_video/` depending on the requested format.
+
+## 📚 Command Reference
+
+### 🤖 auto - Auto Mode
+
+Automatically detect input type and dispatch to the appropriate handler.
+
+**Usage:**
+
+```bash
+da3 auto INPUT_PATH [OPTIONS]
+```
+
+**Input Type Detection:**
+- 🖼️ Single image file (.jpg, .png, .jpeg, .webp, .bmp, .tiff, .tif)
+- 📁 Image directory
+- 🎬 Video file (.mp4, .avi, .mov, .mkv, .flv, .wmv, .webm, .m4v)
+- 📐 COLMAP directory (containing `images/` and `sparse/` subdirectories)
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `INPUT_PATH` | str | Required | Input path (image, directory, video, or COLMAP) |
+| `--model-dir` | str | Default model | Model directory path |
+| `--export-dir` | str | `debug` | Export directory |
+| `--export-format` | str | `glb` | Export format (supports `mini_npz`, `glb`, `feat_vis`, etc., can be combined with hyphens) |
+| `--device` | str | `cuda` | Device to use |
+| `--use-backend` | bool | `False` | Use backend service for inference |
+| `--backend-url` | str | `http://localhost:8008` | Backend service URL |
+| `--process-res` | int | `504` | Processing resolution |
+| `--process-res-method` | str | `upper_bound_resize` | Processing resolution method |
+| `--export-feat` | str | `""` | Export features from specified layers, comma-separated (e.g., `"0,1,2"`) |
+| `--auto-cleanup` | bool | `False` | Automatically clean export directory without confirmation |
+| `--fps` | float | `1.0` | [Video] Frame sampling FPS |
+| `--sparse-subdir` | str | `""` | [COLMAP] Sparse reconstruction subdirectory (e.g., `"0"` for `sparse/0/`) |
+| `--align-to-input-ext-scale` | bool | `True` | [COLMAP] Align prediction to input extrinsics scale |
+| `--use-ray-pose` | bool | `False` | Use ray-based pose estimation instead of camera decoder |
+| `--ref-view-strategy` | str | `saddle_balanced` | Reference view selection strategy: `first`, `middle`, `saddle_balanced`, `saddle_sim_range`. See [docs](funcs/ref_view_strategy.md) |
+| `--conf-thresh-percentile` | float | `40.0` | [GLB] Lower percentile for adaptive confidence threshold |
+| `--num-max-points` | int | `1000000` | [GLB] Maximum number of points in the point cloud |
+| `--show-cameras` | bool | `True` | [GLB] Show camera wireframes in the exported scene |
+| `--feat-vis-fps` | int | `15` | [FEAT_VIS] Frame rate for output video |
+
+**Examples:**
+
+```bash
+# 🖼️ Auto-process an image
+da3 auto path/to/image.jpg --export-dir ./output
+
+# 🎬 Auto-process a video
+da3 auto path/to/video.mp4 --fps 2.0 --export-dir ./output
+
+# 🔧 Use backend service
+da3 auto path/to/input \
+    --export-format mini_npz-glb \
+    --use-backend \
+    --backend-url http://localhost:8008 \
+    --export-dir ./output
+```
+
+---
+
+### 🖼️ image - Single Image Processing
+
+Process a single image for camera pose and depth estimation.
+
+**Usage:**
+
+```bash
+da3 image IMAGE_PATH [OPTIONS]
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `IMAGE_PATH` | str | Required | Input image file path |
+| `--model-dir` | str | Default model | Model directory path |
+| `--export-dir` | str | `debug` | Export directory |
+| `--export-format` | str | `glb` | Export format |
+| `--device` | str | `cuda` | Device to use |
+| `--use-backend` | bool | `False` | Use backend service for inference |
+| `--backend-url` | str | `http://localhost:8008` | Backend service URL |
+| `--process-res` | int | `504` | Processing resolution |
+| `--process-res-method` | str | `upper_bound_resize` | Processing resolution method |
+| `--export-feat` | str | `""` | Export feature layer indices (comma-separated) |
+| `--auto-cleanup` | bool | `False` | Automatically clean export directory |
+| `--use-ray-pose` | bool | `False` | Use ray-based pose estimation instead of camera decoder |
+| `--ref-view-strategy` | str | `saddle_balanced` | Reference view selection strategy. See [docs](funcs/ref_view_strategy.md) |
+| `--conf-thresh-percentile` | float | `40.0` | [GLB] Confidence threshold percentile |
+| `--num-max-points` | int | `1000000` | [GLB] Maximum number of points |
+| `--show-cameras` | bool | `True` | [GLB] Show cameras |
+| `--feat-vis-fps` | int | `15` | [FEAT_VIS] Video frame rate |
+
+**Examples:**
+
+```bash
+# ✨ Basic usage
+da3 image path/to/image.png --export-dir ./output
+
+# ⚡ With backend acceleration
+da3 image path/to/image.png \
+    --use-backend \
+    --backend-url http://localhost:8008 \
+    --export-dir ./output
+
+# 🔍 Export feature visualization
+da3 image image.jpg \
+    --export-format feat_vis \
+    --export-feat "9,19,29,39" \
+    --export-dir ./results
+```
+
+---
+
+### 🗂️ images - Image Directory Processing
+
+Process a directory of images for batch depth estimation.
+
+**Usage:**
+
+```bash
+da3 images IMAGES_DIR [OPTIONS]
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `IMAGES_DIR` | str | Required | Directory path containing images |
+| `--image-extensions` | str | `png,jpg,jpeg` | Image file extensions to process (comma-separated) |
+| `--model-dir` | str | Default model | Model directory path |
+| `--export-dir` | str | `debug` | Export directory |
+| `--export-format` | str | `glb` | Export format |
+| `--device` | str | `cuda` | Device to use |
+| `--use-backend` | bool | `False` | Use backend service for inference |
+| `--backend-url` | str | `http://localhost:8008` | Backend service URL |
+| `--process-res` | int | `504` | Processing resolution |
+| `--process-res-method` | str | `upper_bound_resize` | Processing resolution method |
+| `--export-feat` | str | `""` | Export feature layer indices |
+| `--auto-cleanup` | bool | `False` | Automatically clean export directory |
+| `--use-ray-pose` | bool | `False` | Use ray-based pose estimation instead of camera decoder |
+| `--ref-view-strategy` | str | `saddle_balanced` | Reference view selection strategy. See [docs](funcs/ref_view_strategy.md) |
+| `--conf-thresh-percentile` | float | `40.0` | [GLB] Confidence threshold percentile |
+| `--num-max-points` | int | `1000000` | [GLB] Maximum number of points |
+| `--show-cameras` | bool | `True` | [GLB] Show cameras |
+| `--feat-vis-fps` | int | `15` | [FEAT_VIS] Video frame rate |
+
+**Examples:**
+
+```bash
+# 📁 Process directory (defaults to png/jpg/jpeg)
+da3 images ./image_folder --export-dir ./output
+
+# 🎯 Custom extensions
+da3 images ./dataset --image-extensions "png,jpg,webp" --export-dir ./output
+
+# 🔧 Use backend service
+da3 images ./dataset \
+    --use-backend \
+    --backend-url http://localhost:8008 \
+    --export-dir ./output
+```
+
+---
+
+### 🎬 video - Video Processing
+
+Process video by extracting frames for depth estimation.
+
+**Usage:**
+
+```bash
+da3 video VIDEO_PATH [OPTIONS]
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `VIDEO_PATH` | str | Required | Input video file path |
+| `--fps` | float | `1.0` | Frame extraction sampling FPS |
+| `--model-dir` | str | Default model | Model directory path |
+| `--export-dir` | str | `debug` | Export directory |
+| `--export-format` | str | `glb` | Export format |
+| `--device` | str | `cuda` | Device to use |
+| `--use-backend` | bool | `False` | Use backend service for inference |
+| `--backend-url` | str | `http://localhost:8008` | Backend service URL |
+| `--process-res` | int | `504` | Processing resolution |
+| `--process-res-method` | str | `upper_bound_resize` | Processing resolution method |
+| `--export-feat` | str | `""` | Export feature layer indices |
+| `--auto-cleanup` | bool | `False` | Automatically clean export directory |
+| `--use-ray-pose` | bool | `False` | Use ray-based pose estimation instead of camera decoder |
+| `--ref-view-strategy` | str | `saddle_balanced` | Reference view selection strategy. See [docs](funcs/ref_view_strategy.md) |
+| `--conf-thresh-percentile` | float | `40.0` | [GLB] Confidence threshold percentile |
+| `--num-max-points` | int | `1000000` | [GLB] Maximum number of points |
+| `--show-cameras` | bool | `True` | [GLB] Show cameras |
+| `--feat-vis-fps` | int | `15` | [FEAT_VIS] Video frame rate |
+
+**Examples:**
+
+```bash
+# ��� Basic video processing
+da3 video path/to/video.mp4 --export-dir ./output
+
+# ⚙️ Control frame sampling and resolution
+da3 video path/to/video.mp4 \
+    --fps 2.0 \
+    --process-res 1024 \
+    --export-dir ./output
+
+# 🔧 Use backend service
+da3 video path/to/video.mp4 \
+    --use-backend \
+    --backend-url http://localhost:8008 \
+    --export-dir ./output
+```
+
+---
+
+### 📐 colmap - COLMAP Dataset Processing
+
+Run pose-conditioned depth estimation on COLMAP data.
+
+**Usage:**
+
+```bash
+da3 colmap COLMAP_DIR [OPTIONS]
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `COLMAP_DIR` | str | Required | COLMAP directory containing `images/` and `sparse/` subdirectories |
+| `--sparse-subdir` | str | `""` | Sparse reconstruction subdirectory (e.g., `"0"` for `sparse/0/`) |
+| `--align-to-input-ext-scale` | bool | `True` | Align prediction to input extrinsics scale |
+| `--model-dir` | str | Default model | Model directory path |
+| `--export-dir` | str | `debug` | Export directory |
+| `--export-format` | str | `glb` | Export format |
+| `--device` | str | `cuda` | Device to use |
+| `--use-backend` | bool | `False` | Use backend service for inference |
+| `--backend-url` | str | `http://localhost:8008` | Backend service URL |
+| `--process-res` | int | `504` | Processing resolution |
+| `--process-res-method` | str | `upper_bound_resize` | Processing resolution method |
+| `--export-feat` | str | `""` | Export feature layer indices |
+| `--auto-cleanup` | bool | `False` | Automatically clean export directory |
+| `--use-ray-pose` | bool | `False` | Use ray-based pose estimation instead of camera decoder |
+| `--ref-view-strategy` | str | `saddle_balanced` | Reference view selection strategy. See [docs](funcs/ref_view_strategy.md) |
+| `--conf-thresh-percentile` | float | `40.0` | [GLB] Confidence threshold percentile |
+| `--num-max-points` | int | `1000000` | [GLB] Maximum number of points |
+| `--show-cameras` | bool | `True` | [GLB] Show cameras |
+| `--feat-vis-fps` | int | `15` | [FEAT_VIS] Video frame rate |
+
+**Examples:**
+
+```bash
+# 📐 Process COLMAP dataset
+da3 colmap ./colmap_dataset --export-dir ./output
+
+# 🎯 Use specific sparse subdirectory and align scale
+da3 colmap ./colmap_dataset \
+    --sparse-subdir 0 \
+    --align-to-input-ext-scale \
+    --export-dir ./output
+
+# 🔧 Use backend service
+da3 colmap ./colmap_dataset \
+    --use-backend \
+    --backend-url http://localhost:8008 \
+    --export-dir ./output
+```
+
+---
+
+### 🔧 backend - Backend Service
+
+Start model backend service with integrated gallery.
+
+**Usage:**
+
+```bash
+da3 backend [OPTIONS]
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `--model-dir` | str | Default model | Model directory path |
+| `--device` | str | `cuda` | Device to use |
+| `--host` | str | `127.0.0.1` | Host address to bind to |
+| `--port` | int | `8008` | Port number to bind to |
+| `--gallery-dir` | str | Default gallery dir | Gallery directory path (optional) |
+
+**Features:**
+- 🎯 Keeps model resident in GPU memory
+- 🔌 Provides REST inference API
+- 📊 Integrated dashboard and status monitoring
+- 🖼️ Optional gallery browser (if `--gallery-dir` is provided)
+
+**Available Endpoints:**
+- 🏠 `/` - Home page
+- 📊 `/dashboard` - Dashboard
+- ✅ `/status` - API status
+- 🖼️ `/gallery/` - Gallery browser (if enabled)
+
+**Examples:**
+
+```bash
+# 🚀 Basic backend service
+da3 backend --model-dir depth-anything/DA3NESTED-GIANT-LARGE
+
+# 🖼️ Backend with gallery
+da3 backend \
+    --model-dir depth-anything/DA3NESTED-GIANT-LARGE \
+    --device cuda \
+    --host 0.0.0.0 \
+    --port 8008 \
+    --gallery-dir ./workspace
+
+# 💻 Use CPU
+da3 backend --model-dir depth-anything/DA3NESTED-GIANT-LARGE --device cpu
+```
+
+---
+
+### 🎨 gradio - Gradio Application
+
+Launch Depth Anything 3 Gradio interactive web application.
+
+**Usage:**
+
+```bash
+da3 gradio [OPTIONS]
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `--model-dir` | str | Required | Model directory path |
+| `--workspace-dir` | str | Required | Workspace directory path |
+| `--gallery-dir` | str | Required | Gallery directory path |
+| `--host` | str | `127.0.0.1` | Host address to bind to |
+| `--port` | int | `7860` | Port number to bind to |
+| `--share` | bool | `False` | Create a public link |
+| `--debug` | bool | `False` | Enable debug mode |
+| `--cache-examples` | bool | `False` | Pre-cache all example scenes at startup |
+| `--cache-gs-tag` | str | `""` | Tag to match scene names for high-res+3DGS caching |
+
+**Examples:**
+
+```bash
+# 🎨 Basic Gradio application
+da3 gradio \
+    --model-dir depth-anything/DA3NESTED-GIANT-LARGE \
+    --workspace-dir ./workspace \
+    --gallery-dir ./gallery
+
+# 🌐 Enable sharing and debug
+da3 gradio \
+    --model-dir depth-anything/DA3NESTED-GIANT-LARGE \
+    --workspace-dir ./workspace \
+    --gallery-dir ./gallery \
+    --share \
+    --debug
+
+# ⚡ Pre-cache examples
+da3 gradio \
+    --model-dir depth-anything/DA3NESTED-GIANT-LARGE \
+    --workspace-dir ./workspace \
+    --gallery-dir ./gallery \
+    --cache-examples \
+    --cache-gs-tag "dl3dv"
+```
+
+---
+
+### 🖼️ gallery - Gallery Server
+
+Launch standalone Depth Anything 3 Gallery server.
+
+**Usage:**
+
+```bash
+da3 gallery [OPTIONS]
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `--gallery-dir` | str | Default gallery dir | Gallery root directory |
+| `--host` | str | `127.0.0.1` | Host address to bind to |
+| `--port` | int | `8007` | Port number to bind to |
+| `--open-browser` | bool | `False` | Open browser after launch |
+
+**Note:**
+The gallery expects each scene folder to contain at least `scene.glb` and `scene.jpg`, with optional subfolders such as `depth_vis/` or `gs_video/`.
+
+**Examples:**
+
+```bash
+# 🖼️ Basic gallery server
+da3 gallery --gallery-dir ./workspace
+
+# 🌐 Custom host and port
+da3 gallery \
+    --gallery-dir ./workspace \
+    --host 0.0.0.0 \
+    --port 8007
+
+# 🚀 Auto-open browser
+da3 gallery --gallery-dir ./workspace --open-browser
+```
+
+---
+
+## ⚙️ Parameter Details
+
+### 🔧 Common Parameters
+
+- **`--export-dir`**: Output directory, defaults to `debug`
+- **`--export-format`**: Export format, supports combining multiple formats with hyphens:
+  - 📦 `mini_npz`: Compressed NumPy format
+  - 🎨 `glb`: glTF binary format (3D scene)
+  - 🔍 `feat_vis`: Feature visualization
+  - Example: `mini_npz-glb` exports both formats
+
+- **`--process-res`** / **`--process-res-method`**: Control preprocessing resolution strategy
+  - `process-res`: Target resolution (default 504)
+  - `process-res-method`: Resize method (default `upper_bound_resize`)
+
+- **`--auto-cleanup`**: Remove existing export directory without confirmation
+
+- **`--use-backend`** / **`--backend-url`**: Reuse running backend service
+  - ⚡ Reduces model loading time
+  - 🌐 Supports distributed processing
+
+- **`--export-feat`**: Layer indices for exporting intermediate features (comma-separated)
+  - Example: `"9,19,29,39"`
+
+### 🎨 GLB Export Parameters
+
+- **`--conf-thresh-percentile`**: Lower percentile for adaptive confidence threshold (default 40.0)
+  - Used to filter low-confidence points
+
+- **`--num-max-points`**: Maximum number of points in point cloud (default 1,000,000)
+  - Controls output file size and performance
+
+- **`--show-cameras`**: Show camera wireframes in exported scene (default True)
+
+### 🔍 Feature Visualization Parameters
+
+- **`--feat-vis-fps`**: Frame rate for feature visualization output video (default 15)
+
+### 🎬 Video-Specific Parameters
+
+- **`--fps`**: Video frame extraction sampling rate (default 1.0 FPS)
+  - Higher values extract more frames
+
+### 📐 COLMAP-Specific Parameters
+
+- **`--sparse-subdir`**: Sparse reconstruction subdirectory
+  - Empty string uses `sparse/` directory
+  - `"0"` uses `sparse/0/` directory
+
+- **`--align-to-input-ext-scale`**: Align prediction to input extrinsics scale (default True)
+  - Ensures depth estimation is consistent with COLMAP scale
+
+---
+
+## 💡 Usage Examples
+
+### 1️⃣ Basic Workflow
+
+```bash
+# 🔧 Start backend service
+da3 backend --model-dir depth-anything/DA3NESTED-GIANT-LARGE --host 0.0.0.0 --port 8008
+
+# 🖼️ Process single image
+da3 image image.jpg --export-dir ./output1 --use-backend
+
+# 🎬 Process video
+da3 video video.mp4 --fps 2.0 --export-dir ./output2 --use-backend
+
+# 📐 Process COLMAP dataset
+da3 colmap ./colmap_data --export-dir ./output3 --use-backend
+```
+
+### 2️⃣ Using Auto Mode
+
+```bash
+# 🤖 Auto-detect and process
+da3 auto ./unknown_input --export-dir ./output
+
+# ⚡ With backend acceleration
+da3 auto ./unknown_input \
+    --use-backend \
+    --backend-url http://localhost:8008 \
+    --export-dir ./output
+```
+
+### 3️⃣ Multi-Format Export
+
+```bash
+# 📦 Export both NPZ and GLB formats
+da3 auto assets/examples/SOH \
+    --export-format mini_npz-glb \
+    --export-dir ./workspace/soh
+
+# 🔍 Export feature visualization
+da3 image image.jpg \
+    --export-format feat_vis \
+    --export-feat "9,19,29,39" \
+    --export-dir ./results
+```
+
+### 4️⃣ Advanced Configuration
+
+```bash
+# ⚙️ Custom resolution and point cloud density
+da3 image image.jpg \
+    --process-res 1024 \
+    --num-max-points 2000000 \
+    --conf-thresh-percentile 30.0 \
+    --export-dir ./output
+
+# 📐 COLMAP advanced options
+da3 colmap ./colmap_data \
+    --sparse-subdir 0 \
+    --align-to-input-ext-scale \
+    --process-res 756 \
+    --export-dir ./output
+```
+
+### 5️⃣ Batch Processing Workflow
+
+```bash
+# 🔧 Start backend
+da3 backend \
+    --model-dir depth-anything/DA3NESTED-GIANT-LARGE \
+    --device cuda \
+    --host 0.0.0.0 \
+    --port 8008 \
+    --gallery-dir ./workspace
+
+# 🔄 Batch process multiple scenes
+for scene in scene1 scene2 scene3; do
+    da3 auto ./data/$scene \
+        --export-dir ./workspace/$scene \
+        --use-backend \
+        --auto-cleanup
+done
+
+# 🖼️ Launch gallery to view results
+da3 gallery --gallery-dir ./workspace --open-browser
+```
+
+### 6️⃣ Web Applications
+
+```bash
+# 🎨 Launch Gradio application
+da3 gradio \
+    --model-dir depth-anything/DA3NESTED-GIANT-LARGE \
+    --workspace-dir workspace/gradio \
+    --gallery-dir ./gallery \
+    --host 0.0.0.0 \
+    --port 7860 \
+    --share
+```
+
+### 7️⃣ Transformer Feature Visualization
+
+```bash
+# 🔍 Export Transformer features
+# 📦 Combined with numerical output
+da3 auto video.mp4 \
+    --export-format glb-feat_vis \
+    --export-feat "11,21,31" \
+    --export-dir ./debug \
+    --use-backend
+```
+
+---
+
+## 📝 Notes
+
+1. **🔧 Backend Service**: Recommended for processing multiple tasks to improve efficiency
+2. **💾 GPU Memory**: Be mindful of GPU memory usage when processing high-resolution inputs
+3. **📁 Export Directory**: Use `--auto-cleanup` to avoid manual confirmation for deletion
+4. **🔀 Format Combination**: Multiple export formats can be combined with hyphens (e.g., `mini_npz-glb-feat_vis`)
+5. **📐 COLMAP Data**: Ensure COLMAP directory structure is correct (contains `images/` and `sparse/` subdirectories)
+
+---
+
+## ❓ Getting Help
+
+View detailed help for any command:
+
+```bash
+# 📖 View main help
+da3 --help
+
+# 🔍 View specific command help
+da3 auto --help
+da3 image --help
+da3 backend --help
+```

docs/funcs/ref_view_strategy.md

@@ -0,0 +1,183 @@
+# 📐 Reference View Selection Strategy
+
+## 📖 Overview
+
+Reference view selection is a component in multi-view depth estimation. When processing multiple input views, the model needs to determine which view should serve as the primary reference frame for depth prediction, defining the world coordinate system.
+
+Different reference view will leads to different reconstruction results. This is a known consideration in multi-view geometry and was analyzed in [PI3](https://arxiv.org/abs/2507.13347). The choice of reference view can affect the quality and consistency of depth predictions across the scene.
+
+
+## 🚀 Our Simple Solution: Automatic Reference View Selection
+
+DA3 provides a simple approach to address this through **automatic reference view selection** based on **class tokens**. Instead of relying on heuristics or manual selection, the model analyzes the class token features from all input views and intelligently selects the most suitable reference frame.
+
+---
+
+## 🎨 Available Strategies
+
+### 1. ⚖️ `saddle_balanced` (Recommended, Default)
+
+**Philosophy:**  
+Select a view that achieves balance across multiple feature metrics. This strategy looks for a "middle ground" view that is neither too similar nor too different from other views, making it a stable reference point.
+
+**How it works:**
+1. Extracts and normalizes class tokens from all views
+2. Computes three complementary metrics for each view:
+   - **Similarity score**: Average cosine similarity with other views
+   - **Feature norm**: L2 norm of the original features  
+   - **Feature variance**: Variance across feature dimensions
+3. Normalizes each metric to [0, 1] range
+4. Selects the view closest to 0.5 (median) across all three metrics
+
+### 2. 🎢 `saddle_sim_range`
+
+**Philosophy:**  
+Select a view with the largest similarity range to other views. This identifies "saddle point" views that are highly similar to some views but dissimilar to others, making them information-rich anchor points.
+
+**How it works:**
+1. Computes pairwise cosine similarity between all views
+2. For each view, calculates the range (max - min) of similarities to other views
+3. Selects the view with the maximum similarity range
+
+---
+
+### 3. 1️⃣ `first` (Not Recommended)
+
+**Philosophy:**  
+Always use the first view in the input sequence as the reference.
+
+**How it works:**
+Simply returns index 0.
+
+**When to use:**
+- ⛔ **Not recommended** in general
+- 🔧 Only use when you have manually pre-sorted your views and know the first view is optimal
+- 🐛 Debugging or baseline comparisons
+
+---
+
+### 4. ⏸️ `middle`
+
+**Philosophy:**  
+Select the view in the middle of the input sequence.
+
+**How it works:**
+Returns the view at index `S // 2` where S is the number of views.
+
+**When to use:**
+- ⏱️ **Only recommended when input images are temporally ordered**
+- 🎬 Video sequences (e.g., **DA3-LONG** setting)
+- 📹 Sequential captures where the middle frame likely has the most stable viewpoint
+
+**Specific use case: DA3-LONG** 🎬  
+In video-based depth estimation scenarios (like DA3-LONG), where inputs are consecutive frames, `middle` is often the **optimal choice** because that it has maximum overlap with all other frames.
+
+
+## 💻 Usage
+
+### 🐍 Python API
+
+```python
+from depth_anything_3 import DepthAnything3
+
+model = DepthAnything3.from_pretrained("depth-anything/DA3NESTED-GIANT-LARGE")
+
+# Use default (saddle_balanced)
+prediction = model.inference(
+    images,
+    ref_view_strategy="saddle_balanced"
+)
+
+# For video sequences, consider using middle
+prediction = model.inference(
+    video_frames,
+    ref_view_strategy="middle"  # Good for temporal sequences
+)
+
+# For complex scenes with wide baselines
+prediction = model.inference(
+    images,
+    ref_view_strategy="saddle_sim_range"
+)
+```
+
+### 🖥️ Command Line Interface
+
+```bash
+# Default (saddle_balanced)
+da3 auto input/ --export-dir output/
+
+# Explicitly specify strategy
+da3 auto input/ --ref-view-strategy saddle_balanced
+
+# For video processing
+da3 video input.mp4 --ref-view-strategy middle
+
+# For wide-baseline multi-view
+da3 images captures/ --ref-view-strategy saddle_sim_range
+```
+
+---
+
+### 🎯 When Selection Is Applied
+
+Reference view selection is applied when:
+- 3️⃣ Number of views S ≥ 3
+
+---
+
+## 💡 Recommendations
+
+### 📋 Quick Guide
+
+| Scenario | Recommended Strategy | Rationale |
+|----------|---------------------|-----------|
+| **Default / Unknown** | `saddle_balanced` | Robust, balanced, works well across diverse scenarios |
+| **Video frames** | `middle` | Temporal coherence, stable middle frame |
+| **Wide-baseline multi-view** | `saddle_sim_range` | Maximizes information coverage |
+| **Pre-sorted inputs** | `first` | Use only if you've manually optimized ordering |
+| **Single image** | `first` | Automatically used (no reordering needed for S ≤ 2) |
+
+### ✨ Best Practices
+
+1. 🎯 **Start with defaults**: `saddle_balanced` works well in most cases
+2. 🎬 **Consider your input type**: Use `middle` for videos, `saddle_balanced` for photos
+3. 🔬 **Experiment if needed**: Try different strategies if results are suboptimal
+4. 📊 **Monitor performance**: Check `glb` quality and consistency across views.
+
+---
+
+## 🔧 Technical Details
+
+### 🎚️ Selection Threshold
+
+The reference view selection is only triggered when:
+```python
+num_views >= 3  # At least 3 views required
+```
+
+For 1-2 views, no reordering is performed (equivalent to using `first`).
+
+### ⚙️ Implementation
+
+The selection happens at layer `alt_start - 1` in the vision transformer, before the first global attention layer. This ensures the selected reference view influences the entire depth prediction pipeline.
+
+---
+
+## ❓ FAQ
+
+**Q: 🤔 Why is this feature provided?**  
+A: The model can handle any view order, but this feature provides automatic optimization for reference view selection, which can help improve depth prediction quality in multi-view scenarios.
+
+**Q: ⏱️ Does this add computational cost?**  
+A: The overhead is totally negligible.
+
+**Q: 🎮 Can I manually specify which view to use as reference?**  
+A: Not directly through this parameter. You can pre-sort your input images to place your preferred reference view first and use `ref_view_strategy="first"`.
+
+**Q: ⚙️ What happens if I don't specify this parameter?**  
+A: The default `saddle_balanced` strategy is used automatically.
+
+**Q: 📊 Is this feature used in the DA3 paper benchmarks?**  
+A: No, the paper used `first` as the default strategy for all multi-view experiments. The current default has been updated to `saddle_balanced` for better robustness.
+

notebooks/da3_tutorial.ipynb

@@ -0,0 +1,667 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# 🌊 Depth Anything 3 — From Images to 3D in Seconds\n",
+        "\n",
+        "<div align=\"center\">\n",
+        "\n",
+        "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Aedelon/awesome-depth-anything-3/blob/main/notebooks/da3_tutorial.ipynb)\n",
+        "[![GitHub Stars](https://img.shields.io/github/stars/Aedelon/awesome-depth-anything-3?style=social)](https://github.com/Aedelon/awesome-depth-anything-3)\n",
+        "[![PyPI](https://img.shields.io/pypi/v/awesome-depth-anything-3)](https://pypi.org/project/awesome-depth-anything-3/)\n",
+        "[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n",
+        "\n",
+        "**State-of-the-art monocular depth estimation + 3D reconstruction**\n",
+        "\n",
+        "</div>\n",
+        "\n",
+        "---\n",
+        "\n",
+        "### What you'll get:\n",
+        "\n",
+        "| Input | Output |\n",
+        "|-------|--------|\n",
+        "| 📸 Single image | 🌊 Metric depth map |\n",
+        "| 🎬 Video / Multi-view | ☁️ 3D Point Cloud + Camera poses |\n",
+        "| 🖼️ Any scene | 📦 Downloadable GLB file |\n",
+        "\n",
+        "---\n",
+        "\n",
+        "### ⚡ Quick Start\n",
+        "\n",
+        "1. **Runtime → Change runtime type → T4 GPU** (free tier works!)\n",
+        "2. **Run all cells** (Ctrl+F9) or click ▶️ on each cell\n",
+        "3. **Upload your images** in Section 4\n",
+        "4. **Download your 3D model** (.glb file)\n",
+        "\n",
+        "⏱️ **Total time: ~5 minutes** (including model download)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "#@title 🚀 **1. Install** (run this first!) { display-mode: \"form\" }\n",
+        "#@markdown > ⏱️ Takes ~2 minutes on first run\n",
+        "\n",
+        "%%capture\n",
+        "!pip install awesome-depth-anything-3\n",
+        "\n",
+        "# Verify installation\n",
+        "import torch\n",
+        "from IPython.display import HTML, display\n",
+        "\n",
+        "device = \"cuda\" if torch.cuda.is_available() else \"cpu\"\n",
+        "gpu_name = torch.cuda.get_device_name(0) if device == \"cuda\" else \"None\"\n",
+        "vram = torch.cuda.get_device_properties(0).total_memory / 1e9 if device == \"cuda\" else 0\n",
+        "\n",
+        "if device == \"cuda\":\n",
+        "    status = f'''\n",
+        "    <div style=\"background: linear-gradient(135deg, #10B981, #059669); padding: 20px; border-radius: 12px; color: white; font-family: system-ui;\">\n",
+        "        <h3 style=\"margin: 0 0 10px 0;\">✅ Ready to go!</h3>\n",
+        "        <p style=\"margin: 5px 0;\"><b>GPU:</b> {gpu_name}</p>\n",
+        "        <p style=\"margin: 5px 0;\"><b>VRAM:</b> {vram:.1f} GB</p>\n",
+        "        <p style=\"margin: 5px 0;\"><b>PyTorch:</b> {torch.__version__}</p>\n",
+        "    </div>\n",
+        "    '''\n",
+        "else:\n",
+        "    status = '''\n",
+        "    <div style=\"background: linear-gradient(135deg, #EF4444, #DC2626); padding: 20px; border-radius: 12px; color: white; font-family: system-ui;\">\n",
+        "        <h3 style=\"margin: 0 0 10px 0;\">⚠️ No GPU detected!</h3>\n",
+        "        <p style=\"margin: 5px 0;\">Go to <b>Runtime → Change runtime type → GPU</b></p>\n",
+        "        <p style=\"margin: 5px 0;\">Then restart the notebook.</p>\n",
+        "    </div>\n",
+        "    '''\n",
+        "\n",
+        "display(HTML(status))"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "#@title 🧠 **2. Load Model** { display-mode: \"form\" }\n",
+        "#@markdown Choose model size:\n",
+        "model_size = \"DA3-LARGE\" #@param [\"DA3-SMALL\", \"DA3-BASE\", \"DA3-LARGE\", \"DA3-GIANT\", \"DA3NESTED-GIANT-LARGE\"]\n",
+        "#@markdown ---\n",
+        "#@markdown | Model | Speed | Quality | VRAM |\n",
+        "#@markdown |-------|-------|---------|------|\n",
+        "#@markdown | SMALL | ⚡⚡⚡ | ★★☆ | 4GB |\n",
+        "#@markdown | BASE | ⚡⚡ | ★★★ | 6GB |\n",
+        "#@markdown | LARGE | ⚡ | ★★★★ | 8GB |\n",
+        "#@markdown | GIANT | 🐢 | ★★★★★ | 12GB |\n",
+        "#@markdown | NESTED | 🐢 | ★★★★★+ | 16GB |\n",
+        "\n",
+        "from depth_anything_3.api import DepthAnything3\n",
+        "import time\n",
+        "\n",
+        "print(f\"📥 Loading {model_size}...\")\n",
+        "start = time.time()\n",
+        "\n",
+        "model = DepthAnything3.from_pretrained(f\"depth-anything/{model_size}\")\n",
+        "model = model.to(device).eval()\n",
+        "\n",
+        "print(f\"✅ Model loaded in {time.time()-start:.1f}s\")"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "#@title 🖼️ **3. Try with Sample Image** { display-mode: \"form\" }\n",
+        "#@markdown Run depth estimation on a sample image\n",
+        "\n",
+        "import matplotlib.pyplot as plt\n",
+        "import numpy as np\n",
+        "from PIL import Image\n",
+        "import urllib.request\n",
+        "import os\n",
+        "\n",
+        "# Download sample\n",
+        "os.makedirs(\"samples\", exist_ok=True)\n",
+        "url = \"https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=1280\"\n",
+        "urllib.request.urlretrieve(url, \"samples/mountain.jpg\")\n",
+        "\n",
+        "# Run inference\n",
+        "result = model.inference([\"samples/mountain.jpg\"])\n",
+        "\n",
+        "# Visualize\n",
+        "fig, axes = plt.subplots(1, 2, figsize=(14, 5))\n",
+        "\n",
+        "axes[0].imshow(result.processed_images[0])\n",
+        "axes[0].set_title(\"📸 Input\", fontsize=14, fontweight='bold')\n",
+        "axes[0].axis(\"off\")\n",
+        "\n",
+        "depth = result.depth[0]\n",
+        "im = axes[1].imshow(depth, cmap='Spectral_r')\n",
+        "axes[1].set_title(f\"🌊 Depth (range: {depth.min():.1f}m - {depth.max():.1f}m)\", fontsize=14, fontweight='bold')\n",
+        "axes[1].axis(\"off\")\n",
+        "plt.colorbar(im, ax=axes[1], fraction=0.046, pad=0.04, label='Depth (m)')\n",
+        "\n",
+        "plt.tight_layout()\n",
+        "plt.show()\n",
+        "\n",
+        "print(f\"\\n📊 Output shapes:\")\n",
+        "print(f\"   Depth: {result.depth.shape}\")\n",
+        "print(f\"   Confidence: {result.conf.shape}\")\n",
+        "print(f\"   Camera intrinsics: {result.intrinsics.shape}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "---\n",
+        "\n",
+        "## 📤 4. Use Your Own Images\n",
+        "\n",
+        "Upload your images and get a 3D point cloud!"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "#@title 📁 **Upload Images** { display-mode: \"form\" }\n",
+        "#@markdown Upload **2-50 images** of the same scene from different angles.\n",
+        "#@markdown \n",
+        "#@markdown 💡 **Tips for best results:**\n",
+        "#@markdown - Move the camera, not the objects\n",
+        "#@markdown - 30-50% overlap between consecutive images\n",
+        "#@markdown - Avoid motion blur\n",
+        "#@markdown - Good lighting helps!\n",
+        "\n",
+        "from google.colab import files\n",
+        "import shutil\n",
+        "\n",
+        "# Clean up previous uploads\n",
+        "upload_dir = \"my_images\"\n",
+        "if os.path.exists(upload_dir):\n",
+        "    shutil.rmtree(upload_dir)\n",
+        "os.makedirs(upload_dir, exist_ok=True)\n",
+        "\n",
+        "print(\"📤 Select your images...\")\n",
+        "uploaded = files.upload()\n",
+        "\n",
+        "# Save uploaded files\n",
+        "for filename, data in uploaded.items():\n",
+        "    with open(f\"{upload_dir}/{filename}\", 'wb') as f:\n",
+        "        f.write(data)\n",
+        "\n",
+        "image_files = sorted([f\"{upload_dir}/{f}\" for f in os.listdir(upload_dir) \n",
+        "                      if f.lower().endswith(('.jpg', '.jpeg', '.png', '.webp'))])\n",
+        "\n",
+        "print(f\"\\n✅ Uploaded {len(image_files)} images\")\n",
+        "\n",
+        "# Preview\n",
+        "n_preview = min(6, len(image_files))\n",
+        "fig, axes = plt.subplots(1, n_preview, figsize=(3*n_preview, 3))\n",
+        "if n_preview == 1:\n",
+        "    axes = [axes]\n",
+        "for i, img_path in enumerate(image_files[:n_preview]):\n",
+        "    img = Image.open(img_path)\n",
+        "    axes[i].imshow(img)\n",
+        "    axes[i].set_title(f\"#{i+1}\", fontsize=10)\n",
+        "    axes[i].axis(\"off\")\n",
+        "if len(image_files) > n_preview:\n",
+        "    print(f\"   (showing first {n_preview} of {len(image_files)})\")\n",
+        "plt.tight_layout()\n",
+        "plt.show()"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "#@title ⚡ **Run 3D Reconstruction** { display-mode: \"form\" }\n",
+        "#@markdown This will:\n",
+        "#@markdown 1. Estimate depth for each image\n",
+        "#@markdown 2. Compute camera poses\n",
+        "#@markdown 3. Generate a 3D point cloud\n",
+        "#@markdown 4. Export to GLB format\n",
+        "\n",
+        "from depth_anything_3.utils.export.glb import export_to_glb\n",
+        "import time\n",
+        "\n",
+        "print(f\"🔄 Processing {len(image_files)} images...\")\n",
+        "start = time.time()\n",
+        "\n",
+        "# Run inference\n",
+        "result = model.inference(\n",
+        "    image_files,\n",
+        "    process_res_method=\"upper_bound_resize\",\n",
+        ")\n",
+        "\n",
+        "inference_time = time.time() - start\n",
+        "print(f\"✅ Inference done in {inference_time:.1f}s ({len(image_files)/inference_time:.1f} img/s)\")\n",
+        "\n",
+        "# Export to GLB\n",
+        "output_dir = \"output_3d\"\n",
+        "os.makedirs(output_dir, exist_ok=True)\n",
+        "\n",
+        "print(\"📦 Generating 3D point cloud...\")\n",
+        "export_to_glb(\n",
+        "    result,\n",
+        "    export_dir=output_dir,\n",
+        "    show_cameras=True,\n",
+        "    conf_thresh_percentile=20,  # Filter low-confidence points\n",
+        "    num_max_points=500_000,\n",
+        ")\n",
+        "\n",
+        "print(f\"\\n✅ 3D model saved to {output_dir}/\")\n",
+        "!ls -lh {output_dir}/"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "#@title 📥 **Download Your 3D Model** { display-mode: \"form\" }\n",
+        "#@markdown Downloads a `.glb` file you can view in:\n",
+        "#@markdown - [glTF Viewer](https://gltf-viewer.donmccurdy.com/)\n",
+        "#@markdown - Blender\n",
+        "#@markdown - Windows 3D Viewer\n",
+        "#@markdown - Any 3D software\n",
+        "\n",
+        "from google.colab import files\n",
+        "\n",
+        "glb_file = f\"{output_dir}/point_cloud.glb\"\n",
+        "if os.path.exists(glb_file):\n",
+        "    files.download(glb_file)\n",
+        "    print(\"\\n🎉 Download started!\")\n",
+        "    print(\"\\n👉 View your model: https://gltf-viewer.donmccurdy.com/\")\n",
+        "else:\n",
+        "    print(\"❌ GLB file not found. Run the previous cell first.\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "---\n",
+        "\n",
+        "## 📊 5. Visualize Results"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "#@title 🌊 **View All Depth Maps** { display-mode: \"form\" }\n",
+        "\n",
+        "n_images = len(result.depth)\n",
+        "cols = min(4, n_images)\n",
+        "rows = (n_images + cols - 1) // cols\n",
+        "\n",
+        "fig, axes = plt.subplots(rows, cols, figsize=(4*cols, 4*rows))\n",
+        "axes = np.array(axes).flatten() if n_images > 1 else [axes]\n",
+        "\n",
+        "for i in range(n_images):\n",
+        "    depth = result.depth[i]\n",
+        "    axes[i].imshow(depth, cmap='Spectral_r')\n",
+        "    axes[i].set_title(f\"Frame {i+1}\", fontsize=10)\n",
+        "    axes[i].axis(\"off\")\n",
+        "\n",
+        "# Hide unused subplots\n",
+        "for i in range(n_images, len(axes)):\n",
+        "    axes[i].axis(\"off\")\n",
+        "\n",
+        "plt.suptitle(\"🌊 Depth Maps\", fontsize=16, fontweight='bold')\n",
+        "plt.tight_layout()\n",
+        "plt.show()"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "#@title 📷 **View Camera Poses** { display-mode: \"form\" }\n",
+        "#@markdown Visualize estimated camera positions in 3D\n",
+        "\n",
+        "from mpl_toolkits.mplot3d import Axes3D\n",
+        "\n",
+        "# Extract camera positions from extrinsics\n",
+        "positions = []\n",
+        "for ext in result.extrinsics:\n",
+        "    # Extrinsic is world-to-camera, invert to get camera-to-world\n",
+        "    R = ext[:3, :3]\n",
+        "    t = ext[:3, 3]\n",
+        "    cam_pos = -R.T @ t  # Camera position in world coordinates\n",
+        "    positions.append(cam_pos)\n",
+        "\n",
+        "positions = np.array(positions)\n",
+        "\n",
+        "fig = plt.figure(figsize=(10, 8))\n",
+        "ax = fig.add_subplot(111, projection='3d')\n",
+        "\n",
+        "# Plot camera positions\n",
+        "ax.scatter(positions[:, 0], positions[:, 1], positions[:, 2], \n",
+        "           c=range(len(positions)), cmap='viridis', s=100, marker='o')\n",
+        "\n",
+        "# Connect cameras with lines\n",
+        "ax.plot(positions[:, 0], positions[:, 1], positions[:, 2], \n",
+        "        'b-', alpha=0.5, linewidth=1)\n",
+        "\n",
+        "# Mark first and last\n",
+        "ax.scatter(*positions[0], c='green', s=200, marker='^', label='First')\n",
+        "ax.scatter(*positions[-1], c='red', s=200, marker='v', label='Last')\n",
+        "\n",
+        "ax.set_xlabel('X')\n",
+        "ax.set_ylabel('Y')\n",
+        "ax.set_zlabel('Z')\n",
+        "ax.set_title('📷 Camera Trajectory', fontsize=14, fontweight='bold')\n",
+        "ax.legend()\n",
+        "\n",
+        "plt.tight_layout()\n",
+        "plt.show()\n",
+        "\n",
+        "print(f\"📍 {len(positions)} camera poses estimated\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "---\n",
+        "\n",
+        "## 🎬 6. Process Video"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "#@title 🎬 **Upload Video** { display-mode: \"form\" }\n",
+        "#@markdown Upload a short video (< 30 seconds recommended)\n",
+        "\n",
+        "fps_extract = 2 #@param {type:\"slider\", min:1, max:10, step:1}\n",
+        "#@markdown ↑ Frames per second to extract (lower = faster, higher = more detail)\n",
+        "\n",
+        "from google.colab import files\n",
+        "import subprocess\n",
+        "\n",
+        "print(\"📤 Select a video file...\")\n",
+        "uploaded = files.upload()\n",
+        "\n",
+        "video_file = list(uploaded.keys())[0]\n",
+        "frames_dir = \"video_frames\"\n",
+        "\n",
+        "# Extract frames\n",
+        "if os.path.exists(frames_dir):\n",
+        "    shutil.rmtree(frames_dir)\n",
+        "os.makedirs(frames_dir, exist_ok=True)\n",
+        "\n",
+        "print(f\"🎞️ Extracting frames at {fps_extract} FPS...\")\n",
+        "subprocess.run([\n",
+        "    \"ffmpeg\", \"-i\", video_file, \n",
+        "    \"-vf\", f\"fps={fps_extract}\",\n",
+        "    f\"{frames_dir}/frame_%04d.jpg\",\n",
+        "    \"-hide_banner\", \"-loglevel\", \"error\"\n",
+        "])\n",
+        "\n",
+        "video_images = sorted([f\"{frames_dir}/{f}\" for f in os.listdir(frames_dir)])\n",
+        "print(f\"✅ Extracted {len(video_images)} frames\")\n",
+        "\n",
+        "# Preview\n",
+        "n_preview = min(8, len(video_images))\n",
+        "fig, axes = plt.subplots(1, n_preview, figsize=(2*n_preview, 2))\n",
+        "step = max(1, len(video_images) // n_preview)\n",
+        "for i, ax in enumerate(axes):\n",
+        "    idx = i * step\n",
+        "    if idx < len(video_images):\n",
+        "        ax.imshow(Image.open(video_images[idx]))\n",
+        "    ax.axis(\"off\")\n",
+        "plt.suptitle(f\"🎬 Video Frames ({len(video_images)} total)\", fontsize=12)\n",
+        "plt.tight_layout()\n",
+        "plt.show()"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "#@title ⚡ **Process Video Frames** { display-mode: \"form\" }\n",
+        "\n",
+        "print(f\"🔄 Processing {len(video_images)} frames...\")\n",
+        "start = time.time()\n",
+        "\n",
+        "result_video = model.inference(\n",
+        "    video_images,\n",
+        "    process_res_method=\"upper_bound_resize\",\n",
+        ")\n",
+        "\n",
+        "elapsed = time.time() - start\n",
+        "print(f\"✅ Done in {elapsed:.1f}s ({len(video_images)/elapsed:.1f} FPS)\")\n",
+        "\n",
+        "# Export\n",
+        "video_output = \"video_3d\"\n",
+        "os.makedirs(video_output, exist_ok=True)\n",
+        "\n",
+        "export_to_glb(\n",
+        "    result_video,\n",
+        "    export_dir=video_output,\n",
+        "    show_cameras=True,\n",
+        "    conf_thresh_percentile=15,\n",
+        "    num_max_points=1_000_000,\n",
+        ")\n",
+        "\n",
+        "print(f\"\\n📦 3D model saved!\")\n",
+        "!ls -lh {video_output}/"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "#@title 📥 **Download Video 3D Model** { display-mode: \"form\" }\n",
+        "\n",
+        "glb_file = f\"{video_output}/point_cloud.glb\"\n",
+        "if os.path.exists(glb_file):\n",
+        "    files.download(glb_file)\n",
+        "    print(\"🎉 Download started!\")\n",
+        "else:\n",
+        "    print(\"❌ Run the previous cell first.\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "---\n",
+        "\n",
+        "## 🔧 7. Advanced: Python API"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "#@title 💻 **API Reference** { display-mode: \"form\" }\n",
+        "#@markdown Quick code snippets for common tasks\n",
+        "\n",
+        "from IPython.display import Markdown\n",
+        "\n",
+        "api_docs = '''\n",
+        "### Basic Usage\n",
+        "\n",
+        "```python\n",
+        "from depth_anything_3.api import DepthAnything3\n",
+        "\n",
+        "# Load model\n",
+        "model = DepthAnything3.from_pretrained(\"depth-anything/DA3-LARGE\")\n",
+        "model = model.to(\"cuda\").eval()\n",
+        "\n",
+        "# Single image\n",
+        "result = model.inference([\"image.jpg\"])\n",
+        "depth = result.depth[0]  # Shape: (H, W)\n",
+        "\n",
+        "# Multiple images\n",
+        "result = model.inference([\"img1.jpg\", \"img2.jpg\", \"img3.jpg\"])\n",
+        "depths = result.depth  # Shape: (N, H, W)\n",
+        "```\n",
+        "\n",
+        "### Output Attributes\n",
+        "\n",
+        "| Attribute | Shape | Description |\n",
+        "|-----------|-------|-------------|\n",
+        "| `depth` | `(N, H, W)` | Metric depth in meters |\n",
+        "| `conf` | `(N, H, W)` | Confidence [0-1] |\n",
+        "| `extrinsics` | `(N, 3, 4)` | Camera poses (world-to-cam) |\n",
+        "| `intrinsics` | `(N, 3, 3)` | Camera K matrix |\n",
+        "| `processed_images` | `(N, H, W, 3)` | Resized inputs (uint8) |\n",
+        "\n",
+        "### Export to 3D\n",
+        "\n",
+        "```python\n",
+        "from depth_anything_3.utils.export.glb import export_to_glb\n",
+        "\n",
+        "export_to_glb(\n",
+        "    result,\n",
+        "    export_dir=\"output\",\n",
+        "    show_cameras=True,          # Show camera frustums\n",
+        "    conf_thresh_percentile=20,  # Filter low confidence\n",
+        "    num_max_points=500_000,     # Max points in cloud\n",
+        ")\n",
+        "```\n",
+        "\n",
+        "### CLI Usage\n",
+        "\n",
+        "```bash\n",
+        "# Single image\n",
+        "da3 infer image.jpg -o output/\n",
+        "\n",
+        "# Directory of images\n",
+        "da3 infer images/ -o output/ --model DA3-LARGE\n",
+        "\n",
+        "# Video\n",
+        "da3 infer video.mp4 -o output/ --fps 2\n",
+        "```\n",
+        "'''\n",
+        "\n",
+        "display(Markdown(api_docs))"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "---\n",
+        "\n",
+        "## 💾 8. Save to Google Drive"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "#@title 💾 **Mount Google Drive** { display-mode: \"form\" }\n",
+        "\n",
+        "from google.colab import drive\n",
+        "drive.mount('/content/drive')\n",
+        "\n",
+        "drive_output = \"/content/drive/MyDrive/DepthAnything3_Results\"\n",
+        "os.makedirs(drive_output, exist_ok=True)\n",
+        "print(f\"✅ Drive mounted at: {drive_output}\")"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "#@title 💾 **Save Results to Drive** { display-mode: \"form\" }\n",
+        "\n",
+        "import shutil\n",
+        "from datetime import datetime\n",
+        "\n",
+        "# Create timestamped folder\n",
+        "timestamp = datetime.now().strftime(\"%Y%m%d_%H%M%S\")\n",
+        "save_dir = f\"{drive_output}/{timestamp}\"\n",
+        "os.makedirs(save_dir, exist_ok=True)\n",
+        "\n",
+        "# Copy all outputs\n",
+        "for folder in [\"output_3d\", \"video_3d\"]:\n",
+        "    if os.path.exists(folder):\n",
+        "        for f in os.listdir(folder):\n",
+        "            shutil.copy(f\"{folder}/{f}\", save_dir)\n",
+        "            print(f\"  ✓ {f}\")\n",
+        "\n",
+        "print(f\"\\n✅ Saved to: {save_dir}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "---\n",
+        "\n",
+        "## 🙏 Credits & Links\n",
+        "\n",
+        "<div align=\"center\">\n",
+        "\n",
+        "**Depth Anything 3** by ByteDance Research\n",
+        "\n",
+        "[📄 Paper](https://arxiv.org/abs/2511.10647) • [🌐 Project](https://depth-anything-3.github.io) • [🤗 Models](https://huggingface.co/collections/depth-anything/depth-anything-3)\n",
+        "\n",
+        "---\n",
+        "\n",
+        "**awesome-depth-anything-3** — Optimized fork with batching, caching & CLI\n",
+        "\n",
+        "[⭐ GitHub](https://github.com/Aedelon/awesome-depth-anything-3) • [📦 PyPI](https://pypi.org/project/awesome-depth-anything-3/)\n",
+        "\n",
+        "---\n",
+        "\n",
+        "Made with ❤️ by [Delanoe Pirard](https://github.com/Aedelon)\n",
+        "\n",
+        "</div>"
+      ]
+    }
+  ],
+  "metadata": {
+    "accelerator": "GPU",
+    "colab": {
+      "gpuType": "T4",
+      "provenance": [],
+      "toc_visible": true
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.10.0"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

pyproject.toml

@@ -0,0 +1,144 @@
+[build-system]
+requires = ["hatchling>=1.25", "hatch-vcs>=0.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "awesome-depth-anything-3"
+version = "0.0.0"
+description = "Optimized wrapper for Depth Anything 3 - Metric depth, point clouds, camera poses and novel views from any images"
+readme = "README.md"
+requires-python = ">=3.10, <=3.13"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Delanoe Pirard", email = "delanoe.pirard.pro@gmail.com" }]
+keywords = [
+    "depth-estimation",
+    "3d-reconstruction",
+    "computer-vision",
+    "pytorch",
+    "monocular-depth",
+    "multi-view",
+    "pose-estimation",
+    "point-cloud",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+
+dependencies = [
+    "torch>=2",
+    "torchvision",
+    "kornia>=0.7.0",
+    "einops",
+    "huggingface_hub",
+    "imageio",
+    "numpy<2",
+    "opencv-python",
+    "open3d",
+    "fastapi",
+    "uvicorn",
+    "requests",
+    "typer>=0.9.0,<0.13.0",
+    "pillow",
+    "omegaconf",
+    "evo",
+    "e3nn",
+    "moviepy==1.0.3",
+    "trimesh",
+    "plyfile",
+    "pillow_heif",
+    "safetensors",
+    "pycolmap",
+    "twine>=6.2.0",
+]
+
+[project.optional-dependencies]
+app = ["gradio==4.44.1", "huggingface_hub>=0.19,<1.0", "pillow>=9.0"]
+dev = ["pre-commit", "pytest", "ruff"]
+# CUDA acceleration packages (may require manual install steps)
+xformers = ["xformers; platform_system!='Darwin'"]
+gs = ["gsplat>=1.0.0; platform_system!='Darwin'"]
+# Note: flash-attn package is optional. PyTorch >= 2.2 includes Flash Attention
+# natively via F.scaled_dot_product_attention(). Only install flash-attn if you
+# need the absolute latest optimizations:
+#   pip install flash-attn --no-build-isolation  (requires CUDA toolkit)
+# Convenience bundles
+cuda = ["awesome-depth-anything-3[xformers,gs]"]
+all = ["awesome-depth-anything-3[app,cuda]"]
+
+
+[project.scripts]
+da3 = "depth_anything_3.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/Aedelon/awesome-depth-anything-3"
+Repository = "https://github.com/Aedelon/awesome-depth-anything-3"
+Documentation = "https://github.com/Aedelon/awesome-depth-anything-3#readme"
+Issues = "https://github.com/Aedelon/awesome-depth-anything-3/issues"
+Changelog = "https://github.com/Aedelon/awesome-depth-anything-3/blob/main/CHANGELOG.md"
+Upstream = "https://github.com/ByteDance-Seed/Depth-Anything-3"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/depth_anything_3"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/README.md",
+  "/pyproject.toml",
+  "/src/depth_anything_3",
+]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.mypy]
+plugins = ["jaxtyping.mypy_plugin"]
+
+[tool.black]
+line-length = 99
+target-version = ['py37', 'py38', 'py39', 'py310', 'py311']
+include = '\.pyi?$'
+exclude = '''
+/(
+  | \.git
+)/
+'''
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+include_trailing_comma = true
+known_third_party = ["bson","cruise","cv2","dataloader","diffusers","omegaconf","tensorflow","torch","torchvision","transformers","gsplat"]
+known_first_party = ["common", "data", "models", "projects", "depth_anything_3"]
+sections = ["FUTURE","STDLIB","THIRDPARTY","FIRSTPARTY","LOCALFOLDER"]
+skip_gitignore = true
+line_length = 99
+no_lines_before="THIRDPARTY"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+filterwarnings = [
+    "ignore::DeprecationWarning",
+    "ignore::UserWarning",
+]
+
+[tool.ruff]
+line-length = 99
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]  # Line too long (handled by formatter)

requirements.txt

@@ -0,0 +1,38 @@
+# Install this package from GitHub
+git+https://github.com/Aedelon/awesome-depth-anything-3.git
+
+# Core dependencies - torch MUST be first for xformers
+torch>=2
+torchvision
+numpy<2
+
+# ML/Vision libraries
+einops
+kornia>=0.7.0
+safetensors
+
+# Image/Video processing
+pillow
+pillow_heif
+imageio
+opencv-python
+moviepy==1.0.3
+
+# 3D and geometry
+trimesh
+plyfile
+open3d
+e3nn
+evo
+pycolmap
+
+# API and config
+fastapi
+uvicorn
+requests
+typer>=0.9.0,<0.13.0
+omegaconf
+
+# Gradio app
+gradio>=5.50.0,<6.0
+huggingface_hub>=0.33.5,<2.0

scripts/deploy_hf.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+# Copyright (c) Delanoe Pirard / Aedelon
+# Licensed under the Apache License, Version 2.0
+#
+# Deploy to HuggingFace Spaces with LFS for binary files
+# This script temporarily enables LFS, pushes to HF, then restores normal state
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+cd "$PROJECT_ROOT"
+
+# HuggingFace Spaces YAML front matter
+HF_YAML='---
+title: Awesome Depth Anything 3
+emoji: 🌊
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 5.50.0
+app_file: app.py
+pinned: false
+license: apache-2.0
+short_description: Metric 3D reconstruction from images/video
+---
+
+'
+
+echo "=== HuggingFace Deployment Script ==="
+
+# Save current HEAD
+CURRENT_SHA=$(git rev-parse HEAD)
+echo "Current commit: $CURRENT_SHA"
+
+# Step 1: Configure LFS for binary files
+echo ""
+echo "Step 1: Configuring Git LFS..."
+cat > .gitattributes << 'EOF'
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.webm filter=lfs diff=lfs merge=lfs -text
+EOF
+
+# Step 2: Create deployment branch
+echo ""
+echo "Step 2: Creating deployment branch..."
+git checkout --orphan hf-deploy-temp 2>/dev/null || git checkout hf-deploy-temp
+
+# Reset to get clean state
+git reset
+
+# Step 3: Add YAML to README
+echo ""
+echo "Step 3: Adding YAML front matter to README..."
+cp README.md README.md.original
+echo "$HF_YAML$(cat README.md.original)" > README.md
+
+# Step 4: Stage all files (LFS will handle binaries)
+echo ""
+echo "Step 4: Staging files with LFS..."
+git add .gitattributes
+git add -A
+
+# Step 5: Commit
+echo ""
+echo "Step 5: Committing..."
+git commit -m "Deploy to HuggingFace Spaces" --no-verify || true
+
+# Step 6: Push to HuggingFace
+echo ""
+echo "Step 6: Pushing to HuggingFace Spaces..."
+git push huggingface hf-deploy-temp:main --force
+
+# Step 7: Cleanup - return to main branch
+echo ""
+echo "Step 7: Cleaning up..."
+git checkout main --force
+git branch -D hf-deploy-temp 2>/dev/null || true
+
+# Restore original .gitattributes (no LFS)
+cat > .gitattributes << 'EOF'
+*.png !text !filter !merge !diff
+*.jpg !text !filter !merge !diff
+*.jpeg !text !filter !merge !diff
+*.gif !text !filter !merge !diff
+*.mp4 !text !filter !merge !diff
+*.webm !text !filter !merge !diff
+EOF
+
+echo ""
+echo "=== Done! ==="
+echo "HuggingFace updated with YAML metadata and LFS binaries."
+echo "Local repo restored to normal state (no LFS)."

src/depth_anything_3/api.py

@@ -0,0 +1,718 @@
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Depth Anything 3 API module.
+
+This module provides the main API for Depth Anything 3, including model loading,
+inference, and export capabilities. It supports both single and nested model architectures.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Optional, Sequence
+
+import numpy as np
+import torch
+import torch.nn as nn
+from huggingface_hub import PyTorchModelHubMixin
+from PIL import Image
+
+from depth_anything_3.cache import get_model_cache
+from depth_anything_3.cfg import create_object, load_config
+from depth_anything_3.registry import MODEL_REGISTRY
+from depth_anything_3.specs import Prediction
+from depth_anything_3.utils.adaptive_batching import (
+    AdaptiveBatchConfig,
+    AdaptiveBatchSizeCalculator,
+    adaptive_batch_iterator,
+    estimate_max_batch_size,
+)
+from depth_anything_3.utils.export import export
+from depth_anything_3.utils.geometry import affine_inverse
+from depth_anything_3.utils.io.gpu_input_processor import GPUInputProcessor
+from depth_anything_3.utils.io.input_processor import InputProcessor
+from depth_anything_3.utils.io.output_processor import OutputProcessor
+from depth_anything_3.utils.logger import logger
+from depth_anything_3.utils.pose_align import align_poses_umeyama
+
+torch.backends.cudnn.benchmark = False
+# logger.info("CUDNN Benchmark Disabled")
+
+SAFETENSORS_NAME = "model.safetensors"
+CONFIG_NAME = "config.json"
+
+
+class DepthAnything3(nn.Module, PyTorchModelHubMixin):
+    """
+    Depth Anything 3 main API class.
+
+    This class provides a high-level interface for depth estimation using Depth Anything 3.
+    It supports both single and nested model architectures with metric scaling capabilities.
+
+    Features:
+    - Hugging Face Hub integration via PyTorchModelHubMixin
+    - Support for multiple model presets (vitb, vitg, nested variants)
+    - Automatic mixed precision inference
+    - Export capabilities for various formats (GLB, PLY, NPZ, etc.)
+    - Camera pose estimation and metric depth scaling
+
+    Usage:
+        # Load from Hugging Face Hub
+        model = DepthAnything3.from_pretrained("huggingface/model-name")
+
+        # Or create with specific preset
+        model = DepthAnything3(preset="vitg")
+
+        # Run inference
+        prediction = model.inference(images, export_dir="output", export_format="glb")
+    """
+
+    _commit_hash: str | None = None  # Set by mixin when loading from Hub
+
+    def __init__(self, model_name: str = "da3-large", device: str | torch.device | None = None, use_cache: bool = True, **kwargs):
+        """
+        Initialize DepthAnything3 with specified preset.
+
+        Args:
+            model_name: The name of the model preset to use.
+                        Examples: 'da3-giant', 'da3-large', 'da3metric-large', 'da3nested-giant-large'.
+            device: Target device ('cuda', 'mps', 'cpu'). If None, auto-detect.
+            use_cache: Whether to use model caching (default: True).
+                      Set to False to force reload model from disk.
+            **kwargs: Additional keyword arguments (currently unused).
+        """
+        super().__init__()
+        self.model_name = model_name
+        self.use_cache = use_cache
+
+        # Determine device
+        if device is None:
+            device = self._auto_detect_device()
+        self.device = torch.device(device) if isinstance(device, str) else device
+
+        # Load model configuration
+        self.config = load_config(MODEL_REGISTRY[self.model_name])
+
+        # Build or retrieve model from cache
+        if use_cache:
+            cache = get_model_cache()
+            self.model = cache.get(
+                model_name=self.model_name,
+                device=self.device,
+                loader_fn=lambda: self._create_model()
+            )
+        else:
+            logger.info(f"Model cache disabled, loading {self.model_name} from disk")
+            self.model = self._create_model()
+
+        # Ensure model is on correct device and in eval mode
+        self.model = self.model.to(self.device)
+        self.model.eval()
+
+        # Initialize processors
+        # Use GPUInputProcessor for CUDA/MPS devices to enable GPU ops
+        # Note: NVJPEG decoding is specific to CUDA, MPS will use optimized CPU decoding + GPU resize
+        if self.device.type in ("cuda", "mps"):
+            self.input_processor = GPUInputProcessor(device=self.device)
+            decoding_info = "NVJPEG support enabled" if self.device.type == "cuda" else "TorchVision decoding"
+            logger.info(f"Using GPUInputProcessor ({decoding_info} on {self.device})")
+        else:
+            self.input_processor = InputProcessor()
+            logger.info("Using standard InputProcessor (optimized CPU pipeline)")
+
+        self.output_processor = OutputProcessor()
+
+    def _auto_detect_device(self) -> torch.device:
+        """Auto-detect best available device."""
+        if torch.cuda.is_available():
+            return torch.device("cuda")
+        elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+            return torch.device("mps")
+        else:
+            return torch.device("cpu")
+
+    def _create_model(self) -> nn.Module:
+        """Create and return new model instance on correct device."""
+        model = create_object(self.config)
+        model = model.to(self.device)  # Move to device before caching
+        model.eval()
+        return model
+
+    @torch.inference_mode()
+    def forward(
+        self,
+        image: torch.Tensor,
+        extrinsics: torch.Tensor | None = None,
+        intrinsics: torch.Tensor | None = None,
+        export_feat_layers: list[int] | None = None,
+        infer_gs: bool = False,
+        use_ray_pose: bool = False,
+        ref_view_strategy: str = "saddle_balanced",
+    ) -> dict[str, torch.Tensor]:
+        """
+        Forward pass through the model.
+
+        Args:
+            image: Input batch with shape ``(B, N, 3, H, W)`` on the model device.
+            extrinsics: Optional camera extrinsics with shape ``(B, N, 4, 4)``.
+            intrinsics: Optional camera intrinsics with shape ``(B, N, 3, 3)``.
+            export_feat_layers: Layer indices to return intermediate features for.
+            infer_gs: Enable Gaussian Splatting branch.
+            use_ray_pose: Use ray-based pose estimation instead of camera decoder.
+            ref_view_strategy: Strategy for selecting reference view from multiple views.
+
+        Returns:
+            Dictionary containing model predictions
+        """
+        with torch.no_grad():
+            # MPS doesn't support autocast well - use float32 for stability
+            if image.device.type == "mps":
+                return self.model(
+                    image, extrinsics, intrinsics, export_feat_layers, infer_gs, use_ray_pose, ref_view_strategy
+                )
+            else:
+                # CUDA: use autocast for performance
+                autocast_dtype = torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float16
+                with torch.autocast(device_type=image.device.type, dtype=autocast_dtype):
+                    return self.model(
+                        image, extrinsics, intrinsics, export_feat_layers, infer_gs, use_ray_pose, ref_view_strategy
+                    )
+
+    def inference(
+        self,
+        image: list[np.ndarray | Image.Image | str],
+        extrinsics: np.ndarray | None = None,
+        intrinsics: np.ndarray | None = None,
+        align_to_input_ext_scale: bool = True,
+        infer_gs: bool = False,
+        use_ray_pose: bool = False,
+        ref_view_strategy: str = "saddle_balanced",
+        render_exts: np.ndarray | None = None,
+        render_ixts: np.ndarray | None = None,
+        render_hw: tuple[int, int] | None = None,
+        process_res: int = 504,
+        process_res_method: str = "upper_bound_resize",
+        export_dir: str | None = None,
+        export_format: str = "mini_npz",
+        export_feat_layers: Sequence[int] | None = None,
+        # GLB export parameters
+        conf_thresh_percentile: float = 40.0,
+        num_max_points: int = 1_000_000,
+        show_cameras: bool = True,
+        # Feat_vis export parameters
+        feat_vis_fps: int = 15,
+        # Other export parameters, e.g., gs_ply, gs_video
+        export_kwargs: Optional[dict] = {},
+    ) -> Prediction:
+        """
+        Run inference on input images.
+
+        Args:
+            image: List of input images (numpy arrays, PIL Images, or file paths)
+            extrinsics: Camera extrinsics (N, 4, 4)
+            intrinsics: Camera intrinsics (N, 3, 3)
+            align_to_input_ext_scale: whether to align the input pose scale to the prediction
+            infer_gs: Enable the 3D Gaussian branch (needed for `gs_ply`/`gs_video` exports)
+            use_ray_pose: Use ray-based pose estimation instead of camera decoder (default: False)
+            ref_view_strategy: Strategy for selecting reference view from multiple views.
+                Options: "first", "middle", "saddle_balanced", "saddle_sim_range".
+                Default: "saddle_balanced". For single view input (S ≤ 2), no reordering is performed.
+            render_exts: Optional render extrinsics for Gaussian video export
+            render_ixts: Optional render intrinsics for Gaussian video export
+            render_hw: Optional render resolution for Gaussian video export
+            process_res: Processing resolution
+            process_res_method: Resize method for processing
+            export_dir: Directory to export results
+            export_format: Export format (mini_npz, npz, glb, ply, gs, gs_video)
+            export_feat_layers: Layer indices to export intermediate features from
+            conf_thresh_percentile: [GLB] Lower percentile for adaptive confidence threshold (default: 40.0) # noqa: E501
+            num_max_points: [GLB] Maximum number of points in the point cloud (default: 1,000,000)
+            show_cameras: [GLB] Show camera wireframes in the exported scene (default: True)
+            feat_vis_fps: [FEAT_VIS] Frame rate for output video (default: 15)
+            export_kwargs: additional arguments to export functions.
+
+        Returns:
+            Prediction object containing depth maps and camera parameters
+        """
+        if "gs" in export_format:
+            assert infer_gs, "must set `infer_gs=True` to perform gs-related export."
+
+        if "colmap" in export_format:
+            assert isinstance(image[0], str), "`image` must be image paths for COLMAP export."
+
+        # Preprocess images
+        imgs_cpu, extrinsics, intrinsics = self._preprocess_inputs(
+            image, extrinsics, intrinsics, process_res, process_res_method
+        )
+
+        # Prepare tensors for model
+        imgs, ex_t, in_t = self._prepare_model_inputs(imgs_cpu, extrinsics, intrinsics)
+
+        # Normalize extrinsics
+        ex_t_norm = self._normalize_extrinsics(ex_t.clone() if ex_t is not None else None)
+
+        # Run model forward pass
+        export_feat_layers = list(export_feat_layers) if export_feat_layers is not None else []
+
+        raw_output = self._run_model_forward(
+            imgs, ex_t_norm, in_t, export_feat_layers, infer_gs, use_ray_pose, ref_view_strategy
+        )
+
+        # Convert raw output to prediction
+        prediction = self._convert_to_prediction(raw_output)
+
+        # Align prediction to extrinsincs
+        prediction = self._align_to_input_extrinsics_intrinsics(
+            extrinsics, intrinsics, prediction, align_to_input_ext_scale
+        )
+
+        # Add processed images for visualization
+        prediction = self._add_processed_images(prediction, imgs_cpu)
+
+        # Export if requested
+        if export_dir is not None:
+
+            if "gs" in export_format:
+                if infer_gs and "gs_video" not in export_format:
+                    export_format = f"{export_format}-gs_video"
+                if "gs_video" in export_format:
+                    if "gs_video" not in export_kwargs:
+                        export_kwargs["gs_video"] = {}
+                    export_kwargs["gs_video"].update(
+                        {
+                            "extrinsics": render_exts,
+                            "intrinsics": render_ixts,
+                            "out_image_hw": render_hw,
+                        }
+                    )
+            # Add GLB export parameters
+            if "glb" in export_format:
+                if "glb" not in export_kwargs:
+                    export_kwargs["glb"] = {}
+                export_kwargs["glb"].update(
+                    {
+                        "conf_thresh_percentile": conf_thresh_percentile,
+                        "num_max_points": num_max_points,
+                        "show_cameras": show_cameras,
+                    }
+                )
+            # Add Feat_vis export parameters
+            if "feat_vis" in export_format:
+                if "feat_vis" not in export_kwargs:
+                    export_kwargs["feat_vis"] = {}
+                export_kwargs["feat_vis"].update(
+                    {
+                        "fps": feat_vis_fps,
+                    }
+                )
+            # Add COLMAP export parameters
+            if "colmap" in export_format:
+                if "colmap" not in export_kwargs:
+                    export_kwargs["colmap"] = {}
+                export_kwargs["colmap"].update(
+                    {
+                        "image_paths": image,
+                        "conf_thresh_percentile": conf_thresh_percentile,
+                        "process_res_method": process_res_method,
+                    }
+                )
+            self._export_results(prediction, export_format, export_dir, **export_kwargs)
+
+        return prediction
+
+    def _preprocess_inputs(
+        self,
+        image: list[np.ndarray | Image.Image | str],
+        extrinsics: np.ndarray | None = None,
+        intrinsics: np.ndarray | None = None,
+        process_res: int = 504,
+        process_res_method: str = "upper_bound_resize",
+    ) -> tuple[torch.Tensor, torch.Tensor | None, torch.Tensor | None]:
+        """Preprocess input images using input processor."""
+        start_time = time.time()
+
+        # Determine normalization strategy:
+        # 1. Hybrid (CPU Proc + GPU Device): Skip CPU norm (return uint8), norm on GPU later.
+        # 2. GPU Proc (NVJPEG/Kornia): Perform norm on GPU immediately.
+        # 3. Standard CPU: Perform norm on CPU.
+
+        perform_norm = True
+        if self.device.type in ("cuda", "mps") and not isinstance(self.input_processor, GPUInputProcessor):
+            perform_norm = False
+
+        imgs_cpu, extrinsics, intrinsics = self.input_processor(
+            image,
+            extrinsics.copy() if extrinsics is not None else None,
+            intrinsics.copy() if intrinsics is not None else None,
+            process_res,
+            process_res_method,
+            perform_normalization=perform_norm,
+        )
+        end_time = time.time()
+        logger.info(
+            "Processed Images Done taking",
+            end_time - start_time,
+            "seconds. Shape: ",
+            imgs_cpu.shape,
+        )
+        return imgs_cpu, extrinsics, intrinsics
+
+    def _prepare_model_inputs(
+        self,
+        imgs_cpu: torch.Tensor,
+        extrinsics: torch.Tensor | None,
+        intrinsics: torch.Tensor | None,
+    ) -> tuple[torch.Tensor, torch.Tensor | None, torch.Tensor | None]:
+        """
+        Prepare tensors for model input with optimized device transfer.
+        """
+        device = self._get_model_device()
+
+        # 1. Handle Image Tensor
+        # Compare device types (handles cuda:0 vs cuda comparison)
+        imgs_on_target_device = (imgs_cpu.device.type == device.type)
+        if imgs_on_target_device:
+            # Case A: Already on correct device (GPUInputProcessor)
+            # Ensure correct shape: (B, S, C, H, W) where B=1
+            imgs = imgs_cpu
+            if imgs.dim() == 3:
+                # Single image (C, H, W) -> (1, 1, C, H, W)
+                imgs = imgs.unsqueeze(0).unsqueeze(0)
+            elif imgs.dim() == 4:
+                # Batch of images (N, C, H, W) -> (1, N, C, H, W)
+                imgs = imgs.unsqueeze(0)
+            # dim() == 5 means already correct shape
+            if imgs.dtype == torch.uint8:
+                 # Should not happen with GPUInputProcessor default, but safety fallback
+                 imgs = imgs.float() / 255.0
+                 imgs = InputProcessor.normalize_tensor(
+                    imgs,
+                    mean=[0.485, 0.456, 0.406],
+                    std=[0.229, 0.224, 0.225]
+                 )
+        else:
+            # Case B & C: Needs transfer from CPU
+            if imgs_cpu.dtype == torch.uint8:
+                # Hybrid mode: uint8 -> GPU -> float -> normalize
+                if device.type == "cuda":
+                    imgs_cpu = imgs_cpu.pin_memory()
+
+                imgs = imgs_cpu.to(device, non_blocking=True).float() / 255.0
+                imgs = InputProcessor.normalize_tensor(
+                    imgs,
+                    mean=[0.485, 0.456, 0.406],
+                    std=[0.229, 0.224, 0.225]
+                )
+                imgs = imgs[None] # Add batch dimension (1, N, 3, H, W)
+            else:
+                # Standard mode: float -> GPU
+                if device.type == "cuda":
+                    imgs_cpu = imgs_cpu.pin_memory()
+                imgs = imgs_cpu.to(device, non_blocking=True)[None].float()
+
+        # Convert camera parameters to tensors with non-blocking transfer
+        ex_t = (
+            extrinsics.pin_memory().to(device, non_blocking=True)[None].float()
+            if extrinsics is not None and device.type == "cuda" and extrinsics.device.type == "cpu"
+            else extrinsics.to(device, non_blocking=True)[None].float()
+            if extrinsics is not None and extrinsics.device != device
+            else extrinsics[None].float()
+            if extrinsics is not None
+            else None
+        )
+        in_t = (
+            intrinsics.pin_memory().to(device, non_blocking=True)[None].float()
+            if intrinsics is not None and device.type == "cuda" and intrinsics.device.type == "cpu"
+            else intrinsics.to(device, non_blocking=True)[None].float()
+            if intrinsics is not None and intrinsics.device != device
+            else intrinsics[None].float()
+            if intrinsics is not None
+            else None
+        )
+
+        return imgs, ex_t, in_t
+
+    def _normalize_extrinsics(self, ex_t: torch.Tensor | None) -> torch.Tensor | None:
+        """Normalize extrinsics"""
+        if ex_t is None:
+            return None
+        transform = affine_inverse(ex_t[:, :1])
+        ex_t_norm = ex_t @ transform
+        c2ws = affine_inverse(ex_t_norm)
+        translations = c2ws[..., :3, 3]
+        dists = translations.norm(dim=-1)
+        median_dist = torch.median(dists)
+        median_dist = torch.clamp(median_dist, min=1e-1)
+        ex_t_norm[..., :3, 3] = ex_t_norm[..., :3, 3] / median_dist
+        return ex_t_norm
+
+    def _align_to_input_extrinsics_intrinsics(
+        self,
+        extrinsics: torch.Tensor | None,
+        intrinsics: torch.Tensor | None,
+        prediction: Prediction,
+        align_to_input_ext_scale: bool = True,
+        ransac_view_thresh: int = 10,
+    ) -> Prediction:
+        """Align depth map to input extrinsics"""
+        if extrinsics is None:
+            return prediction
+        prediction.intrinsics = intrinsics.numpy()
+        _, _, scale, aligned_extrinsics = align_poses_umeyama(
+            prediction.extrinsics,
+            extrinsics.numpy(),
+            ransac=len(extrinsics) >= ransac_view_thresh,
+            return_aligned=True,
+            random_state=42,
+        )
+        if align_to_input_ext_scale:
+            prediction.extrinsics = extrinsics[..., :3, :].numpy()
+            prediction.depth /= scale
+        else:
+            prediction.extrinsics = aligned_extrinsics
+        return prediction
+
+    def _run_model_forward(
+        self,
+        imgs: torch.Tensor,
+        ex_t: torch.Tensor | None,
+        in_t: torch.Tensor | None,
+        export_feat_layers: Sequence[int] | None = None,
+        infer_gs: bool = False,
+        use_ray_pose: bool = False,
+        ref_view_strategy: str = "saddle_balanced",
+    ) -> dict[str, torch.Tensor]:
+        """Run model forward pass."""
+        device = imgs.device
+        need_sync = device.type == "cuda"
+        if need_sync:
+            torch.cuda.synchronize(device)
+        start_time = time.time()
+        feat_layers = list(export_feat_layers) if export_feat_layers is not None else None
+        output = self.forward(imgs, ex_t, in_t, feat_layers, infer_gs, use_ray_pose, ref_view_strategy)
+        if need_sync:
+            torch.cuda.synchronize(device)
+        end_time = time.time()
+        logger.info(f"Model Forward Pass Done. Time: {end_time - start_time} seconds")
+        return output
+
+    def _convert_to_prediction(self, raw_output: dict[str, torch.Tensor]) -> Prediction:
+        """Convert raw model output to Prediction object."""
+        start_time = time.time()
+        output = self.output_processor(raw_output)
+        end_time = time.time()
+        logger.info(f"Conversion to Prediction Done. Time: {end_time - start_time} seconds")
+        return output
+
+    def _add_processed_images(self, prediction: Prediction, imgs_cpu: torch.Tensor) -> Prediction:
+        """Add processed images to prediction for visualization."""
+        # Convert from (N, 3, H, W) to (N, H, W, 3)
+        processed_imgs = imgs_cpu.permute(0, 2, 3, 1).cpu().numpy()  # (N, H, W, 3)
+
+        if imgs_cpu.dtype == torch.uint8:
+            # Already uint8, no need to denormalize
+            pass
+        else:
+            # Denormalize from ImageNet normalization
+            mean = np.array([0.485, 0.456, 0.406])
+            std = np.array([0.229, 0.224, 0.225])
+            processed_imgs = processed_imgs * std + mean
+            processed_imgs = np.clip(processed_imgs, 0, 1)
+            processed_imgs = (processed_imgs * 255).astype(np.uint8)
+
+        prediction.processed_images = processed_imgs
+        return prediction
+
+    def _export_results(
+        self, prediction: Prediction, export_format: str, export_dir: str, **kwargs
+    ) -> None:
+        """Export results to specified format and directory."""
+        start_time = time.time()
+        export(prediction, export_format, export_dir, **kwargs)
+        end_time = time.time()
+        logger.info(f"Export Results Done. Time: {end_time - start_time} seconds")
+
+    def _get_model_device(self) -> torch.device:
+        """
+        Get the device where the model is located.
+
+        Returns:
+            Device where the model parameters are located
+
+        Raises:
+            ValueError: If no tensors are found in the model
+        """
+        if self.device is not None:
+            return self.device
+
+        # Find device from parameters
+        for param in self.parameters():
+            self.device = param.device
+            return param.device
+
+        # Find device from buffers
+        for buffer in self.buffers():
+            self.device = buffer.device
+            return buffer.device
+
+        raise ValueError("No tensor found in model")
+
+    # =========================================================================
+    # Adaptive Batching Methods
+    # =========================================================================
+
+    def batch_inference(
+        self,
+        images: list[np.ndarray | Image.Image | str],
+        process_res: int = 504,
+        batch_size: int | str = "auto",
+        max_batch_size: int = 64,
+        target_memory_utilization: float = 0.85,
+        progress_callback: callable | None = None,
+    ) -> list[Prediction]:
+        """
+        Run inference on multiple images with adaptive batching.
+
+        This method automatically determines optimal batch sizes based on
+        available GPU memory, maximizing throughput while preventing OOM errors.
+
+        Args:
+            images: List of input images (numpy arrays, PIL Images, or file paths)
+            process_res: Processing resolution (default: 504)
+            batch_size: Batch size or "auto" for adaptive batching (default: "auto")
+            max_batch_size: Maximum batch size when using adaptive batching (default: 64)
+            target_memory_utilization: Target GPU memory usage 0.0-1.0 (default: 0.85)
+            progress_callback: Optional callback(processed, total) for progress updates
+
+        Returns:
+            List of Prediction objects, one per batch
+
+        Example:
+            >>> model = DepthAnything3(model_name="da3-large")
+            >>> images = ["img1.jpg", "img2.jpg", ..., "img100.jpg"]
+            >>>
+            >>> # Adaptive batching (recommended)
+            >>> results = model.batch_inference(images, process_res=518)
+            >>>
+            >>> # Fixed batch size
+            >>> results = model.batch_inference(images, batch_size=4)
+            >>>
+            >>> # With progress callback
+            >>> def on_progress(done, total):
+            ...     print(f"Processed {done}/{total}")
+            >>> results = model.batch_inference(images, progress_callback=on_progress)
+        """
+        import gc
+
+        num_images = len(images)
+        if num_images == 0:
+            return []
+
+        results: list[Prediction] = []
+
+        # Determine batch size
+        if batch_size == "auto":
+            config = AdaptiveBatchConfig(
+                max_batch_size=max_batch_size,
+                target_memory_utilization=target_memory_utilization,
+            )
+            calculator = AdaptiveBatchSizeCalculator(
+                model_name=self.model_name,
+                device=self.device,
+                config=config,
+            )
+
+            for batch_info in adaptive_batch_iterator(images, calculator, process_res):
+                # Run inference on this batch
+                prediction = self.inference(
+                    image=batch_info.items,
+                    process_res=process_res,
+                )
+                results.append(prediction)
+
+                # Progress callback
+                if progress_callback:
+                    progress_callback(batch_info.end_idx, num_images)
+
+                # Memory cleanup between batches
+                if not batch_info.is_last:
+                    gc.collect()
+                    if self.device.type == "cuda":
+                        torch.cuda.empty_cache()
+                    elif self.device.type == "mps":
+                        torch.mps.empty_cache()
+
+                # Update profiling data for better estimates
+                if calculator.config.enable_profiling and self.device.type == "cuda":
+                    memory_used = torch.cuda.max_memory_allocated(self.device) / (1024 * 1024)
+                    calculator.update_from_profiling(
+                        batch_size=batch_info.batch_size,
+                        memory_used_mb=memory_used,
+                        process_res=process_res,
+                    )
+                    torch.cuda.reset_peak_memory_stats(self.device)
+
+        else:
+            # Fixed batch size
+            fixed_batch_size = int(batch_size)
+            for i in range(0, num_images, fixed_batch_size):
+                end_idx = min(i + fixed_batch_size, num_images)
+                batch_images = images[i:end_idx]
+
+                prediction = self.inference(
+                    image=batch_images,
+                    process_res=process_res,
+                )
+                results.append(prediction)
+
+                if progress_callback:
+                    progress_callback(end_idx, num_images)
+
+                # Memory cleanup
+                if end_idx < num_images:
+                    gc.collect()
+                    if self.device.type == "cuda":
+                        torch.cuda.empty_cache()
+                    elif self.device.type == "mps":
+                        torch.mps.empty_cache()
+
+        return results
+
+    def get_optimal_batch_size(
+        self,
+        process_res: int = 504,
+        target_utilization: float = 0.85,
+    ) -> int:
+        """
+        Get the optimal batch size for current GPU memory state.
+
+        Args:
+            process_res: Processing resolution (default: 504)
+            target_utilization: Target GPU memory usage 0.0-1.0 (default: 0.85)
+
+        Returns:
+            Recommended batch size
+
+        Example:
+            >>> model = DepthAnything3(model_name="da3-large")
+            >>> batch_size = model.get_optimal_batch_size(process_res=518)
+            >>> print(f"Optimal batch size: {batch_size}")
+        """
+        return estimate_max_batch_size(
+            model_name=self.model_name,
+            device=self.device,
+            process_res=process_res,
+            target_utilization=target_utilization,
+        )

src/depth_anything_3/app/css_and_html.py

@@ -0,0 +1,623 @@
+# flake8: noqa: E501
+
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+CSS and HTML content for the Depth Anything 3 Gradio application.
+This module contains all the CSS styles and HTML content blocks
+used in the Gradio interface.
+"""
+
+# CSS Styles for the Gradio interface
+# Color palette:
+# - Primary: #2563EB (Modern Blue)
+# - Secondary: #14B8A6 (Vibrant Teal)
+# - Accent: #F97316 (Electric Orange)
+# - Neutrals: #F9FAFB to #111827
+GRADIO_CSS = """
+/* Add Font Awesome CDN with all styles including brands and colors */
+@import url('https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css');
+
+/* Force light mode */
+html, body, .gradio-container {
+    color-scheme: light !important;
+}
+
+/* CSS Custom Properties for theming */
+:root {
+    --primary: #2563EB;
+    --primary-light: #3B82F6;
+    --primary-dark: #1D4ED8;
+    --secondary: #14B8A6;
+    --secondary-light: #2DD4BF;
+    --secondary-dark: #0D9488;
+    --accent: #F97316;
+    --accent-light: #FB923C;
+    --accent-dark: #EA580C;
+    --neutral-50: #F9FAFB;
+    --neutral-100: #F3F4F6;
+    --neutral-200: #E5E7EB;
+    --neutral-300: #D1D5DB;
+    --neutral-400: #9CA3AF;
+    --neutral-500: #6B7280;
+    --neutral-600: #4B5563;
+    --neutral-700: #374151;
+    --neutral-800: #1F2937;
+    --neutral-900: #111827;
+}
+
+/* Add custom styles for colored icons */
+.fa-color-blue {
+    color: var(--primary);
+}
+
+.fa-color-purple {
+    color: #8B5CF6;
+}
+
+.fa-color-cyan {
+    color: var(--secondary);
+}
+
+.fa-color-green {
+    color: #10B981;
+}
+
+.fa-color-yellow {
+    color: var(--accent);
+}
+
+.fa-color-red {
+    color: #EF4444;
+}
+
+.link-btn {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    text-decoration: none;
+    padding: 12px 24px;
+    border-radius: 50px;
+    font-weight: 500;
+    transition: all 0.3s ease;
+}
+
+/* Dark mode theme */
+@media (prefers-color-scheme: dark) {
+    html, body {
+        background: var(--neutral-800);
+        color: var(--neutral-50);
+    }
+
+    .gradio-container {
+        background: var(--neutral-800);
+        color: var(--neutral-50);
+    }
+
+    .link-btn {
+        background: rgba(20, 184, 166, 0.2);
+        color: white;
+        border: 1px solid rgba(20, 184, 166, 0.4);
+    }
+
+    .link-btn:hover {
+        background: rgba(20, 184, 166, 0.35);
+        transform: translateY(-2px);
+        box-shadow: 0 8px 25px rgba(20, 184, 166, 0.25);
+    }
+
+    .tech-bg {
+        background: linear-gradient(135deg, var(--neutral-900), var(--neutral-800));
+        position: relative;
+        overflow: hidden;
+    }
+
+    .tech-bg::before {
+        content: '';
+        position: absolute;
+        top: 0;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        background:
+            radial-gradient(circle at 20% 80%, rgba(37, 99, 235, 0.15) 0%, transparent 50%),
+            radial-gradient(circle at 80% 20%, rgba(20, 184, 166, 0.15) 0%, transparent 50%),
+            radial-gradient(circle at 40% 40%, rgba(249, 115, 22, 0.1) 0%, transparent 50%);
+        animation: techPulse 8s ease-in-out infinite;
+    }
+
+    .gradio-container .panel,
+    .gradio-container .block,
+    .gradio-container .form {
+        background: rgba(0, 0, 0, 0.3);
+        border: 1px solid rgba(20, 184, 166, 0.2);
+        border-radius: 10px;
+    }
+
+    .gradio-container * {
+        color: var(--neutral-50);
+    }
+
+    .gradio-container label {
+        color: var(--neutral-200);
+    }
+
+    .gradio-container .markdown {
+        color: var(--neutral-200);
+    }
+}
+
+/* Light mode theme */
+@media (prefers-color-scheme: light) {
+    html, body {
+        background: var(--neutral-50);
+        color: var(--neutral-800);
+    }
+
+    .gradio-container {
+        background: var(--neutral-50);
+        color: var(--neutral-800);
+    }
+
+    .tech-bg {
+        background: linear-gradient(135deg, var(--neutral-50), var(--neutral-100));
+        position: relative;
+        overflow: hidden;
+    }
+
+    .link-btn {
+        background: rgba(20, 184, 166, 0.12);
+        color: var(--neutral-700);
+        border: 1px solid rgba(20, 184, 166, 0.3);
+    }
+
+    .link-btn:hover {
+        background: rgba(20, 184, 166, 0.2);
+        transform: translateY(-2px);
+        box-shadow: 0 8px 25px rgba(20, 184, 166, 0.2);
+    }
+
+    .tech-bg::before {
+        content: '';
+        position: absolute;
+        top: 0;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        background:
+            radial-gradient(circle at 20% 80%, rgba(37, 99, 235, 0.08) 0%, transparent 50%),
+            radial-gradient(circle at 80% 20%, rgba(20, 184, 166, 0.08) 0%, transparent 50%),
+            radial-gradient(circle at 40% 40%, rgba(249, 115, 22, 0.06) 0%, transparent 50%);
+        animation: techPulse 8s ease-in-out infinite;
+    }
+
+    .gradio-container .panel,
+    .gradio-container .block,
+    .gradio-container .form {
+        background: rgba(255, 255, 255, 0.9);
+        border: 1px solid rgba(20, 184, 166, 0.2);
+        border-radius: 10px;
+        box-shadow: 0 4px 6px rgba(0, 0, 0, 0.05);
+    }
+
+    .gradio-container * {
+        color: var(--neutral-800);
+    }
+
+    .gradio-container label {
+        color: var(--neutral-600);
+    }
+
+    .gradio-container .markdown {
+        color: var(--neutral-600);
+    }
+}
+
+
+
+
+@keyframes techPulse {
+    0%, 100% { opacity: 0.5; }
+    50% { opacity: 0.8; }
+}
+
+/* Custom log with tech gradient */
+.custom-log * {
+    font-style: italic;
+    font-size: 22px !important;
+    background: linear-gradient(135deg, var(--primary), var(--secondary));
+    background-size: 400% 400%;
+    -webkit-background-clip: text;
+    background-clip: text;
+    font-weight: bold !important;
+    color: transparent !important;
+    text-align: center !important;
+    animation: techGradient 3s ease infinite;
+}
+
+@keyframes techGradient {
+    0% { background-position: 0% 50%; }
+    50% { background-position: 100% 50%; }
+    100% { background-position: 0% 50%; }
+}
+
+@keyframes metricPulse {
+    0%, 100% { background-position: 0% 50%; }
+    50% { background-position: 100% 50%; }
+}
+
+@keyframes pointcloudPulse {
+    0%, 100% { background-position: 0% 50%; }
+    50% { background-position: 100% 50%; }
+}
+
+@keyframes camerasPulse {
+    0%, 100% { background-position: 0% 50%; }
+    50% { background-position: 100% 50%; }
+}
+
+@keyframes gaussiansPulse {
+    0%, 100% { background-position: 0% 50%; }
+    50% { background-position: 100% 50%; }
+}
+
+/* Special colors for key terms - Global styles with gradient animations */
+.metric-text {
+    background: linear-gradient(135deg, #10B981, #059669);
+    background-size: 200% 200%;
+    -webkit-background-clip: text;
+    background-clip: text;
+    color: transparent !important;
+    font-weight: 700;
+    animation: metricPulse 3s ease infinite;
+}
+
+.pointcloud-text {
+    background: linear-gradient(135deg, #10B981, #059669);
+    background-size: 200% 200%;
+    -webkit-background-clip: text;
+    background-clip: text;
+    color: transparent !important;
+    font-weight: 700;
+    animation: pointcloudPulse 3s ease infinite;
+}
+
+.cameras-text {
+    background: linear-gradient(135deg, #F97316, #EA580C);
+    background-size: 200% 200%;
+    -webkit-background-clip: text;
+    background-clip: text;
+    color: transparent !important;
+    font-weight: 700;
+    animation: camerasPulse 3s ease infinite;
+}
+
+.gaussians-text {
+    background: linear-gradient(135deg, #2563EB, #1D4ED8);
+    background-size: 200% 200%;
+    -webkit-background-clip: text;
+    background-clip: text;
+    color: transparent !important;
+    font-weight: 700;
+    animation: gaussiansPulse 3s ease infinite;
+}
+
+.example-log * {
+    font-style: italic;
+    font-size: 16px !important;
+    background: linear-gradient(135deg, var(--primary), var(--secondary));
+    -webkit-background-clip: text;
+    background-clip: text;
+    color: transparent !important;
+}
+
+#my_radio .wrap {
+    display: flex;
+    flex-wrap: nowrap;
+    justify-content: center;
+    align-items: center;
+}
+
+#my_radio .wrap label {
+    display: flex;
+    width: 50%;
+    justify-content: center;
+    align-items: center;
+    margin: 0;
+    padding: 10px 0;
+    box-sizing: border-box;
+}
+
+/* Align navigation buttons with dropdown bottom */
+.navigation-row {
+    display: flex !important;
+    align-items: flex-end !important;
+    gap: 8px !important;
+}
+
+.navigation-row > div:nth-child(1),
+.navigation-row > div:nth-child(3) {
+    align-self: flex-end !important;
+}
+
+.navigation-row > div:nth-child(2) {
+    flex: 1 !important;
+}
+
+/* Make thumbnails clickable with pointer cursor */
+.clickable-thumbnail img {
+    cursor: pointer !important;
+}
+
+.clickable-thumbnail:hover img {
+    cursor: pointer !important;
+    opacity: 0.8;
+    transition: opacity 0.3s ease;
+}
+
+/* Make thumbnail containers narrower horizontally */
+.clickable-thumbnail {
+    padding: 5px 2px !important;
+    margin: 0 2px !important;
+}
+
+.clickable-thumbnail .image-container {
+    margin: 0 !important;
+    padding: 0 !important;
+}
+
+.scene-info {
+    text-align: center !important;
+    padding: 5px 2px !important;
+    margin: 0 !important;
+}
+"""
+
+
+def get_header_html(logo_base64=None):
+    """
+    Generate the main header HTML with logo and title.
+
+    Args:
+        logo_base64 (str, optional): Base64 encoded logo image
+
+    Returns:
+        str: HTML string for the header
+    """
+    return """
+    <div class="tech-bg" style="text-align: center; margin-bottom: 5px; padding: 40px 20px; border-radius: 15px; position: relative; overflow: hidden;">
+        <div style="position: relative; z-index: 2;">
+            <h1 style="margin: 0; font-size: 3.5em; font-weight: 700;
+                background: linear-gradient(135deg, #2563EB, #14B8A6);
+                background-size: 400% 400%;
+                -webkit-background-clip: text;
+                background-clip: text;
+                color: transparent;
+                animation: techGradient 3s ease infinite;
+                text-shadow: 0 0 30px rgba(20, 184, 166, 0.4);
+                letter-spacing: 2px;">
+                Depth Anything 3
+            </h1>
+            <p style="margin: 15px 0 0 0; font-size: 2.16em; font-weight: 300;" class="header-subtitle">
+                Recovering the Visual Space from Any Views
+            </p>
+            <div style="margin-top: 20px;">
+                <a href="https://depth-anything-3.github.io" target="_blank" class="link-btn" style="margin: 0.5em;">
+                    <i class="fas fa-globe" style="margin-right: 8px;"></i> Project Page
+                </a>
+                <a href="https://arxiv.org/abs/2406.09414" target="_blank" class="link-btn" style="margin: 0.5em;">
+                    <i class="fas fa-file-pdf" style="margin-right: 8px;"></i> Paper
+                </a>
+                <a href="https://github.com/Aedelon/awesome-depth-anything-3" target="_blank" class="link-btn" style="margin: 0.5em; background: var(--secondary); color: white; border: none; font-weight: 600;">
+                    <i class="fab fa-github" style="margin-right: 8px;"></i> Awesome Optimized Fork
+                </a>
+                <a href="https://github.com/ByteDance-Seed/Depth-Anything-3" target="_blank" class="link-btn" style="margin: 0.5em;">
+                    <i class="fab fa-github" style="margin-right: 8px;"></i> Original
+                </a>
+            </div>
+        </div>
+    </div>
+
+    <style>
+        .header-subtitle {
+            color: #4B5563;
+        }
+        .tech-bg {
+            background: linear-gradient(135deg, rgba(20, 184, 166, 0.08) 0%, rgba(37, 99, 235, 0.08) 100%) !important;
+        }
+    </style>
+    <script>
+        document.body.classList.add('light');
+        document.documentElement.classList.add('light');
+    </script>
+    """
+
+
+def get_description_html():
+    """
+    Generate the main description and getting started HTML.
+
+    Returns:
+        str: HTML string for the description
+    """
+    return """
+    <div class="description-container" style="padding: 25px; border-radius: 15px; margin: 0 0 20px 0;">
+        <h2 class="description-title" style="margin-top: 0; font-size: 1.6em; text-align: center;">
+            <i class="fas fa-bullseye fa-color-red" style="margin-right: 8px;"></i> What This Demo Does
+        </h2>
+        <div class="description-content" style="padding: 20px; border-radius: 10px; margin: 15px 0; text-align: center;">
+            <p class="description-main" style="line-height: 1.6; margin: 0; font-size: 1.45em;">
+                <strong>Upload images or videos</strong> → <strong>Get <span class="metric-text">Metric</span> <span class="pointcloud-text">Point Clouds</span>, <span class="cameras-text">Cameras</span> and <span class="gaussians-text">Novel Views</span></strong> → <strong>Explore in 3D</strong>
+            </p>
+        </div>
+
+        <div style="text-align: center; margin-top: 15px;">
+            <p class="description-tip" style="font-style: italic; margin: 0;">
+                <i class="fas fa-lightbulb fa-color-yellow" style="margin-right: 8px;"></i> <strong>Tip:</strong> Landscape-oriented images or videos are preferred for best 3D recovering.
+            </p>
+        </div>
+    </div>
+
+    <style>
+        @media (prefers-color-scheme: dark) {
+            .description-container {
+                background: linear-gradient(135deg, rgba(20, 184, 166, 0.08) 0%, rgba(37, 99, 235, 0.08) 100%);
+                border: 1px solid rgba(20, 184, 166, 0.2);
+            }
+            .description-title { color: #14B8A6; }
+            .description-content { background: rgba(0, 0, 0, 0.3); }
+            .description-main { color: #E5E7EB; }
+            .description-text { color: #D1D5DB; }
+            .description-tip { color: #D1D5DB; }
+        }
+
+        @media (prefers-color-scheme: light) {
+            .description-container {
+                background: linear-gradient(135deg, rgba(20, 184, 166, 0.05) 0%, rgba(37, 99, 235, 0.05) 100%);
+                border: 1px solid rgba(20, 184, 166, 0.2);
+            }
+            .description-title { color: #14B8A6; }
+            .description-content { background: transparent; }
+            .description-main { color: #1F2937; }
+            .description-text { color: #4B5563; }
+            .description-tip { color: #4B5563; }
+        }
+    </style>
+    """
+
+
+def get_acknowledgements_html():
+    """
+    Generate the acknowledgements section HTML.
+
+    Returns:
+        str: HTML string for the acknowledgements
+    """
+    return """
+    <div style="background: linear-gradient(135deg, rgba(20, 184, 166, 0.08) 0%, rgba(37, 99, 235, 0.08) 100%);
+                padding: 25px; border-radius: 15px; margin: 20px 0; border: 1px solid rgba(20, 184, 166, 0.2);">
+        <h3 style="color: #14B8A6; margin-top: 0; text-align: center; font-size: 1.4em;">
+            <i class="fas fa-trophy fa-color-yellow" style="margin-right: 8px;"></i> Research Credits & Acknowledgments
+        </h3>
+
+        <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 20px; margin: 15px 0;">
+            <!-- Original Research Section (Left) -->
+            <div style="text-align: center;">
+                <h4 style="color: #2563EB; margin: 10px 0;"><i class="fas fa-flask fa-color-green" style="margin-right: 8px;"></i> Original Research</h4>
+                <p style="color: #9CA3AF; margin: 5px 0;">
+                    <a href="https://depth-anything-3.github.io" target="_blank"
+                       style="color: #14B8A6; text-decoration: none; font-weight: 600;">
+                        Depth Anything 3
+                    </a>
+                </p>
+            </div>
+
+            <!-- Previous Versions Section (Right) -->
+            <div style="text-align: center;">
+                <h4 style="color: #2563EB; margin: 10px 0;"><i class="fas fa-history fa-color-blue" style="margin-right: 8px;"></i> Previous Versions</h4>
+                <div style="display: flex; flex-direction: row; gap: 15px; justify-content: center; align-items: center;">
+                    <p style="color: #9CA3AF; margin: 0;">
+                        <a href="https://huggingface.co/spaces/LiheYoung/Depth-Anything" target="_blank"
+                           style="color: #14B8A6; text-decoration: none; font-weight: 600;">
+                            Depth-Anything
+                        </a>
+                    </p>
+                    <span style="color: #9CA3AF;">•</span>
+                    <p style="color: #9CA3AF; margin: 0;">
+                        <a href="https://huggingface.co/spaces/depth-anything/Depth-Anything-V2" target="_blank"
+                           style="color: #14B8A6; text-decoration: none; font-weight: 600;">
+                            Depth-Anything-V2
+                        </a>
+                    </p>
+                </div>
+            </div>
+        </div>
+
+        <!-- HF Demo Adapted from - Centered at the bottom of the whole block -->
+        <div style="margin-top: 20px; padding-top: 15px; border-top: 1px solid rgba(20, 184, 166, 0.2); text-align: center;">
+            <p style="color: #6B7280; font-size: 0.9em; margin: 0;">
+                <i class="fas fa-code-branch" style="margin-right: 5px; color: #9CA3AF;"></i> HF demo adapted from <a href="https://huggingface.co/spaces/facebook/map-anything" target="_blank" style="color: inherit; text-decoration: none;">Map Anything</a>
+            </p>
+        </div>
+    </div>
+    """
+
+
+def get_gradio_theme():
+    """
+    Get the configured Gradio theme with modern teal/blue colors.
+
+    Color palette:
+    - Primary: Teal (#14B8A6)
+    - Secondary: Blue (#2563EB)
+    - Accent: Orange (#F97316)
+    - Neutrals: Clean grays (#F9FAFB to #111827)
+
+    Returns:
+        gr.themes.Base: Configured Gradio theme
+    """
+    import gradio as gr
+
+    return gr.themes.Base(
+        # Primary hue: Teal
+        primary_hue=gr.themes.Color(
+            c50="#F0FDFA",
+            c100="#CCFBF1",
+            c200="#99F6E4",
+            c300="#5EEAD4",
+            c400="#2DD4BF",
+            c500="#14B8A6",
+            c600="#0D9488",
+            c700="#0F766E",
+            c800="#115E59",
+            c900="#134E4A",
+            c950="#042F2E",
+        ),
+        # Secondary hue: Blue
+        secondary_hue=gr.themes.Color(
+            c50="#EFF6FF",
+            c100="#DBEAFE",
+            c200="#BFDBFE",
+            c300="#93C5FD",
+            c400="#60A5FA",
+            c500="#3B82F6",
+            c600="#2563EB",
+            c700="#1D4ED8",
+            c800="#1E40AF",
+            c900="#1E3A8A",
+            c950="#172554",
+        ),
+        # Neutral hue: Clean grays
+        neutral_hue=gr.themes.Color(
+            c50="#F9FAFB",
+            c100="#F3F4F6",
+            c200="#E5E7EB",
+            c300="#D1D5DB",
+            c400="#9CA3AF",
+            c500="#6B7280",
+            c600="#4B5563",
+            c700="#374151",
+            c800="#1F2937",
+            c900="#111827",
+            c950="#030712",
+        ),
+    )
+
+
+# Measure tab instructions HTML
+MEASURE_INSTRUCTIONS_HTML = """
+### Click points on the image to compute distance.
+> <i class="fas fa-triangle-exclamation fa-color-red" style="margin-right: 5px;"></i> Metric scale estimation is difficult on aerial/drone images.
+"""

src/depth_anything_3/app/gradio_app.py

@@ -0,0 +1,743 @@
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Refactored Gradio App for Depth Anything 3.
+
+This is the main application file that orchestrates all components.
+The original functionality has been split into modular components for better maintainability.
+"""
+
+import argparse
+import os
+from typing import Any, Dict, List
+
+import gradio as gr
+
+from depth_anything_3.app.css_and_html import GRADIO_CSS, get_gradio_theme
+from depth_anything_3.app.modules.event_handlers import EventHandlers
+from depth_anything_3.app.modules.ui_components import UIComponents
+
+# Set environment variables
+os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "expandable_segments:True"
+
+
+class DepthAnything3App:
+    """
+    Main application class for Depth Anything 3 Gradio app.
+    """
+
+    def __init__(self, model_dir: str = None, workspace_dir: str = None, gallery_dir: str = None):
+        """
+        Initialize the application.
+
+        Args:
+            model_dir: Path to the model directory
+            workspace_dir: Path to the workspace directory
+            gallery_dir: Path to the gallery directory
+        """
+        self.model_dir = model_dir
+        self.workspace_dir = workspace_dir
+        self.gallery_dir = gallery_dir
+
+        # Set environment variables for directories
+        if self.model_dir:
+            os.environ["DA3_MODEL_DIR"] = self.model_dir
+        if self.workspace_dir:
+            os.environ["DA3_WORKSPACE_DIR"] = self.workspace_dir
+        if self.gallery_dir:
+            os.environ["DA3_GALLERY_DIR"] = self.gallery_dir
+
+        self.event_handlers = EventHandlers()
+        self.ui_components = UIComponents()
+
+    def cache_examples(
+        self,
+        show_cam: bool = True,
+        filter_black_bg: bool = False,
+        filter_white_bg: bool = False,
+        save_percentage: float = 20.0,
+        num_max_points: int = 1000,
+        cache_gs_tag: str = "",
+        gs_trj_mode: str = "smooth",
+        gs_video_quality: str = "low",
+    ) -> None:
+        """
+        Pre-cache all example scenes at startup.
+
+        Args:
+            show_cam: Whether to show camera in visualization
+            filter_black_bg: Whether to filter black background
+            filter_white_bg: Whether to filter white background
+            save_percentage: Filter percentage for point cloud
+            num_max_points: Maximum number of points
+            cache_gs_tag: Tag to match scene names for high-res+3DGS caching (e.g., "dl3dv")
+            gs_trj_mode: Trajectory mode for 3DGS
+            gs_video_quality: Video quality for 3DGS
+        """
+        from depth_anything_3.app.modules.utils import get_scene_info
+
+        examples_dir = os.path.join(self.workspace_dir, "examples")
+        if not os.path.exists(examples_dir):
+            print(f"Examples directory not found: {examples_dir}")
+            return
+
+        scenes = get_scene_info(examples_dir)
+        if not scenes:
+            print("No example scenes found to cache.")
+            return
+
+        print(f"\n{'='*60}")
+        print(f"Caching {len(scenes)} example scenes...")
+        print(f"{'='*60}\n")
+
+        for i, scene in enumerate(scenes, 1):
+            scene_name = scene["name"]
+
+            # Check if scene name matches the gs tag for high-res+3DGS caching
+            use_high_res_gs = cache_gs_tag and cache_gs_tag.lower() in scene_name.lower()
+
+            if use_high_res_gs:
+                print(f"[{i}/{len(scenes)}] Caching scene: {scene_name} (HIGH-RES + 3DGS)")
+                print(f"  - Number of images: {scene['num_images']}")
+                print(f"  - Matched tag: '{cache_gs_tag}' - using high_res + 3DGS")
+            else:
+                print(f"[{i}/{len(scenes)}] Caching scene: {scene_name} (LOW-RES)")
+                print(f"  - Number of images: {scene['num_images']}")
+
+            try:
+                # Load example scene
+                _, target_dir, _, _, _, _, _, _, _ = self.event_handlers.load_example_scene(
+                    scene_name
+                )
+
+                if target_dir and target_dir != "None":
+                    # Run reconstruction with appropriate settings
+                    print("  - Running reconstruction...")
+                    result = self.event_handlers.gradio_demo(
+                        target_dir=target_dir,
+                        show_cam=show_cam,
+                        filter_black_bg=filter_black_bg,
+                        filter_white_bg=filter_white_bg,
+                        process_res_method="high_res" if use_high_res_gs else "low_res",
+                        save_percentage=save_percentage,
+                        num_max_points=num_max_points,
+                        infer_gs=use_high_res_gs,
+                        ref_view_strategy="saddle_balanced",
+                        gs_trj_mode=gs_trj_mode,
+                        gs_video_quality=gs_video_quality,
+                    )
+
+                    # Check if successful
+                    if result[0] is not None:  # reconstruction_output
+                        print(f"  ✓ Scene '{scene_name}' cached successfully")
+                    else:
+                        print(f"  ✗ Scene '{scene_name}' caching failed: {result[1]}")
+                else:
+                    print(f"  ✗ Scene '{scene_name}' loading failed")
+
+            except Exception as e:
+                print(f"  ✗ Error caching scene '{scene_name}': {str(e)}")
+
+            print()
+
+        print("=" * 60)
+        print("Example scene caching completed!")
+        print("=" * 60 + "\n")
+
+    def create_app(self) -> gr.Blocks:
+        """
+        Create and configure the Gradio application.
+
+        Returns:
+            Configured Gradio Blocks interface
+        """
+        # Get theme and CSS
+        self._theme = get_gradio_theme()
+        self._css = GRADIO_CSS
+
+        with gr.Blocks(theme=self._theme, css=self._css) as demo:
+            # State variables for the tabbed interface
+            is_example = gr.Textbox(label="is_example", visible=False, value="None")
+            processed_data_state = gr.State(value=None)
+            measure_points_state = gr.State(value=[])
+            selected_image_index_state = gr.State(value=0)  # Track selected image index
+            # current_view_index = gr.State(value=0)  # noqa: F841 Track current view index
+
+            # Header and description
+            self.ui_components.create_header_section()
+            self.ui_components.create_description_section()
+
+            target_dir_output = gr.Textbox(label="Target Dir", visible=False, value="None")
+
+            # Main content area
+            with gr.Row():
+                with gr.Column(scale=2):
+                    # Upload section
+                    (
+                        input_video,
+                        s_time_interval,
+                        input_images,
+                        image_gallery,
+                    ) = self.ui_components.create_upload_section()
+
+                with gr.Column(scale=4):
+                    with gr.Column():
+                        # gr.Markdown("**Metric 3D Reconstruction (Point Cloud and Camera Poses)**")
+                        # Reconstruction control section (buttons) - moved below tabs
+
+                        log_output = gr.Markdown(
+                            "Please upload a video or images, then click Reconstruct.",
+                            elem_classes=["custom-log"],
+                        )
+
+                        # Tabbed interface
+                        with gr.Tabs():
+                            with gr.Tab("Point Cloud & Cameras"):
+                                reconstruction_output = (
+                                    self.ui_components.create_3d_viewer_section()
+                                )
+
+                            with gr.Tab("Metric Depth"):
+                                (
+                                    prev_measure_btn,
+                                    measure_view_selector,
+                                    next_measure_btn,
+                                    measure_image,
+                                    measure_depth_image,
+                                    measure_text,
+                                ) = self.ui_components.create_measure_section()
+
+                            with gr.Tab("3DGS Rendered Novel Views"):
+                                gs_video, gs_info = self.ui_components.create_nvs_video()
+
+                        # Inference control section (before inference)
+                        (
+                            model_selector,
+                            process_res_method_dropdown,
+                            infer_gs,
+                            ref_view_strategy_dropdown,
+                        ) = self.ui_components.create_inference_control_section()
+
+                        # Display control section - includes 3DGS options, buttons, and Visualization Options  # noqa: E501
+                        (
+                            show_cam,
+                            filter_black_bg,
+                            filter_white_bg,
+                            save_percentage,
+                            num_max_points,
+                            gs_trj_mode,
+                            gs_video_quality,
+                            submit_btn,
+                            clear_btn,
+                        ) = self.ui_components.create_display_control_section()
+
+                        # bind visibility of gs_trj_mode to infer_gs
+                        infer_gs.change(
+                            fn=lambda checked: (
+                                gr.update(visible=checked),
+                                gr.update(visible=checked),
+                                gr.update(visible=checked),
+                                gr.update(visible=(not checked)),
+                            ),
+                            inputs=infer_gs,
+                            outputs=[gs_trj_mode, gs_video_quality, gs_video, gs_info],
+                        )
+
+            # Example scenes section
+            gr.Markdown("## Example Scenes")
+
+            scenes = self.ui_components.create_example_scenes_section()
+            scene_components = self.ui_components.create_example_scene_grid(scenes)
+
+            # Set up event handlers
+            self._setup_event_handlers(
+                demo,
+                is_example,
+                processed_data_state,
+                measure_points_state,
+                target_dir_output,
+                input_video,
+                input_images,
+                s_time_interval,
+                image_gallery,
+                reconstruction_output,
+                log_output,
+                show_cam,
+                filter_black_bg,
+                filter_white_bg,
+                process_res_method_dropdown,
+                save_percentage,
+                submit_btn,
+                clear_btn,
+                num_max_points,
+                infer_gs,
+                ref_view_strategy_dropdown,
+                selected_image_index_state,
+                measure_view_selector,
+                measure_image,
+                measure_depth_image,
+                measure_text,
+                prev_measure_btn,
+                next_measure_btn,
+                scenes,
+                scene_components,
+                gs_video,
+                gs_info,
+                gs_trj_mode,
+                gs_video_quality,
+                model_selector,
+                s_time_interval,
+            )
+
+            # Acknowledgements
+            self.ui_components.create_acknowledgements_section()
+
+        return demo
+
+    def _setup_event_handlers(
+        self,
+        demo: gr.Blocks,
+        is_example: gr.Textbox,
+        processed_data_state: gr.State,
+        measure_points_state: gr.State,
+        target_dir_output: gr.Textbox,
+        input_video: gr.Video,
+        input_images: gr.File,
+        s_time_interval: gr.Slider,
+        image_gallery: gr.Gallery,
+        reconstruction_output: gr.Model3D,
+        log_output: gr.Markdown,
+        show_cam: gr.Checkbox,
+        filter_black_bg: gr.Checkbox,
+        filter_white_bg: gr.Checkbox,
+        process_res_method_dropdown: gr.Dropdown,
+        save_percentage: gr.Slider,
+        submit_btn: gr.Button,
+        clear_btn: gr.ClearButton,
+        num_max_points: gr.Slider,
+        infer_gs: gr.Checkbox,
+        ref_view_strategy_dropdown: gr.Dropdown,
+        selected_image_index_state: gr.State,
+        measure_view_selector: gr.Dropdown,
+        measure_image: gr.Image,
+        measure_depth_image: gr.Image,
+        measure_text: gr.Markdown,
+        prev_measure_btn: gr.Button,
+        next_measure_btn: gr.Button,
+        scenes: List[Dict[str, Any]],
+        scene_components: List,  # List of gr.Image or gr.Video
+        gs_video: gr.Video,
+        gs_info: gr.Markdown,
+        gs_trj_mode: gr.Dropdown,
+        gs_video_quality: gr.Dropdown,
+        model_selector: gr.Dropdown,
+        s_time_interval_slider: gr.Slider,
+    ) -> None:
+        """
+        Set up all event handlers for the application.
+
+        Args:
+            demo: Gradio Blocks interface
+            All other arguments: Gradio components to connect
+        """
+        # Configure clear button
+        clear_btn.add(
+            [
+                input_video,
+                input_images,
+                reconstruction_output,
+                log_output,
+                target_dir_output,
+                image_gallery,
+                gs_video,
+            ]
+        )
+
+        # Main reconstruction button
+        submit_btn.click(
+            fn=self.event_handlers.gradio_demo,
+            inputs=[
+                target_dir_output,
+                show_cam,
+                filter_black_bg,
+                filter_white_bg,
+                process_res_method_dropdown,
+                save_percentage,
+                num_max_points,
+                infer_gs,
+                ref_view_strategy_dropdown,
+                gs_trj_mode,
+                gs_video_quality,
+                model_selector,
+            ],
+            outputs=[
+                reconstruction_output,
+                log_output,
+                processed_data_state,
+                measure_image,
+                measure_depth_image,
+                measure_text,
+                measure_view_selector,
+                gs_video,
+                gs_info,
+            ],
+        )
+
+        # Real-time visualization updates
+        self._setup_visualization_handlers(
+            show_cam,
+            filter_black_bg,
+            filter_white_bg,
+            process_res_method_dropdown,
+            target_dir_output,
+            is_example,
+            reconstruction_output,
+            log_output,
+        )
+
+        # File upload handlers
+        input_video.change(
+            fn=self.event_handlers.handle_uploads,
+            inputs=[input_video, input_images, s_time_interval],
+            outputs=[reconstruction_output, target_dir_output, image_gallery, log_output],
+        )
+        input_images.change(
+            fn=self.event_handlers.handle_uploads,
+            inputs=[input_video, input_images, s_time_interval],
+            outputs=[reconstruction_output, target_dir_output, image_gallery, log_output],
+        )
+
+        # Navigation handlers
+        self._setup_navigation_handlers(
+            prev_measure_btn,
+            next_measure_btn,
+            measure_view_selector,
+            measure_image,
+            measure_depth_image,
+            measure_points_state,
+            processed_data_state,
+        )
+
+        # Measurement handler
+        measure_image.select(
+            fn=self.event_handlers.measure,
+            inputs=[processed_data_state, measure_points_state, measure_view_selector],
+            outputs=[measure_image, measure_depth_image, measure_points_state, measure_text],
+        )
+
+        # Example scene handlers
+        self._setup_example_scene_handlers(
+            scenes,
+            scene_components,
+            reconstruction_output,
+            target_dir_output,
+            image_gallery,
+            log_output,
+            is_example,
+            processed_data_state,
+            measure_view_selector,
+            measure_image,
+            measure_depth_image,
+            gs_video,
+            gs_info,
+            s_time_interval,
+        )
+
+    def _setup_visualization_handlers(
+        self,
+        show_cam: gr.Checkbox,
+        filter_black_bg: gr.Checkbox,
+        filter_white_bg: gr.Checkbox,
+        process_res_method_dropdown: gr.Dropdown,
+        target_dir_output: gr.Textbox,
+        is_example: gr.Textbox,
+        reconstruction_output: gr.Model3D,
+        log_output: gr.Markdown,
+    ) -> None:
+        """Set up visualization update handlers."""
+        # Common inputs for visualization updates
+        viz_inputs = [
+            target_dir_output,
+            show_cam,
+            is_example,
+            filter_black_bg,
+            filter_white_bg,
+            process_res_method_dropdown,
+        ]
+
+        # Set up change handlers for all visualization controls
+        for component in [show_cam, filter_black_bg, filter_white_bg]:
+            component.change(
+                fn=self.event_handlers.update_visualization,
+                inputs=viz_inputs,
+                outputs=[reconstruction_output, log_output],
+            )
+
+    def _setup_navigation_handlers(
+        self,
+        prev_measure_btn: gr.Button,
+        next_measure_btn: gr.Button,
+        measure_view_selector: gr.Dropdown,
+        measure_image: gr.Image,
+        measure_depth_image: gr.Image,
+        measure_points_state: gr.State,
+        processed_data_state: gr.State,
+    ) -> None:
+        """Set up navigation handlers for measure tab."""
+        # Measure tab navigation
+        prev_measure_btn.click(
+            fn=lambda processed_data, current_selector: self.event_handlers.navigate_measure_view(
+                processed_data, current_selector, -1
+            ),
+            inputs=[processed_data_state, measure_view_selector],
+            outputs=[
+                measure_view_selector,
+                measure_image,
+                measure_depth_image,
+                measure_points_state,
+            ],
+        )
+
+        next_measure_btn.click(
+            fn=lambda processed_data, current_selector: self.event_handlers.navigate_measure_view(
+                processed_data, current_selector, 1
+            ),
+            inputs=[processed_data_state, measure_view_selector],
+            outputs=[
+                measure_view_selector,
+                measure_image,
+                measure_depth_image,
+                measure_points_state,
+            ],
+        )
+
+        measure_view_selector.change(
+            fn=lambda processed_data, selector_value: (
+                self.event_handlers.update_measure_view(
+                    processed_data, int(selector_value.split()[1]) - 1
+                )
+                if selector_value
+                else (None, None, [])
+            ),
+            inputs=[processed_data_state, measure_view_selector],
+            outputs=[measure_image, measure_depth_image, measure_points_state],
+        )
+
+    def _setup_example_scene_handlers(
+        self,
+        scenes: List[Dict[str, Any]],
+        scene_components: List,  # List of gr.Image
+        reconstruction_output: gr.Model3D,
+        target_dir_output: gr.Textbox,
+        image_gallery: gr.Gallery,
+        log_output: gr.Markdown,
+        is_example: gr.Textbox,
+        processed_data_state: gr.State,
+        measure_view_selector: gr.Dropdown,
+        measure_image: gr.Image,
+        measure_depth_image: gr.Image,
+        gs_video: gr.Video,
+        gs_info: gr.Markdown,
+        s_time_interval: gr.Slider,
+    ) -> None:
+        """Set up example scene handlers."""
+        # Use assets/examples directory
+        examples_dir = os.environ.get("DA3_EXAMPLES_DIR", "assets/examples")
+
+        def load_and_update_measure(scene_name: str, fps: float):
+            """Load example scene and update measure view."""
+            print(f"[load_and_update_measure] Called with scene_name={scene_name}, fps={fps}", flush=True)
+            result = self.event_handlers.load_example_scene(scene_name, examples_dir, fps)
+            print(f"[load_and_update_measure] target_dir from result[1]: {result[1]}", flush=True)
+
+            # Update measure view if processed_data is available
+            measure_img = None
+            measure_depth = None
+            if result[4] is not None:  # processed_data exists
+                measure_img, measure_depth, _ = (
+                    self.event_handlers.visualization_handler.update_measure_view(result[4], 0)
+                )
+
+            final_result = result + ("True", measure_img, measure_depth)
+            print(f"[load_and_update_measure] Returning {len(final_result)} values", flush=True)
+            return final_result
+
+        def create_scene_handler(scene_name: str):
+            """Create a handler function for a specific scene."""
+            def handler(fps: float):
+                return load_and_update_measure(scene_name, fps)
+            return handler
+
+        for i, scene in enumerate(scenes):
+            if i < len(scene_components):
+                component = scene_components[i]
+                # Create handler with scene name bound
+                handler_fn = create_scene_handler(scene["name"])
+                outputs = [
+                    reconstruction_output,
+                    target_dir_output,
+                    image_gallery,
+                    log_output,
+                    processed_data_state,
+                    measure_view_selector,
+                    gs_video,
+                    gs_info,
+                    is_example,
+                    measure_image,
+                    measure_depth_image,
+                ]
+
+                # Use click event - s_time_interval value is passed as input
+                component.select(fn=handler_fn, inputs=[s_time_interval], outputs=outputs)
+
+    def launch(self, host: str = "127.0.0.1", port: int = 7860, **kwargs) -> None:
+        """
+        Launch the application.
+
+        Args:
+            host: Host address to bind to
+            port: Port number to bind to
+            **kwargs: Additional arguments for demo.launch()
+        """
+        demo = self.create_app()
+        demo.queue(max_size=20).launch(
+            show_error=True,
+            server_name=host,
+            server_port=port,
+            **kwargs,
+        )
+
+
+def main():
+    """Main function to run the application."""
+    parser = argparse.ArgumentParser(
+        description="Depth Anything 3 Gradio Application",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Basic usage
+  python gradio_app.py --help
+  python gradio_app.py --host 0.0.0.0 --port 8080
+  python gradio_app.py --model-dir /path/to/model --workspace-dir /path/to/workspace
+
+  # Cache examples at startup (all low-res)
+  python gradio_app.py --cache-examples
+
+  # Cache with selective high-res+3DGS for scenes matching tag
+  python gradio_app.py --cache-examples --cache-gs-tag dl3dv
+  # This will use high-res + 3DGS for scenes containing "dl3dv" in their name,
+  # and low-res only for other scenes
+        """,
+    )
+
+    # Server configuration
+    parser.add_argument(
+        "--host", default="127.0.0.1", help="Host address to bind to (default: 127.0.0.1)"
+    )
+    parser.add_argument(
+        "--port", type=int, default=7860, help="Port number to bind to (default: 7860)"
+    )
+
+    # Directory configuration
+    parser.add_argument(
+        "--model-dir",
+        default="depth-anything/DA3NESTED-GIANT-LARGE",
+        help="Path to the model directory (default: depth-anything/DA3NESTED-GIANT-LARGE)",
+    )
+    parser.add_argument(
+        "--workspace-dir",
+        default="workspace/gradio",  # noqa: E501
+        help="Path to the workspace directory (default: workspace/gradio)",  # noqa: E501
+    )
+    parser.add_argument(
+        "--gallery-dir",
+        default="workspace/gallery",
+        help="Path to the gallery directory (default: workspace/gallery)",  # noqa: E501
+    )
+
+    # Additional Gradio options
+    parser.add_argument("--share", action="store_true", help="Create a public link for the app")
+    parser.add_argument("--debug", action="store_true", help="Enable debug mode")
+
+    # Example caching options
+    parser.add_argument(
+        "--cache-examples",
+        action="store_true",
+        help="Pre-cache all example scenes at startup for faster loading",
+    )
+    parser.add_argument(
+        "--cache-gs-tag",
+        type=str,
+        default="",
+        help="Tag to match scene names for high-res+3DGS caching (e.g., 'dl3dv'). Scenes containing this tag will use high_res and infer_gs=True; others will use low_res only.",  # noqa: E501
+    )
+
+    args = parser.parse_args()
+
+    # Create directories if they don't exist
+    os.makedirs(args.workspace_dir, exist_ok=True)
+    os.makedirs(args.gallery_dir, exist_ok=True)
+
+    # Initialize and launch the application
+    app = DepthAnything3App(
+        model_dir=args.model_dir, workspace_dir=args.workspace_dir, gallery_dir=args.gallery_dir
+    )
+
+    # Prepare launch arguments
+    launch_kwargs = {"share": args.share, "debug": args.debug}
+
+    print("Starting Depth Anything 3 Gradio App...")
+    print(f"Host: {args.host}")
+    print(f"Port: {args.port}")
+    print(f"Model Directory: {args.model_dir}")
+    print(f"Workspace Directory: {args.workspace_dir}")
+    print(f"Gallery Directory: {args.gallery_dir}")
+    print(f"Share: {args.share}")
+    print(f"Debug: {args.debug}")
+    print(f"Cache Examples: {args.cache_examples}")
+    if args.cache_examples:
+        if args.cache_gs_tag:
+            print(
+                f"Cache GS Tag: '{args.cache_gs_tag}' (scenes matching this tag will use high-res + 3DGS)"  # noqa: E501
+            )  # noqa: E501
+        else:
+            print("Cache GS Tag: None (all scenes will use low-res only)")
+
+    # Pre-cache examples if requested
+    if args.cache_examples:
+        print("\n" + "=" * 60)
+        print("Pre-caching mode enabled")
+        if args.cache_gs_tag:
+            print(f"Scenes containing '{args.cache_gs_tag}' will use HIGH-RES + 3DGS")
+            print("Other scenes will use LOW-RES only")
+        else:
+            print("All scenes will use LOW-RES only")
+        print("=" * 60)
+        app.cache_examples(
+            show_cam=True,
+            filter_black_bg=False,
+            filter_white_bg=False,
+            save_percentage=5.0,
+            num_max_points=1000,
+            cache_gs_tag=args.cache_gs_tag,
+            gs_trj_mode="smooth",
+            gs_video_quality="low",
+        )
+
+    app.launch(host=args.host, port=args.port, **launch_kwargs)
+
+
+if __name__ == "__main__":
+    main()

src/depth_anything_3/app/modules/__init__.py

@@ -0,0 +1,43 @@
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Modules package for Depth Anything 3 Gradio app.
+
+This package contains all the modular components for the Gradio application.
+"""
+
+from depth_anything_3.app.modules.event_handlers import EventHandlers
+from depth_anything_3.app.modules.file_handlers import FileHandler
+from depth_anything_3.app.modules.model_inference import ModelInference
+from depth_anything_3.app.modules.ui_components import UIComponents
+from depth_anything_3.app.modules.utils import (
+    create_depth_visualization,
+    get_logo_base64,
+    get_scene_info,
+    save_to_gallery_func,
+)
+from depth_anything_3.app.modules.visualization import VisualizationHandler
+
+__all__ = [
+    "ModelInference",
+    "FileHandler",
+    "VisualizationHandler",
+    "EventHandlers",
+    "UIComponents",
+    "create_depth_visualization",
+    "save_to_gallery_func",
+    "get_scene_info",
+    "get_logo_base64",
+]

src/depth_anything_3/app/modules/event_handlers.py

@@ -0,0 +1,624 @@
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Event handling module for Depth Anything 3 Gradio app.
+
+This module handles all event callbacks and user interactions.
+"""
+
+import os
+import time
+from glob import glob
+from typing import Any, Dict, List, Optional, Tuple
+
+import gradio as gr
+import numpy as np
+import torch
+
+from depth_anything_3.app.modules.file_handlers import FileHandler
+from depth_anything_3.app.modules.model_inference import ModelInference
+from depth_anything_3.app.modules.visualization import VisualizationHandler
+from depth_anything_3.utils.memory import cleanup_cuda_memory
+
+
+class EventHandlers:
+    """
+    Handles all event callbacks and user interactions for the Gradio app.
+    """
+
+    def __init__(self):
+        """Initialize the event handlers."""
+        self.model_inference = ModelInference()
+        self.file_handler = FileHandler()
+        self.visualization_handler = VisualizationHandler()
+
+    def clear_fields(self) -> None:
+        """
+        Clears the 3D viewer, the stored target_dir, and empties the gallery.
+        """
+        return None
+
+    def update_log(self) -> str:
+        """
+        Display a quick log message while waiting.
+        """
+        return "Loading and Reconstructing..."
+
+    def save_current_visualization(
+        self,
+        target_dir: str,
+        save_percentage: float,
+        show_cam: bool,
+        filter_black_bg: bool,
+        filter_white_bg: bool,
+        processed_data: Optional[Dict],
+        scene_name: str = "",
+    ) -> str:
+        """
+        Save current visualization results to gallery with specified save percentage.
+
+        Args:
+            target_dir: Directory containing results
+            save_percentage: Percentage of points to save (0-100)
+            show_cam: Whether to show cameras
+            filter_black_bg: Whether to filter black background
+            filter_white_bg: Whether to filter white background
+            processed_data: Processed data from reconstruction
+
+        Returns:
+            Status message
+        """
+        if not target_dir or target_dir == "None" or not os.path.isdir(target_dir):
+            return "No reconstruction available. Please run 'Reconstruct' first."
+
+        if processed_data is None:
+            return "No processed data available. Please run 'Reconstruct' first."
+
+        try:
+            import datetime
+
+            from .utils import save_to_gallery_func
+
+            timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+            if scene_name and scene_name.strip():
+                gallery_name = f"{scene_name.strip()}_{timestamp}_pct{save_percentage:.0f}"
+            else:
+                gallery_name = f"save_{timestamp}_pct{save_percentage:.0f}"
+
+            success, message = save_to_gallery_func(
+                target_dir=target_dir, processed_data=processed_data, gallery_name=gallery_name
+            )
+
+            if success:
+                return (
+                    "Successfully saved to gallery!\n"
+                    f"Gallery name: {gallery_name}\n"
+                    f"Save percentage: {save_percentage}%\n"
+                    f"Show cameras: {show_cam}\n"
+                    f"Filter black bg: {filter_black_bg}\n"
+                    f"Filter white bg: {filter_white_bg}\n\n"
+                    f"{message}"
+                )
+            else:
+                return f"Failed to save to gallery: {message}"
+
+        except Exception as e:
+            return f"Error saving visualization: {str(e)}"
+
+    def gradio_demo(
+        self,
+        target_dir: str,
+        show_cam: bool = True,
+        filter_black_bg: bool = False,
+        filter_white_bg: bool = False,
+        process_res_method: str = "upper_bound_resize",
+        save_percentage: float = 30.0,
+        num_max_points: int = 1_000_000,
+        infer_gs: bool = False,
+        ref_view_strategy: str = "saddle_balanced",
+        gs_trj_mode: str = "extend",
+        gs_video_quality: str = "high",
+        model_name: str = None,
+    ):
+        """
+        Perform reconstruction using the already-created target_dir/images.
+
+        Args:
+            target_dir: Directory containing images
+            show_cam: Whether to show camera
+            filter_black_bg: Whether to filter black background
+            filter_white_bg: Whether to filter white background
+            process_res_method: Method for resizing input images
+            save_percentage: Filter percentage for point cloud
+            num_max_points: Maximum number of points
+            infer_gs: Whether to infer 3D Gaussian Splatting
+            ref_view_strategy: Reference view selection strategy
+            model_name: Model to use (da3-base, da3-large, da3nested-giant-large)
+
+        Returns:
+            Tuple of reconstruction results
+        """
+        from depth_anything_3.app.modules.model_inference import DEFAULT_MODEL
+
+        if model_name is None:
+            model_name = DEFAULT_MODEL
+
+        print(f"[gradio_demo] Called with target_dir={target_dir}, model={model_name}", flush=True)
+
+        if target_dir is None or not os.path.isdir(target_dir) or target_dir == "None":
+            print("[gradio_demo] Invalid target_dir, returning early")
+            return (
+                None,
+                "No valid target directory found. Please upload first.",
+                None,
+                None,
+                None,
+                "",
+                None,
+                gr.update(value=None, visible=False),  # gs_video
+                gr.update(visible=True),  # gs_info
+            )
+
+        start_time = time.time()
+        cleanup_cuda_memory()
+
+        # Get image files for logging
+        target_dir_images = os.path.join(target_dir, "images")
+        all_files = (
+            sorted(os.listdir(target_dir_images)) if os.path.isdir(target_dir_images) else []
+        )
+
+        print(f"[gradio_demo] Running {model_name} on {len(all_files)} images...")
+        print(f"[gradio_demo] Reference view strategy: {ref_view_strategy}")
+
+        try:
+            with torch.no_grad():
+                prediction, processed_data = self.model_inference.run_inference(
+                    target_dir,
+                    process_res_method=process_res_method,
+                    show_camera=show_cam,
+                    save_percentage=save_percentage,
+                    num_max_points=int(num_max_points * 1000),  # Convert K to actual count
+                    infer_gs=infer_gs,
+                    ref_view_strategy=ref_view_strategy,
+                    gs_trj_mode=gs_trj_mode,
+                    gs_video_quality=gs_video_quality,
+                    model_name=model_name,
+                )
+        except Exception as e:
+            error_msg = f"Reconstruction failed: {str(e)}"
+            print(f"[ERROR] {error_msg}")
+            import traceback
+            traceback.print_exc()
+            return (
+                None,
+                error_msg,
+                None,
+                None,
+                None,
+                "",
+                None,
+                gr.update(value=None, visible=False),
+                gr.update(visible=True),
+            )
+
+        # The GLB file is already generated by the API
+        glbfile = os.path.join(target_dir, "scene.glb")
+
+        # Handle 3DGS video based on infer_gs flag
+        gsvideo_path = None
+        gs_video_visible = False
+        gs_info_visible = True
+
+        if infer_gs:
+            try:
+                gsvideo_path = sorted(glob(os.path.join(target_dir, "gs_video", "*.mp4")))[-1]
+                gs_video_visible = True
+                gs_info_visible = False
+            except IndexError:
+                gsvideo_path = None
+                print("3DGS video not found, but infer_gs was enabled")
+
+        # Cleanup
+        cleanup_cuda_memory()
+
+        end_time = time.time()
+        print(f"Total time: {end_time - start_time:.2f} seconds")
+        log_msg = f"Reconstruction Success ({len(all_files)} frames). Waiting for visualization."
+
+        # Populate visualization tabs with processed data
+        depth_vis, measure_img, measure_depth_vis, measure_pts = (
+            self.visualization_handler.populate_visualization_tabs(processed_data)
+        )
+
+        # Update view selectors based on available views
+        depth_selector, measure_selector = self.visualization_handler.update_view_selectors(
+            processed_data
+        )
+
+        return (
+            glbfile,
+            log_msg,
+            processed_data,
+            measure_img,  # measure_image
+            measure_depth_vis,  # measure_depth_image
+            "",  # measure_text (empty initially)
+            measure_selector,  # measure_view_selector
+            gr.update(value=gsvideo_path, visible=gs_video_visible),  # gs_video
+            gr.update(visible=gs_info_visible),  # gs_info visibility
+        )
+
+    def update_visualization(
+        self,
+        target_dir: str,
+        show_cam: bool,
+        is_example: str,
+        filter_black_bg: bool = False,
+        filter_white_bg: bool = False,
+        process_res_method: str = "upper_bound_resize",
+    ) -> Tuple[gr.update, str]:
+        """
+        Reload saved predictions from npz, create (or reuse) the GLB for new parameters,
+        and return it for the 3D viewer.
+
+        Args:
+            target_dir: Directory containing results
+            show_cam: Whether to show camera
+            is_example: Whether this is an example scene
+            filter_black_bg: Whether to filter black background
+            filter_white_bg: Whether to filter white background
+            process_res_method: Method for resizing input images
+
+        Returns:
+            Tuple of (glb_file, log_message)
+        """
+        if not target_dir or target_dir == "None" or not os.path.isdir(target_dir):
+            return (
+                gr.update(),
+                "No reconstruction available. Please click the Reconstruct button first.",
+            )
+
+        # Check if GLB exists (could be cached example or reconstructed scene)
+        glbfile = os.path.join(target_dir, "scene.glb")
+        if os.path.exists(glbfile):
+            return (
+                glbfile,
+                (
+                    "Visualization loaded from cache."
+                    if is_example == "True"
+                    else "Visualization updated."
+                ),
+            )
+
+        # If no GLB but it's an example that hasn't been reconstructed yet
+        if is_example == "True":
+            return (
+                gr.update(),
+                "No reconstruction available. Please click the Reconstruct button first.",
+            )
+
+        # For non-examples, check predictions.npz
+        predictions_path = os.path.join(target_dir, "predictions.npz")
+        if not os.path.exists(predictions_path):
+            error_message = (
+                f"No reconstruction available at {predictions_path}. "
+                "Please run 'Reconstruct' first."
+            )
+            return gr.update(), error_message
+
+        loaded = np.load(predictions_path, allow_pickle=True)
+        predictions = {key: loaded[key] for key in loaded.keys()}  # noqa: F841
+
+        return (
+            glbfile,
+            "Visualization updated.",
+        )
+
+    def handle_uploads(
+        self,
+        input_video: Optional[str],
+        input_images: Optional[List],
+        s_time_interval: float = 10.0,
+    ) -> Tuple[Optional[str], Optional[str], Optional[List], Optional[str]]:
+        """
+        Handle file uploads and update gallery.
+
+        Args:
+            input_video: Path to input video file
+            input_images: List of input image files
+            s_time_interval: Sampling FPS (frames per second) for frame extraction
+
+        Returns:
+            Tuple of (reconstruction_output, target_dir, image_paths, log_message)
+        """
+        return self.file_handler.update_gallery_on_upload(
+            input_video, input_images, s_time_interval
+        )
+
+    def load_example_scene(
+        self, scene_name: str, examples_dir: str = None, s_time_interval: float = None
+    ) -> Tuple[
+        Optional[str],
+        Optional[str],
+        Optional[List],
+        str,
+        Optional[Dict],
+        gr.Dropdown,  # measure_view_selector
+        dict,  # gs_video update (value + visibility)
+        dict,  # gs_info update (visibility)
+    ]:
+        """
+        Load a scene from examples directory.
+
+        Args:
+            scene_name: Name of the scene to load
+            examples_dir: Path to examples directory (if None, uses workspace_dir/examples)
+            s_time_interval: Sampling FPS for video frame extraction (default 1.0)
+
+        Returns:
+            Tuple of (reconstruction_output, target_dir, image_paths, log_message, processed_data, measure_view_selector, gs_video, gs_video_vis, gs_info_vis)  # noqa: E501
+        """
+        if examples_dir is None:
+            # Get workspace directory from environment variable
+            workspace_dir = os.environ.get("DA3_WORKSPACE_DIR", "gradio_workspace")
+            examples_dir = os.path.join(workspace_dir, "examples")
+
+        # Default FPS for video extraction
+        if s_time_interval is None:
+            s_time_interval = 1.0
+
+        reconstruction_output, target_dir, image_paths, log_message = (
+            self.file_handler.load_example_scene(scene_name, examples_dir, s_time_interval)
+        )
+
+        # Try to load cached processed data if available
+        processed_data = None
+        measure_view_selector = gr.Dropdown(choices=["View 1"], value="View 1")
+        gs_video_path = None
+        gs_video_visible = False
+        gs_info_visible = True
+
+        if target_dir and target_dir != "None":
+            predictions_path = os.path.join(target_dir, "predictions.npz")
+            if os.path.exists(predictions_path):
+                try:
+                    # Load predictions from cache
+                    loaded = np.load(predictions_path, allow_pickle=True)
+                    predictions = {key: loaded[key] for key in loaded.keys()}
+
+                    # Reconstruct processed_data structure
+                    num_images = len(predictions.get("images", []))
+                    processed_data = {}
+
+                    for i in range(num_images):
+                        processed_data[i] = {
+                            "image": predictions["images"][i] if "images" in predictions else None,
+                            "depth": predictions["depths"][i] if "depths" in predictions else None,
+                            "depth_image": os.path.join(
+                                target_dir, "depth_vis", f"{i:04d}.jpg"  # Fixed: use .jpg not .png
+                            ),
+                            "intrinsics": (
+                                predictions["intrinsics"][i]
+                                if "intrinsics" in predictions
+                                and i < len(predictions["intrinsics"])
+                                else None
+                            ),
+                            "mask": None,
+                        }
+
+                    # Update measure view selector
+                    choices = [f"View {i + 1}" for i in range(num_images)]
+                    measure_view_selector = gr.Dropdown(choices=choices, value=choices[0])
+
+                except Exception as e:
+                    print(f"Error loading cached data: {e}")
+
+            # Check for cached 3DGS video
+            gs_video_dir = os.path.join(target_dir, "gs_video")
+            if os.path.exists(gs_video_dir):
+                try:
+                    from glob import glob
+
+                    gs_videos = sorted(glob(os.path.join(gs_video_dir, "*.mp4")))
+                    if gs_videos:
+                        gs_video_path = gs_videos[-1]
+                        gs_video_visible = True
+                        gs_info_visible = False
+                        print(f"Loaded cached 3DGS video: {gs_video_path}")
+                except Exception as e:
+                    print(f"Error loading cached 3DGS video: {e}")
+
+        return (
+            reconstruction_output,
+            target_dir,
+            image_paths,
+            log_message,
+            processed_data,
+            measure_view_selector,
+            gr.update(value=gs_video_path, visible=gs_video_visible),  # gs_video
+            gr.update(visible=gs_info_visible),  # gs_info
+        )
+
+    def navigate_depth_view(
+        self,
+        processed_data: Optional[dict],
+        current_selector: str,
+        direction: int,
+    ) -> Tuple[str, Optional[str]]:
+        """
+        Navigate depth view.
+
+        Args:
+            processed_data: Processed data dictionary
+            current_selector: Current selector value
+            direction: Direction to navigate
+
+        Returns:
+            Tuple of (new_selector_value, depth_vis)
+        """
+        return self.visualization_handler.navigate_depth_view(
+            processed_data, current_selector, direction
+        )
+
+    def update_depth_view(
+        self, processed_data: Optional[dict], view_index: int
+    ) -> Optional[str]:
+        """
+        Update depth view for a specific view index.
+
+        Args:
+            processed_data: Processed data dictionary
+            view_index: Index of the view to update
+
+        Returns:
+            Path to depth visualization image or None
+        """
+        return self.visualization_handler.update_depth_view(processed_data, view_index)
+
+    def navigate_measure_view(
+        self,
+        processed_data: Optional[dict],
+        current_selector: str,
+        direction: int,
+    ) -> Tuple[str, Optional[np.ndarray], Optional[np.ndarray], List]:
+        """
+        Navigate measure view.
+
+        Args:
+            processed_data: Processed data dictionary
+            current_selector: Current selector value
+            direction: Direction to navigate
+
+        Returns:
+            Tuple of (new_selector_value, measure_image, depth_right_half, measure_points)
+        """
+        return self.visualization_handler.navigate_measure_view(
+            processed_data, current_selector, direction
+        )
+
+    def update_measure_view(
+        self, processed_data: Optional[dict], view_index: int
+    ) -> Tuple[Optional[np.ndarray], Optional[np.ndarray], List]:
+        """
+        Update measure view for a specific view index.
+
+        Args:
+            processed_data: Processed data dictionary
+            view_index: Index of the view to update
+
+        Returns:
+            Tuple of (measure_image, depth_right_half, measure_points)
+        """
+        return self.visualization_handler.update_measure_view(processed_data, view_index)
+
+    def measure(
+        self,
+        processed_data: Optional[dict],
+        measure_points: List,
+        current_view_selector: str,
+        event: gr.SelectData,
+    ) -> List:
+        """
+        Handle measurement on images.
+
+        Args:
+            processed_data: Processed data dictionary
+            measure_points: List of current measure points
+            current_view_selector: Current view selector value
+            event: Gradio select event
+
+        Returns:
+            List of [image, depth_right_half, measure_points, text]
+        """
+        return self.visualization_handler.measure(
+            processed_data, measure_points, current_view_selector, event
+        )
+
+    def select_first_frame(
+        self, image_gallery: List, selected_index: int = 0
+    ) -> Tuple[List, str, str]:
+        """
+        Select the first frame from the image gallery.
+
+        Args:
+            image_gallery: List of images in the gallery
+            selected_index: Index of the selected image (default: 0)
+
+        Returns:
+            Tuple of (updated_image_gallery, log_message, selected_frame_path)
+        """
+        try:
+            if not image_gallery or len(image_gallery) == 0:
+                return image_gallery, "No images available to select as first frame.", ""
+
+            # Handle None or invalid selected_index
+            if (
+                selected_index is None
+                or selected_index < 0
+                or selected_index >= len(image_gallery)
+            ):
+                selected_index = 0
+                print(f"Invalid selected_index: {selected_index}, using default: 0")
+
+            # Get the selected image based on index
+            selected_image = image_gallery[selected_index]
+            print(f"Selected image index: {selected_index}")
+            print(f"Total images: {len(image_gallery)}")
+
+            # Extract the file path from the selected image
+            selected_frame_path = ""
+            print(f"Selected image type: {type(selected_image)}")
+            print(f"Selected image: {selected_image}")
+
+            if isinstance(selected_image, tuple):
+                # Gradio Gallery returns tuple (path, None)
+                selected_frame_path = selected_image[0]
+            elif isinstance(selected_image, str):
+                selected_frame_path = selected_image
+            elif hasattr(selected_image, "name"):
+                selected_frame_path = selected_image.name
+            elif isinstance(selected_image, dict):
+                if "name" in selected_image:
+                    selected_frame_path = selected_image["name"]
+                elif "path" in selected_image:
+                    selected_frame_path = selected_image["path"]
+                elif "src" in selected_image:
+                    selected_frame_path = selected_image["src"]
+            else:
+                # Try to convert to string
+                selected_frame_path = str(selected_image)
+
+            print(f"Extracted path: {selected_frame_path}")
+
+            # Extract filename from the path for matching
+            import os
+
+            selected_filename = os.path.basename(selected_frame_path)
+            print(f"Selected filename: {selected_filename}")
+
+            # Move the selected image to the front
+            updated_gallery = [selected_image] + [
+                img for img in image_gallery if img != selected_image
+            ]
+
+            log_message = (
+                f"Selected frame: {selected_filename}. "
+                f"Moved to first position. Total frames: {len(updated_gallery)}"
+            )
+            return updated_gallery, log_message, selected_filename
+
+        except Exception as e:
+            print(f"Error selecting first frame: {e}")
+            return image_gallery, f"Error selecting first frame: {e}", ""

src/depth_anything_3/app/modules/file_handlers.py

@@ -0,0 +1,327 @@
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+File handling module for Depth Anything 3 Gradio app.
+
+This module handles file uploads, video processing, and file operations.
+"""
+
+import os
+import shutil
+import time
+from datetime import datetime
+from typing import List, Optional, Tuple
+
+import cv2
+from PIL import Image
+from pillow_heif import register_heif_opener
+
+register_heif_opener()
+
+
+class FileHandler:
+    """
+    Handles file uploads and processing for the Gradio app.
+    """
+
+    def __init__(self):
+        """Initialize the file handler."""
+
+    def handle_uploads(
+        self,
+        input_video: Optional[str],
+        input_images: Optional[List],
+        s_time_interval: float = 10.0,
+    ) -> Tuple[str, List[str]]:
+        """
+        Create a new 'target_dir' + 'images' subfolder, and place user-uploaded
+        images or extracted frames from video into it.
+
+        Args:
+            input_video: Path to input video file
+            input_images: List of input image files
+            s_time_interval: Sampling FPS (frames per second) for frame extraction
+
+        Returns:
+            Tuple of (target_dir, image_paths)
+        """
+        start_time = time.time()
+
+        # Get workspace directory from environment variable or use default
+        workspace_dir = os.environ.get("DA3_WORKSPACE_DIR", "gradio_workspace")
+        if not os.path.exists(workspace_dir):
+            os.makedirs(workspace_dir)
+
+        # Create input_images subdirectory
+        input_images_dir = os.path.join(workspace_dir, "input_images")
+        if not os.path.exists(input_images_dir):
+            os.makedirs(input_images_dir)
+
+        # Create a unique folder name within input_images
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+        target_dir = os.path.join(input_images_dir, f"session_{timestamp}")
+        target_dir_images = os.path.join(target_dir, "images")
+
+        # Clean up if somehow that folder already exists
+        if os.path.exists(target_dir):
+            shutil.rmtree(target_dir)
+        os.makedirs(target_dir)
+        os.makedirs(target_dir_images)
+
+        image_paths = []
+
+        # Handle images
+        if input_images is not None:
+            image_paths.extend(self._process_images(input_images, target_dir_images))
+
+        # Handle video
+        if input_video is not None:
+            image_paths.extend(
+                self._process_video(input_video, target_dir_images, s_time_interval)
+            )
+
+        # Sort final images for gallery
+        image_paths = sorted(image_paths)
+
+        end_time = time.time()
+        print(f"Files copied to {target_dir_images}; took {end_time - start_time:.3f} seconds")
+        return target_dir, image_paths
+
+    def _process_images(self, input_images: List, target_dir_images: str) -> List[str]:
+        """
+        Process uploaded images.
+
+        Args:
+            input_images: List of input image files
+            target_dir_images: Target directory for images
+
+        Returns:
+            List of processed image paths
+        """
+        image_paths = []
+
+        for file_data in input_images:
+            if isinstance(file_data, dict) and "name" in file_data:
+                file_path = file_data["name"]
+            else:
+                file_path = file_data
+
+            # Check if the file is a HEIC image
+            file_ext = os.path.splitext(file_path)[1].lower()
+            if file_ext in [".heic", ".heif"]:
+                # Convert HEIC to JPEG for better gallery compatibility
+                try:
+                    with Image.open(file_path) as img:
+                        # Convert to RGB if necessary (HEIC can have different color modes)
+                        if img.mode not in ("RGB", "L"):
+                            img = img.convert("RGB")
+
+                        # Create JPEG filename
+                        base_name = os.path.splitext(os.path.basename(file_path))[0]
+                        dst_path = os.path.join(target_dir_images, f"{base_name}.jpg")
+
+                        # Save as JPEG with high quality
+                        img.save(dst_path, "JPEG", quality=95)
+                        image_paths.append(dst_path)
+                        print(
+                            f"Converted HEIC to JPEG: {os.path.basename(file_path)} -> "
+                            f"{os.path.basename(dst_path)}"
+                        )
+                except Exception as e:
+                    print(f"Error converting HEIC file {file_path}: {e}")
+                    # Fall back to copying as is
+                    dst_path = os.path.join(target_dir_images, os.path.basename(file_path))
+                    shutil.copy(file_path, dst_path)
+                    image_paths.append(dst_path)
+            else:
+                # Regular image files - copy as is
+                dst_path = os.path.join(target_dir_images, os.path.basename(file_path))
+                shutil.copy(file_path, dst_path)
+                image_paths.append(dst_path)
+
+        return image_paths
+
+    def _process_video(
+        self, input_video: str, target_dir_images: str, s_time_interval: float
+    ) -> List[str]:
+        """
+        Process video file and extract frames.
+
+        Args:
+            input_video: Path to input video file
+            target_dir_images: Target directory for extracted frames
+            s_time_interval: Sampling FPS (frames per second) for frame extraction
+
+        Returns:
+            List of extracted frame paths
+        """
+        image_paths = []
+
+        if isinstance(input_video, dict) and "name" in input_video:
+            video_path = input_video["name"]
+        else:
+            video_path = input_video
+
+        vs = cv2.VideoCapture(video_path)
+        fps = vs.get(cv2.CAP_PROP_FPS)
+        frame_interval = max(1, int(fps / s_time_interval))  # Convert FPS to frame interval
+
+        count = 0
+        video_frame_num = 0
+        while True:
+            gotit, frame = vs.read()
+            if not gotit:
+                break
+            count += 1
+            if count % frame_interval == 0:
+                image_path = os.path.join(target_dir_images, f"{video_frame_num:06}.png")
+                cv2.imwrite(image_path, frame)
+                image_paths.append(image_path)
+                video_frame_num += 1
+
+        return image_paths
+
+    def update_gallery_on_upload(
+        self,
+        input_video: Optional[str],
+        input_images: Optional[List],
+        s_time_interval: float = 10.0,
+    ) -> Tuple[Optional[str], Optional[str], Optional[List], Optional[str]]:
+        """
+        Handle file uploads and update gallery.
+
+        Args:
+            input_video: Path to input video file
+            input_images: List of input image files
+            s_time_interval: Sampling FPS (frames per second) for frame extraction
+
+        Returns:
+            Tuple of (reconstruction_output, target_dir, image_paths, log_message)
+        """
+        if not input_video and not input_images:
+            return None, None, None, None
+
+        target_dir, image_paths = self.handle_uploads(input_video, input_images, s_time_interval)
+        return (
+            None,
+            target_dir,
+            image_paths,
+            "Upload complete. Click 'Reconstruct' to begin 3D processing.",
+        )
+
+    def load_example_scene(
+        self, scene_name: str, examples_dir: str = "examples", s_time_interval: float = 1.0
+    ) -> Tuple[Optional[str], Optional[str], Optional[List], str]:
+        """
+        Load a scene from examples directory.
+
+        Args:
+            scene_name: Name of the scene to load
+            examples_dir: Path to examples directory
+            s_time_interval: Sampling FPS for video frame extraction (default 1.0)
+
+        Returns:
+            Tuple of (reconstruction_output, target_dir, image_paths, log_message)
+        """
+        from depth_anything_3.app.modules.utils import get_scene_info
+
+        scenes = get_scene_info(examples_dir)
+
+        # Find the selected scene
+        selected_scene = None
+        for scene in scenes:
+            if scene["name"] == scene_name:
+                selected_scene = scene
+                break
+
+        if selected_scene is None:
+            return None, None, None, "Scene not found"
+
+        # Check if this is a video scene
+        is_video_scene = selected_scene.get("type") == "video"
+
+        # Use fixed directory name for examples (not timestamp-based)
+        workspace_dir = os.environ.get("DA3_WORKSPACE_DIR", "gradio_workspace")
+        input_images_dir = os.path.join(workspace_dir, "input_images")
+        if not os.path.exists(input_images_dir):
+            os.makedirs(input_images_dir)
+
+        # For video scenes, include FPS in folder name so different FPS = different cache
+        if is_video_scene:
+            target_dir = os.path.join(
+                input_images_dir, f"example_{scene_name}_fps{s_time_interval:.1f}"
+            )
+        else:
+            target_dir = os.path.join(input_images_dir, f"example_{scene_name}")
+        target_dir_images = os.path.join(target_dir, "images")
+
+        # Check if already cached (GLB file exists)
+        glb_path = os.path.join(target_dir, "scene.glb")
+        is_cached = os.path.exists(glb_path)
+
+        # Create directory if it doesn't exist
+        if not os.path.exists(target_dir):
+            os.makedirs(target_dir)
+            os.makedirs(target_dir_images)
+
+        # Process images or extract video frames if directory is new or empty
+        if not os.path.exists(target_dir_images) or len(os.listdir(target_dir_images)) == 0:
+            os.makedirs(target_dir_images, exist_ok=True)
+            image_paths = []
+
+            if is_video_scene:
+                # Extract frames from video using specified FPS
+                video_path = selected_scene.get("video_file")
+                if video_path:
+                    image_paths = self._process_video(
+                        video_path, target_dir_images, s_time_interval
+                    )
+            else:
+                # Copy images
+                for file_path in selected_scene["image_files"]:
+                    dst_path = os.path.join(target_dir_images, os.path.basename(file_path))
+                    shutil.copy(file_path, dst_path)
+                    image_paths.append(dst_path)
+        else:
+            # Use existing images
+            image_paths = sorted(
+                [
+                    os.path.join(target_dir_images, f)
+                    for f in os.listdir(target_dir_images)
+                    if f.lower().endswith((".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".tif"))
+                ]
+            )
+
+        num_frames = len(image_paths)
+        scene_type = "video" if is_video_scene else "scene"
+
+        # Return cached GLB if available
+        if is_cached:
+            return (
+                glb_path,  # Return cached reconstruction
+                target_dir,  # Set target directory
+                image_paths,  # Set gallery
+                f"Loaded cached {scene_type} '{scene_name}' with {num_frames} frames.",
+            )
+        else:
+            return (
+                None,  # No cached reconstruction
+                target_dir,  # Set target directory
+                image_paths,  # Set gallery
+                (
+                    f"Loaded {scene_type} '{scene_name}' with {num_frames} frames. "
+                    "Click 'Reconstruct' to begin 3D processing."
+                ),
+            )

src/depth_anything_3/app/modules/model_inference.py

@@ -0,0 +1,454 @@
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates
+# Optimizations (c) Delanoe Pirard / Aedelon - Apache 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Model inference module for Depth Anything 3 Gradio app.
+
+This module handles all model-related operations including inference,
+data processing, and result preparation.
+
+Optimizations based on benchmarks:
+- Smart batch sizing per model/device (MPS: B=4 for small/base, B=2 for large, B=1 for giant)
+- CUDA: Adaptive batching at 85% memory utilization
+- CPU: Always batch=1
+- Model caching for 200x faster subsequent loads
+"""
+
+import glob
+import os
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+import torch
+
+from depth_anything_3.api import DepthAnything3
+from depth_anything_3.utils.export.glb import export_to_glb
+from depth_anything_3.utils.export.gs import export_to_gs_video
+from depth_anything_3.utils.memory import cleanup_cuda_memory
+
+# Available models for UI selection
+AVAILABLE_MODELS = {
+    "da3-small": "Small (fastest, ~27 img/s)",
+    "da3-base": "Base (fast, ~10 img/s)",
+    "da3-large": "Large (balanced, ~4 img/s)",
+    "da3-giant": "Giant (high quality, ~1.6 img/s)",
+    "da3nested-giant-large": "Giant+Large (best quality, ~1.5 img/s)",
+}
+
+# Mapping from UI names to HuggingFace repo IDs
+MODEL_TO_HF_REPO = {
+    "da3-small": "depth-anything/DA3-SMALL",
+    "da3-base": "depth-anything/DA3-BASE",
+    "da3-large": "depth-anything/DA3-LARGE",
+    "da3-giant": "depth-anything/DA3-GIANT",
+    "da3nested-giant-large": "depth-anything/DA3NESTED-GIANT-LARGE",
+}
+
+DEFAULT_MODEL = "da3nested-giant-large"
+
+
+class ModelInference:
+    """
+    Handles model inference and data processing for Depth Anything 3.
+
+    Uses benchmark-optimized batch sizes:
+    - MPS: B=4 for small/base, B=2 for large, B=1 for giant
+    - CUDA: Adaptive batching (85% VRAM utilization)
+    - CPU: B=1 always
+    """
+
+    def __init__(self):
+        """Initialize the model inference handler."""
+        self.model: Optional[DepthAnything3] = None
+        self.current_model_name: Optional[str] = None
+        self.device: Optional[torch.device] = None
+
+    def _get_optimal_batch_size(
+        self, num_images: int, model_name: str, device_type: str
+    ) -> int:
+        """
+        Get optimal batch size based on benchmarks.
+
+        Benchmark results (MPS, 1280x720):
+        - da3-small: B=4 → 27.2 img/s (vs B=1 → 22.2 img/s)
+        - da3-base:  B=4 → 11.6 img/s (vs B=1 → 10.7 img/s)
+        - da3-large: B=2 → 3.8 img/s  (B=4 slower due to memory pressure)
+        - da3-giant: B=1 → 1.6 img/s  (B=4 → 1.2 img/s, worse!)
+
+        Args:
+            num_images: Number of images to process
+            model_name: Name of the model
+            device_type: Device type ('cuda', 'mps', 'cpu')
+
+        Returns:
+            Optimal batch size
+        """
+        if device_type == "cpu":
+            return 1
+
+        # MPS: Use benchmark-optimized fixed batch sizes
+        if device_type == "mps":
+            if "small" in model_name:
+                return min(4, num_images)
+            elif "base" in model_name:
+                return min(4, num_images)
+            elif "giant" in model_name:
+                return 1
+            else:  # large
+                return min(2, num_images)
+
+        # CUDA: Conservative batch size, can be tuned
+        if "giant" in model_name:
+            return min(2, num_images)
+        elif "large" in model_name:
+            return min(4, num_images)
+        else:
+            return min(8, num_images)
+
+    def initialize_model(self, device: torch.device, model_name: str = None) -> None:
+        """
+        Initialize the DepthAnything3 model.
+
+        Args:
+            device: Device to load the model on
+            model_name: Model name to load (default: da3-base)
+        """
+        if model_name is None:
+            model_name = os.environ.get("DA3_MODEL_NAME", DEFAULT_MODEL)
+
+        # Check if we need to reload the model
+        need_reload = (
+            self.model is None
+            or self.current_model_name != model_name
+            or self.device != device
+        )
+
+        if need_reload:
+            # Cleanup old model if exists
+            if self.model is not None:
+                print(f"[ModelInference] Unloading {self.current_model_name}")
+                del self.model
+                self.model = None
+                cleanup_cuda_memory()
+
+            # Get HuggingFace repo ID from model name
+            hf_repo = MODEL_TO_HF_REPO.get(model_name, model_name)
+            print(f"[ModelInference] Loading model: {model_name} ({hf_repo}) on {device}")
+            start_time = time.time()
+
+            # Use from_pretrained to load from HuggingFace
+            self.model = DepthAnything3.from_pretrained(hf_repo)
+            self.model = self.model.to(device)
+            self.current_model_name = model_name
+            self.device = device
+
+            load_time = time.time() - start_time
+            print(f"[ModelInference] Model loaded in {load_time:.2f}s")
+        else:
+            print(f"[ModelInference] Reusing cached model: {model_name}")
+
+        self.model.eval()
+
+    def run_inference(
+        self,
+        target_dir: str,
+        filter_black_bg: bool = False,
+        filter_white_bg: bool = False,
+        process_res_method: str = "upper_bound_resize",
+        show_camera: bool = True,
+        save_percentage: float = 30.0,
+        num_max_points: int = 1_000_000,
+        infer_gs: bool = False,
+        ref_view_strategy: str = "saddle_balanced",
+        gs_trj_mode: str = "extend",
+        gs_video_quality: str = "high",
+        model_name: str = None,
+    ) -> Tuple[Any, dict]:
+        """
+        Run DepthAnything3 model inference on images.
+
+        All images are processed in a single batch for optimal performance.
+
+        Args:
+            target_dir: Directory containing images
+            filter_black_bg: Whether to filter black background
+            filter_white_bg: Whether to filter white background
+            process_res_method: Method for resizing input images
+            show_camera: Whether to show camera in 3D view
+            save_percentage: Percentage of points to save (0-100)
+            num_max_points: Maximum number of points in point cloud
+            infer_gs: Whether to infer 3D Gaussian Splatting
+            ref_view_strategy: Reference view selection strategy
+            gs_trj_mode: Trajectory mode for 3DGS
+            gs_video_quality: Video quality for 3DGS
+            model_name: Model to use (default: da3-base)
+
+        Returns:
+            Tuple of (prediction, processed_data)
+        """
+        inference_start = time.time()
+        print(f"[ModelInference] Processing images from {target_dir}")
+
+        # Device check - support CUDA, MPS (Apple Silicon), and CPU
+        if torch.cuda.is_available():
+            device = torch.device("cuda")
+        elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+            device = torch.device("mps")
+        else:
+            device = torch.device("cpu")
+
+        # Initialize model (with caching)
+        if model_name is None:
+            model_name = DEFAULT_MODEL
+        self.initialize_model(device, model_name)
+
+        # Get image paths
+        image_folder_path = os.path.join(target_dir, "images")
+        all_image_paths = sorted(glob.glob(os.path.join(image_folder_path, "*")))
+
+        # Filter for image files
+        image_extensions = [".jpg", ".jpeg", ".png", ".bmp", ".tiff", ".tif"]
+        image_paths = [
+            path
+            for path in all_image_paths
+            if any(path.lower().endswith(ext) for ext in image_extensions)
+        ]
+
+        num_images = len(image_paths)
+        print(f"[ModelInference] Found {num_images} images")
+
+        if num_images == 0:
+            raise ValueError("No images found. Check your upload.")
+
+        # Map UI options to actual method names
+        method_mapping = {"high_res": "lower_bound_resize", "low_res": "upper_bound_resize"}
+        actual_method = method_mapping.get(process_res_method, "upper_bound_crop")
+
+        # Get optimal batch size based on benchmarks
+        batch_size = self._get_optimal_batch_size(num_images, model_name, device.type)
+        print(
+            f"[ModelInference] Batched inference: model={model_name}, "
+            f"device={device.type}, images={num_images}, batch_size={batch_size}"
+        )
+
+        # Run model inference with batching
+        with torch.no_grad():
+            if num_images <= batch_size:
+                # Single batch - process all at once
+                prediction = self.model.inference(
+                    image_paths,
+                    export_dir=None,
+                    process_res_method=actual_method,
+                    infer_gs=infer_gs,
+                    ref_view_strategy=ref_view_strategy,
+                )
+            else:
+                # Multiple batches - process in chunks and merge
+                predictions = []
+                for i in range(0, num_images, batch_size):
+                    batch_paths = image_paths[i : i + batch_size]
+                    print(f"[ModelInference] Processing batch {i // batch_size + 1}/{(num_images + batch_size - 1) // batch_size} ({len(batch_paths)} images)")
+                    batch_pred = self.model.inference(
+                        batch_paths,
+                        export_dir=None,
+                        process_res_method=actual_method,
+                        infer_gs=False,  # Only infer GS on final merged result
+                        ref_view_strategy=ref_view_strategy,
+                    )
+                    predictions.append(batch_pred)
+
+                # Merge all batch predictions
+                prediction = self._merge_predictions(predictions)
+        # num_max_points: int = 1_000_000,
+        export_to_glb(
+            prediction,
+            filter_black_bg=filter_black_bg,
+            filter_white_bg=filter_white_bg,
+            export_dir=target_dir,
+            show_cameras=show_camera,
+            conf_thresh_percentile=save_percentage,
+            num_max_points=int(num_max_points),
+        )
+
+        # export to gs video if needed
+        if infer_gs:
+            mode_mapping = {"extend": "extend", "smooth": "interpolate_smooth"}
+            print(f"GS mode: {gs_trj_mode}; Backend mode: {mode_mapping[gs_trj_mode]}")
+            export_to_gs_video(
+                prediction,
+                export_dir=target_dir,
+                chunk_size=4,
+                trj_mode=mode_mapping.get(gs_trj_mode, "extend"),
+                enable_tqdm=True,
+                vis_depth="hcat",
+                video_quality=gs_video_quality,
+            )
+
+        # Save predictions.npz for caching metric depth data
+        self._save_predictions_cache(target_dir, prediction)
+
+        # Process results
+        processed_data = self._process_results(target_dir, prediction, image_paths)
+
+        # Clean up using centralized memory utilities for consistency with backend
+        cleanup_cuda_memory()
+
+        inference_time = time.time() - inference_start
+        throughput = num_images / inference_time if inference_time > 0 else 0
+        print(
+            f"[ModelInference] Completed in {inference_time:.2f}s "
+            f"({throughput:.1f} img/s)"
+        )
+
+        return prediction, processed_data
+
+    def _merge_predictions(self, predictions: List[Any]) -> Any:
+        """
+        Merge multiple batch predictions into a single prediction.
+
+        Args:
+            predictions: List of Prediction objects from batch inference
+
+        Returns:
+            Merged Prediction object
+        """
+        if not predictions:
+            return None
+        if len(predictions) == 1:
+            return predictions[0]
+
+        from depth_anything_3.specs import Prediction
+
+        # Concatenate arrays from all predictions
+        merged_depth = np.concatenate([p.depth for p in predictions], axis=0)
+        merged_conf = (
+            np.concatenate([p.conf for p in predictions], axis=0)
+            if predictions[0].conf is not None
+            else None
+        )
+        merged_processed_images = (
+            np.concatenate([p.processed_images for p in predictions], axis=0)
+            if predictions[0].processed_images is not None
+            else None
+        )
+        merged_extrinsics = (
+            np.concatenate([p.extrinsics for p in predictions], axis=0)
+            if predictions[0].extrinsics is not None
+            else None
+        )
+        merged_intrinsics = (
+            np.concatenate([p.intrinsics for p in predictions], axis=0)
+            if predictions[0].intrinsics is not None
+            else None
+        )
+
+        # Create merged prediction (use is_metric from first batch)
+        merged = Prediction(
+            depth=merged_depth,
+            is_metric=predictions[0].is_metric,
+            conf=merged_conf,
+            extrinsics=merged_extrinsics,
+            intrinsics=merged_intrinsics,
+            processed_images=merged_processed_images,
+        )
+
+        print(f"[ModelInference] Merged {len(predictions)} batches into single prediction")
+        return merged
+
+    def _save_predictions_cache(self, target_dir: str, prediction: Any) -> None:
+        """
+        Save predictions data to predictions.npz for caching.
+
+        Args:
+            target_dir: Directory to save the cache
+            prediction: Model prediction object
+        """
+        try:
+            output_file = os.path.join(target_dir, "predictions.npz")
+
+            # Build save dict with prediction data
+            save_dict = {}
+
+            # Save processed images if available
+            if prediction.processed_images is not None:
+                save_dict["images"] = prediction.processed_images
+
+            # Save depth data
+            if prediction.depth is not None:
+                save_dict["depths"] = np.round(prediction.depth, 6)
+
+            # Save confidence if available
+            if prediction.conf is not None:
+                save_dict["conf"] = np.round(prediction.conf, 2)
+
+            # Save camera parameters
+            if prediction.extrinsics is not None:
+                save_dict["extrinsics"] = prediction.extrinsics
+            if prediction.intrinsics is not None:
+                save_dict["intrinsics"] = prediction.intrinsics
+
+            # Save to file
+            np.savez_compressed(output_file, **save_dict)
+            print(f"Saved predictions cache to: {output_file}")
+
+        except Exception as e:
+            print(f"Warning: Failed to save predictions cache: {e}")
+
+    def _process_results(
+        self, target_dir: str, prediction: Any, image_paths: list
+    ) -> dict:
+        """
+        Process model results into structured data.
+
+        Args:
+            target_dir: Directory containing results
+            prediction: Model prediction object
+            image_paths: List of input image paths
+
+        Returns:
+            Dictionary containing processed data for each view
+        """
+        processed_data = {}
+
+        # Read generated depth visualization files
+        depth_vis_dir = os.path.join(target_dir, "depth_vis")
+
+        if os.path.exists(depth_vis_dir):
+            depth_files = sorted(glob.glob(os.path.join(depth_vis_dir, "*.jpg")))
+            for i, depth_file in enumerate(depth_files):
+                # Use processed images directly from API
+                processed_image = None
+                if prediction.processed_images is not None and i < len(
+                    prediction.processed_images
+                ):
+                    processed_image = prediction.processed_images[i]
+
+                processed_data[i] = {
+                    "depth_image": depth_file,
+                    "image": processed_image,
+                    "original_image_path": image_paths[i] if i < len(image_paths) else None,
+                    "depth": prediction.depth[i] if i < len(prediction.depth) else None,
+                    "intrinsics": (
+                        prediction.intrinsics[i]
+                        if prediction.intrinsics is not None and i < len(prediction.intrinsics)
+                        else None
+                    ),
+                    "mask": None,  # No mask information available
+                }
+
+        return processed_data
+
+    # cleanup() removed: call cleanup_cuda_memory() directly where needed.

src/depth_anything_3/app/modules/ui_components.py

@@ -0,0 +1,497 @@
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+UI components module for Depth Anything 3 Gradio app.
+
+This module contains UI component definitions and layout functions.
+"""
+
+import os
+from typing import Any, Dict, List, Tuple
+
+import gradio as gr
+
+from depth_anything_3.app.modules.utils import get_logo_base64, get_scene_info
+
+
+class UIComponents:
+    """
+    Handles UI component creation and layout for the Gradio app.
+    """
+
+    def __init__(self):
+        """Initialize the UI components handler."""
+
+    def create_upload_section(self) -> Tuple[gr.Video, gr.Slider, gr.File, gr.Gallery]:
+        """
+        Create the upload section with video, images, and gallery components.
+
+        Returns:
+            A tuple of Gradio components: (input_video, s_time_interval, input_images, image_gallery).
+        """
+        input_video = gr.Video(label="Upload Video", interactive=True)
+        s_time_interval = gr.Slider(
+            minimum=0.1,
+            maximum=60,
+            value=10,
+            step=0.1,
+            label="Sampling FPS (Frames Per Second)",
+            interactive=True,
+            visible=True,
+        )
+        input_images = gr.File(file_count="multiple", label="Upload Images", interactive=True)
+        image_gallery = gr.Gallery(
+            label="Preview",
+            columns=4,
+            height="300px",
+            object_fit="contain",
+            allow_preview=True,
+            interactive=False,
+        )
+
+        return input_video, s_time_interval, input_images, image_gallery
+
+    def create_3d_viewer_section(self) -> gr.Model3D:
+        """
+        Create the 3D viewer component.
+
+        Returns:
+            3D model viewer component
+        """
+        return gr.Model3D(
+            height=520,
+            zoom_speed=0.5,
+            pan_speed=0.5,
+            clear_color=[0.0, 0.0, 0.0, 0.0],
+            key="persistent_3d_viewer",
+            elem_id="reconstruction_3d_viewer",
+        )
+
+    def create_nvs_video(self) -> Tuple[gr.Video, gr.Markdown]:
+        """
+        Create the 3DGS rendered video display component and info message.
+
+        Returns:
+            Tuple of (video component, info message component)
+        """
+        with gr.Column():
+            gs_info = gr.Markdown(
+                (
+                    "‼️ **3D Gaussian Splatting rendering is currently DISABLED.** <br><br><br>"
+                    "To render novel views from 3DGS, "
+                    "enable **Infer 3D Gaussian Splatting** below. <br>"
+                    "Next, in **Visualization Options**, "
+                    "*optionally* configure the **rendering trajectory** (default: smooth) "
+                    "and **video quality** (default: low), "
+                    "then click **Reconstruct**."
+                ),
+                visible=True,
+                height=520,
+            )
+            gs_video = gr.Video(
+                height=520,
+                label="3DGS Rendered NVS Video (depth shown for reference only)",
+                interactive=False,
+                visible=False,
+            )
+        return gs_video, gs_info
+
+    def create_depth_section(self) -> Tuple[gr.Button, gr.Dropdown, gr.Button, gr.Image]:
+        """
+        Create the depth visualization section.
+
+        Returns:
+            A tuple of (prev_depth_btn, depth_view_selector, next_depth_btn, depth_map)
+        """
+        with gr.Row(elem_classes=["navigation-row"]):
+            prev_depth_btn = gr.Button("◀ Previous", size="sm", scale=1)
+            depth_view_selector = gr.Dropdown(
+                choices=["View 1"],
+                value="View 1",
+                label="Select View",
+                scale=2,
+                interactive=True,
+                allow_custom_value=True,
+            )
+            next_depth_btn = gr.Button("Next ▶", size="sm", scale=1)
+        depth_map = gr.Image(
+            type="numpy",
+            label="Colorized Depth Map",
+            format="png",
+            interactive=False,
+        )
+
+        return prev_depth_btn, depth_view_selector, next_depth_btn, depth_map
+
+    def create_measure_section(
+        self,
+    ) -> Tuple[gr.Button, gr.Dropdown, gr.Button, gr.Image, gr.Image, gr.Markdown]:
+        """
+        Create the measurement section.
+
+        Returns:
+            A tuple of (prev_measure_btn, measure_view_selector, next_measure_btn, measure_image,
+            measure_depth_image, measure_text)
+        """
+        from depth_anything_3.app.css_and_html import MEASURE_INSTRUCTIONS_HTML
+
+        gr.Markdown(MEASURE_INSTRUCTIONS_HTML)
+        with gr.Row(elem_classes=["navigation-row"]):
+            prev_measure_btn = gr.Button("◀ Previous", size="sm", scale=1)
+            measure_view_selector = gr.Dropdown(
+                choices=["View 1"],
+                value="View 1",
+                label="Select View",
+                scale=2,
+                interactive=True,
+                allow_custom_value=True,
+            )
+            next_measure_btn = gr.Button("Next ▶", size="sm", scale=1)
+        with gr.Row():
+            measure_image = gr.Image(
+                type="numpy",
+                show_label=False,
+                format="webp",
+                interactive=False,
+                sources=[],
+                label="RGB Image",
+                scale=1,
+                height=275,
+            )
+            measure_depth_image = gr.Image(
+                type="numpy",
+                show_label=False,
+                format="webp",
+                interactive=False,
+                sources=[],
+                label="Depth Visualization (Right Half)",
+                scale=1,
+                height=275,
+            )
+        gr.Markdown(
+            "**Note:** Images have been adjusted to model processing size. "
+            "Click two points on the RGB image to measure distance."
+        )
+        measure_text = gr.Markdown("")
+
+        return (
+            prev_measure_btn,
+            measure_view_selector,
+            next_measure_btn,
+            measure_image,
+            measure_depth_image,
+            measure_text,
+        )
+
+    def create_inference_control_section(
+        self,
+    ) -> Tuple[gr.Dropdown, gr.Dropdown, gr.Checkbox, gr.Dropdown]:
+        """
+        Create the inference control section (before inference).
+
+        Returns:
+            Tuple of (model_selector, process_res_method_dropdown, infer_gs, ref_view_strategy)
+        """
+        from depth_anything_3.app.modules.model_inference import AVAILABLE_MODELS, DEFAULT_MODEL
+
+        with gr.Row():
+            # Model selector - most important control
+            model_selector = gr.Dropdown(
+                choices=list(AVAILABLE_MODELS.keys()),
+                value=DEFAULT_MODEL,
+                label="Model",
+                info="da3-base: fast | da3-large: balanced | giant: best quality",
+                scale=1,
+            )
+            process_res_method_dropdown = gr.Dropdown(
+                choices=["high_res", "low_res"],
+                value="low_res",
+                label="Image Processing Method",
+                info="low_res for much more images",
+                scale=1,
+            )
+            infer_gs = gr.Checkbox(
+                label="Infer 3D Gaussian Splatting",
+                value=False,
+                info=(
+                    'Enable novel view rendering from 3DGS (<i class="fas fa-triangle-exclamation '
+                    'fa-color-red"></i> requires extra processing time)'
+                ),
+                scale=1,
+            )
+            ref_view_strategy = gr.Dropdown(
+                choices=["saddle_balanced", "saddle_sim_range", "first", "middle"],
+                value="saddle_balanced",
+                label="Reference View Strategy",
+                info="Strategy for selecting reference view from multiple inputs",
+                scale=1,
+            )
+
+        return (model_selector, process_res_method_dropdown, infer_gs, ref_view_strategy)
+
+    def create_display_control_section(
+        self,
+    ) -> Tuple[
+        gr.Checkbox,
+        gr.Checkbox,
+        gr.Checkbox,
+        gr.Slider,
+        gr.Slider,
+        gr.Dropdown,
+        gr.Dropdown,
+        gr.Button,
+        gr.ClearButton,
+    ]:
+        """
+        Create the display control section (options for visualization).
+
+        Returns:
+            Tuple of display control components including buttons
+        """
+        with gr.Column():
+            # 3DGS options at the top
+            with gr.Row():
+                gs_trj_mode = gr.Dropdown(
+                    choices=["smooth", "extend"],
+                    value="smooth",
+                    label=("Rendering trajectory for 3DGS viewpoints (requires n_views ≥ 2)"),
+                    info=("'smooth' for view interpolation; 'extend' for longer trajectory"),
+                    visible=False,  # initially hidden
+                )
+                gs_video_quality = gr.Dropdown(
+                    choices=["low", "medium", "high"],
+                    value="low",
+                    label=("Video quality for 3DGS rendered outputs"),
+                    info=("'low' for faster loading speed; 'high' for better visual quality"),
+                    visible=False,  # initially hidden
+                )
+
+            # Reconstruct and Clear buttons (before Visualization Options)
+            with gr.Row():
+                submit_btn = gr.Button("Reconstruct", scale=1, variant="primary")
+                clear_btn = gr.ClearButton(scale=1)
+
+            gr.Markdown("### Visualization Options: (Click Reconstruct to update)")
+            show_cam = gr.Checkbox(label="Show Camera", value=True)
+            filter_black_bg = gr.Checkbox(label="Filter Black Background", value=False)
+            filter_white_bg = gr.Checkbox(label="Filter White Background", value=False)
+            save_percentage = gr.Slider(
+                minimum=0,
+                maximum=100,
+                value=10,
+                step=1,
+                label="Filter Percentage",
+                info="Confidence Threshold (%): Higher values filter more points.",
+            )
+            num_max_points = gr.Slider(
+                minimum=1000,
+                maximum=100000,
+                value=1000,
+                step=1000,
+                label="Max Points (K points)",
+                info="Maximum number of points to export to GLB (in thousands)",
+            )
+
+        return (
+            show_cam,
+            filter_black_bg,
+            filter_white_bg,
+            save_percentage,
+            num_max_points,
+            gs_trj_mode,
+            gs_video_quality,
+            submit_btn,
+            clear_btn,
+        )
+
+    def create_control_section(
+        self,
+    ) -> Tuple[
+        gr.Button,
+        gr.ClearButton,
+        gr.Dropdown,
+        gr.Checkbox,
+        gr.Checkbox,
+        gr.Checkbox,
+        gr.Checkbox,
+        gr.Checkbox,
+        gr.Dropdown,
+        gr.Checkbox,
+        gr.Textbox,
+    ]:
+        """
+        Create the control section with buttons and options.
+
+        Returns:
+            Tuple of control components
+        """
+        with gr.Row():
+            submit_btn = gr.Button("Reconstruct", scale=1, variant="primary")
+            clear_btn = gr.ClearButton(
+                scale=1,
+            )
+
+        with gr.Row():
+            frame_filter = gr.Dropdown(
+                choices=["All"], value="All", label="Show Points from Frame"
+            )
+            with gr.Column():
+                gr.Markdown("### Visualization Option: (Click Reconstruct to update)")
+                show_cam = gr.Checkbox(label="Show Camera", value=True)
+                show_mesh = gr.Checkbox(label="Show Mesh", value=True)
+                filter_black_bg = gr.Checkbox(label="Filter Black Background", value=False)
+                filter_white_bg = gr.Checkbox(label="Filter White Background", value=False)
+                gr.Markdown("### Reconstruction Options: (updated on next run)")
+                apply_mask_checkbox = gr.Checkbox(
+                    label="Apply mask for predicted ambiguous depth classes & edges",
+                    value=True,
+                )
+                process_res_method_dropdown = gr.Dropdown(
+                    choices=[
+                        "upper_bound_resize",
+                        "upper_bound_crop",
+                        "lower_bound_resize",
+                        "lower_bound_crop",
+                    ],
+                    value="upper_bound_resize",
+                    label="Image Processing Method",
+                    info="Method for resizing input images",
+                )
+                save_to_gallery_checkbox = gr.Checkbox(
+                    label="Save to Gallery",
+                    value=False,
+                    info="Save current reconstruction results to gallery directory",
+                )
+                gallery_name_input = gr.Textbox(
+                    label="Gallery Name",
+                    placeholder="Enter a name for the gallery folder",
+                    value="",
+                    info="Leave empty for auto-generated name with timestamp",
+                )
+
+        return (
+            submit_btn,
+            clear_btn,
+            frame_filter,
+            show_cam,
+            show_mesh,
+            filter_black_bg,
+            filter_white_bg,
+            apply_mask_checkbox,
+            process_res_method_dropdown,
+            save_to_gallery_checkbox,
+            gallery_name_input,
+        )
+
+    def create_example_scenes_section(self) -> List[Dict[str, Any]]:
+        """
+        Create the example scenes section.
+
+        Returns:
+            List of scene information dictionaries
+        """
+        # Use assets/examples directory for example scenes
+        examples_dir = os.environ.get("DA3_EXAMPLES_DIR", "assets/examples")
+
+        # Get scene information
+        scenes = get_scene_info(examples_dir)
+
+        return scenes
+
+    def create_example_scene_grid(self, scenes: List[Dict[str, Any]]) -> List:
+        """
+        Create the example scene grid.
+
+        Args:
+            scenes: List of scene information dictionaries
+
+        Returns:
+            List of scene components (gr.Image or gr.Video) in same order as scenes
+        """
+        scene_components = []
+
+        if scenes:
+            for i in range(0, len(scenes), 4):  # Process 4 scenes per row
+                with gr.Row():
+                    for j in range(4):
+                        scene_idx = i + j
+                        if scene_idx < len(scenes):
+                            scene = scenes[scene_idx]
+                            scene_type = scene.get("type", "images")
+
+                            with gr.Column(scale=1, elem_classes=["clickable-thumbnail"]):
+                                # Use Image for both image and video scenes
+                                # (video scenes use first frame as thumbnail)
+                                scene_component = gr.Image(
+                                    value=scene["thumbnail"],
+                                    height=150,
+                                    interactive=False,
+                                    show_label=False,
+                                    elem_id=f"scene_thumb_{scene['name']}",
+                                    sources=[],
+                                )
+                                scene_components.append(scene_component)
+
+                                if scene_type == "video":
+                                    # Scene name for video
+                                    gr.Markdown(
+                                        f"**{scene['name']}** \n 🎬 video",
+                                        elem_classes=["scene-info"],
+                                    )
+                                else:
+                                    # Scene name and image count
+                                    gr.Markdown(
+                                        f"**{scene['name']}** \n {scene['num_images']} images",
+                                        elem_classes=["scene-info"],
+                                    )
+                        else:
+                            # Empty column to maintain grid structure
+                            with gr.Column(scale=1):
+                                pass
+
+        return scene_components
+
+    def create_header_section(self) -> gr.HTML:
+        """
+        Create the header section with logo and title.
+
+        Returns:
+            Header HTML component
+        """
+        from depth_anything_3.app.css_and_html import get_header_html
+
+        return gr.HTML(get_header_html(get_logo_base64()))
+
+    def create_description_section(self) -> gr.HTML:
+        """
+        Create the description section.
+
+        Returns:
+            Description HTML component
+        """
+        from depth_anything_3.app.css_and_html import get_description_html
+
+        return gr.HTML(get_description_html())
+
+    def create_acknowledgements_section(self) -> gr.HTML:
+        """
+        Create the acknowledgements section.
+
+        Returns:
+            Acknowledgements HTML component
+        """
+        from depth_anything_3.app.css_and_html import get_acknowledgements_html
+
+        return gr.HTML(get_acknowledgements_html())

src/depth_anything_3/app/modules/utils.py

@@ -0,0 +1,269 @@
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Utility functions for Depth Anything 3 Gradio app.
+
+This module contains helper functions for data processing, visualization,
+and file operations.
+"""
+
+
+import json
+import os
+import shutil
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+
+def create_depth_visualization(depth: np.ndarray) -> Optional[np.ndarray]:
+    """
+    Create a colored depth visualization.
+
+    Args:
+        depth: Depth array
+
+    Returns:
+        Colored depth visualization or None
+    """
+    if depth is None:
+        return None
+
+    # Normalize depth to 0-1 range
+    depth_min = depth[depth > 0].min() if (depth > 0).any() else 0
+    depth_max = depth.max()
+
+    if depth_max <= depth_min:
+        return None
+
+    # Normalize depth
+    depth_norm = (depth - depth_min) / (depth_max - depth_min)
+    depth_norm = np.clip(depth_norm, 0, 1)
+
+    # Apply colormap (using matplotlib's viridis colormap)
+    import matplotlib.cm as cm
+
+    # Convert to colored image
+    depth_colored = cm.viridis(depth_norm)[:, :, :3]  # Remove alpha channel
+    depth_colored = (depth_colored * 255).astype(np.uint8)
+
+    return depth_colored
+
+
+def save_to_gallery_func(
+    target_dir: str, processed_data: dict, gallery_name: Optional[str] = None
+) -> Tuple[bool, str]:
+    """
+    Save the current reconstruction results to the gallery directory.
+
+    Args:
+        target_dir: Source directory containing reconstruction results
+        processed_data: Processed data dictionary
+        gallery_name: Name for the gallery folder
+
+    Returns:
+        Tuple of (success, message)
+    """
+    try:
+        # Get gallery directory from environment variable or use default
+        gallery_dir = os.environ.get(
+            "DA3_GALLERY_DIR",
+            "workspace/gallery",
+        )
+        if not os.path.exists(gallery_dir):
+            os.makedirs(gallery_dir)
+
+        # Use provided name or create a unique name
+        if gallery_name is None or gallery_name.strip() == "":
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            gallery_name = f"reconstruction_{timestamp}"
+
+        gallery_path = os.path.join(gallery_dir, gallery_name)
+
+        # Check if directory already exists
+        if os.path.exists(gallery_path):
+            return False, f"Save failed: folder '{gallery_name}' already exists"
+
+        # Create the gallery directory
+        os.makedirs(gallery_path, exist_ok=True)
+
+        # Copy GLB file
+        glb_source = os.path.join(target_dir, "scene.glb")
+        glb_dest = os.path.join(gallery_path, "scene.glb")
+        if os.path.exists(glb_source):
+            shutil.copy2(glb_source, glb_dest)
+
+        # Copy depth visualization images
+        depth_vis_dir = os.path.join(target_dir, "depth_vis")
+        if os.path.exists(depth_vis_dir):
+            gallery_depth_vis = os.path.join(gallery_path, "depth_vis")
+            shutil.copytree(depth_vis_dir, gallery_depth_vis)
+
+        # Copy original images
+        images_source = os.path.join(target_dir, "images")
+        if os.path.exists(images_source):
+            gallery_images = os.path.join(gallery_path, "images")
+            shutil.copytree(images_source, gallery_images)
+
+        scene_preview_source = os.path.join(target_dir, "scene.jpg")
+        scene_preview_dest = os.path.join(gallery_path, "scene.jpg")
+        shutil.copy2(scene_preview_source, scene_preview_dest)
+
+        # Save metadata
+        metadata = {
+            "timestamp": datetime.now().strftime("%Y%m%d_%H%M%S"),
+            "num_images": len(processed_data) if processed_data else 0,
+            "gallery_name": gallery_name,
+        }
+
+        with open(os.path.join(gallery_path, "metadata.json"), "w") as f:
+            json.dump(metadata, f, indent=2)
+
+        print(f"Saved reconstruction to gallery: {gallery_path}")
+        return True, f"Save successful: saved to {gallery_path}"
+
+    except Exception as e:
+        print(f"Error saving to gallery: {e}")
+        return False, f"Save failed: {str(e)}"
+
+
+def _extract_video_thumbnail(video_path: str) -> str:
+    """
+    Extract the first frame of a video as a thumbnail image.
+
+    Args:
+        video_path: Path to the video file
+
+    Returns:
+        Path to the thumbnail image (or video path if extraction fails)
+    """
+    import tempfile
+
+    import cv2
+
+    try:
+        cap = cv2.VideoCapture(video_path)
+        ret, frame = cap.read()
+        cap.release()
+
+        if ret and frame is not None:
+            # Save thumbnail to temp directory
+            video_name = os.path.splitext(os.path.basename(video_path))[0]
+            thumbnail_dir = os.path.join(tempfile.gettempdir(), "da3_video_thumbnails")
+            os.makedirs(thumbnail_dir, exist_ok=True)
+            thumbnail_path = os.path.join(thumbnail_dir, f"{video_name}_thumb.jpg")
+            cv2.imwrite(thumbnail_path, frame)
+            return thumbnail_path
+    except Exception as e:
+        print(f"Error extracting video thumbnail: {e}")
+
+    # Fallback to video path if extraction fails
+    return video_path
+
+
+def get_scene_info(examples_dir: str) -> List[Dict[str, Any]]:
+    """
+    Get information about scenes in the examples directory.
+
+    Supports:
+    - Folders containing images (scene folders)
+    - Video files at the root level
+
+    Args:
+        examples_dir: Path to examples directory
+
+    Returns:
+        List of scene information dictionaries
+    """
+    import glob
+
+    scenes = []
+    if not os.path.exists(examples_dir):
+        return scenes
+
+    for item in sorted(os.listdir(examples_dir)):
+        item_path = os.path.join(examples_dir, item)
+
+        if os.path.isdir(item_path):
+            # Find all image files in the scene folder
+            image_extensions = ["*.jpg", "*.jpeg", "*.png", "*.bmp", "*.tiff", "*.tif"]
+            image_files = []
+            for ext in image_extensions:
+                image_files.extend(glob.glob(os.path.join(item_path, ext)))
+                image_files.extend(glob.glob(os.path.join(item_path, ext.upper())))
+
+            if image_files:
+                # Sort images and get the first one for thumbnail
+                image_files = sorted(image_files)
+                first_image = image_files[0]
+                num_images = len(image_files)
+
+                scenes.append(
+                    {
+                        "name": item,
+                        "path": item_path,
+                        "thumbnail": first_image,
+                        "num_images": num_images,
+                        "image_files": image_files,
+                        "type": "images",
+                    }
+                )
+
+        elif os.path.isfile(item_path):
+            # Check if it's a video file
+            video_extensions = [".mp4", ".avi", ".mov", ".mkv", ".webm"]
+            ext = os.path.splitext(item)[1].lower()
+            if ext in video_extensions:
+                name = os.path.splitext(item)[0]
+                # Extract first frame as thumbnail
+                thumbnail_path = _extract_video_thumbnail(item_path)
+                scenes.append(
+                    {
+                        "name": name,
+                        "path": item_path,
+                        "thumbnail": thumbnail_path,  # First frame as thumbnail
+                        "num_images": 0,
+                        "image_files": [],
+                        "video_file": item_path,
+                        "type": "video",
+                    }
+                )
+
+    return scenes
+
+
+# NOTE: cleanup was moved to a single canonical helper in
+# `depth_anything_3.utils.memory.cleanup_cuda_memory`.
+# Callers should import and call that directly instead of using this module.
+
+
+def get_logo_base64() -> Optional[str]:
+    """
+    Convert WAI logo to base64 for embedding in HTML.
+
+    Returns:
+        Base64 encoded logo string or None
+    """
+    import base64
+
+    logo_path = "examples/WAI-Logo/wai_logo.png"
+    try:
+        with open(logo_path, "rb") as img_file:
+            img_data = img_file.read()
+            base64_str = base64.b64encode(img_data).decode()
+            return f"data:image/png;base64,{base64_str}"
+    except FileNotFoundError:
+        return None

src/depth_anything_3/app/modules/visualization.py

@@ -0,0 +1,435 @@
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Visualization module for Depth Anything 3 Gradio app.
+
+This module handles visualization updates, navigation, and measurement functionality.
+"""
+
+import os
+from typing import Any, Dict, List, Optional, Tuple
+
+import cv2
+import gradio as gr
+import numpy as np
+
+
+class VisualizationHandler:
+    """
+    Handles visualization updates and navigation for the Gradio app.
+    """
+
+    def __init__(self):
+        """Initialize the visualization handler."""
+
+    def update_view_selectors(
+        self, processed_data: Optional[dict]
+    ) -> Tuple[gr.Dropdown, gr.Dropdown]:
+        """
+        Update view selector dropdowns based on available views.
+
+        Args:
+            processed_data: Processed data dictionary
+
+        Returns:
+            Tuple of (depth_view_selector, measure_view_selector)
+        """
+        if processed_data is None or len(processed_data) == 0:
+            choices = ["View 1"]
+        else:
+            num_views = len(processed_data)
+            choices = [f"View {i + 1}" for i in range(num_views)]
+
+        return (
+            gr.Dropdown(choices=choices, value=choices[0]),  # depth_view_selector
+            gr.Dropdown(choices=choices, value=choices[0]),  # measure_view_selector
+        )
+
+    def get_view_data_by_index(
+        self, processed_data: Optional[dict], view_index: int
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Get view data by index, handling bounds.
+
+        Args:
+            processed_data: Processed data dictionary
+            view_index: Index of the view to get
+
+        Returns:
+            View data dictionary or None
+        """
+        if processed_data is None or len(processed_data) == 0:
+            return None
+
+        view_keys = list(processed_data.keys())
+        if view_index < 0 or view_index >= len(view_keys):
+            view_index = 0
+
+        return processed_data[view_keys[view_index]]
+
+    def update_depth_view(
+        self, processed_data: Optional[dict], view_index: int
+    ) -> Optional[str]:
+        """
+        Update depth view for a specific view index.
+
+        Args:
+            processed_data: Processed data dictionary
+            view_index: Index of the view to update
+
+        Returns:
+            Path to depth visualization image or None
+        """
+        view_data = self.get_view_data_by_index(processed_data, view_index)
+        if view_data is None or view_data.get("depth_image") is None:
+            return None
+
+        # Return the depth visualization image directly
+        return view_data["depth_image"]
+
+    def navigate_depth_view(
+        self,
+        processed_data: Optional[dict],
+        current_selector_value: str,
+        direction: int,
+    ) -> Tuple[str, Optional[str]]:
+        """
+        Navigate depth view (direction: -1 for previous, +1 for next).
+
+        Args:
+            processed_data: Processed data dictionary
+            current_selector_value: Current selector value
+            direction: Direction to navigate (-1 for previous, +1 for next)
+
+        Returns:
+            Tuple of (new_selector_value, depth_vis)
+        """
+        if processed_data is None or len(processed_data) == 0:
+            return "View 1", None
+
+        # Parse current view number
+        try:
+            current_view = int(current_selector_value.split()[1]) - 1
+        except:  # noqa
+            current_view = 0
+
+        num_views = len(processed_data)
+        new_view = (current_view + direction) % num_views
+
+        new_selector_value = f"View {new_view + 1}"
+        depth_vis = self.update_depth_view(processed_data, new_view)
+
+        return new_selector_value, depth_vis
+
+    def update_measure_view(
+        self, processed_data: Optional[dict], view_index: int
+    ) -> Tuple[Optional[np.ndarray], Optional[np.ndarray], List]:
+        """
+        Update measure view for a specific view index.
+
+        Args:
+            processed_data: Processed data dictionary
+            view_index: Index of the view to update
+
+        Returns:
+            Tuple of (measure_image, depth_right_half, measure_points)
+        """
+        view_data = self.get_view_data_by_index(processed_data, view_index)
+        if view_data is None:
+            return None, None, []  # image, depth_right_half, measure_points
+
+        # Get the processed (resized) image
+        if "image" in view_data and view_data["image"] is not None:
+            image = view_data["image"].copy()
+        else:
+            return None, None, []
+
+        # Ensure image is in uint8 format
+        if image.dtype != np.uint8:
+            if image.max() <= 1.0:
+                image = (image * 255).astype(np.uint8)
+            else:
+                image = image.astype(np.uint8)
+
+        # Extract right half of the depth visualization (pure depth part)
+        depth_image_path = view_data.get("depth_image", None)
+        depth_right_half = None
+
+        if depth_image_path and os.path.exists(depth_image_path):
+            try:
+                # Load the combined depth visualization image
+                depth_combined = cv2.imread(depth_image_path)
+                depth_combined = cv2.cvtColor(depth_combined, cv2.COLOR_BGR2RGB)
+                if depth_combined is not None:
+                    height, width = depth_combined.shape[:2]
+                    # Extract right half (depth visualization part)
+                    depth_right_half = depth_combined[:, width // 2 :]
+            except Exception as e:
+                print(f"Error extracting depth right half: {e}")
+
+        return image, depth_right_half, []
+
+    def navigate_measure_view(
+        self,
+        processed_data: Optional[dict],
+        current_selector_value: str,
+        direction: int,
+    ) -> Tuple[str, Optional[np.ndarray], Optional[str], List]:
+        """
+        Navigate measure view (direction: -1 for previous, +1 for next).
+
+        Args:
+            processed_data: Processed data dictionary
+            current_selector_value: Current selector value
+            direction: Direction to navigate (-1 for previous, +1 for next)
+
+        Returns:
+            Tuple of (new_selector_value, measure_image, depth_image_path, measure_points)
+        """
+        if processed_data is None or len(processed_data) == 0:
+            return "View 1", None, None, []
+
+        # Parse current view number
+        try:
+            current_view = int(current_selector_value.split()[1]) - 1
+        except:  # noqa
+            current_view = 0
+
+        num_views = len(processed_data)
+        new_view = (current_view + direction) % num_views
+
+        new_selector_value = f"View {new_view + 1}"
+        measure_image, depth_right_half, measure_points = self.update_measure_view(
+            processed_data, new_view
+        )
+
+        return new_selector_value, measure_image, depth_right_half, measure_points
+
+    def populate_visualization_tabs(
+        self, processed_data: Optional[dict]
+    ) -> Tuple[Optional[str], Optional[np.ndarray], Optional[str], List]:
+        """
+        Populate the depth and measure tabs with processed data.
+
+        Args:
+            processed_data: Processed data dictionary
+
+        Returns:
+            Tuple of (depth_vis, measure_img, depth_image_path, measure_points)
+        """
+        if processed_data is None or len(processed_data) == 0:
+            return None, None, None, []
+
+        # Use update function to get depth visualization
+        depth_vis = self.update_depth_view(processed_data, 0)
+        measure_img, depth_right_half, _ = self.update_measure_view(processed_data, 0)
+
+        return depth_vis, measure_img, depth_right_half, []
+
+    def reset_measure(
+        self, processed_data: Optional[dict]
+    ) -> Tuple[Optional[np.ndarray], List, str]:
+        """
+        Reset measure points.
+
+        Args:
+            processed_data: Processed data dictionary
+
+        Returns:
+            Tuple of (image, measure_points, text)
+        """
+        if processed_data is None or len(processed_data) == 0:
+            return None, [], ""
+
+        # Return the first view image
+        first_view = list(processed_data.values())[0]
+        return first_view["image"], [], ""
+
+    def measure(
+        self,
+        processed_data: Optional[dict],
+        measure_points: List,
+        current_view_selector: str,
+        event: gr.SelectData,
+    ) -> List:
+        """
+        Handle measurement on images.
+
+        Args:
+            processed_data: Processed data dictionary
+            measure_points: List of current measure points
+            current_view_selector: Current view selector value
+            event: Gradio select event
+
+        Returns:
+            List of [image, depth_right_half, measure_points, text]
+        """
+        try:
+            print(f"Measure function called with selector: {current_view_selector}")
+
+            if processed_data is None or len(processed_data) == 0:
+                return [None, [], "No data available"]
+
+            # Use the currently selected view instead of always using the first view
+            try:
+                current_view_index = int(current_view_selector.split()[1]) - 1
+            except:  # noqa
+                current_view_index = 0
+
+            print(f"Using view index: {current_view_index}")
+
+            # Get view data safely
+            if current_view_index < 0 or current_view_index >= len(processed_data):
+                current_view_index = 0
+
+            view_keys = list(processed_data.keys())
+            current_view = processed_data[view_keys[current_view_index]]
+
+            if current_view is None:
+                return [None, [], "No view data available"]
+
+            point2d = event.index[0], event.index[1]
+            print(f"Clicked point: {point2d}")
+
+            measure_points.append(point2d)
+
+            # Get image and depth visualization
+            image, depth_right_half, _ = self.update_measure_view(
+                processed_data, current_view_index
+            )
+            if image is None:
+                return [None, [], "No image available"]
+
+            image = image.copy()
+
+            # Ensure image is in uint8 format for proper cv2 operations
+            try:
+                if image.dtype != np.uint8:
+                    if image.max() <= 1.0:
+                        # Image is in [0, 1] range, convert to [0, 255]
+                        image = (image * 255).astype(np.uint8)
+                    else:
+                        # Image is already in [0, 255] range
+                        image = image.astype(np.uint8)
+            except Exception as e:
+                print(f"Image conversion error: {e}")
+                return [None, [], f"Image conversion error: {e}"]
+
+            # Draw circles for points
+            try:
+                for p in measure_points:
+                    if 0 <= p[0] < image.shape[1] and 0 <= p[1] < image.shape[0]:
+                        image = cv2.circle(image, p, radius=5, color=(255, 0, 0), thickness=2)
+            except Exception as e:
+                print(f"Drawing error: {e}")
+                return [None, [], f"Drawing error: {e}"]
+
+            # Get depth information from processed_data
+            depth_text = ""
+            try:
+                for i, p in enumerate(measure_points):
+                    if (
+                        current_view["depth"] is not None
+                        and 0 <= p[1] < current_view["depth"].shape[0]
+                        and 0 <= p[0] < current_view["depth"].shape[1]
+                    ):
+                        d = current_view["depth"][p[1], p[0]]
+                        depth_text += f"- **P{i + 1} depth: {d:.2f}m**\n"
+                    else:
+                        depth_text += f"- **P{i + 1}: Click position ({p[0]}, {p[1]}) - No depth information**\n"  # noqa: E501
+            except Exception as e:
+                print(f"Depth text error: {e}")
+                depth_text = f"Error computing depth: {e}\n"
+
+            if len(measure_points) == 2:
+                try:
+                    point1, point2 = measure_points
+                    # Draw line
+                    if (
+                        0 <= point1[0] < image.shape[1]
+                        and 0 <= point1[1] < image.shape[0]
+                        and 0 <= point2[0] < image.shape[1]
+                        and 0 <= point2[1] < image.shape[0]
+                    ):
+                        image = cv2.line(image, point1, point2, color=(255, 0, 0), thickness=2)
+
+                    # Compute 3D distance using depth information and camera intrinsics
+                    distance_text = "- **Distance: Unable to calculate 3D distance**"
+                    if (
+                        current_view["depth"] is not None
+                        and 0 <= point1[1] < current_view["depth"].shape[0]
+                        and 0 <= point1[0] < current_view["depth"].shape[1]
+                        and 0 <= point2[1] < current_view["depth"].shape[0]
+                        and 0 <= point2[0] < current_view["depth"].shape[1]
+                    ):
+                        try:
+                            # Get depth values at the two points
+                            d1 = current_view["depth"][point1[1], point1[0]]
+                            d2 = current_view["depth"][point2[1], point2[0]]
+
+                            # Convert 2D pixel coordinates to 3D world coordinates
+                            if current_view["intrinsics"] is not None:
+                                # Get camera intrinsics
+                                K = current_view["intrinsics"]  # 3x3 intrinsic matrix
+                                fx, fy = K[0, 0], K[1, 1]  # focal lengths
+                                cx, cy = K[0, 2], K[1, 2]  # principal point
+
+                                # Convert pixel coordinates to normalized camera coordinates
+                                # Point 1: (u1, v1) -> (x1, y1, z1)
+                                u1, v1 = point1[0], point1[1]
+                                x1 = (u1 - cx) * d1 / fx
+                                y1 = (v1 - cy) * d1 / fy
+                                z1 = d1
+
+                                # Point 2: (u2, v2) -> (x2, y2, z2)
+                                u2, v2 = point2[0], point2[1]
+                                x2 = (u2 - cx) * d2 / fx
+                                y2 = (v2 - cy) * d2 / fy
+                                z2 = d2
+
+                                # Calculate 3D Euclidean distance
+                                p1_3d = np.array([x1, y1, z1])
+                                p2_3d = np.array([x2, y2, z2])
+                                distance_3d = np.linalg.norm(p1_3d - p2_3d)
+
+                                distance_text = f"- **Distance: {distance_3d:.2f}m**"
+                            else:
+                                # Fallback to simplified calculation if no intrinsics
+                                pixel_distance = np.sqrt(
+                                    (point1[0] - point2[0]) ** 2 + (point1[1] - point2[1]) ** 2
+                                )
+                                avg_depth = (d1 + d2) / 2
+                                scale_factor = avg_depth / 1000  # Rough scaling factor
+                                estimated_3d_distance = pixel_distance * scale_factor
+                                distance_text = f"- **Distance: {estimated_3d_distance:.2f}m (estimated, no intrinsics)**"  # noqa: E501
+
+                        except Exception as e:
+                            print(f"Distance computation error: {e}")
+                            distance_text = f"- **Distance computation error: {e}**"
+
+                    measure_points = []
+                    text = depth_text + distance_text
+                    print(f"Measurement complete: {text}")
+                    return [image, depth_right_half, measure_points, text]
+                except Exception as e:
+                    print(f"Final measurement error: {e}")
+                    return [None, [], f"Measurement error: {e}"]
+            else:
+                print(f"Single point measurement: {depth_text}")
+                return [image, depth_right_half, measure_points, depth_text]
+
+        except Exception as e:
+            print(f"Overall measure function error: {e}")
+            return [None, [], f"Measure function error: {e}"]

src/depth_anything_3/cache.py

@@ -0,0 +1,190 @@
+"""
+Model caching utilities for Depth Anything 3.
+
+Provides model caching functionality to avoid reloading model weights on every instantiation.
+This significantly reduces latency for repeated model creation (2-5s gain).
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Dict, Optional, Tuple
+
+import torch
+import torch.nn as nn
+
+from depth_anything_3.utils.logger import logger
+
+
+class ModelCache:
+    """
+    Thread-safe singleton cache for Depth Anything 3 models.
+
+    Caches loaded model weights to avoid reloading from disk on every instantiation.
+    Each unique combination of (model_name, device) is cached separately.
+
+    Usage:
+        cache = ModelCache()
+        model = cache.get(model_name, device, loader_fn)
+        # loader_fn is only called if cache miss
+
+    Thread Safety:
+        Uses threading.Lock to ensure thread-safe access to cache.
+
+    Memory Management:
+        - Models are kept in cache until explicitly cleared
+        - Use clear() to free memory when needed
+        - Use clear_device() to clear specific device models
+    """
+
+    _instance: Optional["ModelCache"] = None
+    _lock = threading.Lock()
+
+    def __new__(cls):
+        """Singleton pattern to ensure single cache instance."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self):
+        """Initialize cache storage."""
+        if self._initialized:
+            return
+
+        self._cache: Dict[Tuple[str, str], nn.Module] = {}
+        self._cache_lock = threading.Lock()
+        self._initialized = True
+        logger.info("ModelCache initialized")
+
+    def get(
+        self,
+        model_name: str,
+        device: torch.device | str,
+        loader_fn: callable,
+    ) -> nn.Module:
+        """
+        Get cached model or load if not in cache.
+
+        Args:
+            model_name: Name of the model (e.g., "da3-large")
+            device: Target device (cuda, mps, cpu)
+            loader_fn: Function to load model if cache miss
+                      Should return nn.Module
+
+        Returns:
+            Cached or freshly loaded model on specified device
+
+        Example:
+            >>> cache = ModelCache()
+            >>> model = cache.get(
+            ...     "da3-large",
+            ...     "cuda",
+            ...     lambda: create_model()
+            ... )
+        """
+        device_str = str(device)
+        cache_key = (model_name, device_str)
+
+        with self._cache_lock:
+            if cache_key in self._cache:
+                logger.debug(f"Model cache HIT: {model_name} on {device_str}")
+                return self._cache[cache_key]
+
+            logger.info(f"Model cache MISS: {model_name} on {device_str}. Loading...")
+            model = loader_fn()
+            self._cache[cache_key] = model
+            logger.info(f"Model cached: {model_name} on {device_str}")
+
+            return model
+
+    def clear(self) -> None:
+        """
+        Clear entire cache and free memory.
+
+        Removes all cached models and forces garbage collection.
+        Useful when switching between many different models.
+        """
+        with self._cache_lock:
+            num_cached = len(self._cache)
+            self._cache.clear()
+
+            # Force garbage collection to free GPU memory
+            import gc
+
+            gc.collect()
+            if torch.cuda.is_available():
+                torch.cuda.empty_cache()
+            if hasattr(torch, "mps") and torch.backends.mps.is_available():
+                torch.mps.empty_cache()
+
+            logger.info(f"Model cache cleared ({num_cached} models removed)")
+
+    def clear_device(self, device: torch.device | str) -> None:
+        """
+        Clear all models on specific device.
+
+        Args:
+            device: Device to clear (e.g., "cuda", "mps", "cpu")
+
+        Example:
+            >>> cache = ModelCache()
+            >>> cache.clear_device("cuda")  # Clear all CUDA models
+        """
+        device_str = str(device)
+
+        with self._cache_lock:
+            keys_to_remove = [key for key in self._cache if key[1] == device_str]
+            for key in keys_to_remove:
+                del self._cache[key]
+
+            # Free device memory
+            if "cuda" in device_str and torch.cuda.is_available():
+                torch.cuda.empty_cache()
+            elif "mps" in device_str and hasattr(torch, "mps") and torch.backends.mps.is_available():
+                torch.mps.empty_cache()
+
+            logger.info(f"Model cache cleared for device {device_str} ({len(keys_to_remove)} models removed)")
+
+    def get_cache_info(self) -> Dict[str, int]:
+        """
+        Get cache statistics.
+
+        Returns:
+            Dictionary with cache info:
+                - total: Total number of cached models
+                - by_device: Number of models per device
+        """
+        with self._cache_lock:
+            info = {
+                "total": len(self._cache),
+                "by_device": {},
+            }
+
+            for model_name, device_str in self._cache.keys():
+                if device_str not in info["by_device"]:
+                    info["by_device"][device_str] = 0
+                info["by_device"][device_str] += 1
+
+            return info
+
+
+# Global singleton instance
+_global_cache = ModelCache()
+
+
+def get_model_cache() -> ModelCache:
+    """
+    Get global model cache instance.
+
+    Returns:
+        Singleton ModelCache instance
+
+    Example:
+        >>> from depth_anything_3.cache import get_model_cache
+        >>> cache = get_model_cache()
+        >>> cache.clear()
+    """
+    return _global_cache

src/depth_anything_3/cfg.py

@@ -0,0 +1,145 @@
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Configuration utility functions
+"""
+
+import importlib
+from pathlib import Path
+from typing import Any, Callable, List, Union
+
+from omegaconf import DictConfig, ListConfig, OmegaConf
+
+try:
+    OmegaConf.register_new_resolver("eval", eval)
+except Exception as e:
+    # if eval is not available, we can just pass
+    print(f"Error registering eval resolver: {e}")
+
+
+def load_config(path: str, argv: List[str] = None) -> Union[DictConfig, ListConfig]:
+    """
+    Load a configuration. Will resolve inheritance.
+    Supports both file paths and module paths (e.g., depth_anything_3.configs.giant).
+    """
+    # Check if path is a module path (contains dots but no slashes and doesn't end with .yaml)
+    if "." in path and "/" not in path and not path.endswith(".yaml"):
+        # It's a module path, load from package resources
+        path_parts = path.split(".")[1:]
+        config_path = Path(__file__).resolve().parent
+        for part in path_parts:
+            config_path = config_path.joinpath(part)
+        config_path = config_path.with_suffix(".yaml")
+        config = OmegaConf.load(str(config_path))
+    else:
+        # It's a file path (absolute, relative, or with .yaml extension)
+        config = OmegaConf.load(path)
+
+    if argv is not None:
+        config_argv = OmegaConf.from_dotlist(argv)
+        config = OmegaConf.merge(config, config_argv)
+    config = resolve_recursive(config, resolve_inheritance)
+    return config
+
+
+def resolve_recursive(
+    config: Any,
+    resolver: Callable[[Union[DictConfig, ListConfig]], Union[DictConfig, ListConfig]],
+) -> Any:
+    config = resolver(config)
+    if isinstance(config, DictConfig):
+        for k in config.keys():
+            v = config.get(k)
+            if isinstance(v, (DictConfig, ListConfig)):
+                config[k] = resolve_recursive(v, resolver)
+    if isinstance(config, ListConfig):
+        for i in range(len(config)):
+            v = config.get(i)
+            if isinstance(v, (DictConfig, ListConfig)):
+                config[i] = resolve_recursive(v, resolver)
+    return config
+
+
+def resolve_inheritance(config: Union[DictConfig, ListConfig]) -> Any:
+    """
+    Recursively resolve inheritance if the config contains:
+    __inherit__: path/to/parent.yaml or a ListConfig of such paths.
+    """
+    if isinstance(config, DictConfig):
+        inherit = config.pop("__inherit__", None)
+
+        if inherit:
+            inherit_list = inherit if isinstance(inherit, ListConfig) else [inherit]
+
+            parent_config = None
+            for parent_path in inherit_list:
+                assert isinstance(parent_path, str)
+                parent_config = (
+                    load_config(parent_path)
+                    if parent_config is None
+                    else OmegaConf.merge(parent_config, load_config(parent_path))
+                )
+
+            if len(config.keys()) > 0:
+                config = OmegaConf.merge(parent_config, config)
+            else:
+                config = parent_config
+    return config
+
+
+def import_item(path: str, name: str) -> Any:
+    """
+    Import a python item. Example: import_item("path.to.file", "MyClass") -> MyClass
+    """
+    return getattr(importlib.import_module(path), name)
+
+
+def create_object(config: DictConfig) -> Any:
+    """
+    Create an object from config.
+    The config is expected to contains the following:
+    __object__:
+      path: path.to.module
+      name: MyClass
+      args: as_config | as_params (default to as_config)
+    """
+    config = DictConfig(config)
+    item = import_item(
+        path=config.__object__.path,
+        name=config.__object__.name,
+    )
+    args = config.__object__.get("args", "as_config")
+    if args == "as_config":
+        return item(config)
+    if args == "as_params":
+        config = OmegaConf.to_object(config)
+        config.pop("__object__")
+        return item(**config)
+    raise NotImplementedError(f"Unknown args type: {args}")
+
+
+def create_dataset(path: str, *args, **kwargs) -> Any:
+    """
+    Create a dataset. Requires the file to contain a "create_dataset" function.
+    """
+    return import_item(path, "create_dataset")(*args, **kwargs)
+
+
+def to_dict_recursive(config_obj):
+    if isinstance(config_obj, DictConfig):
+        return {k: to_dict_recursive(v) for k, v in config_obj.items()}
+    elif isinstance(config_obj, ListConfig):
+        return [to_dict_recursive(item) for item in config_obj]
+    return config_obj