Initial code release for NeurIPS 2026 D&B reviewer reference

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+dataset_metadata/manifests_h100/SHA256SUMS_tartanground.txt filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,31 @@
+__pycache__/
+*.py[cod]
+.DS_Store
+.env
+.venv/
+venv/
+*.egg-info/
+
+# Local data, generated outputs, and large third-party artifacts.
+data/*
+!data/README.md
+outputs/
+logs/
+checkpoints/
+third_party/*
+!third_party/README.md
+*.blend
+*.glb
+*.gltf
+*.ply
+*.obj
+*.fbx
+*.exr
+*.npy
+*.npz
+*.pt
+*.pth
+*.ckpt
+
+# Keep checked-in result templates, but ignore local regenerated variants.
+results/*.local.csv

CITATION.cff

@@ -0,0 +1,9 @@
+cff-version: 1.2.0
+message: "If you use this code, please cite the associated anonymous NeurIPS submission during review and the camera-ready paper after publication."
+title: "CM-EVS: Conflict-Minimized Efficient View Selection for Scalable 3D Scene Data Acquisition"
+authors:
+  - family-names: "Anonymous"
+    given-names: "Authors"
+date-released: 2026-04-27
+license: MIT
+

GITHUB_UPLOAD.md

@@ -0,0 +1,31 @@
+# Anonymous GitHub Upload Guide
+
+The NeurIPS review policy requires the code URL to be accessible and anonymized at submission time. Use an anonymous repository service or a repository that does not reveal author identity.
+
+## Final Local Check
+
+Run from the repository root:
+
+```bash
+bash scripts/run_tiny.sh
+rm -rf outputs
+bash scripts/check_anonymity.sh
+```
+
+## Initialize and Push
+
+```bash
+git init
+git add .
+git commit -m "Anonymous CM-EVS code release"
+git branch -M main
+git remote add origin <anonymous-repository-url>
+git push -u origin main
+```
+
+Before pushing, verify that `git status --short` does not include local scene data, rendered outputs, checkpoints, or third-party dataset assets.
+
+## OpenReview Field
+
+Paste the anonymous repository URL into the **Code URL** field. If the repository is mirrored through an anonymous hosting service, use the anonymized URL rather than a personal GitHub URL.
+

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Anonymous Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

README.md

@@ -0,0 +1,157 @@
+# CM-EVS Anonymous Code Release
+
+This repository contains the anonymous code release for **CM-EVS: Conflict-Minimized Efficient View Selection for Scalable 3D Scene Data Acquisition**.
+
+The release is intentionally organized around one primary review path:
+
+```text
+Blender indoor .blend scenes
+  -> candidate generation
+  -> conflict-minimized view selection
+  -> selected ERP rendering
+  -> coverage, oracle-gap, and quality-audit outputs
+```
+
+HM3D/GLB and ScanNet++/PLY support is included as secondary adapters, but the first path reviewers should inspect is the Blender-indoor path.
+
+## Review-Ready Entry Points
+
+| Purpose | Command |
+| --- | --- |
+| No-data smoke test | `bash scripts/run_tiny.sh` |
+| Blender-indoor dry run | `DRY_RUN=1 BLENDER=/path/to/blender INPUT_DIR=/path/to/blend_scenes bash scripts/run_blender_indoor.sh` |
+| Full Blender-indoor run | `BLENDER=/path/to/blender INPUT_DIR=/path/to/blend_scenes bash scripts/run_blender_indoor.sh` |
+| Summarize Blender-indoor run | `python3 scripts/summarize_blender_indoor_run.py --output-root outputs/blender_indoor` |
+| Anonymity check | `bash scripts/check_anonymity.sh` |
+
+The smoke test is designed to run without private assets. The full Blender-indoor run requires local `.blend` scenes and a Blender executable.
+
+## Repository Layout
+
+```text
+.
+├── pipelines/               # full scene pipelines; Blender indoor is the primary path
+├── scripts/                 # review and reproduction entry points
+├── configs/                 # default and source-specific configs
+├── core/                    # ERP projection, tangent extraction, depth, and warping modules
+├── tools/                   # semantic and navigability helpers
+├── utils/                   # IO and pose utilities
+├── examples/                # tiny Blender-indoor-style metadata example
+├── metadata_examples/       # JSON schemas for candidate/selection logs
+├── data/                    # local data mount point, not tracked
+├── third_party/             # optional external dependencies, not tracked
+└── results/                 # generated result CSVs
+```
+
+## Environment
+
+```bash
+conda env create -f environment.yml
+conda activate cmevs
+```
+
+If Conda is unavailable:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Minimal Smoke Test
+
+```bash
+bash scripts/run_tiny.sh
+```
+
+Expected outputs:
+
+```text
+outputs/tiny/metadata/candidates.jsonl
+outputs/tiny/metadata/selected_viewpoints.json
+outputs/tiny/metadata/per_step_log.jsonl
+outputs/tiny/renders/
+outputs/tiny/results/coverage_main.csv
+outputs/tiny/results/oracle_validation.csv
+outputs/tiny/results/audit_50_frames.csv
+```
+
+This test validates the repository wiring and metadata contracts. It is not intended to reproduce paper-scale numbers.
+
+## Paper Experiments
+
+The driver scripts for the §6 evaluation experiments (fixed-budget coverage, oracle-gain validation, λ sweep, cross-source robustness, downstream depth) are scheduled to be released alongside the camera-ready paper. The current release ships the algorithmic core (`scripts/build_candidates.py`, `scripts/select_views.py`, `scripts/render_selected.py`), the per-stage evaluation building blocks (`scripts/evaluate_coverage.py`, `scripts/evaluate_oracle_gap.py`, `scripts/audit_quality.py`), and the metadata-contract example through the smoke test. Reviewers can verify the algorithmic core end-to-end via the smoke test above.
+
+## Primary Full Run: Blender Indoor
+
+Put `.blend` scenes under `data/blender_indoor/`, or point `INPUT_DIR` to another directory. Nested layouts are supported; the first subdirectory under `INPUT_DIR` is used as the scene name.
+
+Dry run:
+
+```bash
+DRY_RUN=1 \
+BLENDER=/path/to/blender \
+INPUT_DIR=data/blender_indoor \
+OUTPUT_ROOT=outputs/blender_indoor \
+bash scripts/run_blender_indoor.sh
+```
+
+Full run:
+
+```bash
+BLENDER=/path/to/blender \
+INPUT_DIR=data/blender_indoor \
+OUTPUT_ROOT=outputs/blender_indoor \
+NUM_FRAMES=30 \
+RESOLUTION=2048,1024 \
+bash scripts/run_blender_indoor.sh
+```
+
+Equivalent direct CLI:
+
+```bash
+export PYTHONPATH="$PWD:$PWD/pipelines:${PYTHONPATH:-}"
+
+python3 pipelines/run_full_pipeline.py \
+  --blender /path/to/blender \
+  --input-dir data/blender_indoor \
+  --output-root outputs/blender_indoor \
+  --num-frames 30 \
+  --resolution 2048,1024 \
+  --grid-spacing 0.5 \
+  --min-frames 5 \
+  --stop-gain 0.08
+```
+
+## Secondary Adapters
+
+The repository also includes adapters for additional sources used in robustness analyses:
+
+- `configs/blender_outdoor.yaml`: generic `.glb` / `.gltf` scenes.
+- `configs/hm3d.yaml`: HM3D-style `.glb` / `.gltf` scenes.
+- `configs/scannetpp.yaml`: ScanNet++-style `.ply` scenes.
+
+These adapters are provided for completeness, but the Blender-indoor route is the recommended first reviewer path.
+
+## Data and Checkpoints
+
+This repository does not redistribute third-party scene assets, dataset files, or model checkpoints. Put local assets under `data/` or pass absolute paths via CLI. The `data/` directory is ignored by git.
+
+Depth Pro is optional for ERPT-style depth fusion. If used, place it under:
+
+```text
+third_party/ml-depth-pro/
+third_party/ml-depth-pro/checkpoints/depth_pro.pt
+```
+
+## Final Submission Check
+
+Before uploading the code URL or zip:
+
+```bash
+bash scripts/run_tiny.sh
+rm -rf outputs
+bash scripts/check_anonymity.sh
+```
+
+The code is released under the MIT License for review. Dataset assets remain governed by their original licenses.

README_REPRODUCE.md

@@ -0,0 +1,95 @@
+# Reproducibility Guide
+
+This guide maps the code release to the experiments in the paper. The primary reproducibility path is Blender indoor; other sources are retained as secondary adapters for robustness checks.
+
+## Primary Asset Requirement
+
+| Source | Expected Input | Primary Command |
+| --- | --- | --- |
+| Blender indoor | `.blend` scenes | `scripts/run_blender_indoor.sh` |
+
+The repository does not redistribute scene assets. Reviewers can run the no-data smoke test immediately, and can run the full path after mounting local `.blend` scenes.
+
+## Secondary Assets
+
+| Source | Expected Input | Config |
+| --- | --- | --- |
+| Blender outdoor / generic meshes | `.glb` or `.gltf` | `configs/blender_outdoor.yaml` |
+| HM3D | `.glb` or `.gltf` plus optional semantic/navmesh files | `configs/hm3d.yaml` |
+| ScanNet++ | `.ply` | `configs/scannetpp.yaml` |
+
+## Building Blocks Available in This Release
+
+| Module | Purpose | Entry Point |
+| --- | --- | --- |
+| Candidate generation | Phase 1 of §3 — produce \(\mathcal{P}_\varphi\) | `scripts/build_candidates.py` |
+| Conflict-aware selection | Phase 2 of §3 — greedy with \(s_t = G_t - \lambda L_t + \beta B_t\) | `scripts/select_views.py` |
+| Selected-view rendering | Phase 3 — final ERP render from chosen candidates | `scripts/render_selected.py` |
+| Coverage metric | §6.1 high-resolution oracle coverage | `scripts/evaluate_coverage.py` |
+| Oracle-gain validation | §6.2 warping vs. pre-render-all comparison | `scripts/evaluate_oracle_gap.py` |
+| Quality audit | Appendix F.2 50-frame audit | `scripts/audit_quality.py` |
+| Run summarization | Aggregate per-scene `selected_frames.json` into a CSV | `scripts/summarize_blender_indoor_run.py` |
+| Audit summarization | Aggregate per-frame audit results into a CSV | `scripts/summarize_quality_audit.py` |
+
+The §6 driver scripts that orchestrate these building blocks across an entire baseline sweep (e.g., the `K\!\in\!\{8,16,24,32\}` table of §6.1, the \(\lambda\) sweep of §6.5, and the four-source benchmark of §6.6) are scheduled to be released alongside the camera-ready paper.
+
+## Minimal Review Run
+
+```bash
+bash scripts/run_tiny.sh
+```
+
+This validates the Blender-indoor-style metadata format, greedy selection loop, render-output contract, coverage metric, oracle-gap script, and quality audit script — end-to-end without any private scene assets.
+
+## Blender-Indoor Full Run
+
+```bash
+DRY_RUN=1 \
+BLENDER=/path/to/blender \
+INPUT_DIR=/path/to/blend_scenes \
+OUTPUT_ROOT=outputs/blender_indoor \
+bash scripts/run_blender_indoor.sh
+```
+
+After confirming the detected scene list, remove `DRY_RUN=1`:
+
+```bash
+BLENDER=/path/to/blender \
+INPUT_DIR=/path/to/blend_scenes \
+OUTPUT_ROOT=outputs/blender_indoor \
+NUM_FRAMES=30 \
+RESOLUTION=2048,1024 \
+GRID_SPACING=0.5 \
+bash scripts/run_blender_indoor.sh
+```
+
+## Metric Scripts
+
+The native Blender-indoor pipeline emits `selected_frames.json` under each scene output directory. Summarize a completed run with:
+
+```bash
+python3 scripts/summarize_blender_indoor_run.py \
+  --output-root outputs/blender_indoor \
+  --output outputs/blender_indoor/results/coverage_main.csv
+```
+
+If you have consolidated candidate and selection metadata into the normalized JSONL/JSON contract used by the smoke test, use:
+
+```bash
+python3 scripts/evaluate_coverage.py \
+  --candidates outputs/blender_indoor/metadata/candidates.jsonl \
+  --selected outputs/blender_indoor/metadata/selected_viewpoints.json \
+  --output outputs/blender_indoor/results/coverage_main.csv
+
+python3 scripts/evaluate_oracle_gap.py \
+  --candidates outputs/blender_indoor/metadata/candidates.jsonl \
+  --selected outputs/blender_indoor/metadata/selected_viewpoints.json \
+  --output outputs/blender_indoor/results/oracle_validation.csv
+
+python3 scripts/audit_quality.py \
+  --render-dir outputs/blender_indoor/renders \
+  --metadata outputs/blender_indoor/metadata/selected_viewpoints.json \
+  --output outputs/blender_indoor/results/audit_50_frames.csv
+```
+
+The exact dataset paths should be adapted to the local machine. Do not commit generated data, logs, checkpoints, third-party repositories, or scene assets to the anonymous code repository.

SHA256SUMS

@@ -0,0 +1,60 @@
+7c9e65d5cbe4069429eeb1b091992bb662d402f05fcc6689010af6d40a4b2170  .gitignore
+56bad452228b39e39bc3b441c1451eae2e314a6e9b025063beb1a9475c93ade8  CITATION.cff
+f6afa50672dccfb3c42c2468e6bbd6430bf3dd63a2a945ef356c82871b8b56b3  GITHUB_UPLOAD.md
+2c14d7ac4ef207357073eabef1bc7f65853ab248237550a5542a59ba677f8ade  LICENSE
+53f3e568310533e684abb1260e61a3102e1361d7cf4cabb0cc6047c311deb31c  README.md
+efb670c7a9eef10060a1d50f36be3670402e20716f1c01d7ed70964ae1879e14  README_REPRODUCE.md
+4cd137b698a2087a9d3a57c848a5484154324eb79139dfdd523a84b29b34eadd  SUBMISSION_CHECKLIST.md
+a195a9cdf86c7c2d23d5259fa0cb3cc75dd327411be3b3f5d78f227f36ad4a8c  configs/base_erpt.yaml
+0086890995745e230a23ef766795af44e5cd633f792d9e9386594d6b1a339586  configs/blender_indoor.yaml
+3147f7c85a712e6f02f17330640ecb8c6bda0ff5b9994f22e90f95a53633adfb  configs/blender_outdoor.yaml
+4e03f04feaee0a3d0d355e6a260c93d0d0ecd44e3b58b7ee6c23a710fcefcfd9  configs/default.yaml
+93ddb9458d7caaa9898df553a1a9f756b5fca0cdc6514edff226b13176c0577e  configs/hm3d.yaml
+00cd245e4e590b8f7f649cfa87170099d758c0f166970755270b2f752a478666  configs/scannetpp.yaml
+f41e12d62f7dc5f0fa6259d8d35dfc8ea20f2fdd94e1bed3dcbbe07ae856dd48  configs/tiny.yaml
+9b3d00ec613ce18b4eeadbc9af0053251e074c61e8937062d79442fe9282b48f  core/__init__.py
+3fad91fe28ebd11a98178179622a2cee9ad2dfb0f057ae62eae5f3821f0e985e  core/coordinate.py
+06b214daacd64b0de9747abc2d50d0318ac7ce122f315d48c5e05d891a78d221  core/depth_estimation.py
+31fbacffa8b2b0aa40eddfea6d7ba53c28137d9ee6ad91298771f66c98e8cf73  core/depth_fusion.py
+ee596d36829271f164a4e1d6a297aaa42ef8eaaa0339d3b4b14f3b9089b084c7  core/erp_projection.py
+f714d3d887b142cb63f0c1fc23dde0949b1e179330964edb6216bc06d5d318ab  core/erp_warp.py
+a8a1ba38ffde69fd0c07f653fc388dc9fc53eb5aa2b95a3ed58d54848714e03e  core/tangent_extraction.py
+21e7c6c68fd31d5c63f6cb9f949e38adf78a5660f83650481afccc418b9390ab  data/README.md
+e5261ad1221380fad1174aeb931355679f419f8bfa8266f3bff06d9b2b917f75  dataset_metadata/croissant.json
+c9e7127fc7c6de554516ee219e8aeaa2fca1b00951099d973c7e8af8db32ea95  environment.yml
+4b6766691ae074a066ed06919cc372a2849b435e372e6a24849154d0b09c1195  examples/metadata/candidates.jsonl
+71c290335857fd7b4a53e507bc94fa6e6c20d1fbdc768fed0e9de20e11229e65  examples/tiny_blender_scene/README.md
+ae204fa937a7a427e8bc06fe204ecc16e26eba191a0187b98e6ed20e0a9d7ace  metadata_examples/candidates.schema.json
+6839cf7fd0bf08de9006ae76b007843fd6ceb997a83a7e632b0b051f903ce789  metadata_examples/per_step_log.schema.json
+23832a8e7d3b0b7e52d0beb7d71f45c210b558d336f7e48bf6b81fbb3a1d8388  metadata_examples/selected_viewpoints.schema.json
+bddf800be3a0e5046fdf8a5435733d19199e16d63df25a2ba62de9c1c50f46ba  pipelines/get_blend_bounds.py
+4de927c2825256599466766e323d3530eb10b55ea9b618953660bbff9b8ee4d1  pipelines/render_erp_blender.py
+7313dc7cd2fb4a03b9fdfe19503511ac7551a2c231a2e83f66b02fcbdcd55798  pipelines/run_blend_pipeline.py
+eff64bfb9b1a5d8fa4add9fa7e006b750c3c029220c9ea3cb2e39f735c92a9a6  pipelines/run_full_pipeline.py
+1008e53f357b0cb3126139b682ceede7d329b6e3dfa2f178b4cf62d7eda591f9  pipelines/run_hm3d_pipeline.py
+0e72c1081ff0f541a552731d7e86eda3380f652e8866f6bb612f64ba8c57cd5b  pipelines/run_pipeline.py
+8c03c3f667f9ee1466d1c183359bf9a4d182473675d07515f8dfcbecfca39928  pipelines/run_ply_pipeline.py
+b853a2be65e05a38435cadda54c29926a5c8d6c9a96b68752478a24bda42ca76  requirements.txt
+72dbcd63d46db055eaf12d5afc7a5bdd402833ef03c886db570d47fde476efdf  results/README.md
+dd7ed0dc4e17143b0cb2be9269035cc67a6f0d2292992426d4362091143c14f3  scripts/_common.py
+3c41a31d1723ce8bcba2a619ee79ee986ddb51e368664c073b97359feda45b48  scripts/audit_quality.py
+d6fbe64e1cf56d7e3d487e108207e47797cbc1e17b2063786b965674e4d831fa  scripts/build_candidates.py
+9c7cff2bbfaaf0bb52d8ed9b604f3a7167885d1e514a3ab6469f3909f5d1a7e5  scripts/check_anonymity.sh
+d52befd9b56357de17dbe33ef840a352d6152695319a9446dc5c71bfca6d70f6  scripts/evaluate_coverage.py
+bd2c6c8fb8869ca34608254c2719b9484a9817628e82e3802b0d4efd13d5c568  scripts/evaluate_oracle_gap.py
+21adb3f4cde65b77387873555f16df4a8b260bc0901bc555a2eab9b7db85930c  scripts/render_selected.py
+e9392972fb7937bc42c493cb18b96bba4f5bf2cad207e07bf30750083e9bd710  scripts/run_blender_indoor.sh
+54f6a5af30881ac32f867a8d22437c999f390871cb162319d79e77e2d96b1e4f  scripts/run_tiny.sh
+00c330c04a8ca40e30251efccda7e716ae3a8876056a5688d34279c0fb02029f  scripts/select_views.py
+90a20ddfd55c434dd9df4496dd757f00ccfd18f76c24affd6b3fe67e466df1a3  scripts/selection_metrics.py
+8ce9e1d8d99ab19b899eae3abfcd345cfb2405ede6541db97884526a3e8173c6  scripts/summarize_blender_indoor_run.py
+a03153d20d38fb6805aaa980b659c1964d312f209605fbdbd692ef3b3db44232  scripts/summarize_quality_audit.py
+e4cfbffc9ce620f47f977aa6a4cc78f546125ac33189948f5da8a41ac3bf5690  third_party/README.md
+e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  tools/__init__.py
+043e8fc09641621a207543857f621195b9365e2da9ce9d8f6cfd6517cdcd99d9  tools/make_sha256sums.sh
+1f28cb01c320379ce4138842f848fdcae2db224b805942d0e17c20d132c74609  tools/navmesh_utils.py
+08dc49bc2f8bf272274625235f7a9eeec99f94bb3e011778731cc87f28157552  tools/semantic_utils.py
+80b87f28df042b2789fd650aec2bbf97a29b6d3a20bb2b13b7dba3c64ec8e06a  tools/update_croissant_with_real_hashes.py
+1a930f2a701e468558e3953ca94c744c68747b7a0e25fe92c736a80b2876839e  utils/__init__.py
+4c06aec86567d13a8bb54a3fcb9e4826c57635fbc04c3ae49e3f9c43202cf88d  utils/io_utils.py
+6a6b8e7e61b3cad791e6337c2247a9986416250bd4a3ee2eaf2a5c42a9e0215d  utils/pose_utils.py

SUBMISSION_CHECKLIST.md

@@ -0,0 +1,29 @@
+# Code Submission Checklist
+
+Use this checklist before pasting the Code URL into OpenReview.
+
+| Requirement | Status | Where to Check |
+| --- | --- | --- |
+| Anonymous repository content | Ready | `bash scripts/check_anonymity.sh` |
+| Executable smoke test | Ready | `bash scripts/run_tiny.sh` |
+| Primary Blender-indoor entry point | Ready | `scripts/run_blender_indoor.sh` |
+| Native Blender-indoor result summarizer | Ready | `scripts/summarize_blender_indoor_run.py` |
+| Per-stage evaluation building blocks | Ready | `scripts/evaluate_coverage.py`, `scripts/evaluate_oracle_gap.py`, `scripts/audit_quality.py` |
+| Clear README | Ready | `README.md` |
+| Reproducibility guide | Ready | `README_REPRODUCE.md` |
+| Environment specification | Ready | `environment.yml`, `requirements.txt` |
+| Dataset paths excluded | Ready | `.gitignore`, `data/README.md` |
+| Third-party checkpoints excluded | Ready | `.gitignore`, `third_party/README.md` |
+| License included | Ready | `LICENSE` |
+| Metadata schemas included | Ready | `metadata_examples/` |
+| Generated outputs excluded before upload | Check manually | `find . -maxdepth 2 -type d -name outputs` |
+
+Recommended final commands:
+
+```bash
+bash scripts/run_tiny.sh
+rm -rf outputs
+bash scripts/check_anonymity.sh
+```
+
+Then upload the repository or zip archive.

configs/base_erpt.yaml

@@ -0,0 +1,142 @@
+# =============================================================================
+# ERPT Pipeline Configuration（移植自原版 ERPT）
+# 严格遵循 ERPT_native 坐标系约定：右手系 [X右, Y上, Z前]
+# =============================================================================
+
+# --- 数据路径 ---
+data:
+  data_dir: "inputs"
+  output_dir: "outputs"
+  depth_dir: null                    # 可选：外部深度目录
+
+# --- ERP 参数 ---
+erp:
+  auto_size: true                    # 自动从图像检测尺寸
+  width: 4096                        # 参考宽度
+  height: 2048                       # 参考高度
+
+# --- Tangent 切片参数（原版配置） ---
+tangent:
+  scheme: "icosahedron"
+  num_faces: 20
+  add_poles: true
+  face_resolution: 768               # 每个 face 的分辨率（像素）
+  fov_deg: 90.0                      # 普通 face 的基础 FOV（度）
+  padding_factor: 1.3                # 有效 FOV = 90 * 1.3 = 117°
+  pole_fov_deg: 160.0                # 极区切片使用更大 FOV
+  pole_resolution: 768               # 极区分辨率
+  pole_extra_rings: 2                # 额外极区密采样环数
+  seam_wrap: true
+
+# --- Depth Pro 参数（原版配置） ---
+depth_pro:
+  enabled: true
+  repo_dir: "third_party/ml-depth-pro"
+  checkpoint_path: "third_party/ml-depth-pro/checkpoints/depth_pro.pt"
+  precision: "fp16"                  # "fp32" | "fp16" | "bf16"
+  depth_def: "z"                     # "z" (z-depth) | "ray" (ray-depth)
+  pass_f_px: true                    # 传递已知焦距
+
+# --- 深度融合参数（原版配置） ---
+fusion:
+  blend_mode: "multiband"            # "softmin_invdepth" | "multiband"
+  output_scale: 1.10                 # 全局尺度校正
+
+  # 权重模式
+  weight_mode: "cosine"
+  k: 4                               # cosine 权重指数
+
+  # 深度竞争
+  depth_competition: "softmin_invdepth"
+  softmin_alpha: 10.0
+
+  # 极区处理
+  pole_boost: false
+  pole_boost_factor: 1.5
+  pole_latitude_deg: 75.0
+  pole_ramp_deg: 10.0
+
+  pole_ring:
+    enabled: false
+    min_latitude_deg: 60.0
+    ramp_deg: 10.0
+
+  face_pole_suppress:
+    enabled: false
+    min_latitude_deg: 70.0
+    ramp_deg: 10.0
+    min_scale: 0.4
+
+  # 极区一致性校正
+  pole_consistency:
+    enabled: true
+    min_latitude_deg: 60.0
+    min_overlap_pixels: 4000
+    max_abs_log_shift: 0.7
+    ref_slice_types: ["face", "pole_ring"]
+    target_slice_types: ["pole_north", "pole_south"]
+
+  # Z-buffer 门限
+  project_zbuffer_eps_abs_m: 0.02
+  project_zbuffer_eps_rel: 0.02
+
+  # Multiband 金字塔
+  multiband:
+    levels: 6
+    highfreq_levels: 2
+    eps: 1.0e-6
+
+  # 有效性
+  min_weight_sum: 1.0e-6
+
+# --- Warp 参数（原版配置） ---
+warp:
+  enabled: true
+  center_frame: 0
+  target_frames: "auto"              # "auto" 自动识别所有非中心帧；或指定列表如 [1, 2, 3]
+
+  # Splatting 方法
+  method: "softmax_splatting"        # "softmax_splatting" | "zbuffer_splatting" | "zbuffer_point"
+  alpha: 2.0                         # softmax 温度
+
+  # 自适应 Splat 半径
+  splat_radius_px: 1.5               # 基础半径
+  radius_min_px: 0.6                 # 半径下限
+  radius_max_px: 2.2                 # 中纬度上限
+  radius_max_pole_px: 3.4            # 极区上限
+  pole_radius_scale: 3.0             # 极区放大因子
+  pole_lat_threshold: 60.0           # 极区纬度阈值（度）
+  depth_radius_scale: false          # 深度缩放
+  depth_ref_m: 2.0                   # 深度参考值
+  depth_scale_factor: 1.0            # 深度已在 fusion.output_scale 烘焙
+  depth_edge_aware: true             # 深度边缘感知
+  depth_edge_threshold: 0.3          # 深度梯度阈值
+  depth_edge_min_scale: 0.12         # 边缘处最小半径缩放
+
+  # 遮挡门控
+  occlusion_gate:
+    enabled: true
+    abs_eps_m: 0.05
+    rel_eps: 0.05
+
+  # Z-buffer 参数
+  zbuffer_eps_abs_m: 0.03
+  zbuffer_eps_rel: 0.03
+  zbuffer_min_weight: 0.001
+
+  # 空洞填充
+  hole_fill_enabled: false
+  max_hole_px: 16
+
+  # 有效性
+  min_weight_sum: 1.0e-4
+  min_hit_sum: 1.0e-6
+
+  # 输出控制
+  output_flow: true
+  output_depth: true
+
+# --- 运行参数 ---
+run:
+  device: "cuda"
+  save_intermediates: true

configs/blender_indoor.yaml

@@ -0,0 +1,17 @@
+experiment:
+  source: blender_indoor
+  input_kind: blend
+
+pipeline:
+  blender: /path/to/blender
+  input_dir: data/blender_indoor
+  output_root: outputs/blender_indoor
+  num_frames: 30
+  resolution: "2048,1024"
+  grid_spacing: 0.5
+  camera_height: null
+  min_frames: 5
+  stop_gain: 0.08
+  stop_score: -0.3
+  stop_delta: 0.08
+

configs/blender_outdoor.yaml

@@ -0,0 +1,17 @@
+experiment:
+  source: blender_outdoor
+  input_kind: glb
+
+pipeline:
+  blender: /path/to/blender
+  input_dir: data/blender_outdoor
+  output_root: outputs/blender_outdoor
+  num_frames: 30
+  resolution: "2048,1024"
+  grid_spacing: 1.0
+  camera_height: null
+  min_frames: 5
+  stop_gain: 0.08
+  stop_score: -0.3
+  stop_delta: 0.08
+

configs/default.yaml

@@ -0,0 +1,22 @@
+# Default review configuration.
+# The anonymous release is organized around the Blender-indoor path.
+
+experiment:
+  source: blender_indoor
+  input_kind: blend
+  review_path: primary
+
+pipeline:
+  blender: /path/to/blender
+  input_dir: data/blender_indoor
+  output_root: outputs/blender_indoor
+  num_frames: 30
+  resolution: "2048,1024"
+  grid_spacing: 0.5
+  camera_height: null
+  min_frames: 5
+  stop_gain: 0.08
+  stop_score: -0.3
+  stop_delta: 0.08
+  rotation_type: random_yaw
+

configs/hm3d.yaml

@@ -0,0 +1,17 @@
+experiment:
+  source: hm3d
+  input_kind: glb
+
+pipeline:
+  blender: /path/to/blender
+  input_dir: data/hm3d
+  output_root: outputs/hm3d
+  num_frames: 30
+  resolution: "2048,1024"
+  grid_spacing: 0.5
+  camera_height: null
+  min_frames: 5
+  stop_gain: 0.08
+  stop_score: -0.3
+  stop_delta: 0.08
+

configs/scannetpp.yaml

@@ -0,0 +1,17 @@
+experiment:
+  source: scannetpp
+  input_kind: ply
+
+pipeline:
+  input_dir: data/scannetpp
+  output_root: outputs/scannetpp
+  num_frames: 30
+  resolution: "2048,1024"
+  grid_spacing: 0.5
+  point_size: 2.0
+  z_up: true
+  min_frames: 5
+  stop_gain: 0.08
+  stop_score: -0.3
+  stop_delta: 0.08
+

configs/tiny.yaml

@@ -0,0 +1,15 @@
+experiment:
+  name: blender_indoor_tiny_smoke_test
+  mode: blender_indoor_tiny
+  random_seed: 2026
+
+selection:
+  budget: 4
+  lambda_conflict: 0.35
+  min_gain: 0.01
+
+outputs:
+  root: outputs/tiny
+  metadata_dir: outputs/tiny/metadata
+  render_dir: outputs/tiny/renders
+  result_dir: outputs/tiny/results

core/__init__.py

@@ -0,0 +1,35 @@
+"""
+ERPT Core 模块
+
+包含：
+- tangent_extraction: ERP -> Tangent 切片生成
+- depth_estimation: Depth Pro 深度估计
+- depth_fusion: Tangent Depth -> ERP Depth 融合
+- coordinate: 坐标系定义（锁定）
+- erp_projection: ERP 投影（锁定）
+"""
+from .tangent_extraction import (
+    TangentSlice,
+    build_icosahedron_slices,
+    extract_all_tangents,
+    extract_tangent_from_erp,
+    compute_coverage_mask,
+    compute_ray_directions_for_slice,
+)
+
+from .depth_estimation import (
+    DepthEstimator,
+    estimate_all_tangent_depths,
+)
+
+from .depth_fusion import (
+    fuse_tangent_depths_to_erp,
+    visualize_depth,
+    save_depth_visualization,
+)
+
+from .erp_warp import (
+    WarpResult,
+    warp_erp_to_target,
+    create_comparison_image,
+)

core/coordinate.py

@@ -0,0 +1,191 @@
+"""
+坐标系约定和四元数工具
+
+ERPT_native 坐标系标准：
+- 世界坐标系：右手系 [X右, Y上, Z前]
+- 满足：X × Y = Z（右手法则）
+- ERP投影约定：
+  - lon = atan2(x, z)：经度，范围 [-π, π]
+  - lat = asin(y)：纬度，范围 [-π/2, π/2]
+  - 图像中心（u=W/2, v=H/2）看向 +Z 方向
+  - 图像顶部是 +Y 方向（上）
+
+位姿格式：
+- position: [x, y, z]，相机中心在世界坐标系的位置（米）
+- rotation_quaternion: [w, x, y, z]，表示 camera->world 旋转 (R_cw)
+
+数学约定：
+- P_world = R_cw @ P_cam + t（相机坐标系到世界坐标系）
+- P_cam = R_wc @ (P_world - t)（世界坐标系到相机坐标系）
+- R_wc = R_cw^T
+"""
+
+import numpy as np
+from typing import Tuple
+
+
+def quat_wxyz_to_rotation_matrix(q: np.ndarray) -> np.ndarray:
+    """
+    四元数转旋转矩阵
+    
+    输入四元数表示 camera->world 旋转 (R_cw)
+    
+    Args:
+        q: (4,) 四元数 [w, x, y, z]，需归一化
+        
+    Returns:
+        R: (3, 3) 旋转矩阵 R_cw
+    """
+    q = np.asarray(q, dtype=np.float64).flatten()
+    assert q.shape == (4,), f"Expected shape (4,), got {q.shape}"
+    
+    # 归一化
+    norm = np.linalg.norm(q)
+    if norm < 1e-9:
+        raise ValueError(f"Quaternion norm too small: {norm}")
+    q = q / norm
+    
+    w, x, y, z = q[0], q[1], q[2], q[3]
+    
+    # 旋转矩阵公式
+    R = np.array([
+        [1 - 2*(y*y + z*z), 2*(x*y - w*z),     2*(x*z + w*y)],
+        [2*(x*y + w*z),     1 - 2*(x*x + z*z), 2*(y*z - w*x)],
+        [2*(x*z - w*y),     2*(y*z + w*x),     1 - 2*(x*x + y*y)]
+    ], dtype=np.float64)
+    
+    return R
+
+
+def rotation_matrix_to_quat_wxyz(R: np.ndarray) -> np.ndarray:
+    """
+    旋转矩阵转四元数
+    
+    Args:
+        R: (3, 3) 旋转矩阵
+        
+    Returns:
+        q: (4,) 四元数 [w, x, y, z]
+    """
+    R = np.asarray(R, dtype=np.float64).reshape(3, 3)
+    
+    # 确保正交性（SVD正交化）
+    U, _, Vt = np.linalg.svd(R)
+    R = U @ Vt
+    if np.linalg.det(R) < 0:
+        U[:, -1] *= -1
+        R = U @ Vt
+    
+    # Shepperd's method
+    trace = np.trace(R)
+    
+    if trace > 0:
+        s = 2.0 * np.sqrt(trace + 1.0)
+        w = 0.25 * s
+        x = (R[2, 1] - R[1, 2]) / s
+        y = (R[0, 2] - R[2, 0]) / s
+        z = (R[1, 0] - R[0, 1]) / s
+    elif R[0, 0] > R[1, 1] and R[0, 0] > R[2, 2]:
+        s = 2.0 * np.sqrt(1.0 + R[0, 0] - R[1, 1] - R[2, 2])
+        w = (R[2, 1] - R[1, 2]) / s
+        x = 0.25 * s
+        y = (R[0, 1] + R[1, 0]) / s
+        z = (R[0, 2] + R[2, 0]) / s
+    elif R[1, 1] > R[2, 2]:
+        s = 2.0 * np.sqrt(1.0 + R[1, 1] - R[0, 0] - R[2, 2])
+        w = (R[0, 2] - R[2, 0]) / s
+        x = (R[0, 1] + R[1, 0]) / s
+        y = 0.25 * s
+        z = (R[1, 2] + R[2, 1]) / s
+    else:
+        s = 2.0 * np.sqrt(1.0 + R[2, 2] - R[0, 0] - R[1, 1])
+        w = (R[1, 0] - R[0, 1]) / s
+        x = (R[0, 2] + R[2, 0]) / s
+        y = (R[1, 2] + R[2, 1]) / s
+        z = 0.25 * s
+    
+    q = np.array([w, x, y, z], dtype=np.float64)
+    
+    # 归一化
+    q = q / np.linalg.norm(q)
+    
+    # 确保 w >= 0（唯一性）
+    if q[0] < 0:
+        q = -q
+    
+    return q
+
+
+def R_cw_to_R_wc(R_cw: np.ndarray) -> np.ndarray:
+    """
+    camera->world 旋转矩阵转换为 world->camera
+    
+    R_wc = R_cw^T
+    
+    Args:
+        R_cw: (3, 3) camera->world 旋转矩阵
+        
+    Returns:
+        R_wc: (3, 3) world->camera 旋转矩阵
+    """
+    return R_cw.T
+
+
+def R_wc_to_R_cw(R_wc: np.ndarray) -> np.ndarray:
+    """
+    world->camera 旋转矩阵转换为 camera->world
+    
+    R_cw = R_wc^T
+    
+    Args:
+        R_wc: (3, 3) world->camera 旋转矩阵
+        
+    Returns:
+        R_cw: (3, 3) camera->world 旋转矩阵
+    """
+    return R_wc.T
+
+
+def validate_rotation_matrix(R: np.ndarray, tol: float = 1e-5) -> Tuple[bool, str]:
+    """
+    验证旋转矩阵的有效性
+    
+    Args:
+        R: (3, 3) 待验证的矩阵
+        tol: 容差
+        
+    Returns:
+        (is_valid, message)
+    """
+    R = np.asarray(R, dtype=np.float64).reshape(3, 3)
+    
+    # 检查正交性：R^T @ R = I
+    I = R.T @ R
+    orth_err = np.max(np.abs(I - np.eye(3)))
+    if orth_err > tol:
+        return False, f"Orthogonality error: {orth_err:.6e} > {tol}"
+    
+    # 检查行列式：det(R) = +1
+    det = np.linalg.det(R)
+    if np.abs(det - 1.0) > tol:
+        return False, f"Determinant error: det(R)={det:.6f}, expected 1.0"
+    
+    return True, "Valid rotation matrix"
+
+
+def orthonormalize_rotation(R: np.ndarray) -> np.ndarray:
+    """
+    使用SVD正交化旋转矩阵
+    
+    Args:
+        R: (3, 3) 近似旋转矩阵
+        
+    Returns:
+        R_orth: (3, 3) 正交化后的旋转矩阵
+    """
+    U, _, Vt = np.linalg.svd(R)
+    R_orth = U @ Vt
+    if np.linalg.det(R_orth) < 0:
+        U[:, -1] *= -1
+        R_orth = U @ Vt
+    return R_orth

core/depth_estimation.py

@@ -0,0 +1,185 @@
+"""
+Depth Pro Wrapper（移植自原版 ERPT）
+
+封装 Apple Depth Pro 单目深度估计模型。
+
+API 使用说明:
+    1. 使用 depth_pro.create_model_and_transforms() 创建模型和预处理 transforms
+    2. 输入 RGB 图像 (PIL Image 或 numpy array)
+    3. 调用 model.infer(image, f_px=focal_length) 得到深度
+    4. 输出 depth 单位为米 (m)
+
+深度定义:
+    - Depth Pro 输出的是透视相机的 z-depth (沿相机前向轴的深度)
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+import torch
+from PIL import Image
+
+from .tangent_extraction import TangentSlice
+
+# 模型缓存，避免重复加载
+_MODEL_CACHE: Dict[str, Tuple[torch.nn.Module, Any]] = {}
+
+
+def _get_precision(cfg: Dict[str, Any]) -> torch.dtype:
+    """获取计算精度"""
+    prec = cfg.get("depth_pro", {}).get("precision", "fp16")
+    if prec == "fp16":
+        return torch.float16
+    elif prec == "bf16":
+        return torch.bfloat16
+    return torch.float32
+
+
+def _load_depthpro_model(
+    cfg: Dict[str, Any],
+    device: torch.device,
+) -> Tuple[torch.nn.Module, Any]:
+    """
+    加载 Depth Pro 模型和 transforms
+
+    Depth Pro 默认从 ./checkpoints/depth_pro.pt 加载权重，
+    因此需要切换到 repo 目录加载模型。
+    """
+    dcfg = cfg.get("depth_pro", {})
+
+    # 获取 Depth Pro 仓库目录
+    repo_dir = Path(dcfg.get("repo_dir", "third_party/ml-depth-pro"))
+    if not repo_dir.is_absolute():
+        root = Path(str(cfg.get("_project_root", Path.cwd())))
+        repo_dir = root / repo_dir
+
+    checkpoint_path = repo_dir / "checkpoints" / "depth_pro.pt"
+
+    precision = _get_precision(cfg)
+    cache_key = f"{checkpoint_path}_{device}_{precision}"
+
+    if cache_key in _MODEL_CACHE:
+        return _MODEL_CACHE[cache_key]
+
+    # 添加 Depth Pro 路径到 sys.path
+    if repo_dir.exists():
+        src_path = str(repo_dir / "src")
+        if src_path not in sys.path:
+            sys.path.insert(0, src_path)
+        if str(repo_dir) not in sys.path:
+            sys.path.insert(0, str(repo_dir))
+
+    try:
+        import depth_pro
+    except ImportError as e:
+        raise RuntimeError(
+            f"Failed to import depth_pro module. "
+            f"Please ensure ml-depth-pro is installed at {repo_dir}\n"
+            f"Error: {e}"
+        ) from e
+
+    if not checkpoint_path.exists():
+        raise FileNotFoundError(
+            f"Depth Pro checkpoint not found: {checkpoint_path}\n"
+            f"Please place depth_pro.pt in {checkpoint_path.parent}"
+        )
+
+    print(f"[DepthPro] Loading model from {checkpoint_path}")
+    print(f"[DepthPro] Device: {device}, Precision: {precision}")
+
+    # 保存当前目录并切换到 repo_dir（Depth Pro 默认从 ./checkpoints 加载）
+    original_cwd = os.getcwd()
+    try:
+        os.chdir(repo_dir)
+
+        # 使用官方 API 加载模型
+        model, transform = depth_pro.create_model_and_transforms(
+            device=device,
+            precision=precision,
+        )
+
+        model.eval()
+        print(f"[DepthPro] Model loaded successfully")
+
+    finally:
+        os.chdir(original_cwd)
+
+    _MODEL_CACHE[cache_key] = (model, transform)
+    return model, transform
+
+
+class DepthEstimator:
+    """
+    Depth Pro 深度估计器封装类
+
+    提供统一的接口用于批量深度估计。
+    """
+
+    def __init__(self, cfg: Dict[str, Any], device: torch.device):
+        self.cfg = cfg
+        self.device = device
+        self.model, self.transform = _load_depthpro_model(cfg, device)
+        self.pass_f_px = bool(cfg.get("depth_pro", {}).get("pass_f_px", True))
+
+    @torch.no_grad()
+    def predict_single(self, rgb: np.ndarray, f_px: Optional[float] = None) -> np.ndarray:
+        """
+        单张图像深度预测
+
+        Args:
+            rgb: (H, W, 3) uint8 numpy array
+            f_px: 可选的 focal length (像素)
+
+        Returns:
+            (H, W) float32 numpy array, 单位米
+        """
+        pil_img = Image.fromarray(rgb.astype(np.uint8))
+        img_tensor = self.transform(pil_img)
+
+        f_px_tensor = None
+        if f_px is not None and self.pass_f_px:
+            f_px_tensor = torch.tensor([f_px], device=self.device)
+
+        prediction = self.model.infer(img_tensor, f_px=f_px_tensor)
+        return prediction["depth"].detach().cpu().float().numpy().astype(np.float32)
+
+
+def estimate_all_tangent_depths(
+    tangent_rgbs: Dict[str, np.ndarray],
+    slices: List[TangentSlice],
+    cfg: Dict[str, Any],
+    device: torch.device,
+) -> Dict[str, np.ndarray]:
+    """
+    对所有切片估计深度
+
+    Args:
+        tangent_rgbs: {slice_id: rgb_array} 字典
+        slices: 切片规格列表
+        cfg: 配置字典
+        device: 计算设备
+
+    Returns:
+        tangent_depths: {slice_id: depth_array} 字典
+    """
+    estimator = DepthEstimator(cfg, device)
+
+    # 建立 slice_id -> f_px 映射
+    f_px_map = {s.slice_id: s.f_px for s in slices}
+
+    results = {}
+    total = len(tangent_rgbs)
+
+    for i, (slice_id, rgb) in enumerate(tangent_rgbs.items()):
+        f_px = f_px_map.get(slice_id)
+        depth = estimator.predict_single(rgb, f_px=f_px)
+        results[slice_id] = depth
+
+        print(f"  [{i+1}/{total}] {slice_id}: "
+              f"depth range [{depth.min():.2f}, {depth.max():.2f}] m")
+
+    return results

core/depth_fusion.py

@@ -0,0 +1,769 @@
+"""
+Tangent Depth -> ERP Depth 融合模块（完整移植自原版 ERPT）
+
+核心功能：
+1. 将每个切片的深度回投影到 ERP
+2. 使用 cosine 权重实现平滑融合（无块状边界）
+3. 使用 softmin(1/depth) 处理重叠区深度竞争
+4. 极区增强处理
+5. Multiband 金字塔融合（消除接缝）
+6. Pole consistency 极区深度对齐
+7. Z-buffer 门控投影（保持边缘锐利）
+
+关键算法：
+- Cosine 权重: w_face = max(0, dot(ray, face_center))^k
+- Depth 竞争: softmin(1/depth) 确保近处优先且平滑过渡
+- Forward splatting 将切片像素投影到 ERP
+- Multiband: Gaussian/Laplacian 金字塔融合
+
+输出：
+- depth_range: ERP range depth (float32, meters)
+- weight_sum: 权重和（用于 debug）
+- valid_mask: 有效掩码
+"""
+from __future__ import annotations
+
+import math
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+import torch
+
+from .tangent_extraction import TangentSlice
+
+
+# =============================================================================
+# 基础工具函数
+# =============================================================================
+
+def compute_cosine_weight(
+    ray_dirs: torch.Tensor,
+    face_center: torch.Tensor,
+    k: float = 4.0,
+) -> torch.Tensor:
+    """
+    计算 cosine 权重: w = max(0, dot(ray, face_center))^k
+    """
+    dots = torch.sum(ray_dirs * face_center.view(1, 1, 3), dim=-1)
+    weights = torch.clamp(dots, min=0.0) ** k
+    return weights
+
+
+def _dirs_to_erp_uv(
+    dirs_world: torch.Tensor,
+    erp_h: int,
+    erp_w: int,
+) -> Tuple[torch.Tensor, torch.Tensor]:
+    """将世界坐标方向转换为 ERP 像素坐标"""
+    x = dirs_world[..., 0]
+    y = dirs_world[..., 1]
+    z = dirs_world[..., 2]
+
+    lon = torch.atan2(x, z)
+    lat = torch.asin(torch.clamp(y, -1.0, 1.0))
+
+    u = (lon + math.pi) / (2.0 * math.pi) * float(erp_w)
+    u = torch.remainder(u, float(erp_w))
+    v = (math.pi / 2.0 - lat) / math.pi * float(erp_h - 1)
+    v = torch.clamp(v, 0.0, float(erp_h - 1))
+
+    return u, v
+
+
+# =============================================================================
+# 极区权重处理
+# =============================================================================
+
+def _apply_pole_weights(
+    slice_type: str,
+    dirs_world: torch.Tensor,
+    base_weight: torch.Tensor,
+    fusion_cfg: Dict[str, Any],
+) -> torch.Tensor:
+    """极区权重门控与增强"""
+    # pole_ring gating
+    pole_ring_cfg = fusion_cfg.get("pole_ring", {})
+    pole_ring_enabled = bool(pole_ring_cfg.get("enabled", True))
+    pole_ring_min_lat_deg = float(pole_ring_cfg.get("min_latitude_deg", 60.0))
+    pole_ring_ramp_deg = float(pole_ring_cfg.get("ramp_deg", 10.0))
+
+    if slice_type == "pole_ring":
+        if not pole_ring_enabled:
+            return torch.zeros_like(base_weight)
+        lat = torch.asin(torch.clamp(dirs_world[..., 1], -1.0, 1.0)) * (180.0 / math.pi)
+        abs_lat = torch.abs(lat)
+        ramp = torch.clamp(
+            (abs_lat - pole_ring_min_lat_deg) / max(pole_ring_ramp_deg, 1e-3),
+            min=0.0, max=1.0,
+        )
+        return base_weight * ramp
+
+    # pole caps progressive boost
+    pole_boost = bool(fusion_cfg.get("pole_boost", True))
+    pole_boost_factor = float(fusion_cfg.get("pole_boost_factor", 1.5))
+    pole_latitude_deg = float(fusion_cfg.get("pole_latitude_deg", 75.0))
+    pole_ramp_deg = float(fusion_cfg.get("pole_ramp_deg", 10.0))
+
+    if pole_boost and slice_type in ("pole_north", "pole_south"):
+        lat = torch.asin(torch.clamp(dirs_world[..., 1], -1.0, 1.0)) * (180.0 / math.pi)
+        abs_lat = torch.abs(lat)
+        ramp = torch.clamp(
+            (abs_lat - pole_latitude_deg) / max(pole_ramp_deg, 1e-3),
+            min=0.0, max=1.0,
+        )
+        mult = 1.0 + ramp * (pole_boost_factor - 1.0)
+        return base_weight * mult
+
+    # faces 在极区衰减
+    face_pole_cfg = fusion_cfg.get("face_pole_suppress", {})
+    if slice_type == "face" and bool(face_pole_cfg.get("enabled", True)):
+        min_lat = float(face_pole_cfg.get("min_latitude_deg", 70.0))
+        ramp_deg = float(face_pole_cfg.get("ramp_deg", 10.0))
+        min_scale = float(face_pole_cfg.get("min_scale", 0.4))
+        lat = torch.asin(torch.clamp(dirs_world[..., 1], -1.0, 1.0)) * (180.0 / math.pi)
+        abs_lat = torch.abs(lat)
+        t = torch.clamp((abs_lat - min_lat) / max(ramp_deg, 1e-3), 0.0, 1.0)
+        scale = 1.0 - t * (1.0 - min_scale)
+        return base_weight * scale
+
+    return base_weight
+
+
+# =============================================================================
+# Forward splatting（softmin_invdepth 模式用）
+# =============================================================================
+
+def _forward_splat(
+    erp_h: int,
+    erp_w: int,
+    u: torch.Tensor,
+    v: torch.Tensor,
+    range_depth: torch.Tensor,
+    weight: torch.Tensor,
+    accum_weighted_invdepth: torch.Tensor,
+    accum_weight: torch.Tensor,
+    depth_competition: str,
+    softmin_alpha: float,
+    pole_boost: bool,
+    pole_boost_factor: float,
+    pole_latitude_deg: float,
+) -> None:
+    """Forward splatting with bilinear interpolation"""
+    u_flat = u.reshape(-1)
+    v_flat = v.reshape(-1)
+    d_flat = range_depth.reshape(-1)
+    w_flat = weight.reshape(-1)
+
+    valid = torch.isfinite(d_flat) & (d_flat > 0.0) & torch.isfinite(w_flat) & (w_flat > 0.0)
+
+    u0 = torch.floor(u_flat).to(torch.int64)
+    v0 = torch.floor(v_flat).to(torch.int64)
+    du = (u_flat - u0.to(u_flat.dtype)).clamp(0.0, 1.0)
+    dv = (v_flat - v0.to(v_flat.dtype)).clamp(0.0, 1.0)
+
+    u0_wrap = torch.remainder(u0, erp_w)
+    u1_wrap = torch.remainder(u0 + 1, erp_w)
+    v1 = v0 + 1
+
+    w00 = (1.0 - du) * (1.0 - dv)
+    w10 = du * (1.0 - dv)
+    w01 = (1.0 - du) * dv
+    w11 = du * dv
+
+    if depth_competition == "softmin_invdepth":
+        inv_depth = 1.0 / torch.clamp(d_flat, min=1e-6)
+        value_to_splat = inv_depth
+    elif depth_competition == "softmax_negdepth":
+        exp_weight = torch.exp(-softmin_alpha * d_flat)
+        w_flat = w_flat * exp_weight
+        value_to_splat = d_flat
+    else:
+        value_to_splat = d_flat
+
+    def _add(u_idx, v_idx, bilinear_w):
+        v_ok = (v_idx >= 0) & (v_idx < erp_h)
+        m = valid & v_ok
+        u_safe = torch.where(m, u_idx, torch.zeros_like(u_idx))
+        v_safe = torch.where(m, v_idx, torch.zeros_like(v_idx))
+        idx = v_safe * erp_w + u_safe
+        final_w = torch.where(m, bilinear_w * w_flat, torch.zeros_like(bilinear_w))
+        final_val = torch.where(m, bilinear_w * w_flat * value_to_splat, torch.zeros_like(bilinear_w))
+        accum_weight.scatter_add_(0, idx, final_w)
+        accum_weighted_invdepth.scatter_add_(0, idx, final_val)
+
+    _add(u0_wrap, v0, w00)
+    _add(u1_wrap, v0, w10)
+    _add(u0_wrap, v1, w01)
+    _add(u1_wrap, v1, w11)
+
+
+# =============================================================================
+# Z-buffer 门控投影（multiband 模式用）
+# =============================================================================
+
+def _project_slice_to_erp_disp_weight_zbuffer(
+    depth_t: torch.Tensor,
+    slice_spec: TangentSlice,
+    cfg: Dict[str, Any],
+    erp_h: int,
+    erp_w: int,
+    depth_def: str,
+    k: float,
+    device: torch.device,
+) -> Tuple[torch.Tensor, torch.Tensor]:
+    """
+    将单个切片投影到 ERP，输出 disparity(1/range) 与 weight。
+    采用 per-slice z-buffer（min depth）避免同一 slice 内的边缘被平均糊掉。
+    """
+    fusion_cfg = cfg.get("fusion", {})
+    weight_mode = str(fusion_cfg.get("weight_mode", "cosine"))
+
+    res = slice_spec.resolution
+    K = slice_spec.K
+    R_cw = slice_spec.R_cw
+
+    fx, fy = float(K[0, 0]), float(K[1, 1])
+    cx, cy = float(K[0, 2]), float(K[1, 2])
+
+    xs = torch.arange(res, device=device, dtype=torch.float32)
+    ys = torch.arange(res, device=device, dtype=torch.float32)
+    yv, xv = torch.meshgrid(ys, xs, indexing="ij")
+
+    x_cam = (xv - cx) / fx
+    y_cam = -(yv - cy) / fy
+    z_cam = torch.ones_like(x_cam)
+
+    dirs_cam = torch.stack([x_cam, y_cam, z_cam], dim=-1)
+    ray_len = torch.norm(dirs_cam, dim=-1, keepdim=True).clamp(min=1e-9)
+    dirs_cam = dirs_cam / ray_len
+
+    R = torch.tensor(R_cw, device=device, dtype=torch.float32)
+    dirs_world = torch.einsum("ij,hwj->hwi", R, dirs_cam)
+
+    # range depth
+    if depth_def == "z":
+        range_depth = depth_t * ray_len.squeeze(-1)
+    else:
+        range_depth = depth_t
+
+    u, v = _dirs_to_erp_uv(dirs_world, erp_h, erp_w)
+
+    if weight_mode == "cosine":
+        face_center = torch.tensor(slice_spec.center_dir, device=device, dtype=torch.float32)
+        base_w = compute_cosine_weight(dirs_world, face_center, k=k)
+    else:
+        base_w = torch.ones_like(range_depth)
+
+    base_w = _apply_pole_weights(slice_spec.slice_type, dirs_world, base_w, fusion_cfg)
+
+    u_flat = u.reshape(-1)
+    v_flat = v.reshape(-1)
+    d_flat = range_depth.reshape(-1)
+    w_flat = base_w.reshape(-1)
+
+    valid = torch.isfinite(d_flat) & (d_flat > 0.0) & torch.isfinite(w_flat) & (w_flat > 0.0)
+
+    u0 = torch.floor(u_flat).to(torch.int64)
+    v0 = torch.floor(v_flat).to(torch.int64)
+    du = (u_flat - u0.float()).clamp(0.0, 1.0)
+    dv = (v_flat - v0.float()).clamp(0.0, 1.0)
+
+    u0w = torch.remainder(u0, erp_w)
+    u1w = torch.remainder(u0 + 1, erp_w)
+    v1 = v0 + 1
+
+    bw00 = (1.0 - du) * (1.0 - dv)
+    bw10 = du * (1.0 - dv)
+    bw01 = (1.0 - du) * dv
+    bw11 = du * dv
+
+    # Pass A: min depth
+    min_depth = torch.full((erp_h * erp_w,), float("inf"), device=device, dtype=torch.float32)
+
+    def _amin(ui, vi, bw):
+        m = valid & (vi >= 0) & (vi < erp_h)
+        ui_safe = torch.where(m, ui, torch.zeros_like(ui))
+        vi_safe = torch.where(m, vi, torch.zeros_like(vi))
+        idx = vi_safe * erp_w + ui_safe
+        cand = torch.where(m, d_flat, torch.full_like(d_flat, float("inf")))
+        min_depth.scatter_reduce_(0, idx, cand, reduce="amin", include_self=True)
+
+    _amin(u0w, v0, bw00)
+    _amin(u1w, v0, bw10)
+    _amin(u0w, v1, bw01)
+    _amin(u1w, v1, bw11)
+
+    # Pass B: accumulate disparity near min depth
+    disp_acc = torch.zeros(erp_h * erp_w, device=device, dtype=torch.float32)
+    w_acc = torch.zeros(erp_h * erp_w, device=device, dtype=torch.float32)
+
+    eps_abs = float(fusion_cfg.get("project_zbuffer_eps_abs_m", 0.02))
+    eps_rel = float(fusion_cfg.get("project_zbuffer_eps_rel", 0.02))
+
+    inv_d = 1.0 / torch.clamp(d_flat, min=1e-6)
+
+    def _acc(ui, vi, bw):
+        m = valid & (vi >= 0) & (vi < erp_h)
+        ui_safe = torch.where(m, ui, torch.zeros_like(ui))
+        vi_safe = torch.where(m, vi, torch.zeros_like(vi))
+        idx = vi_safe * erp_w + ui_safe
+        md = min_depth.gather(0, idx)
+        gate = d_flat <= (md * (1.0 + eps_rel) + eps_abs)
+        mm = m & gate
+        w_here = torch.where(mm, bw * w_flat, torch.zeros_like(bw))
+        disp_here = torch.where(mm, w_here * inv_d, torch.zeros_like(w_here))
+        w_acc.scatter_add_(0, idx, w_here)
+        disp_acc.scatter_add_(0, idx, disp_here)
+
+    _acc(u0w, v0, bw00)
+    _acc(u1w, v0, bw10)
+    _acc(u0w, v1, bw01)
+    _acc(u1w, v1, bw11)
+
+    w_map = w_acc.view(erp_h, erp_w)
+    disp_map = torch.zeros_like(w_map)
+    m = w_map > 1e-9
+    disp_map[m] = disp_acc.view(erp_h, erp_w)[m] / w_map[m]
+    return disp_map, w_map
+
+
+# =============================================================================
+# Multiband 金字塔工具
+# =============================================================================
+
+def _pad_circular_w(x: torch.Tensor, pad: int) -> torch.Tensor:
+    if pad <= 0:
+        return x
+    return torch.cat([x[..., -pad:], x, x[..., :pad]], dim=-1)
+
+
+def _gauss5_kernel(device: torch.device, dtype: torch.dtype) -> torch.Tensor:
+    k1 = torch.tensor([1.0, 4.0, 6.0, 4.0, 1.0], device=device, dtype=dtype)
+    k1 = k1 / k1.sum()
+    k2 = (k1[:, None] * k1[None, :]).view(1, 1, 5, 5)
+    return k2
+
+
+def _blur_circular_w(x: torch.Tensor, kernel: torch.Tensor) -> torch.Tensor:
+    import torch.nn.functional as F
+    pad = kernel.shape[-1] // 2
+    xw = _pad_circular_w(x, pad)
+    xwh = F.pad(xw, (0, 0, pad, pad), mode="reflect")
+    return F.conv2d(xwh, kernel)
+
+
+def _down2(x: torch.Tensor) -> torch.Tensor:
+    return x[..., ::2, ::2]
+
+
+def _upsample2_circular_w(x: torch.Tensor, out_h: int, out_w: int) -> torch.Tensor:
+    import torch.nn.functional as F
+    x3 = torch.cat([x, x, x], dim=-1)
+    y3 = F.interpolate(x3, size=(out_h, out_w * 3), mode="bilinear", align_corners=False)
+    return y3[..., out_w: 2 * out_w]
+
+
+# =============================================================================
+# 主融合函数
+# =============================================================================
+
+@torch.no_grad()
+def fuse_tangent_depths_to_erp(
+    tangent_depths: Dict[str, np.ndarray],
+    slices: List[TangentSlice],
+    cfg: Dict[str, Any],
+    device: torch.device,
+    debug_dir: Optional[Path] = None,
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """
+    将所有切片深度融合为 ERP range depth
+
+    Args:
+        tangent_depths: {slice_id: depth_array}
+        slices: 切片规格列表
+        cfg: 配置字典
+        device: 计算设备
+
+    Returns:
+        depth_range: (erp_h, erp_w) ERP range depth, float32
+        weight_sum: (erp_h, erp_w) 权重和
+        valid_mask: (erp_h, erp_w) uint8
+    """
+    erp_cfg = cfg.get("erp", {})
+    erp_h = int(erp_cfg.get("height", 1024))
+    erp_w = int(erp_cfg.get("width", 2048))
+
+    fusion_cfg = cfg.get("fusion", {})
+    blend_mode = str(fusion_cfg.get("blend_mode", "softmin_invdepth"))
+
+    if blend_mode == "multiband":
+        depth_np, weight_np, valid_np = _fuse_multiband(
+            tangent_depths, slices, cfg, device, erp_h, erp_w, debug_dir,
+        )
+    else:
+        depth_np, weight_np, valid_np = _fuse_softmin(
+            tangent_depths, slices, cfg, device, erp_h, erp_w,
+        )
+
+    # output_scale 校正
+    output_scale = float(fusion_cfg.get("output_scale", 1.0))
+    if output_scale != 1.0:
+        valid = np.isfinite(depth_np) & (depth_np > 0)
+        depth_np[valid] *= output_scale
+
+    return depth_np, weight_np, valid_np
+
+
+def _fuse_softmin(
+    tangent_depths: Dict[str, np.ndarray],
+    slices: List[TangentSlice],
+    cfg: Dict[str, Any],
+    device: torch.device,
+    erp_h: int,
+    erp_w: int,
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """softmin_invdepth 模式融合"""
+    fusion_cfg = cfg.get("fusion", {})
+    weight_mode = str(fusion_cfg.get("weight_mode", "cosine"))
+    k = float(fusion_cfg.get("k", 4.0))
+    depth_competition = str(fusion_cfg.get("depth_competition", "softmin_invdepth"))
+    softmin_alpha = float(fusion_cfg.get("softmin_alpha", 10.0))
+    min_weight_sum = float(fusion_cfg.get("min_weight_sum", 1e-6))
+    pole_boost = bool(fusion_cfg.get("pole_boost", True))
+    pole_boost_factor = float(fusion_cfg.get("pole_boost_factor", 1.5))
+    pole_latitude_deg = float(fusion_cfg.get("pole_latitude_deg", 75.0))
+    pole_ring_cfg = fusion_cfg.get("pole_ring", {})
+    pole_ring_enabled = bool(pole_ring_cfg.get("enabled", True))
+    pole_ring_min_lat_deg = float(pole_ring_cfg.get("min_latitude_deg", 60.0))
+    pole_ring_ramp_deg = float(pole_ring_cfg.get("ramp_deg", 5.0))
+    depth_def = str(cfg.get("depth_pro", {}).get("depth_def", "z"))
+
+    accum_weighted_invdepth = torch.zeros(erp_h * erp_w, device=device, dtype=torch.float32)
+    accum_weight = torch.zeros(erp_h * erp_w, device=device, dtype=torch.float32)
+
+    for s in slices:
+        if s.slice_id not in tangent_depths:
+            continue
+        depth_np = tangent_depths[s.slice_id]
+        depth_t = torch.from_numpy(depth_np.astype(np.float32)).to(device)
+
+        res = s.resolution
+        K = s.K
+        R_cw = s.R_cw
+        fx, fy = float(K[0, 0]), float(K[1, 1])
+        cx, cy = float(K[0, 2]), float(K[1, 2])
+
+        xs = torch.arange(res, device=device, dtype=torch.float32)
+        ys = torch.arange(res, device=device, dtype=torch.float32)
+        yv, xv = torch.meshgrid(ys, xs, indexing="ij")
+
+        x_cam = (xv - cx) / fx
+        y_cam = -(yv - cy) / fy
+        z_cam = torch.ones_like(x_cam)
+
+        dirs_cam = torch.stack([x_cam, y_cam, z_cam], dim=-1)
+        dirs_cam = dirs_cam / torch.clamp(torch.norm(dirs_cam, dim=-1, keepdim=True), min=1e-9)
+
+        R = torch.tensor(R_cw, device=device, dtype=torch.float32)
+        dirs_world = torch.einsum("ij,hwj->hwi", R, dirs_cam)
+
+        if depth_def == "z":
+            ray_length = torch.sqrt(x_cam ** 2 + y_cam ** 2 + 1.0)
+            range_depth = depth_t * ray_length
+        else:
+            range_depth = depth_t
+
+        u, v = _dirs_to_erp_uv(dirs_world, erp_h, erp_w)
+
+        if weight_mode == "cosine":
+            face_center = torch.tensor(s.center_dir, device=device, dtype=torch.float32)
+            base_weight = compute_cosine_weight(dirs_world, face_center, k=k)
+        else:
+            base_weight = torch.ones_like(range_depth)
+
+        if s.slice_type == "pole_ring":
+            if not pole_ring_enabled:
+                base_weight = torch.zeros_like(base_weight)
+            else:
+                lat = torch.asin(torch.clamp(dirs_world[..., 1], -1.0, 1.0)) * (180.0 / math.pi)
+                abs_lat = torch.abs(lat)
+                ramp = torch.clamp(
+                    (abs_lat - pole_ring_min_lat_deg) / max(pole_ring_ramp_deg, 1e-3),
+                    min=0.0, max=1.0,
+                )
+                base_weight = base_weight * ramp
+
+        if pole_boost and s.slice_type in ("pole_north", "pole_south"):
+            base_weight = base_weight * pole_boost_factor
+
+        _forward_splat(
+            erp_h, erp_w, u, v, range_depth, base_weight,
+            accum_weighted_invdepth, accum_weight,
+            depth_competition, softmin_alpha,
+            pole_boost, pole_boost_factor, pole_latitude_deg,
+        )
+
+    valid_mask_t = accum_weight > min_weight_sum
+
+    if depth_competition == "softmin_invdepth":
+        avg_invdepth = torch.zeros_like(accum_weighted_invdepth)
+        avg_invdepth[valid_mask_t] = accum_weighted_invdepth[valid_mask_t] / accum_weight[valid_mask_t]
+        depth_out = torch.zeros_like(avg_invdepth)
+        depth_out[valid_mask_t] = 1.0 / torch.clamp(avg_invdepth[valid_mask_t], min=1e-6)
+    else:
+        depth_out = torch.zeros_like(accum_weighted_invdepth)
+        depth_out[valid_mask_t] = accum_weighted_invdepth[valid_mask_t] / accum_weight[valid_mask_t]
+
+    depth_out[~valid_mask_t] = float("nan")
+
+    depth_out = depth_out.reshape(erp_h, erp_w)
+    weight_sum = accum_weight.reshape(erp_h, erp_w)
+    valid_mask = valid_mask_t.reshape(erp_h, erp_w)
+
+    return (
+        depth_out.cpu().numpy().astype(np.float32),
+        weight_sum.cpu().numpy().astype(np.float32),
+        valid_mask.cpu().numpy().astype(np.uint8),
+    )
+
+
+def _fuse_multiband(
+    tangent_depths: Dict[str, np.ndarray],
+    slices: List[TangentSlice],
+    cfg: Dict[str, Any],
+    device: torch.device,
+    erp_h: int,
+    erp_w: int,
+    debug_dir: Optional[Path] = None,
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Multiband 金字塔融合"""
+    fusion_cfg = cfg.get("fusion", {})
+    mb_cfg = fusion_cfg.get("multiband", {})
+    levels = int(mb_cfg.get("levels", 6))
+    highfreq_levels = int(mb_cfg.get("highfreq_levels", 2))
+    eps = float(mb_cfg.get("eps", 1e-6))
+    min_weight_sum = float(fusion_cfg.get("min_weight_sum", 1e-6))
+
+    depth_def = str(cfg.get("depth_pro", {}).get("depth_def", "z"))
+    k = float(fusion_cfg.get("k", 4.0))
+
+    # Pole consistency 配置
+    pole_cons_cfg = fusion_cfg.get("pole_consistency", {})
+    if not isinstance(pole_cons_cfg, dict):
+        pole_cons_cfg = {}
+    pole_cons_enabled = bool(pole_cons_cfg.get("enabled", False))
+    pole_cons_min_lat_deg = float(pole_cons_cfg.get("min_latitude_deg", 60.0))
+    pole_cons_min_overlap = int(pole_cons_cfg.get("min_overlap_pixels", 4000))
+    pole_cons_max_abs_log_shift = float(pole_cons_cfg.get("max_abs_log_shift", 0.7))
+    pole_cons_ref_types = [str(x) for x in pole_cons_cfg.get("ref_slice_types", ["face", "pole_ring"])]
+    pole_cons_target_types = [str(x) for x in pole_cons_cfg.get("target_slice_types", ["pole_north", "pole_south"])]
+
+    top_v_max = int(math.floor((90.0 - pole_cons_min_lat_deg) / 180.0 * float(max(erp_h - 1, 1))))
+    bot_v_min = int(math.ceil((90.0 + pole_cons_min_lat_deg) / 180.0 * float(max(erp_h - 1, 1))))
+    top_v_max = max(0, min(erp_h - 1, top_v_max))
+    bot_v_min = max(0, min(erp_h - 1, bot_v_min))
+
+    ref_num_top = ref_den_top = ref_num_bot = ref_den_bot = None
+    pole_pending: List[TangentSlice] = []
+    if pole_cons_enabled:
+        ref_num_top = torch.zeros((top_v_max + 1, erp_w), device=device, dtype=torch.float32)
+        ref_den_top = torch.zeros_like(ref_num_top)
+        ref_num_bot = torch.zeros((erp_h - bot_v_min, erp_w), device=device, dtype=torch.float32)
+        ref_den_bot = torch.zeros_like(ref_num_bot)
+
+    # Per-level accumulators
+    kernel = _gauss5_kernel(device=device, dtype=torch.float32)
+
+    Hs = [erp_h]
+    Ws = [erp_w]
+    for _ in range(1, levels):
+        Hs.append(max(1, Hs[-1] // 2))
+        Ws.append(max(1, Ws[-1] // 2))
+
+    fused_lap: List[torch.Tensor] = []
+    best_w: List[torch.Tensor] = []
+    sum_w: List[torch.Tensor] = []
+    sum_w_lap: List[torch.Tensor] = []
+
+    for l in range(levels):
+        shape = (1, 1, Hs[l], Ws[l])
+        if l < highfreq_levels:
+            fused_lap.append(torch.zeros(shape, device=device, dtype=torch.float32))
+            best_w.append(torch.zeros(shape, device=device, dtype=torch.float32))
+        else:
+            fused_lap.append(torch.zeros(shape, device=device, dtype=torch.float32))
+            sum_w.append(torch.zeros(shape, device=device, dtype=torch.float32))
+            sum_w_lap.append(torch.zeros(shape, device=device, dtype=torch.float32))
+
+    weight_sum0 = torch.zeros(erp_h, erp_w, device=device, dtype=torch.float32)
+
+    def _process_one_slice(s: TangentSlice, depth_np: np.ndarray):
+        depth_t = torch.from_numpy(depth_np.astype(np.float32)).to(device)
+
+        disp0, w0 = _project_slice_to_erp_disp_weight_zbuffer(
+            depth_t, s, cfg, erp_h, erp_w, depth_def, k, device,
+        )
+        return disp0, w0
+
+    def _blend_into_pyramid(disp0: torch.Tensor, w0: torch.Tensor):
+        nonlocal weight_sum0
+        weight_sum0 += w0
+
+        disp_pyr = [disp0.unsqueeze(0).unsqueeze(0)]
+        w_pyr = [w0.unsqueeze(0).unsqueeze(0)]
+
+        for l in range(1, levels):
+            num = _blur_circular_w(disp_pyr[l - 1] * w_pyr[l - 1], kernel)
+            den = _blur_circular_w(w_pyr[l - 1], kernel)
+            num_ds = _down2(num)
+            den_ds = _down2(den)
+            disp_ds = num_ds / torch.clamp(den_ds, min=eps)
+            disp_pyr.append(disp_ds)
+            w_pyr.append(den_ds)
+
+        lap_pyr: List[torch.Tensor] = []
+        for l in range(levels - 1):
+            up = _upsample2_circular_w(disp_pyr[l + 1], Hs[l], Ws[l])
+            lap_pyr.append(disp_pyr[l] - up)
+        lap_pyr.append(disp_pyr[-1])
+
+        for l in range(levels):
+            wl = w_pyr[l]
+            Ll = lap_pyr[l]
+            if l < highfreq_levels:
+                better = wl > best_w[l]
+                fused_lap[l] = torch.where(better, Ll, fused_lap[l])
+                best_w[l] = torch.where(better, wl, best_w[l])
+            else:
+                idx = l - highfreq_levels
+                sum_w_lap[idx] += wl * Ll
+                sum_w[idx] += wl
+
+    # Process non-pole slices first
+    for s in slices:
+        if s.slice_id not in tangent_depths:
+            continue
+        if pole_cons_enabled and (s.slice_type in pole_cons_target_types):
+            pole_pending.append(s)
+            continue
+
+        disp0, w0 = _process_one_slice(s, tangent_depths[s.slice_id])
+
+        # Reference accumulation for pole consistency
+        if pole_cons_enabled and (s.slice_type in pole_cons_ref_types):
+            if ref_num_top is not None and top_v_max >= 0:
+                ref_num_top += disp0[:top_v_max + 1] * w0[:top_v_max + 1]
+                ref_den_top += w0[:top_v_max + 1]
+            if ref_num_bot is not None and bot_v_min < erp_h:
+                ref_num_bot += disp0[bot_v_min:] * w0[bot_v_min:]
+                ref_den_bot += w0[bot_v_min:]
+
+        _blend_into_pyramid(disp0, w0)
+
+    # Pole consistency pass
+    if pole_cons_enabled and pole_pending and ref_num_top is not None:
+        ref_disp_top = ref_num_top / torch.clamp(ref_den_top, min=eps)
+        ref_disp_bot = ref_num_bot / torch.clamp(ref_den_bot, min=eps)
+
+        for s in pole_pending:
+            disp0, w0 = _process_one_slice(s, tangent_depths[s.slice_id])
+
+            try:
+                if s.slice_type == "pole_north":
+                    disp_other = disp0[:top_v_max + 1]
+                    w_other = w0[:top_v_max + 1]
+                    disp_ref = ref_disp_top
+                    den_ref = ref_den_top
+                else:
+                    disp_other = disp0[bot_v_min:]
+                    w_other = w0[bot_v_min:]
+                    disp_ref = ref_disp_bot
+                    den_ref = ref_den_bot
+
+                overlap = (w_other > 1e-9) & (den_ref > 1e-9) & (disp_other > eps) & (disp_ref > eps)
+                n_overlap = int(overlap.sum().item())
+                if n_overlap >= pole_cons_min_overlap:
+                    log_ref = -torch.log(disp_ref[overlap].clamp(min=eps))
+                    log_other = -torch.log(disp_other[overlap].clamp(min=eps))
+                    shift = float(torch.median(log_ref - log_other).item())
+                    shift = max(-pole_cons_max_abs_log_shift, min(pole_cons_max_abs_log_shift, shift))
+                    disp0 = disp0 * float(math.exp(-shift))
+            except Exception:
+                pass
+
+            _blend_into_pyramid(disp0, w0)
+
+    # Finalize lowfreq levels
+    for l in range(highfreq_levels, levels):
+        idx = l - highfreq_levels
+        fused_lap[l] = sum_w_lap[idx] / torch.clamp(sum_w[idx], min=eps)
+
+    # Reconstruct fused disparity
+    disp = fused_lap[-1]
+    for l in range(levels - 2, -1, -1):
+        disp = _upsample2_circular_w(disp, Hs[l], Ws[l]) + fused_lap[l]
+
+    disp0_fused = disp.squeeze(0).squeeze(0)
+    depth = torch.zeros_like(disp0_fused)
+    m = disp0_fused > eps
+    depth[m] = 1.0 / disp0_fused[m]
+    depth[~m] = float("nan")
+
+    weight_np = weight_sum0.detach().cpu().numpy().astype(np.float32)
+    depth_np = depth.detach().cpu().numpy().astype(np.float32)
+    valid_np = (weight_np > min_weight_sum).astype(np.uint8)
+
+    return depth_np, weight_np, valid_np
+
+
+# =============================================================================
+# 可视化函数
+# =============================================================================
+
+def visualize_depth(
+    depth: np.ndarray,
+    vmin: Optional[float] = None,
+    vmax: Optional[float] = None,
+) -> np.ndarray:
+    """
+    可视化深度图（percentile + TURBO colormap）
+
+    Returns:
+        vis: (H, W, 3) uint8 RGB
+    """
+    d = depth.astype(np.float32).copy()
+    valid = np.isfinite(d) & (d > 0)
+
+    if not np.any(valid):
+        return np.zeros((d.shape[0], d.shape[1], 3), dtype=np.uint8)
+
+    if vmin is None:
+        vmin = float(np.percentile(d[valid], 2))
+    if vmax is None:
+        vmax = float(np.percentile(d[valid], 98))
+    vmax = max(vmax, vmin + 1e-6)
+
+    d_norm = (np.clip(d, vmin, vmax) - vmin) / (vmax - vmin)
+    d_norm[~valid] = 0.0
+    d_u8 = (d_norm * 255).astype(np.uint8)
+
+    try:
+        import cv2
+        cm = cv2.applyColorMap(d_u8, cv2.COLORMAP_TURBO)
+        return cv2.cvtColor(cm, cv2.COLOR_BGR2RGB)
+    except ImportError:
+        return np.stack([d_u8, d_u8, d_u8], axis=-1)
+
+
+def save_depth_visualization(
+    depth: np.ndarray,
+    output_path: Path,
+    vmin: Optional[float] = None,
+    vmax: Optional[float] = None,
+) -> None:
+    """保存深度可视化图像"""
+    import cv2
+    vis = visualize_depth(depth, vmin=vmin, vmax=vmax)
+    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+    cv2.imwrite(str(output_path), cv2.cvtColor(vis, cv2.COLOR_RGB2BGR))

core/erp_projection.py

@@ -0,0 +1,277 @@
+"""
+ERP 投影模块
+
+ERPT_native ERP投影约定：
+- 经度：lon = atan2(x, z)，范围 [-π, π]
+- 纬度：lat = asin(y)，范围 [-π/2, π/2]
+- 像素坐标：u ∈ [0, W), v ∈ [0, H)
+- 图像中心 (u=W/2, v=H/2) 对应 (lon=0, lat=0)，看向 +Z
+- 图像顶部 (v=0) 对应 lat=+π/2，看向 +Y（上）
+- 图像底部 (v=H-1) 对应 lat=-π/2，看向 -Y（下）
+- 图像右边 lon增加，对应 +X 方向
+
+像素到经纬度映射：
+  lon = (u / W) * 2π - π
+  lat = π/2 - (v / (H-1)) * π
+
+方向向量（相机坐标系，也是世界坐标系当无旋转时）：
+  x = sin(lon) * cos(lat)   # 右
+  y = sin(lat)              # 上
+  z = cos(lon) * cos(lat)   # 前
+"""
+
+import math
+import numpy as np
+import torch
+from typing import Tuple, Union
+
+
+def erp_to_lonlat(
+    u: Union[np.ndarray, torch.Tensor],
+    v: Union[np.ndarray, torch.Tensor],
+    H: int,
+    W: int,
+) -> Tuple[Union[np.ndarray, torch.Tensor], Union[np.ndarray, torch.Tensor]]:
+    """
+    ERP像素坐标转经纬度
+    
+    Args:
+        u: 水平像素坐标，范围 [0, W)
+        v: 垂直像素坐标，范围 [0, H)
+        H: 图像高度
+        W: 图像宽度
+        
+    Returns:
+        lon: 经度，范围 [-π, π]
+        lat: 纬度，范围 [-π/2, π/2]
+    """
+    # lon = (u / W) * 2π - π
+    lon = (u / float(W)) * (2.0 * math.pi) - math.pi
+    
+    # lat = π/2 - (v / (H-1)) * π
+    lat = (math.pi / 2.0) - (v / float(H - 1)) * math.pi
+    
+    return lon, lat
+
+
+def lonlat_to_erp(
+    lon: Union[np.ndarray, torch.Tensor],
+    lat: Union[np.ndarray, torch.Tensor],
+    H: int,
+    W: int,
+) -> Tuple[Union[np.ndarray, torch.Tensor], Union[np.ndarray, torch.Tensor]]:
+    """
+    经纬度转ERP像素坐标
+    
+    Args:
+        lon: 经度，范围 [-π, π]
+        lat: 纬度，范围 [-π/2, π/2]
+        H: 图像高度
+        W: 图像宽度
+        
+    Returns:
+        u: 水平像素坐标
+        v: 垂直像素坐标
+    """
+    # u = (lon + π) / (2π) * W
+    u = (lon + math.pi) / (2.0 * math.pi) * float(W)
+    
+    # v = (π/2 - lat) / π * (H-1)
+    v = (math.pi / 2.0 - lat) / math.pi * float(H - 1)
+    
+    return u, v
+
+
+def lonlat_to_direction(
+    lon: Union[np.ndarray, torch.Tensor],
+    lat: Union[np.ndarray, torch.Tensor],
+) -> Union[np.ndarray, torch.Tensor]:
+    """
+    经纬度转方向向量（单位向量）
+    
+    坐标系：[X右, Y上, Z前]
+    
+    Args:
+        lon: 经度
+        lat: 纬度
+        
+    Returns:
+        dirs: (..., 3) 单位方向向量 [x, y, z]
+    """
+    if isinstance(lon, torch.Tensor):
+        cos_lat = torch.cos(lat)
+        x = torch.sin(lon) * cos_lat  # 右
+        y = torch.sin(lat)            # 上
+        z = torch.cos(lon) * cos_lat  # 前
+        dirs = torch.stack([x, y, z], dim=-1)
+    else:
+        cos_lat = np.cos(lat)
+        x = np.sin(lon) * cos_lat
+        y = np.sin(lat)
+        z = np.cos(lon) * cos_lat
+        dirs = np.stack([x, y, z], axis=-1)
+    
+    return dirs
+
+
+def direction_to_lonlat(
+    dirs: Union[np.ndarray, torch.Tensor],
+) -> Tuple[Union[np.ndarray, torch.Tensor], Union[np.ndarray, torch.Tensor]]:
+    """
+    方向向量转经纬度
+    
+    Args:
+        dirs: (..., 3) 方向向量 [x, y, z]
+        
+    Returns:
+        lon: 经度
+        lat: 纬度
+    """
+    x = dirs[..., 0]
+    y = dirs[..., 1]
+    z = dirs[..., 2]
+    
+    if isinstance(dirs, torch.Tensor):
+        # 归一化
+        norm = torch.norm(dirs, dim=-1, keepdim=False)
+        norm = torch.clamp(norm, min=1e-9)
+        
+        # lon = atan2(x, z)
+        lon = torch.atan2(x, z)
+        
+        # lat = asin(y / norm)
+        y_normalized = torch.clamp(y / norm, -1.0, 1.0)
+        lat = torch.asin(y_normalized)
+    else:
+        norm = np.linalg.norm(dirs, axis=-1)
+        norm = np.maximum(norm, 1e-9)
+        
+        lon = np.arctan2(x, z)
+        y_normalized = np.clip(y / norm, -1.0, 1.0)
+        lat = np.arcsin(y_normalized)
+    
+    return lon, lat
+
+
+def erp_to_direction(
+    u: Union[np.ndarray, torch.Tensor],
+    v: Union[np.ndarray, torch.Tensor],
+    H: int,
+    W: int,
+) -> Union[np.ndarray, torch.Tensor]:
+    """
+    ERP像素坐标转方向向量
+    
+    Args:
+        u: 水平像素坐标
+        v: 垂直像素坐标
+        H: 图像高度
+        W: 图像宽度
+        
+    Returns:
+        dirs: (..., 3) 单位方向向量 [x, y, z]
+    """
+    lon, lat = erp_to_lonlat(u, v, H, W)
+    return lonlat_to_direction(lon, lat)
+
+
+def direction_to_erp(
+    dirs: Union[np.ndarray, torch.Tensor],
+    H: int,
+    W: int,
+) -> Tuple[Union[np.ndarray, torch.Tensor], Union[np.ndarray, torch.Tensor]]:
+    """
+    方向向量转ERP像素坐标
+    
+    Args:
+        dirs: (..., 3) 方向向量 [x, y, z]
+        H: 图像高度
+        W: 图像宽度
+        
+    Returns:
+        u: 水平像素坐标
+        v: 垂直像素坐标
+    """
+    lon, lat = direction_to_lonlat(dirs)
+    return lonlat_to_erp(lon, lat, H, W)
+
+
+def create_erp_grid(
+    H: int,
+    W: int,
+    device: torch.device = None,
+) -> Tuple[torch.Tensor, torch.Tensor]:
+    """
+    创建ERP像素网格
+    
+    Args:
+        H: 图像高度
+        W: 图像宽度
+        device: 计算设备
+        
+    Returns:
+        uu: (H, W) 水平坐标网格
+        vv: (H, W) 垂直坐标网格
+    """
+    if device is None:
+        device = torch.device("cpu")
+    
+    us = torch.arange(W, device=device, dtype=torch.float32)
+    vs = torch.arange(H, device=device, dtype=torch.float32)
+    vv, uu = torch.meshgrid(vs, us, indexing="ij")
+    
+    return uu, vv
+
+
+def create_direction_grid(
+    H: int,
+    W: int,
+    device: torch.device = None,
+) -> torch.Tensor:
+    """
+    创建ERP方向向量网格
+    
+    Args:
+        H: 图像高度
+        W: 图像宽度
+        device: 计算设备
+        
+    Returns:
+        dirs: (H, W, 3) 单位方向向量
+    """
+    uu, vv = create_erp_grid(H, W, device)
+    return erp_to_direction(uu, vv, H, W)
+
+
+def wrap_u(u: Union[np.ndarray, torch.Tensor], W: int) -> Union[np.ndarray, torch.Tensor]:
+    """
+    水平坐标环绕处理（ERP在水平方向是周期性的）
+    
+    Args:
+        u: 水平像素坐标
+        W: 图像宽度
+        
+    Returns:
+        u_wrapped: 环绕后的坐标，范围 [0, W)
+    """
+    if isinstance(u, torch.Tensor):
+        return torch.remainder(u, float(W))
+    else:
+        return np.mod(u, float(W))
+
+
+def clamp_v(v: Union[np.ndarray, torch.Tensor], H: int) -> Union[np.ndarray, torch.Tensor]:
+    """
+    垂直坐标裁剪处理
+    
+    Args:
+        v: 垂直像素坐标
+        H: 图像高度
+        
+    Returns:
+        v_clamped: 裁剪后的坐标，范围 [0, H-1]
+    """
+    if isinstance(v, torch.Tensor):
+        return torch.clamp(v, 0.0, float(H - 1))
+    else:
+        return np.clip(v, 0.0, float(H - 1))

core/erp_warp.py

@@ -0,0 +1,591 @@
+"""
+ERP Forward Warp 模块（移植自原版 ERPT erp_softsplat.py）
+
+使用锁定的投影/坐标系接口：
+- core.erp_projection: erp_to_direction, direction_to_erp, wrap_u, clamp_v
+- utils.pose_utils: Pose (R_cw, R_wc, position)
+
+算法流程：
+1. 对每个 src ERP 像素，通过 erp_to_direction 获取射线方向
+2. 根据深度计算 3D 点，变换到目标相机坐标系
+3. 通过 direction_to_erp 投影到目标 ERP
+4. Forward splatting 累积 RGB（softmax / zbuffer / point）
+
+支持的 splatting 方法：
+- softmax_splatting（默认）：自适应半径 + 高斯核 + softmax 深度竞争
+- zbuffer_splatting：两遍 z-buffer 硬遮挡
+- zbuffer_point：最近邻投影
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple
+
+import cv2
+import numpy as np
+import torch
+
+from .erp_projection import (
+    erp_to_direction,
+    direction_to_erp,
+    wrap_u,
+    create_erp_grid,
+)
+
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from utils.pose_utils import Pose
+
+
+@dataclass
+class WarpResult:
+    """Warp 结果"""
+    warped_rgb: np.ndarray                      # (H, W, 3) uint8
+    valid_mask: np.ndarray                      # (H, W) uint8, 1=valid, 0=invalid
+    flow: Optional[np.ndarray]                  # (H, W, 2) float32, optical flow
+    weight_sum: np.ndarray                      # (H, W) float32
+    warped_depth: Optional[np.ndarray] = None   # (H, W) float32, NaN=invalid
+
+
+# =============================================================================
+# Forward Projection（坐标变换）
+# =============================================================================
+
+@torch.no_grad()
+def _forward_project(
+    src_depth_t: torch.Tensor,
+    src_pose: Pose,
+    tgt_pose: Pose,
+    erp_h: int,
+    erp_w: int,
+    device: torch.device,
+    uu: Optional[torch.Tensor] = None,
+    vv: Optional[torch.Tensor] = None,
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
+    """
+    将源 ERP 像素投影到目标 ERP
+
+    使用锁定的 erp_projection 接口进行坐标变换。
+
+    Returns:
+        u_tgt, v_tgt: (H, W) 目标像素坐标
+        range_tgt: (H, W) 目标 range depth
+        dirs_tgt: (H, W, 3) 目标方向向量
+    """
+    if uu is None or vv is None:
+        uu, vv = create_erp_grid(erp_h, erp_w, device)
+
+    # 1. 源像素 -> 方向（源相机坐标系）
+    dirs_src = erp_to_direction(uu, vv, erp_h, erp_w)  # (H, W, 3)
+
+    # 2. 方向 * 深度 -> 源相机坐标系 3D 点
+    P_cam_src = dirs_src * src_depth_t.unsqueeze(-1)    # (H, W, 3)
+
+    # 3. 源相机 -> 世界
+    R_cw_src = torch.tensor(src_pose.R_cw, device=device, dtype=torch.float32)
+    t_src = torch.tensor(src_pose.position, device=device, dtype=torch.float32)
+    P_world = torch.einsum("ij,hwj->hwi", R_cw_src, P_cam_src) + t_src
+
+    # 4. 世界 -> 目标相机
+    R_wc_tgt = torch.tensor(tgt_pose.R_wc, device=device, dtype=torch.float32)
+    t_tgt = torch.tensor(tgt_pose.position, device=device, dtype=torch.float32)
+    P_cam_tgt = torch.einsum("ij,hwj->hwi", R_wc_tgt, P_world - t_tgt)
+
+    # 5. 目标 range depth 和方向
+    range_tgt = torch.norm(P_cam_tgt, dim=-1)
+    dirs_tgt = P_cam_tgt / torch.clamp(range_tgt.unsqueeze(-1), min=1e-9)
+
+    # 6. 方向 -> 目标 ERP 像素
+    u_tgt, v_tgt = direction_to_erp(dirs_tgt, erp_h, erp_w)
+    u_tgt = wrap_u(u_tgt, erp_w)
+
+    return u_tgt, v_tgt, range_tgt, dirs_tgt
+
+
+# =============================================================================
+# Adaptive Softmax Splatting
+# =============================================================================
+
+def _adaptive_splat_rgb(
+    erp_h: int,
+    erp_w: int,
+    u: torch.Tensor,
+    v: torch.Tensor,
+    rgb: torch.Tensor,
+    depth_compete: torch.Tensor,
+    valid: torch.Tensor,
+    alpha: float,
+    radius: torch.Tensor,
+    occlusion_gate: Optional[Dict[str, Any]] = None,
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
+    """
+    自适应半径 softmax splatting
+
+    - 高斯核加权
+    - softmax(alpha * inv_depth) 深度竞争
+    - 可选 occlusion gate（近似 z-buffer 门控）
+    """
+    device = u.device
+    u_flat = u.reshape(-1)
+    v_flat = v.reshape(-1)
+    rgb_flat = rgb.reshape(-1, 3)
+    d_flat = depth_compete.reshape(-1)
+    valid_flat = valid.reshape(-1)
+    r_flat = radius.reshape(-1)
+
+    # 安全深度
+    safe_d = torch.where(
+        valid_flat & torch.isfinite(d_flat) & (d_flat > 0),
+        d_flat, torch.ones_like(d_flat),
+    )
+
+    # Softmax 权重 = exp(alpha * inv_depth)
+    inv_d = 1.0 / torch.clamp(safe_d, min=0.1)
+    valid_inv = inv_d[valid_flat]
+    inv_max = valid_inv.max() if len(valid_inv) > 0 else inv_d.max()
+    exp_w = torch.exp(alpha * (inv_d - inv_max))
+
+    # 可选 occlusion gate
+    gate_enabled = False
+    min_d_flat: Optional[torch.Tensor] = None
+    gate_abs = 0.0
+    gate_rel = 0.0
+    if occlusion_gate and bool(occlusion_gate.get("enabled", False)):
+        gate_enabled = True
+        gate_abs = float(occlusion_gate.get("abs_eps_m", 0.05))
+        gate_rel = float(occlusion_gate.get("rel_eps", 0.05))
+        u_nn = torch.round(u_flat).to(torch.long)
+        v_nn = torch.round(v_flat).to(torch.long)
+        u_nn = torch.remainder(u_nn, erp_w)
+        v_ok = (v_nn >= 0) & (v_nn < erp_h)
+        v_nn_c = torch.clamp(v_nn, 0, erp_h - 1)
+        idx_nn = v_nn_c * erp_w + u_nn
+        min_d_flat = torch.full((erp_h * erp_w,), float("inf"), device=device)
+        d_nn = torch.where(valid_flat & v_ok & torch.isfinite(d_flat),
+                           d_flat, torch.full_like(d_flat, float("inf")))
+        min_d_flat.scatter_reduce_(0, idx_nn, d_nn, reduce="amin", include_self=True)
+
+    accum_rgb = torch.zeros(erp_h, erp_w, 3, device=device, dtype=torch.float32)
+    accum_w = torch.zeros(erp_h, erp_w, device=device, dtype=torch.float32)
+    accum_hit = torch.zeros(erp_h, erp_w, device=device, dtype=torch.float32)
+    accum_d = torch.zeros(erp_h, erp_w, device=device, dtype=torch.float32)
+
+    u0 = torch.floor(u_flat).to(torch.int64)
+    v0 = torch.floor(v_flat).to(torch.int64)
+    du = (u_flat - u0.float()).clamp(0, 1)
+    dv = (v_flat - v0.float()).clamp(0, 1)
+
+    # Splat 范围
+    valid_radii = r_flat[valid_flat & torch.isfinite(r_flat)]
+    max_r = min(int(valid_radii.max().item()) + 1, 5) if len(valid_radii) > 0 else 2
+
+    def _add(u_idx, v_idx, bw):
+        v_ok = (v_idx >= 0) & (v_idx < erp_h)
+        m = valid_flat & v_ok & torch.isfinite(d_flat)
+        u_safe = torch.where(m, u_idx, torch.zeros_like(u_idx))
+        v_safe = torch.where(m, v_idx, torch.zeros_like(v_idx))
+        idx = v_safe * erp_w + u_safe
+
+        if gate_enabled and min_d_flat is not None:
+            md = min_d_flat.gather(0, idx)
+            gate = d_flat <= (md * (1.0 + gate_rel) + gate_abs)
+            mm = m & gate
+        else:
+            mm = m
+
+        final_w = torch.where(mm, bw * exp_w, torch.zeros_like(bw))
+        hit_w = torch.where(mm, bw, torch.zeros_like(bw))
+        accum_w.view(-1).scatter_add_(0, idx, final_w)
+        accum_hit.view(-1).scatter_add_(0, idx, hit_w)
+        accum_rgb.view(-1, 3).scatter_add_(
+            0, idx.unsqueeze(-1).expand(-1, 3),
+            (final_w.unsqueeze(-1) * rgb_flat).float(),
+        )
+        accum_d.view(-1).scatter_add_(0, idx, (final_w * d_flat).float())
+
+    for di in range(-max_r, max_r + 1):
+        for dj in range(-max_r, max_r + 1):
+            dist_ij = math.sqrt(di * di + dj * dj)
+            if dist_ij > max_r + 0.5:
+                continue
+            dx = float(di) - du
+            dy = float(dj) - dv
+            dist = torch.sqrt(dx * dx + dy * dy)
+            within = dist <= (r_flat + 0.5)
+            gauss_w = torch.where(
+                within,
+                torch.exp(-0.5 * (dist / r_flat.clamp(min=0.5)) ** 2),
+                torch.zeros_like(r_flat),
+            )
+            u_off = torch.remainder(u0 + di, erp_w)
+            v_off = v0 + dj
+            _add(u_off, v_off, gauss_w)
+
+    return accum_rgb, accum_w, accum_hit, accum_d
+
+
+# =============================================================================
+# Z-Buffer Splatting
+# =============================================================================
+
+def _zbuffer_splat_rgb(
+    erp_h: int, erp_w: int,
+    u: torch.Tensor, v: torch.Tensor,
+    rgb: torch.Tensor, depth_compete: torch.Tensor, valid: torch.Tensor,
+    eps_abs_m: float, eps_rel: float, min_w: float,
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
+    """Z-buffer 硬遮挡 forward splatting（两遍法）"""
+    device = u.device
+    u_flat, v_flat = u.reshape(-1), v.reshape(-1)
+    d_flat = depth_compete.reshape(-1)
+    rgb_flat = rgb.reshape(-1, 3)
+    valid_flat = valid.reshape(-1)
+
+    m0 = valid_flat & torch.isfinite(u_flat) & torch.isfinite(v_flat) & \
+         torch.isfinite(d_flat) & (d_flat > 0.0)
+
+    u0 = torch.floor(u_flat).to(torch.int64)
+    v0 = torch.floor(v_flat).to(torch.int64)
+    du = (u_flat - u0.float()).clamp(0, 1)
+    dv = (v_flat - v0.float()).clamp(0, 1)
+    u0w = torch.remainder(u0, erp_w)
+    u1w = torch.remainder(u0 + 1, erp_w)
+    v1 = v0 + 1
+    w00 = (1 - du) * (1 - dv)
+    w10 = du * (1 - dv)
+    w01 = (1 - du) * dv
+    w11 = du * dv
+
+    # Pass A: min depth
+    min_depth = torch.full((erp_h * erp_w,), float("inf"), device=device)
+
+    def _amin(ui, vi, w):
+        m = m0 & (vi >= 0) & (vi < erp_h) & (w >= min_w)
+        us = torch.where(m, ui, torch.zeros_like(ui))
+        vs = torch.where(m, vi, torch.zeros_like(vi))
+        idx = vs * erp_w + us
+        cand = torch.where(m, d_flat, torch.full_like(d_flat, float("inf")))
+        min_depth.scatter_reduce_(0, idx, cand, reduce="amin", include_self=True)
+
+    _amin(u0w, v0, w00); _amin(u1w, v0, w10)
+    _amin(u0w, v1, w01); _amin(u1w, v1, w11)
+
+    # Pass B: accumulate near-front
+    accum_rgb = torch.zeros(erp_h, erp_w, 3, device=device)
+    accum_w = torch.zeros(erp_h, erp_w, device=device)
+    accum_hit = torch.zeros(erp_h, erp_w, device=device)
+    accum_d = torch.zeros(erp_h, erp_w, device=device)
+
+    def _acc(ui, vi, w):
+        m = m0 & (vi >= 0) & (vi < erp_h) & (w >= min_w)
+        us = torch.where(m, ui, torch.zeros_like(ui))
+        vs = torch.where(m, vi, torch.zeros_like(vi))
+        idx = vs * erp_w + us
+        md = min_depth.gather(0, idx)
+        gate = d_flat <= (md * (1 + eps_rel) + eps_abs_m)
+        mm = m & gate
+        wf = torch.where(mm, w, torch.zeros_like(w))
+        accum_w.view(-1).scatter_add_(0, idx, wf)
+        accum_hit.view(-1).scatter_add_(0, idx, wf)
+        accum_rgb.view(-1, 3).scatter_add_(
+            0, idx.unsqueeze(-1).expand(-1, 3),
+            (wf.unsqueeze(-1) * rgb_flat).float(),
+        )
+        accum_d.view(-1).scatter_add_(0, idx, (wf * d_flat).float())
+
+    _acc(u0w, v0, w00); _acc(u1w, v0, w10)
+    _acc(u0w, v1, w01); _acc(u1w, v1, w11)
+
+    return accum_rgb, accum_w, accum_hit, accum_d
+
+
+# =============================================================================
+# Z-Buffer Point
+# =============================================================================
+
+def _zbuffer_point_rgb(
+    erp_h: int, erp_w: int,
+    u: torch.Tensor, v: torch.Tensor,
+    rgb: torch.Tensor, depth_compete: torch.Tensor, valid: torch.Tensor,
+    eps_abs_m: float, eps_rel: float,
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
+    """Z-buffer 点渲染（radius=0, winner-take-all）"""
+    device = u.device
+    u_flat, v_flat = u.reshape(-1), v.reshape(-1)
+    d_flat = depth_compete.reshape(-1)
+    rgb_flat = rgb.reshape(-1, 3)
+    valid_flat = valid.reshape(-1)
+
+    m0 = valid_flat & torch.isfinite(u_flat) & torch.isfinite(v_flat) & \
+         torch.isfinite(d_flat) & (d_flat > 0.0)
+
+    u_nn = torch.remainder(torch.round(u_flat).to(torch.int64), erp_w)
+    v_nn = torch.round(v_flat).to(torch.int64)
+    v_ok = (v_nn >= 0) & (v_nn < erp_h)
+    m = m0 & v_ok
+    us = torch.where(m, u_nn, torch.zeros_like(u_nn))
+    vs = torch.where(m, v_nn, torch.zeros_like(v_nn))
+    idx = vs * erp_w + us
+
+    # Pass A: min depth
+    min_depth = torch.full((erp_h * erp_w,), float("inf"), device=device)
+    cand = torch.where(m, d_flat, torch.full_like(d_flat, float("inf")))
+    min_depth.scatter_reduce_(0, idx, cand, reduce="amin", include_self=True)
+
+    # Pass B
+    md = min_depth.gather(0, idx)
+    gate = d_flat <= (md * (1 + eps_rel) + eps_abs_m)
+    mm = m & gate
+    wf = torch.where(mm, torch.ones_like(d_flat), torch.zeros_like(d_flat))
+
+    accum_rgb = torch.zeros(erp_h, erp_w, 3, device=device)
+    accum_w = torch.zeros(erp_h, erp_w, device=device)
+    accum_hit = torch.zeros(erp_h, erp_w, device=device)
+    accum_d = torch.zeros(erp_h, erp_w, device=device)
+
+    accum_w.view(-1).scatter_add_(0, idx, wf)
+    accum_hit.view(-1).scatter_add_(0, idx, wf)
+    accum_rgb.view(-1, 3).scatter_add_(
+        0, idx.unsqueeze(-1).expand(-1, 3),
+        (wf.unsqueeze(-1) * rgb_flat).float(),
+    )
+    accum_d.view(-1).scatter_add_(0, idx, (wf * d_flat).float())
+
+    return accum_rgb, accum_w, accum_hit, accum_d
+
+
+# =============================================================================
+# Hole Fill
+# =============================================================================
+
+def _edge_aware_hole_fill(
+    rgb: np.ndarray, mask: np.ndarray,
+    max_hole_px: int = 5,
+    inpaint_radius: int = 2,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """小洞填充（只填充极小洞，避免 disocclusion 被错误填充）"""
+    holes = (mask == 0).astype(np.uint8)
+    if holes.sum() == 0:
+        return rgb, mask
+
+    num, labels, stats, _ = cv2.connectedComponentsWithStats(holes, connectivity=8)
+    fill_mask = np.zeros_like(holes)
+    max_area = max_hole_px * max_hole_px
+
+    for i in range(1, num):
+        area = stats[i, cv2.CC_STAT_AREA]
+        if area <= max_area:
+            fill_mask[labels == i] = 1
+
+    if fill_mask.sum() == 0:
+        return rgb, mask
+
+    rgb_bgr = cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)
+    filled = cv2.inpaint(rgb_bgr, fill_mask, inpaint_radius, cv2.INPAINT_TELEA)
+    filled_rgb = cv2.cvtColor(filled, cv2.COLOR_BGR2RGB)
+
+    rgb_out = rgb.copy()
+    mask_out = mask.copy()
+    fill_bool = fill_mask > 0
+    rgb_out[fill_bool] = filled_rgb[fill_bool]
+    mask_out[fill_bool] = 1
+
+    return rgb_out, mask_out
+
+
+# =============================================================================
+# 主函数
+# =============================================================================
+
+@torch.no_grad()
+def warp_erp_to_target(
+    src_rgb: np.ndarray,
+    src_depth: np.ndarray,
+    src_pose: Pose,
+    tgt_pose: Pose,
+    cfg: Dict[str, Any],
+    device: torch.device,
+) -> WarpResult:
+    """
+    从源 ERP 视角 warp 到目标 ERP 视角
+
+    使用锁定的 erp_projection.py 进行坐标变换，
+    ���用锁定的 pose_utils.Pose 进行位姿处理。
+
+    Args:
+        src_rgb: (H, W, 3) uint8 源 RGB
+        src_depth: (H, W) float32 源 range depth（米）
+        src_pose: 源相机位姿（Pose 实例）
+        tgt_pose: 目标相机位姿（Pose 实例）
+        cfg: 配置字典
+        device: 计算设备
+
+    Returns:
+        WarpResult
+    """
+    warp_cfg = cfg.get("warp", {})
+    method = str(warp_cfg.get("method", "softmax_splatting"))
+    alpha = float(warp_cfg.get("alpha", 2.0))
+    min_weight_sum = float(warp_cfg.get("min_weight_sum", 1e-4))
+    output_flow = bool(warp_cfg.get("output_flow", True))
+    output_depth = bool(warp_cfg.get("output_depth", True))
+    depth_scale_factor = float(warp_cfg.get("depth_scale_factor", 1.0))
+
+    # Z-buffer 参数
+    z_eps_abs = float(warp_cfg.get("zbuffer_eps_abs_m", 0.03))
+    z_eps_rel = float(warp_cfg.get("zbuffer_eps_rel", 0.03))
+    z_min_w = float(warp_cfg.get("zbuffer_min_weight", 1e-3))
+
+    # 自适应半径参数
+    base_radius = float(warp_cfg.get("splat_radius_px", 1.5))
+    radius_min = float(warp_cfg.get("radius_min_px", 0.6))
+    radius_max_eq = float(warp_cfg.get("radius_max_px", 2.2))
+    radius_max_pole = float(warp_cfg.get("radius_max_pole_px", 3.4))
+    pole_radius_scale = float(warp_cfg.get("pole_radius_scale", 3.0))
+    pole_lat_threshold = float(warp_cfg.get("pole_lat_threshold", 60.0)) * math.pi / 180.0
+    depth_radius_scale = bool(warp_cfg.get("depth_radius_scale", False))
+    depth_ref = float(warp_cfg.get("depth_ref_m", 2.0))
+    depth_edge_aware = bool(warp_cfg.get("depth_edge_aware", True))
+    depth_edge_threshold = float(warp_cfg.get("depth_edge_threshold", 0.3))
+    depth_edge_min_scale = float(warp_cfg.get("depth_edge_min_scale", 0.12))
+
+    # Hole fill
+    hole_fill = bool(warp_cfg.get("hole_fill_enabled", False)) and method not in ("zbuffer_splatting", "zbuffer_point")
+    max_hole_px = int(warp_cfg.get("max_hole_px", 16))
+
+    erp_h, erp_w = src_rgb.shape[:2]
+
+    # 转 tensor
+    src_rgb_t = torch.from_numpy(src_rgb.astype(np.float32)).to(device) / 255.0
+    src_depth_t = torch.from_numpy(src_depth.astype(np.float32)).to(device)
+    if depth_scale_factor != 1.0:
+        src_depth_t *= depth_scale_factor
+
+    valid = torch.isfinite(src_depth_t) & (src_depth_t > 0.0)
+
+    # --- 深度边缘掩码 ---
+    depth_edge_scale = torch.ones_like(src_depth_t)
+    if depth_edge_aware:
+        from torch.nn.functional import conv2d
+        sobel_x = torch.tensor([[-1, 0, 1], [-2, 0, 2], [-1, 0, 1]],
+                                dtype=torch.float32, device=device).view(1, 1, 3, 3)
+        sobel_y = torch.tensor([[-1, -2, -1], [0, 0, 0], [1, 2, 1]],
+                                dtype=torch.float32, device=device).view(1, 1, 3, 3)
+        safe_d = torch.where(valid, src_depth_t, src_depth_t[valid].median() if valid.any() else torch.ones_like(src_depth_t))
+        log_d = torch.log(torch.clamp(safe_d, min=0.1)).unsqueeze(0).unsqueeze(0)
+        gx = conv2d(log_d, sobel_x, padding=1).squeeze()
+        gy = conv2d(log_d, sobel_y, padding=1).squeeze()
+        grad = torch.sqrt(gx ** 2 + gy ** 2)
+        gmax = grad.max()
+        if gmax > 1e-6:
+            gnorm = grad / gmax
+        else:
+            gnorm = torch.zeros_like(grad)
+        depth_edge_scale = torch.clamp(
+            1.0 - gnorm / max(depth_edge_threshold, 1e-6),
+            min=depth_edge_min_scale, max=1.0,
+        )
+        depth_edge_scale = torch.where(torch.isfinite(depth_edge_scale),
+                                        depth_edge_scale, torch.ones_like(depth_edge_scale))
+
+    # --- ERP 网格 ---
+    uu, vv = create_erp_grid(erp_h, erp_w, device)
+
+    # --- Forward project ---
+    u_tgt, v_tgt, range_tgt, dirs_tgt = _forward_project(
+        src_depth_t, src_pose, tgt_pose, erp_h, erp_w, device, uu, vv,
+    )
+
+    # --- 自适应半径 ---
+    lat_tgt = torch.asin(torch.clamp(dirs_tgt[..., 1], -1.0, 1.0))
+    abs_lat = torch.abs(lat_tgt)
+    pole_factor = torch.clamp(
+        (abs_lat - pole_lat_threshold) / (0.5 * math.pi - pole_lat_threshold),
+        min=0.0, max=1.0,
+    )
+    lat_scale = 1.0 + pole_factor * (pole_radius_scale - 1.0)
+
+    if depth_radius_scale:
+        safe_range = torch.where(valid, range_tgt, torch.full_like(range_tgt, depth_ref))
+        d_scale = 1.0 / (1.0 + safe_range / depth_ref)
+    else:
+        d_scale = torch.ones_like(range_tgt)
+
+    adaptive_radius = base_radius * lat_scale * d_scale * depth_edge_scale
+    adaptive_radius = torch.where(valid, adaptive_radius, torch.full_like(adaptive_radius, base_radius))
+    radius_max_local = radius_max_eq + pole_factor * (radius_max_pole - radius_max_eq)
+    adaptive_radius = torch.clamp(adaptive_radius, min=radius_min)
+    adaptive_radius = torch.minimum(adaptive_radius, radius_max_local)
+
+    # --- Splatting ---
+    if method == "zbuffer_splatting":
+        _rgb, _w, _hit, _d = _zbuffer_splat_rgb(
+            erp_h, erp_w, u_tgt, v_tgt, src_rgb_t, range_tgt, valid,
+            z_eps_abs, z_eps_rel, z_min_w,
+        )
+    elif method == "zbuffer_point":
+        _rgb, _w, _hit, _d = _zbuffer_point_rgb(
+            erp_h, erp_w, u_tgt, v_tgt, src_rgb_t, range_tgt, valid,
+            z_eps_abs, z_eps_rel,
+        )
+    else:
+        _rgb, _w, _hit, _d = _adaptive_splat_rgb(
+            erp_h, erp_w, u_tgt, v_tgt, src_rgb_t, range_tgt, valid,
+            alpha, adaptive_radius, warp_cfg.get("occlusion_gate", None),
+        )
+
+    # --- 归一化 ---
+    denom = _w > 0.0
+    out_rgb = torch.zeros_like(_rgb)
+    out_rgb[denom] = _rgb[denom] / _w[denom].unsqueeze(-1)
+
+    min_hit = float(warp_cfg.get("min_hit_sum", 1e-6))
+    valid_mask = _hit > min_hit
+
+    warped_np = (out_rgb.clamp(0, 1) * 255).byte().cpu().numpy()
+    mask_np = valid_mask.cpu().numpy().astype(np.uint8)
+    weight_np = _hit.cpu().numpy().astype(np.float32)
+
+    # --- Warped depth ---
+    warped_depth_np = None
+    if output_depth:
+        out_d = torch.full((erp_h, erp_w), float("nan"), device=device)
+        out_d[denom] = _d[denom] / torch.clamp(_w[denom], min=1e-9)
+        out_d[~valid_mask] = float("nan")
+        warped_depth_np = out_d.cpu().numpy().astype(np.float32)
+
+    # --- Hole fill ---
+    if hole_fill:
+        warped_np, mask_np = _edge_aware_hole_fill(warped_np, mask_np, max_hole_px)
+
+    # --- Optical flow ---
+    flow_np = None
+    if output_flow:
+        du = u_tgt - uu
+        du = (du + 0.5 * erp_w) % erp_w - 0.5 * erp_w
+        dv = v_tgt - vv
+        flow_np = torch.stack([du, dv], dim=-1).cpu().numpy().astype(np.float32)
+
+    return WarpResult(
+        warped_rgb=warped_np,
+        valid_mask=mask_np,
+        flow=flow_np,
+        weight_sum=weight_np,
+        warped_depth=warped_depth_np,
+    )
+
+
+def create_comparison_image(
+    warped_rgb: np.ndarray,
+    valid_mask: np.ndarray,
+    gt_rgb: Optional[np.ndarray] = None,
+) -> np.ndarray:
+    """创建对比图（warped | GT），如无 GT 则只返回 warped"""
+    vis = warped_rgb.copy()
+    vis[valid_mask == 0] = 0
+
+    if gt_rgb is not None:
+        return np.concatenate([vis, gt_rgb], axis=0)
+    return vis

core/tangent_extraction.py

@@ -0,0 +1,566 @@
+"""
+ERP -> Tangent 切片生成模块（移植自原版 ERPT）
+
+功能：
+1. 生成 icosahedron 20 面的相机朝向
+2. 生成 north/south pole 额外切片（使用更大 FOV）
+3. 从 ERP 采样生成透视切片（支持 seam wrap）
+4. 输出切片 RGB 和元数据
+
+关键算法：
+- icosahedron 面法向计算
+- 相机坐标系构建（look-at）
+- ERP -> 透视投影（grid_sample with seam wrap）
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+import torch
+import torch.nn.functional as F
+
+
+@dataclass
+class TangentSlice:
+    """切片规格"""
+    slice_id: str                    # 切片 ID（如 "face_00", "north", "south"）
+    slice_type: str                  # 类型："face" | "pole_north" | "pole_south"
+    center_dir: np.ndarray           # 切片中心方向（世界坐标，单位向量）
+    R_cw: np.ndarray                 # 相机到世界的旋转矩阵 (3,3)
+    fov_deg: float                   # 视场角（度）
+    resolution: int                  # 输出分辨率（像素，正方形）
+    K: np.ndarray                    # 相机内参 (3,3)
+    f_px: float                      # 焦距（像素）
+
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为可 JSON 序列化的字典"""
+        return {
+            "slice_id": self.slice_id,
+            "slice_type": self.slice_type,
+            "center_dir": self.center_dir.tolist(),
+            "R_cw": self.R_cw.tolist(),
+            "fov_deg": float(self.fov_deg),
+            "resolution": int(self.resolution),
+            "K": self.K.tolist(),
+            "f_px": float(self.f_px),
+        }
+
+
+def _compute_icosahedron_face_centers() -> List[np.ndarray]:
+    """
+    计算正二十面体 20 个面的中心方向（单位向量）
+
+    正二十面体有 12 个顶点、20 个面、30 条边。
+    每个面是等边三角形，面中心 = (v0 + v1 + v2) / 3 归一化
+
+    Returns:
+        20 个单位向量的列表，每个指向一个面的中心
+    """
+    # 黄金比例
+    phi = (1.0 + math.sqrt(5.0)) / 2.0
+
+    # 正二十面体 12 个顶点（坐标已归一化）
+    vertices = np.array([
+        [-1,  phi, 0],
+        [ 1,  phi, 0],
+        [-1, -phi, 0],
+        [ 1, -phi, 0],
+        [0, -1,  phi],
+        [0,  1,  phi],
+        [0, -1, -phi],
+        [0,  1, -phi],
+        [ phi, 0, -1],
+        [ phi, 0,  1],
+        [-phi, 0, -1],
+        [-phi, 0,  1],
+    ], dtype=np.float64)
+
+    # 归一化顶点
+    vertices = vertices / np.linalg.norm(vertices, axis=1, keepdims=True)
+
+    # 20 个面的顶点索引
+    faces = [
+        (0, 11, 5), (0, 5, 1), (0, 1, 7), (0, 7, 10), (0, 10, 11),
+        (1, 5, 9), (5, 11, 4), (11, 10, 2), (10, 7, 6), (7, 1, 8),
+        (3, 9, 4), (3, 4, 2), (3, 2, 6), (3, 6, 8), (3, 8, 9),
+        (4, 9, 5), (2, 4, 11), (6, 2, 10), (8, 6, 7), (9, 8, 1),
+    ]
+
+    centers = []
+    for i0, i1, i2 in faces:
+        center = vertices[i0] + vertices[i1] + vertices[i2]
+        center = center / np.linalg.norm(center)
+        centers.append(center.astype(np.float32))
+
+    return centers
+
+
+def _look_at_rotation(forward: np.ndarray, up_hint: Optional[np.ndarray] = None) -> np.ndarray:
+    """
+    构建从相机坐标系到世界坐标系的旋转矩阵
+
+    相机坐标系约定：
+    - +Z: 前向（forward）
+    - +Y: 上方（up）
+    - +X: 右方（right = up × forward）
+
+    Args:
+        forward: 相机前向方向（世界坐标，单位向量）
+        up_hint: 上方提示（默认世界 Y 轴）
+
+    Returns:
+        R_cw: (3,3) 旋转矩阵，v_world = R_cw @ v_cam
+    """
+    f = np.asarray(forward, dtype=np.float64).reshape(3)
+    f = f / (np.linalg.norm(f) + 1e-12)
+
+    if up_hint is None:
+        up_hint = np.array([0.0, 1.0, 0.0], dtype=np.float64)
+    u = np.asarray(up_hint, dtype=np.float64).reshape(3)
+    u = u / (np.linalg.norm(u) + 1e-12)
+
+    # 如果 forward 与 up_hint 几乎平行，换一个 up_hint
+    if abs(np.dot(f, u)) > 0.95:
+        u = np.array([0.0, 0.0, 1.0], dtype=np.float64)
+
+    # 右方向 = up × forward
+    r = np.cross(u, f)
+    r = r / (np.linalg.norm(r) + 1e-12)
+
+    # 真正的上方向 = forward × right
+    u2 = np.cross(f, r)
+    u2 = u2 / (np.linalg.norm(u2) + 1e-12)
+
+    # 旋转矩阵的列是相机坐标轴在世界坐标系中的表示
+    R_cw = np.stack([r, u2, f], axis=1)
+    return R_cw.astype(np.float32)
+
+
+def _compute_intrinsics(resolution: int, fov_deg: float) -> Tuple[np.ndarray, float]:
+    """
+    计算针孔相机内参
+
+    Args:
+        resolution: 图像分辨率（正方形）
+        fov_deg: 水平视场角（度）
+
+    Returns:
+        K: (3,3) 内参矩阵
+        f_px: 焦距（像素）
+    """
+    fov_rad = np.deg2rad(fov_deg)
+    f_px = 0.5 * resolution / np.tan(0.5 * fov_rad)
+
+    cx = (resolution - 1) * 0.5
+    cy = (resolution - 1) * 0.5
+
+    K = np.array([
+        [f_px, 0.0,  cx],
+        [0.0,  f_px, cy],
+        [0.0,  0.0,  1.0]
+    ], dtype=np.float32)
+
+    return K, float(f_px)
+
+
+def build_icosahedron_slices(cfg: Dict[str, Any]) -> List[TangentSlice]:
+    """
+    根据配置构建 icosahedron + poles 切片列表
+
+    360MonoDepth 风格：使用 padding_factor 而非 overlap_pad_deg
+    有效 FOV = base_fov * padding_factor
+
+    Args:
+        cfg: 配置字典（包含 tangent 配置）
+
+    Returns:
+        切片规格列表
+    """
+    tcfg = cfg.get("tangent", {})
+
+    # 基本参数
+    face_resolution = int(tcfg.get("face_resolution", 768))
+    fov_deg = float(tcfg.get("fov_deg", 90.0))
+
+    # 360MonoDepth 风格 padding（优先使用 padding_factor）
+    padding_factor = float(tcfg.get("padding_factor", 1.3))
+    overlap_pad_deg = float(tcfg.get("overlap_pad_deg", 0.0))  # 向后兼容
+
+    # 计算有效 FOV
+    if padding_factor > 1.0:
+        effective_fov = fov_deg * padding_factor
+    else:
+        effective_fov = fov_deg + overlap_pad_deg
+
+    # 限制最大 FOV 避免极端畸变
+    effective_fov = min(effective_fov, 170.0)
+
+    # 极区参数（增强覆盖）
+    add_poles = bool(tcfg.get("add_poles", True))
+    pole_fov_deg = float(tcfg.get("pole_fov_deg", 150.0))  # 默认更大
+    pole_resolution = int(tcfg.get("pole_resolution", face_resolution))
+    pole_extra_rings = int(tcfg.get("pole_extra_rings", 0))  # 额外极区密采样
+
+    slices = []
+
+    # 1. 添加 20 个 icosahedron 面
+    face_centers = _compute_icosahedron_face_centers()
+    for i, center in enumerate(face_centers):
+        R_cw = _look_at_rotation(center)
+        K, f_px = _compute_intrinsics(face_resolution, effective_fov)
+
+        slices.append(TangentSlice(
+            slice_id=f"face_{i:02d}",
+            slice_type="face",
+            center_dir=center,
+            R_cw=R_cw,
+            fov_deg=effective_fov,
+            resolution=face_resolution,
+            K=K,
+            f_px=f_px,
+        ))
+
+    # 2. 添加极区切片
+    if add_poles:
+        # 北极（+Y）
+        north_dir = np.array([0.0, 1.0, 0.0], dtype=np.float32)
+        R_north = _look_at_rotation(north_dir, up_hint=np.array([0.0, 0.0, -1.0]))
+        K_north, f_north = _compute_intrinsics(pole_resolution, pole_fov_deg)
+
+        slices.append(TangentSlice(
+            slice_id="north",
+            slice_type="pole_north",
+            center_dir=north_dir,
+            R_cw=R_north,
+            fov_deg=pole_fov_deg,
+            resolution=pole_resolution,
+            K=K_north,
+            f_px=f_north,
+        ))
+
+        # 南极（-Y）
+        south_dir = np.array([0.0, -1.0, 0.0], dtype=np.float32)
+        R_south = _look_at_rotation(south_dir, up_hint=np.array([0.0, 0.0, 1.0]))
+        K_south, f_south = _compute_intrinsics(pole_resolution, pole_fov_deg)
+
+        slices.append(TangentSlice(
+            slice_id="south",
+            slice_type="pole_south",
+            center_dir=south_dir,
+            R_cw=R_south,
+            fov_deg=pole_fov_deg,
+            resolution=pole_resolution,
+            K=K_south,
+            f_px=f_south,
+        ))
+
+        # 3. 额外极区密采样环（可选）
+        if pole_extra_rings > 0:
+            _add_polar_ring_slices(
+                slices, pole_extra_rings, pole_resolution, pole_fov_deg * 0.8
+            )
+
+    return slices
+
+
+def _add_polar_ring_slices(
+    slices: List[TangentSlice],
+    num_rings: int,
+    resolution: int,
+    fov_deg: float,
+) -> None:
+    """
+    添加额外的极区密采样切片（环状分布在极区附近）
+    """
+    latitudes = [math.radians(75)]
+    if num_rings > 1:
+        latitudes = [math.radians(60 + 25 * i / (num_rings - 1)) for i in range(num_rings)]
+
+    K, f_px = _compute_intrinsics(resolution, fov_deg)
+
+    for ring_idx, lat in enumerate(latitudes):
+        num_slices_per_ring = 6
+        for lon_idx in range(num_slices_per_ring):
+            lon = lon_idx * 2 * math.pi / num_slices_per_ring
+
+            # 北极附近
+            x_n = math.cos(lat) * math.sin(lon)
+            y_n = math.sin(lat)
+            z_n = math.cos(lat) * math.cos(lon)
+            dir_n = np.array([x_n, y_n, z_n], dtype=np.float32)
+            R_n = _look_at_rotation(dir_n)
+
+            slices.append(TangentSlice(
+                slice_id=f"pole_ring_n_{ring_idx}_{lon_idx}",
+                slice_type="pole_ring",
+                center_dir=dir_n,
+                R_cw=R_n,
+                fov_deg=fov_deg,
+                resolution=resolution,
+                K=K,
+                f_px=f_px,
+            ))
+
+            # 南极附近
+            y_s = -math.sin(lat)
+            dir_s = np.array([x_n, y_s, z_n], dtype=np.float32)
+            R_s = _look_at_rotation(dir_s)
+
+            slices.append(TangentSlice(
+                slice_id=f"pole_ring_s_{ring_idx}_{lon_idx}",
+                slice_type="pole_ring",
+                center_dir=dir_s,
+                R_cw=R_s,
+                fov_deg=fov_deg,
+                resolution=resolution,
+                K=K,
+                f_px=f_px,
+            ))
+
+
+def _build_sample_grid(
+    slice_spec: TangentSlice,
+    erp_h: int,
+    erp_w: int,
+    device: torch.device,
+) -> torch.Tensor:
+    """
+    构建从 ERP 采样到切片的网格
+
+    对于切片的每个像素 (u, v):
+    1. 反投影到相机坐标系射线方向
+    2. 旋转到世界坐标系
+    3. 计算球面经纬度
+    4. 映射到 ERP 像素坐标
+    """
+    res = slice_spec.resolution
+    K = slice_spec.K
+    R_cw = slice_spec.R_cw
+
+    fx, fy = float(K[0, 0]), float(K[1, 1])
+    cx, cy = float(K[0, 2]), float(K[1, 2])
+
+    # 切片像素坐标
+    xs = torch.arange(res, device=device, dtype=torch.float32)
+    ys = torch.arange(res, device=device, dtype=torch.float32)
+    yv, xv = torch.meshgrid(ys, xs, indexing="ij")  # (H, W)
+
+    # 反投影到相机坐标系
+    x_cam = (xv - cx) / fx
+    y_cam = -(yv - cy) / fy  # 图像 y 向下，相机 y 向上
+    z_cam = torch.ones_like(x_cam)
+
+    # 归一化射线方向
+    dirs_cam = torch.stack([x_cam, y_cam, z_cam], dim=-1)  # (H, W, 3)
+    dirs_cam = dirs_cam / torch.clamp(torch.norm(dirs_cam, dim=-1, keepdim=True), min=1e-9)
+
+    # 旋转到世界坐标系
+    R = torch.tensor(R_cw, device=device, dtype=torch.float32)
+    dirs_world = torch.einsum("ij,hwj->hwi", R, dirs_cam)  # (H, W, 3)
+
+    # 计算球面坐标
+    x = dirs_world[..., 0]
+    y = dirs_world[..., 1]
+    z = dirs_world[..., 2]
+
+    lon = torch.atan2(x, z)
+    lat = torch.asin(torch.clamp(y, -1.0, 1.0))
+
+    # 映射到 ERP 像素坐标
+    u = (lon + math.pi) / (2.0 * math.pi) * float(erp_w)
+    v = (math.pi / 2.0 - lat) / math.pi * float(erp_h - 1)
+
+    # Seam wrap: ERP 在 x 方向扩展 3 倍，采样时从中间段采样
+    u_padded = u + float(erp_w)
+    erp_w_padded = erp_w * 3
+
+    x_norm = (u_padded / float(erp_w_padded - 1)) * 2.0 - 1.0
+    y_norm = (v / float(erp_h - 1)) * 2.0 - 1.0
+
+    grid = torch.stack([x_norm, y_norm], dim=-1).unsqueeze(0)  # (1, H, W, 2)
+    return grid
+
+
+@torch.no_grad()
+def extract_tangent_from_erp(
+    erp_rgb: torch.Tensor,
+    slice_spec: TangentSlice,
+    device: torch.device,
+) -> np.ndarray:
+    """
+    从 ERP 提取单个切片
+
+    Args:
+        erp_rgb: (1, 3, H, W) ERP 图像
+        slice_spec: 切片规格
+        device: 计算设备
+
+    Returns:
+        tangent_rgb: (H, W, 3) uint8 numpy array
+    """
+    erp_h, erp_w = erp_rgb.shape[2], erp_rgb.shape[3]
+
+    # Seam wrap: 扩展 ERP 宽度
+    erp_padded = torch.cat([erp_rgb, erp_rgb, erp_rgb], dim=-1)  # (1, 3, H, 3W)
+
+    # 构建采样网格
+    grid = _build_sample_grid(slice_spec, erp_h, erp_w, device)
+
+    # 采样
+    tangent = F.grid_sample(
+        erp_padded,
+        grid,
+        mode="bilinear",
+        padding_mode="border",
+        align_corners=True,
+    )  # (1, 3, res, res)
+
+    # 转换为 numpy
+    tangent_np = (tangent.squeeze(0).permute(1, 2, 0).clamp(0, 1) * 255.0).byte().cpu().numpy()
+    return tangent_np
+
+
+@torch.no_grad()
+def extract_all_tangents(
+    erp_rgb_np: np.ndarray,
+    slices: List[TangentSlice],
+    device: torch.device,
+) -> Dict[str, np.ndarray]:
+    """
+    从 ERP 提取所有切片
+
+    Args:
+        erp_rgb_np: (H, W, 3) ERP 图像 numpy array
+        slices: 切片规格列表
+        device: 计算设备
+
+    Returns:
+        字典 {slice_id: tangent_rgb}
+    """
+    erp_t = torch.from_numpy(erp_rgb_np).to(device).permute(2, 0, 1).float() / 255.0
+    erp_t = erp_t.unsqueeze(0)  # (1, 3, H, W)
+
+    results = {}
+    for s in slices:
+        tangent = extract_tangent_from_erp(erp_t, s, device)
+        results[s.slice_id] = tangent
+
+    return results
+
+
+def compute_ray_directions_for_slice(
+    slice_spec: TangentSlice,
+    device: torch.device,
+) -> torch.Tensor:
+    """
+    计算切片每个像素对应的世界坐标系射线方向（融合时使用）
+
+    Returns:
+        dirs_world: (H, W, 3) 单位方向向量
+    """
+    res = slice_spec.resolution
+    K = slice_spec.K
+    R_cw = slice_spec.R_cw
+
+    fx, fy = float(K[0, 0]), float(K[1, 1])
+    cx, cy = float(K[0, 2]), float(K[1, 2])
+
+    xs = torch.arange(res, device=device, dtype=torch.float32)
+    ys = torch.arange(res, device=device, dtype=torch.float32)
+    yv, xv = torch.meshgrid(ys, xs, indexing="ij")
+
+    x_cam = (xv - cx) / fx
+    y_cam = -(yv - cy) / fy
+    z_cam = torch.ones_like(x_cam)
+
+    dirs_cam = torch.stack([x_cam, y_cam, z_cam], dim=-1)
+    dirs_cam = dirs_cam / torch.clamp(torch.norm(dirs_cam, dim=-1, keepdim=True), min=1e-9)
+
+    R = torch.tensor(R_cw, device=device, dtype=torch.float32)
+    dirs_world = torch.einsum("ij,hwj->hwi", R, dirs_cam)
+
+    return dirs_world
+
+
+@torch.no_grad()
+def compute_coverage_mask(
+    slices: List[TangentSlice],
+    erp_h: int,
+    erp_w: int,
+    device: torch.device,
+) -> Tuple[np.ndarray, Dict[str, float]]:
+    """
+    计算 ERP 覆盖率掩码（纯几何计算）
+
+    Returns:
+        coverage_mask: (H, W) uint8, 255=covered, 0=uncovered
+        stats: 覆盖率统计字典
+    """
+    coverage = torch.zeros(erp_h, erp_w, device=device, dtype=torch.float32)
+
+    for s in slices:
+        res = s.resolution
+        K = s.K
+        R_cw = s.R_cw
+
+        fx, fy = float(K[0, 0]), float(K[1, 1])
+        cx, cy = float(K[0, 2]), float(K[1, 2])
+
+        xs = torch.arange(res, device=device, dtype=torch.float32)
+        ys = torch.arange(res, device=device, dtype=torch.float32)
+        yv, xv = torch.meshgrid(ys, xs, indexing="ij")
+
+        x_cam = (xv - cx) / fx
+        y_cam = -(yv - cy) / fy
+        z_cam = torch.ones_like(x_cam)
+
+        dirs_cam = torch.stack([x_cam, y_cam, z_cam], dim=-1)
+        dirs_cam = dirs_cam / torch.clamp(torch.norm(dirs_cam, dim=-1, keepdim=True), min=1e-9)
+
+        R = torch.tensor(R_cw, device=device, dtype=torch.float32)
+        dirs_world = torch.einsum("ij,hwj->hwi", R, dirs_cam)
+
+        x = dirs_world[..., 0]
+        y = dirs_world[..., 1]
+        z = dirs_world[..., 2]
+
+        lon = torch.atan2(x, z)
+        lat = torch.asin(torch.clamp(y, -1.0, 1.0))
+
+        u = (lon + math.pi) / (2.0 * math.pi) * float(erp_w)
+        v = (math.pi / 2.0 - lat) / math.pi * float(erp_h - 1)
+
+        u_int = torch.round(u).to(torch.int64)
+        v_int = torch.round(v).to(torch.int64)
+
+        u_int = torch.clamp(u_int % erp_w, 0, erp_w - 1)
+        v_int = torch.clamp(v_int, 0, erp_h - 1)
+
+        idx = v_int * erp_w + u_int
+        idx = idx.reshape(-1)
+
+        coverage_flat = coverage.reshape(-1)
+        coverage_flat.scatter_add_(0, idx, torch.ones_like(idx, dtype=torch.float32))
+
+    covered = coverage > 0
+    coverage_mask = (covered.float() * 255).byte().cpu().numpy()
+
+    total_pixels = erp_h * erp_w
+    covered_pixels = int(covered.sum().item())
+
+    pole_rows = int(erp_h * 0.1)
+    north_covered = covered[:pole_rows, :].float().mean().item()
+    south_covered = covered[-pole_rows:, :].float().mean().item()
+
+    stats = {
+        "total_coverage": covered_pixels / total_pixels * 100,
+        "uncovered_pixels": total_pixels - covered_pixels,
+        "north_pole_coverage": north_covered * 100,
+        "south_pole_coverage": south_covered * 100,
+    }
+
+    return coverage_mask, stats

data/README.md

@@ -0,0 +1,16 @@
+# Data Directory
+
+Place local scene assets here when running experiments. Do not commit dataset files to the anonymous repository.
+
+Recommended layout:
+
+```text
+data/
+├── blender_indoor/
+├── blender_outdoor/
+├── hm3d/
+└── scannetpp/
+```
+
+You may also pass absolute paths directly to the pipeline CLI.
+

dataset_metadata/croissant.json

@@ -0,0 +1,414 @@
+{
+  "@context": {
+    "@language": "en",
+    "@vocab": "https://schema.org/",
+    "citeAs": "cr:citeAs",
+    "column": "cr:column",
+    "conformsTo": "dct:conformsTo",
+    "cr": "http://mlcommons.org/croissant/",
+    "rai": "http://mlcommons.org/croissant/RAI/",
+    "data": {
+      "@id": "cr:data",
+      "@type": "@json"
+    },
+    "dataType": {
+      "@id": "cr:dataType",
+      "@type": "@vocab"
+    },
+    "dct": "http://purl.org/dc/terms/",
+    "examples": {
+      "@id": "cr:examples",
+      "@type": "@json"
+    },
+    "extract": "cr:extract",
+    "field": "cr:field",
+    "fileProperty": "cr:fileProperty",
+    "fileObject": "cr:fileObject",
+    "fileSet": "cr:fileSet",
+    "format": "cr:format",
+    "includes": "cr:includes",
+    "isLiveDataset": "cr:isLiveDataset",
+    "jsonPath": "cr:jsonPath",
+    "key": "cr:key",
+    "md5": "cr:md5",
+    "parentField": "cr:parentField",
+    "path": "cr:path",
+    "recordSet": "cr:recordSet",
+    "references": "cr:references",
+    "regex": "cr:regex",
+    "repeated": "cr:repeated",
+    "replace": "cr:replace",
+    "samplingRate": "cr:samplingRate",
+    "sc": "https://schema.org/",
+    "separator": "cr:separator",
+    "source": "cr:source",
+    "subField": "cr:subField",
+    "transform": "cr:transform"
+  },
+  "@type": "sc:Dataset",
+  "conformsTo": "http://mlcommons.org/croissant/1.0",
+  "name": "CM-EVS",
+  "description": "CM-EVS is a curated panoramic RGB-D dataset built under a single principle: maximize the geometric coverage of a 3D scene with the fewest equirectangular (ERP) frames possible. The headline release contains 11,583 ERP RGB-depth-pose frames over 326 Blender indoor scenes (CC-BY 4.0), each paired with the per-step provenance log of the depth-conflict-aware curator that selected it. The full v1.0 release additionally provides 786,344 frames re-encoded from TartanGround (783,944 frames over 63 environments) and OB3D (2,400 frames over 12 scenes) outdoor sources into the same ERP and world-to-camera pose schema, plus license-aware adapter packages for HM3D (14,475 frames over 401 rooms after local regeneration) and ScanNet++ (8,267 frames over 500 scans after local regeneration) that produce matched frames locally without redistributing licensed assets.",
+  "version": "1.0.0",
+  "license": "https://creativecommons.org/licenses/by/4.0/",
+  "url": "https://huggingface.co/datasets/anon-cmevs-2026/cmevs-erp-eval",
+  "citeAs": "@inproceedings{cmevs2026, title={{CM-EVS}: A Coverage-Curated Panoramic {RGB-D} Dataset for Indoor Scene Understanding}, author={Anonymous Author(s)}, booktitle={NeurIPS 2026 Datasets and Benchmarks Track (under review)}, year={2026}}",
+  "creator": {
+    "@type": "Organization",
+    "name": "Anonymous (double-blind submission)"
+  },
+  "datePublished": "2026-05-01",
+  "keywords": [
+    "panoramic",
+    "equirectangular",
+    "ERP",
+    "RGB-D",
+    "view planning",
+    "fixed-budget",
+    "data-centric",
+    "viewpoint provenance",
+    "indoor scene understanding",
+    "panoramic depth estimation",
+    "novel view synthesis",
+    "world model pretraining"
+  ],
+  "isLiveDataset": false,
+  "distribution": [
+    {
+      "@type": "cr:FileObject",
+      "@id": "blender-indoor-archive.tar",
+      "name": "blender-indoor-archive.tar",
+      "contentUrl": "https://huggingface.co/datasets/anon-cmevs-2026/cmevs-erp-eval/resolve/main/blender_indoor.tar",
+      "encodingFormat": "application/x-tar",
+      "sha256": "TODO_SHA256"
+    },
+    {
+      "@type": "cr:FileSet",
+      "@id": "blender-indoor-rgb",
+      "name": "blender-indoor-rgb",
+      "containedIn": {
+        "@id": "blender-indoor-archive.tar"
+      },
+      "encodingFormat": "image/png",
+      "includes": "rgb/*.png"
+    },
+    {
+      "@type": "cr:FileSet",
+      "@id": "blender-indoor-depth",
+      "name": "blender-indoor-depth",
+      "containedIn": {
+        "@id": "blender-indoor-archive.tar"
+      },
+      "encodingFormat": "application/octet-stream",
+      "includes": "depth/*.npy"
+    },
+    {
+      "@type": "cr:FileSet",
+      "@id": "blender-indoor-pose",
+      "name": "blender-indoor-pose",
+      "containedIn": {
+        "@id": "blender-indoor-archive.tar"
+      },
+      "encodingFormat": "application/json",
+      "includes": "pose/*.json"
+    },
+    {
+      "@type": "cr:FileSet",
+      "@id": "blender-indoor-metadata",
+      "name": "blender-indoor-metadata",
+      "containedIn": {
+        "@id": "blender-indoor-archive.tar"
+      },
+      "encodingFormat": "application/json",
+      "includes": "metadata/*.json*"
+    },
+    {
+      "@type": "cr:FileObject",
+      "@id": "outdoor-tartanground-adapter.tar",
+      "name": "outdoor-tartanground-adapter.tar",
+      "contentUrl": "https://huggingface.co/datasets/anon-cmevs-2026/cmevs-erp-eval/resolve/main/outdoor_tartanground_adapter.tar",
+      "encodingFormat": "application/x-tar",
+      "sha256": "TODO_SHA256"
+    },
+    {
+      "@type": "cr:FileObject",
+      "@id": "outdoor-ob3d-adapter.tar",
+      "name": "outdoor-ob3d-adapter.tar",
+      "contentUrl": "https://huggingface.co/datasets/anon-cmevs-2026/cmevs-erp-eval/resolve/main/outdoor_ob3d_adapter.tar",
+      "encodingFormat": "application/x-tar",
+      "sha256": "TODO_SHA256"
+    },
+    {
+      "@type": "cr:FileObject",
+      "@id": "hm3d-adapter.tar",
+      "name": "hm3d-adapter.tar",
+      "contentUrl": "https://huggingface.co/datasets/anon-cmevs-2026/cmevs-erp-eval/resolve/main/hm3d_adapter.tar",
+      "encodingFormat": "application/x-tar",
+      "sha256": "TODO_SHA256"
+    },
+    {
+      "@type": "cr:FileObject",
+      "@id": "scannetpp-adapter.tar",
+      "name": "scannetpp-adapter.tar",
+      "contentUrl": "https://huggingface.co/datasets/anon-cmevs-2026/cmevs-erp-eval/resolve/main/scannetpp_adapter.tar",
+      "encodingFormat": "application/x-tar",
+      "sha256": "TODO_SHA256"
+    },
+    {
+      "@type": "cr:FileObject",
+      "@id": "curator-source-code.tar",
+      "name": "curator-source-code.tar",
+      "contentUrl": "https://huggingface.co/datasets/anon-cmevs-2026/cmevs-erp-eval/resolve/main/code.tar",
+      "encodingFormat": "application/x-tar",
+      "sha256": "TODO_SHA256"
+    },
+    {
+      "@type": "cr:FileObject",
+      "@id": "documentation.tar",
+      "name": "documentation.tar",
+      "contentUrl": "https://huggingface.co/datasets/anon-cmevs-2026/cmevs-erp-eval/resolve/main/docs.tar",
+      "encodingFormat": "application/x-tar",
+      "sha256": "TODO_SHA256"
+    },
+    {
+      "@type": "cr:FileObject",
+      "@id": "frame-manifest.csv",
+      "name": "frame-manifest.csv",
+      "contentUrl": "https://huggingface.co/datasets/anon-cmevs-2026/cmevs-erp-eval/resolve/main/frame_manifest.csv",
+      "encodingFormat": "text/csv",
+      "sha256": "TODO_SHA256"
+    }
+  ],
+  "recordSet": [
+    {
+      "@type": "cr:RecordSet",
+      "@id": "erp-frame-records",
+      "name": "erp-frame-records",
+      "description": "One record per released ERP frame. Curator-only fields (viewpoint_score, coverage_gain, conflict_ratio, candidate_id) are populated only for frames produced by the depth-conflict-aware curator; outdoor re-encoded frames carry the schema fields without per-step provenance.",
+      "field": [
+        {
+          "@type": "cr:Field",
+          "@id": "erp-frame-records/frame_id",
+          "name": "frame_id",
+          "dataType": "sc:Text",
+          "source": {
+            "fileObject": {
+              "@id": "frame-manifest.csv"
+            },
+            "extract": {
+              "column": "frame_id"
+            }
+          }
+        },
+        {
+          "@type": "cr:Field",
+          "@id": "erp-frame-records/source",
+          "name": "source",
+          "dataType": "sc:Text",
+          "source": {
+            "fileObject": {
+              "@id": "frame-manifest.csv"
+            },
+            "extract": {
+              "column": "source"
+            }
+          }
+        },
+        {
+          "@type": "cr:Field",
+          "@id": "erp-frame-records/scene_id",
+          "name": "scene_id",
+          "dataType": "sc:Text",
+          "source": {
+            "fileObject": {
+              "@id": "frame-manifest.csv"
+            },
+            "extract": {
+              "column": "scene_id"
+            }
+          }
+        },
+        {
+          "@type": "cr:Field",
+          "@id": "erp-frame-records/room_id",
+          "name": "room_id",
+          "dataType": "sc:Text",
+          "source": {
+            "fileObject": {
+              "@id": "frame-manifest.csv"
+            },
+            "extract": {
+              "column": "room_id"
+            }
+          }
+        },
+        {
+          "@type": "cr:Field",
+          "@id": "erp-frame-records/split",
+          "name": "split",
+          "dataType": "sc:Text",
+          "source": {
+            "fileObject": {
+              "@id": "frame-manifest.csv"
+            },
+            "extract": {
+              "column": "split"
+            }
+          }
+        },
+        {
+          "@type": "cr:Field",
+          "@id": "erp-frame-records/rgb",
+          "name": "rgb",
+          "dataType": "sc:ImageObject",
+          "source": {
+            "fileObject": {
+              "@id": "frame-manifest.csv"
+            },
+            "extract": {
+              "column": "rgb_path"
+            }
+          }
+        },
+        {
+          "@type": "cr:Field",
+          "@id": "erp-frame-records/depth",
+          "name": "depth",
+          "dataType": "sc:Text",
+          "source": {
+            "fileObject": {
+              "@id": "frame-manifest.csv"
+            },
+            "extract": {
+              "column": "depth_path"
+            }
+          }
+        },
+        {
+          "@type": "cr:Field",
+          "@id": "erp-frame-records/pose_quaternion",
+          "name": "pose_quaternion",
+          "dataType": "sc:Text",
+          "source": {
+            "fileObject": {
+              "@id": "frame-manifest.csv"
+            },
+            "extract": {
+              "column": "pose_quaternion"
+            }
+          }
+        },
+        {
+          "@type": "cr:Field",
+          "@id": "erp-frame-records/pose_position",
+          "name": "pose_position",
+          "dataType": "sc:Text",
+          "source": {
+            "fileObject": {
+              "@id": "frame-manifest.csv"
+            },
+            "extract": {
+              "column": "pose_position"
+            }
+          }
+        },
+        {
+          "@type": "cr:Field",
+          "@id": "erp-frame-records/camera_type",
+          "name": "camera_type",
+          "dataType": "sc:Text",
+          "source": {
+            "fileObject": {
+              "@id": "frame-manifest.csv"
+            },
+            "extract": {
+              "column": "camera_type"
+            }
+          }
+        },
+        {
+          "@type": "cr:Field",
+          "@id": "erp-frame-records/viewpoint_score",
+          "name": "viewpoint_score",
+          "dataType": "sc:Float",
+          "source": {
+            "fileObject": {
+              "@id": "frame-manifest.csv"
+            },
+            "extract": {
+              "column": "viewpoint_score"
+            }
+          }
+        },
+        {
+          "@type": "cr:Field",
+          "@id": "erp-frame-records/coverage_gain",
+          "name": "coverage_gain",
+          "dataType": "sc:Float",
+          "source": {
+            "fileObject": {
+              "@id": "frame-manifest.csv"
+            },
+            "extract": {
+              "column": "coverage_gain"
+            }
+          }
+        },
+        {
+          "@type": "cr:Field",
+          "@id": "erp-frame-records/conflict_ratio",
+          "name": "conflict_ratio",
+          "dataType": "sc:Float",
+          "source": {
+            "fileObject": {
+              "@id": "frame-manifest.csv"
+            },
+            "extract": {
+              "column": "conflict_ratio"
+            }
+          }
+        },
+        {
+          "@type": "cr:Field",
+          "@id": "erp-frame-records/candidate_id",
+          "name": "candidate_id",
+          "dataType": "sc:Text",
+          "source": {
+            "fileObject": {
+              "@id": "frame-manifest.csv"
+            },
+            "extract": {
+              "column": "candidate_id"
+            }
+          }
+        }
+      ]
+    }
+  ],
+  "rai:dataCollection": "Indoor data is produced by the CM-EVS pipeline (asset loading, coordinate normalization, candidate generation, 26-direction geometric-validity filtering, conflict-aware greedy selection, 2048x1024 high-resolution Cycles ERP rendering, export under the unified schema). Outdoor data is sourced from TartanGround and OB3D and re-encoded into the unified schema; the curator is not run on outdoor sources in v1.0. HM3D and ScanNet++ frames are not redistributed; the release ships adapter regeneration scripts.",
+  "rai:dataPreprocessingProtocol": "Coordinate normalization to a right-handed +X-right, +Y-up, +Z-forward world frame with the OpenCV-style camera frame; pose stored as a scalar-first world-to-camera quaternion plus a position relative to the scene's first selected frame. AABB computation; source-specific candidate generation; 26-direction geometric-validity filter. Cubemap-to-ERP re-encoding at native resolution for outdoor sources; optional exposure adjustment for Blender; output schema conversion. Candidate probes, intermediate caches, pre-render-all oracle frames, and locally regenerated HM3D / ScanNet++ outputs are excluded from the public frame count F_pub.",
+  "rai:dataAnnotationProtocol": "No human annotation is performed. All labels (split, source, scene id, viewpoint score, coverage gain, conflict ratio) are produced automatically by the curator pipeline and recorded in metadata/per_step_log.jsonl and metadata/selected_viewpoints.json.",
+  "rai:dataReleaseMaintenancePlan": "Versioned releases on a 6-month cadence. Errata tracked via the project repository; SHA256 manifests refreshed at every release; HM3D and ScanNet++ regeneration scripts updated when upstream APIs, file layouts, or access terms change.",
+  "rai:dataUseCases": [
+    "Panoramic depth estimation",
+    "ERP novel-view synthesis",
+    "Panoramic Gaussian-splatting reconstruction",
+    "Panoramic world-model pretraining",
+    "Fixed-budget viewpoint policy evaluation"
+  ],
+  "rai:dataLimitations": [
+    "Real-scan derived frames (HM3D, ScanNet++) are not redistributed; users must accept upstream license terms and regenerate locally.",
+    "Outdoor frames are re-encoded source trajectories rather than curator-selected subsets and therefore do not carry per-step provenance.",
+    "Synthetic-real transfer must be validated separately by source; we do not claim Blender-only gains imply real-scan gains.",
+    "Geometry-validity filters may fail in atria, semi-outdoor spaces, narrow transitions, noisy scans, or pure point-cloud scenes."
+  ],
+  "rai:personalSensitiveInformation": "No new personal data is collected. Real-scan sources (HM3D, ScanNet++) may depict private indoor layouts and are not redistributed as derived frames. Even regeneration scripts and viewpoint metadata can reveal where observations would be sampled within a private space; users must comply with upstream source access terms.",
+  "rai:dataBiases": [
+    "Source assets inherit geographic, architectural, and scanning biases.",
+    "HM3D and ScanNet++ are skewed toward scanned residential indoor spaces.",
+    "Blender assets are skewed toward staged residential, office, and architectural scenes.",
+    "Outdoor sources (TartanGround, OB3D) are skewed toward simulator-generated terrain along circular trajectories.",
+    "Synthetic Blender materials may not match real-scan sensor noise."
+  ],
+  "rai:dataSocialImpact": "CM-EVS lowers the engineering cost of producing auditable panoramic RGB-D resources from existing 3D scenes. Positive uses include panoramic perception, data-centric evaluation, view-planning research, and 3D-consistent world-model pretraining. Potential harms include over-trusting synthetic data, obscuring upstream dataset bias, and using real indoor scans in privacy-sensitive settings. The release therefore separates public synthetic frames from licensed real-scan regeneration and documents intended uses, non-uses, and source licenses."
+}

dataset_metadata/manifests_h100/ARCHIVE_DIGESTS.txt

@@ -0,0 +1,6 @@
+74e54654e43a6faa89ca4e50aec00a8e0366cdb3207ae16ee2c5efb1d2be70c1  SHA256SUMS_blender_indoor_round1+2.txt
+8cda976ce5a9180cf03bda4408ccf921d4ba295eb6ea1b31d66f76bdde398679  SHA256SUMS_blender_indoor_round2.txt
+7b7a42ab4aae6c22764d1447bfe35cb7210fd11d1b306497131058736f05e20e  SHA256SUMS_HM3D.txt
+60ecb00e2063f6efacc9408137fda5a73a4ac61647bd3cf8c32cc1e31839bc6f  SHA256SUMS_scannetpp.txt
+5e0285d4a3c472fee245501abb9be92ce0dada5f361cad1253bb51ded6e89f99  SHA256SUMS_OB3D.txt
+b13e68a7e6ff7ced448e841649f84d0fc6d7a4fe96c120150e42bffbdf2f06bf  SHA256SUMS_tartanground.txt

dataset_metadata/manifests_h100/README.md

@@ -0,0 +1,104 @@
+# H100 数据快照 SHA256 清单
+
+> 生成时间：2026-05-02 06:48 UTC（H100 节点 `node96`）
+> 数据根：`/data/data_wr/data_shushu/` (7 TB 数据盘)
+> **范围：仅包含本论文相关的 6 个数据子目录**
+
+---
+
+## 这些清单是什么
+
+这是 H100 上**本论文相关数据**的逐文件 SHA-256 留底。每行格式：
+
+```
+<sha256-hex>  <relative-path-from-data-root>
+```
+
+可用 `shasum -a 256 -c` / `sha256sum -c` 在数据所在机器上原地校验。
+
+`ARCHIVE_DIGESTS.txt` 是每份 `SHA256SUMS_*.txt` 自身的 SHA-256，作为各 archive 的"内容指纹"。
+
+---
+
+## 论文 → H100 数据映射
+
+V4 §4.3 表 4 列出 5 个数据来源；H100 上 Blender indoor 因为采样轮次不同分成两个目录存放：
+
+| 论文来源（V4 §4.3） | V4 声称规模 | H100 子目录 | 实际数量（manifest 行数 = 文件数）|
+| --- | --- | --- | --- |
+| **Blender indoor**（CC-BY 4.0）| 326 场景 / 11,583 帧 | `combined/blender_indoor_FOU_threshold-0.2_round1+2`（第 1 轮 + 第 1+2 轮合并）| 19,271 |
+| | | `combined/blender_indoor_FOU_threshold-0.2_round2`（第 2 轮独立提取）| 20,673 |
+| **HM3D**（adapter，不再分发）| 401 rooms / 14,475 帧 | `combined/HM3D` | 43,431 |
+| **ScanNet++**（adapter，不再分发）| 500 scans / 8,267 帧 | `combined/scannetpp_threshold0.2` | 24,801 |
+| **OB3D**（户外，按上游许可）| 12 场景 / 2,400 帧 | `continuous/OB3D_shushu`（12 场景 × 2 视角 = 24 份）| 7,246 |
+| **TartanGround**（户外，**不再分发**）| 63 environments / 783,944 帧 | `continuous/Tartanground`（11 个环境，762 parts；其余环境仍在用户本地）| 342,064 |
+
+**Blender 只有室内**，没有 outdoor — 论文中的 outdoor 部分由 TartanGround + OB3D 提供。
+
+---
+
+## 为什么没有写到 `croissant.json`
+
+`croissant.json` 里 `cr:FileObject.sha256` 字段的语义是：**用户从 `contentUrl` 下载到的 .tar 文件的 SHA-256**。我们目前还**没有**把数据打包成最终发布 archive，因此那些字段保持 `TODO_SHA256` 占位。
+
+H100 上的目录结构与 `croissant.json` 里的发布产物**不是一一对应**：
+
+- `blender-indoor-archive.tar` 应是 **curator 筛选过的 11,583 帧 / 326 场景**，需要从 `round1+2` 与 `round2` 两个 H100 子目录中合并去重 + curator 选帧后再 tar，**这一步还没做**。
+- `*-adapter.tar`（HM3D / ScanNet++ / TartanGround / OB3D）应是 **adapter 脚本 + 元数据包**，**不**包含数据帧。脚本目前在 `cmevs_anonymous_code_release/scripts/` + `adapters/` 下，也还没单独打包成 tar。
+
+这里的 SHA256SUMS 只是当前 H100 数据状态的"内部留底"，**不会上传到 HF / OpenReview**，仅供你后续：
+- 增量补 TartanGround 时比对哪些 part 已处理
+- 重组 / 重新打包发布 archive 时确认源数据没被改动
+
+---
+
+## 何时把哈希填进 `croissant.json`
+
+当你**实际打包发布 archive** 后：
+
+```bash
+# 1. 在打包好的 .tar 上重算
+shasum -a 256 blender_indoor_v1.tar
+# 2. 把哈希写入 croissant.json 中 blender-indoor-archive.tar 的 sha256 字段
+#    或运行：tools/update_croissant_with_real_hashes.py
+```
+
+reviewer 下载验证时用的就是这个哈希。
+
+---
+
+## 文件清单
+
+| 文件 | 行数（=文件数）| 大小 | H100 路径 |
+| --- | ---: | ---: | --- |
+| `ARCHIVE_DIGESTS.txt` | 6 | 568 B | `~/cmevs_release_hashing/manifests/` |
+| `SHA256SUMS_blender_indoor_round1+2.txt` | 19,271 | 2.9 MB | `combined/blender_indoor_FOU_threshold-0.2_round1+2` |
+| `SHA256SUMS_blender_indoor_round2.txt` | 20,673 | 3.0 MB | `combined/blender_indoor_FOU_threshold-0.2_round2` |
+| `SHA256SUMS_HM3D.txt` | 43,431 | 5.2 MB | `combined/HM3D` |
+| `SHA256SUMS_scannetpp.txt` | 24,801 | 3.0 MB | `combined/scannetpp_threshold0.2` |
+| `SHA256SUMS_OB3D.txt` | 7,246 | 930 KB | `continuous/OB3D_shushu` |
+| `SHA256SUMS_tartanground.txt` | 342,064 | 47 MB | `continuous/Tartanground` |
+
+合计：**457,486 行**（一行 = 一个文件的 sha256），约 **62 MB**（不含 README）。
+
+---
+
+## 排除的目录
+
+H100 数据根下还有以下子目录，但**与本论文无关**，因此**未生成 manifest**：
+
+- `combined/data_离散_1m间距` — 1m 间距实验性采样，未进入论文最终发布
+- `continuous/shushu_line_连续` — 室内连续直线轨迹，未进入论文
+- `continuous/shushu_circle_连续` — 室内连续圆形轨迹，未进入论文
+- `Robustness/` — 鲁棒性评估数据（洋红坏帧筛选用），未进入论文
+
+如果未来这些目录进入发布范围，再单独跑 `~/cmevs_release_hashing/run_hashes.sh` 补哈希即可。
+
+---
+
+## 上游许可重要说明
+
+- **TartanGround 不再分发为 ERP 重新编码帧**——与 V4 §4.2 表 3 `Direct release: no` 一致。这里的 sha256 仅作 H100 内部留底；最终发布只发 adapter 脚本 + 场景 id + 元数据。
+- **HM3D / ScanNet++ 同理**：上游 EULA / ToS 不允许再分发衍生 RGB-D 帧。
+- **OB3D**：��上游许可范围内可再分发；具体由发布前的许可核查决定。
+- **可直接发布的部分**：仅 Blender indoor（CC-BY 4.0 资产渲染）。

dataset_metadata/manifests_h100/SHA256SUMS_tartanground.txt

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

environment.yml

@@ -0,0 +1,25 @@
+name: cmevs
+channels:
+  - pytorch
+  - nvidia
+  - conda-forge
+dependencies:
+  - python=3.10
+  - pip
+  - numpy>=1.24
+  - scipy
+  - pandas
+  - pyyaml
+  - pillow
+  - matplotlib
+  - scikit-learn
+  - pytorch
+  - torchvision
+  - cudatoolkit
+  - pip:
+      - opencv-python
+      - open3d
+      - trimesh
+      - tqdm
+      - jsonschema
+

examples/metadata/candidates.jsonl

@@ -0,0 +1,7 @@
+{"candidate_id":"tiny_000","source":"blender_indoor_tiny","scene_id":"tiny_blend_scene","position":[0.0,1.6,0.0],"yaw_deg":0.0,"valid":true,"rejection_layer":"accepted","single_view_probe_coverage":0.31,"conflict_prior":0.05,"covered_cells":["a","b","c","d"],"oracle_gain":0.30,"runtime_s":0.02}
+{"candidate_id":"tiny_001","source":"blender_indoor_tiny","scene_id":"tiny_blend_scene","position":[1.0,1.6,0.0],"yaw_deg":45.0,"valid":true,"rejection_layer":"accepted","single_view_probe_coverage":0.34,"conflict_prior":0.12,"covered_cells":["c","d","e","f","g"],"oracle_gain":0.28,"runtime_s":0.02}
+{"candidate_id":"tiny_002","source":"blender_indoor_tiny","scene_id":"tiny_blend_scene","position":[2.0,1.6,0.5],"yaw_deg":90.0,"valid":true,"rejection_layer":"accepted","single_view_probe_coverage":0.27,"conflict_prior":0.02,"covered_cells":["h","i","j"],"oracle_gain":0.24,"runtime_s":0.02}
+{"candidate_id":"tiny_003","source":"blender_indoor_tiny","scene_id":"tiny_blend_scene","position":[0.5,1.6,1.5],"yaw_deg":135.0,"valid":true,"rejection_layer":"accepted","single_view_probe_coverage":0.22,"conflict_prior":0.18,"covered_cells":["a","k","l"],"oracle_gain":0.16,"runtime_s":0.02}
+{"candidate_id":"tiny_004","source":"blender_indoor_tiny","scene_id":"tiny_blend_scene","position":[1.5,1.6,1.5],"yaw_deg":180.0,"valid":true,"rejection_layer":"accepted","single_view_probe_coverage":0.29,"conflict_prior":0.06,"covered_cells":["m","n","o","p"],"oracle_gain":0.26,"runtime_s":0.02}
+{"candidate_id":"tiny_005","source":"blender_indoor_tiny","scene_id":"tiny_blend_scene","position":[3.0,1.6,1.5],"yaw_deg":270.0,"valid":false,"rejection_layer":"visibility","single_view_probe_coverage":0.04,"conflict_prior":0.35,"covered_cells":[],"oracle_gain":0.01,"runtime_s":0.01}
+

examples/tiny_blender_scene/README.md

@@ -0,0 +1,5 @@
+# Tiny Example
+
+This directory intentionally contains no Blender asset. The tiny smoke test uses Blender-indoor-style metadata in `examples/metadata/candidates.jsonl` so that reviewers can run the repository without private or third-party scene data.
+
+For real rendering, place `.blend`, `.glb`, `.gltf`, or `.ply` scene files under `data/` and use the commands in the top-level README.

metadata_examples/candidates.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CM-EVS candidate metadata",
+  "type": "object",
+  "required": [
+    "candidate_id",
+    "source",
+    "scene_id",
+    "position",
+    "valid",
+    "single_view_probe_coverage",
+    "conflict_prior",
+    "covered_cells"
+  ],
+  "properties": {
+    "candidate_id": {"type": "string"},
+    "source": {"type": "string"},
+    "scene_id": {"type": "string"},
+    "position": {
+      "type": "array",
+      "items": {"type": "number"},
+      "minItems": 3,
+      "maxItems": 3
+    },
+    "yaw_deg": {"type": "number"},
+    "valid": {"type": "boolean"},
+    "rejection_layer": {"type": "string"},
+    "single_view_probe_coverage": {"type": "number"},
+    "conflict_prior": {"type": "number"},
+    "covered_cells": {
+      "type": "array",
+      "items": {"type": "string"}
+    },
+    "oracle_gain": {"type": "number"},
+    "runtime_s": {"type": "number"}
+  }
+}
+

metadata_examples/per_step_log.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CM-EVS per-step selection log",
+  "type": "object",
+  "required": ["step", "candidate_id", "score", "marginal_gain", "coverage_after"],
+  "properties": {
+    "step": {"type": "integer"},
+    "candidate_id": {"type": "string"},
+    "score": {"type": "number"},
+    "marginal_gain": {"type": "number"},
+    "coverage_after": {"type": "number"},
+    "conflict_prior": {"type": "number"}
+  }
+}
+

metadata_examples/selected_viewpoints.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CM-EVS selected viewpoints",
+  "type": "object",
+  "required": ["scene_id", "method", "selected_viewpoints", "summary"],
+  "properties": {
+    "scene_id": {"type": "string"},
+    "method": {"type": "string"},
+    "selected_viewpoints": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["candidate_id", "rank", "position", "yaw_deg"],
+        "properties": {
+          "candidate_id": {"type": "string"},
+          "rank": {"type": "integer"},
+          "position": {
+            "type": "array",
+            "items": {"type": "number"},
+            "minItems": 3,
+            "maxItems": 3
+          },
+          "yaw_deg": {"type": "number"},
+          "score": {"type": "number"},
+          "marginal_gain": {"type": "number"}
+        }
+      }
+    },
+    "summary": {"type": "object"}
+  }
+}
+

pipelines/get_blend_bounds.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""
+获取.blend文件的场景信息（相机位置、边界框）
+
+此脚本在Blender内部执行，用于获取.blend文件的场景信息。
+输出JSON格式的数据供batch_render.py使用。
+
+智能检测策略：
+1. 如果场景中有相机，使用相机位置作为第一帧参考
+2. 如果没有相机，使用室内对象（Floor、Wall、Room等）的边界框计算中心
+
+使用方法:
+    blender --background --python get_blend_bounds.py -- \
+        --blend "path/to/scene.blend"
+
+输出格式:
+    [BOUNDS] {"bounds_min": [...], "bounds_max": [...], "center": [...], "camera": {...}}
+"""
+
+import bpy
+import sys
+import json
+import argparse
+from mathutils import Vector
+
+
+# 室内对象关键词
+INDOOR_KEYWORDS = [
+    'room', 'interior', 'floor', 'wall', 'ceiling', 'indoor',
+    'kitchen', 'bathroom', 'bedroom', 'living', 'dining',
+    'door', 'window', 'lamp', 'light', 'sofa', 'table', 'chair',
+    'bed', 'desk', 'cabinet', 'shelf', 'carpet', 'curtain',
+    'stair', 'corridor', 'hallway', 'closet', 'wardrobe'
+]
+
+
+def parse_args():
+    """解析命令行参数"""
+    argv = sys.argv
+    if "--" in argv:
+        argv = argv[argv.index("--") + 1:]
+    else:
+        argv = []
+    
+    parser = argparse.ArgumentParser(description="获取.blend文件场景信息")
+    parser.add_argument("--blend", type=str, required=True,
+                        help=".blend文件路径")
+    
+    return parser.parse_args(argv)
+
+
+def is_indoor_object(obj_name):
+    """判断对象是否是室内对象"""
+    name_lower = obj_name.lower()
+    return any(kw in name_lower for kw in INDOOR_KEYWORDS)
+
+
+def get_scene_cameras():
+    """
+    获取场景中的所有相机
+    
+    Returns:
+        cameras: 相机信息列表 [{"name": str, "position": [x,y,z], "rotation": [x,y,z]}, ...]
+    """
+    cameras = []
+    for obj in bpy.context.scene.objects:
+        if obj.type == 'CAMERA':
+            loc = obj.location
+            rot = obj.rotation_euler
+            cameras.append({
+                "name": obj.name,
+                "position": [loc.x, loc.y, loc.z],
+                "rotation": [rot.x, rot.y, rot.z]
+            })
+    return cameras
+
+
+def get_scene_bounds(indoor_only=True):
+    """
+    获取场景中mesh物体的边界框（Blender坐标系：X右, Y前, Z上）
+    
+    Args:
+        indoor_only: 是否仅考虑室内对象（默认True）
+    
+    Returns:
+        bounds_min: 边界框最小坐标 [x, y, z]
+        bounds_max: 边界框最大坐标 [x, y, z]
+        center: 几何中心 [x, y, z]
+        indoor_count: 室内对象数量
+    """
+    min_coords = [float('inf'), float('inf'), float('inf')]
+    max_coords = [float('-inf'), float('-inf'), float('-inf')]
+    
+    mesh_count = 0
+    indoor_count = 0
+    
+    for obj in bpy.context.scene.objects:
+        if obj.type == 'MESH':
+            mesh_count += 1
+            
+            # 如果启用室内过滤，检查对象名称
+            if indoor_only and not is_indoor_object(obj.name):
+                continue
+            
+            indoor_count += 1
+            
+            # 获取世界坐标下的边界框
+            for corner in obj.bound_box:
+                world_corner = obj.matrix_world @ Vector(corner)
+                for i in range(3):
+                    min_coords[i] = min(min_coords[i], world_corner[i])
+                    max_coords[i] = max(max_coords[i], world_corner[i])
+    
+    # 如果没有找到任何符合条件的mesh
+    if min_coords[0] == float('inf'):
+        if indoor_only:
+            print(f"[WARN] 未找到室内对象，回退到全场景边界框", file=sys.stderr)
+            return get_scene_bounds(indoor_only=False)
+        else:
+            print(f"[WARN] 未找到任何mesh对象，使用默认边界框", file=sys.stderr)
+            min_coords = [-5, -5, 0]
+            max_coords = [5, 5, 3]
+            indoor_count = 0
+    
+    # 计算几何中心
+    center = [
+        (min_coords[0] + max_coords[0]) / 2,
+        (min_coords[1] + max_coords[1]) / 2,
+        (min_coords[2] + max_coords[2]) / 2
+    ]
+    
+    mode_str = "室内对象" if indoor_only else "全场景"
+    print(f"[INFO] 边界框模式: {mode_str}", file=sys.stderr)
+    print(f"[INFO] 找到 {indoor_count}/{mesh_count} 个对象", file=sys.stderr)
+    print(f"[INFO] 边界框: min={[f'{x:.2f}' for x in min_coords]}, max={[f'{x:.2f}' for x in max_coords]}", file=sys.stderr)
+    print(f"[INFO] 几何中心: [{center[0]:.2f}, {center[1]:.2f}, {center[2]:.2f}]", file=sys.stderr)
+    
+    return min_coords, max_coords, center, indoor_count
+
+
+def main():
+    args = parse_args()
+    
+    print(f"[INFO] 打开.blend文件: {args.blend}", file=sys.stderr)
+    
+    # 打开.blend文件
+    bpy.ops.wm.open_mainfile(filepath=args.blend)
+    
+    # 1. 检测场景中的相机
+    cameras = get_scene_cameras()
+    print(f"[INFO] 检测到 {len(cameras)} 个相机", file=sys.stderr)
+    
+    camera_info = None
+    first_frame_position = None
+    position_source = "none"
+    
+    if cameras:
+        # 使用第一个相机的位置作为参考
+        cam = cameras[0]
+        camera_info = cam
+        first_frame_position = cam["position"]
+        position_source = "camera"
+        print(f"[INFO] 使用相机 '{cam['name']}' 的位置作为第一帧参考", file=sys.stderr)
+        print(f"[INFO] 相机位置: [{cam['position'][0]:.2f}, {cam['position'][1]:.2f}, {cam['position'][2]:.2f}]", file=sys.stderr)
+    
+    # 2. 获取室内对象边界框
+    bounds_min, bounds_max, center, indoor_count = get_scene_bounds(indoor_only=True)
+    
+    # 如果没有相机，使用室内边界框中心
+    if first_frame_position is None:
+        first_frame_position = center
+        position_source = "indoor_bounds_center"
+        print(f"[INFO] 无相机，使用室内边界框中心作为第一帧位置", file=sys.stderr)
+    
+    # 3. 获取场景单位比例（用于将米转换为场景单位）
+    unit_scale = bpy.context.scene.unit_settings.scale_length
+    unit_system = bpy.context.scene.unit_settings.system
+    print(f"[INFO] 场景单位: scale={unit_scale}, system={unit_system}", file=sys.stderr)
+    
+    # 输出JSON格式（供batch_render.py解析）
+    result = {
+        "bounds_min": bounds_min,
+        "bounds_max": bounds_max,
+        "center": center,
+        "first_frame_position": first_frame_position,
+        "position_source": position_source,
+        "camera": camera_info,
+        "cameras_count": len(cameras),
+        "indoor_objects_count": indoor_count,
+        "unit_scale": unit_scale,  # 用于米->场景单位转换
+        "coordinate_system": "blender_z_up"  # X右, Y前, Z上
+    }
+    
+    # 使用特殊前缀，便于batch_render.py解析
+    print(f"[BOUNDS] {json.dumps(result)}")
+
+
+if __name__ == "__main__":
+    main()

pipelines/render_erp_blender.py

@@ -0,0 +1,1015 @@
+#!/usr/bin/env python3
+"""
+Blender ERP全景图渲染脚本
+
+此脚本在Blender内部执行，用于渲染ERP（等距圆柱投影）全景图。
+
+使用方法:
+    blender --background --python render_erp_blender.py -- \
+        --mesh "path/to/mesh.glb" \
+        --output "output/panorama_0000.png" \
+        --camera-pos "0.0,0.5,0.0" \
+        --camera-rot "0.0,0.0,0.0" \
+        --resolution "1024,512"
+"""
+
+import bpy
+import sys
+import os
+import json
+import math
+import argparse
+from mathutils import Vector, Euler, Quaternion
+
+
+def parse_args():
+    """解析命令行参数（Blender的--之后的参数）"""
+    # 找到'--'之后的参数
+    argv = sys.argv
+    if "--" in argv:
+        argv = argv[argv.index("--") + 1:]
+    else:
+        argv = []
+    
+    parser = argparse.ArgumentParser(description="Blender ERP渲染脚本")
+    parser.add_argument("--mesh", type=str, required=True,
+                        help="输入mesh文件路径（GLB/GLTF/OBJ）")
+    parser.add_argument("--output", type=str, required=True,
+                        help="输出图像路径")
+    parser.add_argument("--pose-output", type=str, default=None,
+                        help="输出位姿JSON路径（默认与图像同名）")
+    parser.add_argument("--camera-pos", type=str, default="0.0,0.0,0.0",
+                        help="相机位置 x,y,z")
+    parser.add_argument("--camera-rot", type=str, default="0.0,0.0,0.0",
+                        help="相机旋转 roll,pitch,yaw（弧度）")
+    parser.add_argument("--camera-rot-quat", type=str, default=None,
+                        help="（已废弃）相机旋转四元数 w,x,y,z。现在主路径使用 --camera-rot Euler角")
+    parser.add_argument("--resolution", type=str, default="1024,512",
+                        help="渲染分辨率 width,height")
+    parser.add_argument("--samples", type=int, default=16,
+                        help="渲染采样数（默认16，Emission材质不需要高采样，可大幅提升渲染速度）")
+    parser.add_argument("--engine", type=str, default="CYCLES",
+                        choices=["BLENDER_EEVEE", "CYCLES"],
+                        help="渲染引擎（全景图必须使用CYCLES）")
+    parser.add_argument("--frame-id", type=int, default=0,
+                        help="帧序号")
+    parser.add_argument("--ref-position", type=str, default=None,
+                        help="参考帧位置 x,y,z（Y-up坐标系），None表示第一帧")
+    parser.add_argument("--ref-quaternion", type=str, default=None,
+                        help="参考帧四元数 w,x,y,z，None表示第一帧")
+    parser.add_argument("--render-depth", action="store_true",
+                        help="是否渲染深度图（保存为.npy格式）")
+    parser.add_argument("--depth-output", type=str, default=None,
+                        help="深度图输出路径（默认与图像同目录，后缀_depth.npy）")
+    
+    return parser.parse_args(argv)
+
+
+def clear_scene():
+    """清空当前场景"""
+    # 选择所有对象
+    bpy.ops.object.select_all(action='SELECT')
+    # 删除选中的对象
+    bpy.ops.object.delete(use_global=False)
+    
+    # 清理孤立数据
+    for block in bpy.data.meshes:
+        if block.users == 0:
+            bpy.data.meshes.remove(block)
+    for block in bpy.data.materials:
+        if block.users == 0:
+            bpy.data.materials.remove(block)
+    for block in bpy.data.textures:
+        if block.users == 0:
+            bpy.data.textures.remove(block)
+    for block in bpy.data.images:
+        if block.users == 0:
+            bpy.data.images.remove(block)
+
+
+def import_mesh(mesh_path):
+    """导入mesh文件"""
+    ext = os.path.splitext(mesh_path)[1].lower()
+    
+    if ext in ['.glb', '.gltf']:
+        bpy.ops.import_scene.gltf(filepath=mesh_path)
+    elif ext == '.obj':
+        bpy.ops.wm.obj_import(filepath=mesh_path)
+    elif ext == '.fbx':
+        bpy.ops.import_scene.fbx(filepath=mesh_path)
+    elif ext == '.ply':
+        bpy.ops.wm.ply_import(filepath=mesh_path)
+    else:
+        raise ValueError(f"不支持的文件格式: {ext}")
+    
+    print(f"[INFO] 导入mesh: {mesh_path}")
+    
+    # 获取导入的对象
+    imported_objects = [obj for obj in bpy.context.selected_objects]
+    print(f"[INFO] 导入了 {len(imported_objects)} 个对象")
+    
+    # 为房间结构添加程序化纹理
+    apply_procedural_textures(imported_objects)
+    
+    return imported_objects
+
+
+def is_room_structure(obj_name):
+    """
+    判断对象是否是房间结构（墙面、地板、天花板）
+    
+    房间结构的常见命名模式：
+    1. None.obj - 标准3D-Front房间结构
+    2. geometry_N - 无纹理的通用几何体
+    3. 纯数字.obj (如 12670.obj) - 数字ID命名的结构
+    """
+    name_lower = obj_name.lower()
+    
+    # 模式1: 包含 "none"
+    if 'none' in name_lower:
+        return True
+    
+    # 模式2: 以 "geometry_" 开头
+    if name_lower.startswith('geometry_') or name_lower.startswith('geometry.'):
+        return True
+    
+    # 模式3: 纯数字命名 (如 "12670.obj", "7319.obj")
+    base_name = obj_name.replace('.obj', '').replace('.OBJ', '')
+    if base_name.isdigit():
+        return True
+    
+    return False
+
+
+def apply_procedural_textures(objects):
+    """为所有对象添加Emission材质（材质预览模式：显示原始颜色，不受光照影响）"""
+    applied_count = 0
+    for obj in objects:
+        if obj.type != 'MESH':
+            continue
+        
+        # 检查对象是否有材质，或者材质是否为空
+        has_material = obj.data.materials and len(obj.data.materials) > 0 and obj.data.materials[0] is not None
+        
+        # 为所有对象应用Emission材质（材质预览模式）
+        # 这样所有对象都会显示原始颜色，不受光照影响
+        if not has_material or is_room_structure(obj.name):
+            # 没有材质或者是房间结构：应用Emission材质
+            print(f"[INFO] 为对象添加Emission材质: {obj.name}")
+            apply_room_material(obj)
+            applied_count += 1
+        else:
+            # 有材质：也转换为Emission材质（确保所有对象都使用Emission模式）
+            print(f"[INFO] 将对象材质转换为Emission: {obj.name}")
+            convert_to_emission_material(obj)
+            applied_count += 1
+    
+    if applied_count == 0:
+        print("[WARN] 未找到需要添加材质的对象")
+    else:
+        print(f"[INFO] 共为 {applied_count} 个对象添加了Emission材质（材质预览模式）")
+
+
+def apply_room_material(obj):
+    """为房间结构应用程序化材质（墙面、地板、天花板）"""
+    # 创建新材质
+    mat = bpy.data.materials.new(name="RoomProceduralMaterial")
+    mat.use_nodes = True
+    
+    nodes = mat.node_tree.nodes
+    links = mat.node_tree.links
+    
+    # 清除默认节点
+    nodes.clear()
+    
+    # 创建输出节点
+    output = nodes.new('ShaderNodeOutputMaterial')
+    output.location = (800, 0)
+    
+    # 使用几何节点获取法线
+    geometry = nodes.new('ShaderNodeNewGeometry')
+    geometry.location = (-600, 0)
+    
+    # 分离法线的Z分量
+    separate_xyz = nodes.new('ShaderNodeSeparateXYZ')
+    separate_xyz.location = (-400, 0)
+    links.new(geometry.outputs['Normal'], separate_xyz.inputs['Vector'])
+    
+    # === 判断天花板（法线Z < -0.5，朝下的面） ===
+    ceiling_check = nodes.new('ShaderNodeMath')
+    ceiling_check.operation = 'LESS_THAN'
+    ceiling_check.inputs[1].default_value = -0.5
+    ceiling_check.location = (-200, 100)
+    links.new(separate_xyz.outputs['Z'], ceiling_check.inputs[0])
+    
+    # === 判断地板（法线Z > 0.5，朝上的面） ===
+    floor_check = nodes.new('ShaderNodeMath')
+    floor_check.operation = 'GREATER_THAN'
+    floor_check.inputs[1].default_value = 0.5
+    floor_check.location = (-200, -100)
+    links.new(separate_xyz.outputs['Z'], floor_check.inputs[0])
+    
+    # === 创建三种材质 ===
+    floor_shader = create_wood_floor_material(nodes, links)
+    floor_shader.location = (0, 300)
+    
+    wall_shader = create_brick_wall_material(nodes, links)  # 砖墙材质
+    wall_shader.location = (0, 0)
+    
+    ceiling_shader = create_grid_ceiling_material(nodes, links)  # 网格天花板
+    ceiling_shader.location = (0, -300)
+    
+    # === 混合着色器：先混合地板和墙面 ===
+    mix_floor_wall = nodes.new('ShaderNodeMixShader')
+    mix_floor_wall.location = (300, 100)
+    links.new(floor_check.outputs['Value'], mix_floor_wall.inputs['Fac'])
+    links.new(wall_shader.outputs['Emission'], mix_floor_wall.inputs[1])  # Emission材质输出
+    links.new(floor_shader.outputs['Emission'], mix_floor_wall.inputs[2])  # Emission材质输出
+    
+    # === 混合着色器：再混合天花板 ===
+    mix_final = nodes.new('ShaderNodeMixShader')
+    mix_final.location = (500, 0)
+    links.new(ceiling_check.outputs['Value'], mix_final.inputs['Fac'])
+    links.new(mix_floor_wall.outputs['Shader'], mix_final.inputs[1])
+    links.new(ceiling_shader.outputs['Emission'], mix_final.inputs[2])  # Emission材质输出
+    
+    # 连接输出
+    links.new(mix_final.outputs['Shader'], output.inputs['Surface'])
+    
+    # 应用材质到对象
+    if obj.data.materials:
+        obj.data.materials[0] = mat
+    else:
+        obj.data.materials.append(mat)
+    
+    print(f"[INFO] Emission材质已应用（地板+砖墙+网格天花板，材质预览模式）")
+
+
+def convert_to_emission_material(obj):
+    """将现有材质转换为Emission材质（材质预览模式）"""
+    if not obj.data.materials or len(obj.data.materials) == 0:
+        # 如果没有材质，直接应用房间材质
+        apply_room_material(obj)
+        return
+    
+    # 获取现有材质
+    existing_mat = obj.data.materials[0]
+    if existing_mat is None:
+        apply_room_material(obj)
+        return
+    
+    # 如果���质已经有节点，尝试提取Base Color并转换为Emission
+    if existing_mat.use_nodes:
+        nodes = existing_mat.node_tree.nodes
+        links = existing_mat.node_tree.links
+        
+        # 查找Principled BSDF节点
+        bsdf_node = None
+        for node in nodes:
+            if node.type == 'BSDF_PRINCIPLED':
+                bsdf_node = node
+                break
+        
+        if bsdf_node and 'Base Color' in bsdf_node.inputs:
+            # 找到Base Color输入
+            base_color_input = bsdf_node.inputs['Base Color']
+            
+            # 创建Emission节点
+            emission = nodes.new('ShaderNodeEmission')
+            emission.name = "Emission"
+            emission.location = bsdf_node.location
+            
+            # 获取Base Color的值或连接
+            if base_color_input.is_linked:
+                # 如果有连接，连接到Emission
+                color_source = base_color_input.links[0].from_node
+                color_output = base_color_input.links[0].from_socket
+                links.new(color_output, emission.inputs['Color'])
+            else:
+                # 如果没有连接，使用默认值
+                emission.inputs['Color'].default_value = base_color_input.default_value
+            
+            emission.inputs['Strength'].default_value = 1.0  # Emission强度（材质预览模式，避免过曝）
+            
+            # 找到输出节点并连接
+            output_node = None
+            for node in nodes:
+                if node.type == 'OUTPUT_MATERIAL':
+                    output_node = node
+                    break
+            
+            if output_node:
+                # 断开原有连接
+                if output_node.inputs['Surface'].is_linked:
+                    for link in output_node.inputs['Surface'].links:
+                        existing_mat.node_tree.links.remove(link)
+                # 连接Emission
+                links.new(emission.outputs['Emission'], output_node.inputs['Surface'])
+                print(f"[INFO] 已将材质转换为Emission: {obj.name}")
+                return
+    
+    # 如果无法转换，直接应用房间材质
+    apply_room_material(obj)
+
+
+def create_wood_floor_material(nodes, links):
+    """创建木地板程序化材质（Emission模式，显示原始颜色）"""
+    # 使用Emission材质，直接发光，不受光照影响
+    emission = nodes.new('ShaderNodeEmission')
+    emission.name = "FloorEmission"
+    
+    # 木纹噪波纹理
+    noise = nodes.new('ShaderNodeTexNoise')
+    noise.inputs['Scale'].default_value = 20.0
+    noise.inputs['Detail'].default_value = 8.0
+    noise.inputs['Roughness'].default_value = 0.6
+    noise.location = (-600, 200)
+    
+    # 波浪纹理（模拟木纹条纹）
+    wave = nodes.new('ShaderNodeTexWave')
+    wave.wave_type = 'BANDS'
+    wave.bands_direction = 'X'
+    wave.inputs['Scale'].default_value = 3.0
+    wave.inputs['Distortion'].default_value = 5.0
+    wave.inputs['Detail'].default_value = 3.0
+    wave.location = (-600, 0)
+    
+    # 颜色渐变（木材颜色）
+    color_ramp = nodes.new('ShaderNodeValToRGB')
+    color_ramp.color_ramp.elements[0].color = (0.15, 0.08, 0.04, 1.0)  # 深棕色
+    color_ramp.color_ramp.elements[1].color = (0.35, 0.20, 0.10, 1.0)  # 浅棕色
+    color_ramp.location = (-400, 100)
+    
+    # 混合噪波和波浪
+    mix_rgb = nodes.new('ShaderNodeMix')
+    mix_rgb.data_type = 'RGBA'
+    mix_rgb.inputs['Factor'].default_value = 0.5
+    mix_rgb.location = (-400, 0)
+    
+    links.new(noise.outputs['Fac'], mix_rgb.inputs['A'])
+    links.new(wave.outputs['Fac'], mix_rgb.inputs['B'])
+    links.new(mix_rgb.outputs['Result'], color_ramp.inputs['Fac'])
+    
+    # 连接到Emission材质（直接显示颜色，不受光照影响）
+    links.new(color_ramp.outputs['Color'], emission.inputs['Color'])
+    emission.inputs['Strength'].default_value = 1.0  # Emission强度（材质预览模式，避免过曝）
+    
+    return emission
+
+
+def create_brick_wall_material(nodes, links):
+    """创建砖墙程序化材质（Emission模式，显示原始颜色）"""
+    # 使用Emission材质，直接发光，不受光照影响
+    emission = nodes.new('ShaderNodeEmission')
+    emission.name = "BrickWallEmission"
+    
+    # 使用纹理坐标
+    tex_coord = nodes.new('ShaderNodeTexCoord')
+    tex_coord.location = (-800, 0)
+    
+    # 缩放映射（控制砖块大小）
+    mapping = nodes.new('ShaderNodeMapping')
+    mapping.inputs['Scale'].default_value = (4.0, 8.0, 1.0)  # X方向砖块较宽
+    mapping.location = (-600, 0)
+    links.new(tex_coord.outputs['Generated'], mapping.inputs['Vector'])
+    
+    # 砖块纹理
+    brick = nodes.new('ShaderNodeTexBrick')
+    brick.inputs['Color1'].default_value = (0.6, 0.3, 0.2, 1.0)  # 砖红色
+    brick.inputs['Color2'].default_value = (0.5, 0.25, 0.15, 1.0)  # 深砖红色
+    brick.inputs['Mortar'].default_value = (0.85, 0.85, 0.8, 1.0)  # 灰白色砂浆
+    brick.inputs['Scale'].default_value = 3.0
+    brick.inputs['Mortar Size'].default_value = 0.02
+    brick.inputs['Mortar Smooth'].default_value = 0.1
+    brick.inputs['Bias'].default_value = 0.0
+    brick.inputs['Brick Width'].default_value = 0.5
+    brick.inputs['Row Height'].default_value = 0.25
+    brick.location = (-400, 0)
+    links.new(mapping.outputs['Vector'], brick.inputs['Vector'])
+    
+    # 添加细微噪波增加真实感
+    noise = nodes.new('ShaderNodeTexNoise')
+    noise.inputs['Scale'].default_value = 50.0
+    noise.inputs['Detail'].default_value = 3.0
+    noise.location = (-400, -200)
+    links.new(mapping.outputs['Vector'], noise.inputs['Vector'])
+    
+    # 混合砖块颜色和噪波
+    mix_color = nodes.new('ShaderNodeMix')
+    mix_color.data_type = 'RGBA'
+    mix_color.inputs['Factor'].default_value = 0.1
+    mix_color.location = (-200, 0)
+    links.new(brick.outputs['Color'], mix_color.inputs['A'])
+    links.new(noise.outputs['Color'], mix_color.inputs['B'])
+    
+    # 连接到Emission材质（直接显示颜色，不受光照影响）
+    links.new(mix_color.outputs['Result'], emission.inputs['Color'])
+    emission.inputs['Strength'].default_value = 2.0  # Emission强度（材质预览模式，避免过曝）
+    
+    return emission
+
+
+def create_grid_ceiling_material(nodes, links):
+    """创建网格天花板程序化材质（Emission模式，显示原始颜色）"""
+    # 使用Emission材质，直接发光，不受光照影响
+    emission = nodes.new('ShaderNodeEmission')
+    emission.name = "GridCeilingEmission"
+    
+    # 使用纹理坐标
+    tex_coord = nodes.new('ShaderNodeTexCoord')
+    tex_coord.location = (-800, -400)
+    
+    # 缩放映射
+    mapping = nodes.new('ShaderNodeMapping')
+    mapping.inputs['Scale'].default_value = (5.0, 5.0, 1.0)
+    mapping.location = (-600, -400)
+    links.new(tex_coord.outputs['Generated'], mapping.inputs['Vector'])
+    
+    # 分离XY坐标
+    separate = nodes.new('ShaderNodeSeparateXYZ')
+    separate.location = (-400, -400)
+    links.new(mapping.outputs['Vector'], separate.inputs['Vector'])
+    
+    # X方向网格线（使用正弦波）
+    math_sin_x = nodes.new('ShaderNodeMath')
+    math_sin_x.operation = 'SINE'
+    math_sin_x.location = (-200, -350)
+    
+    math_mul_x = nodes.new('ShaderNodeMath')
+    math_mul_x.operation = 'MULTIPLY'
+    math_mul_x.inputs[1].default_value = 6.28  # 2*PI
+    math_mul_x.location = (-300, -350)
+    links.new(separate.outputs['X'], math_mul_x.inputs[0])
+    links.new(math_mul_x.outputs['Value'], math_sin_x.inputs[0])
+    
+    # Y方向网格线
+    math_sin_y = nodes.new('ShaderNodeMath')
+    math_sin_y.operation = 'SINE'
+    math_sin_y.location = (-200, -500)
+    
+    math_mul_y = nodes.new('ShaderNodeMath')
+    math_mul_y.operation = 'MULTIPLY'
+    math_mul_y.inputs[1].default_value = 6.28
+    math_mul_y.location = (-300, -500)
+    links.new(separate.outputs['Y'], math_mul_y.inputs[0])
+    links.new(math_mul_y.outputs['Value'], math_sin_y.inputs[0])
+    
+    # 取绝对值使线条清晰
+    abs_x = nodes.new('ShaderNodeMath')
+    abs_x.operation = 'ABSOLUTE'
+    abs_x.location = (-100, -350)
+    links.new(math_sin_x.outputs['Value'], abs_x.inputs[0])
+    
+    abs_y = nodes.new('ShaderNodeMath')
+    abs_y.operation = 'ABSOLUTE'
+    abs_y.location = (-100, -500)
+    links.new(math_sin_y.outputs['Value'], abs_y.inputs[0])
+    
+    # 合并X和Y网格（取最小值形成网格交叉）
+    math_min = nodes.new('ShaderNodeMath')
+    math_min.operation = 'MINIMUM'
+    math_min.location = (0, -425)
+    links.new(abs_x.outputs['Value'], math_min.inputs[0])
+    links.new(abs_y.outputs['Value'], math_min.inputs[1])
+    
+    # 颜色渐变：网格线深色，格子浅色
+    color_ramp = nodes.new('ShaderNodeValToRGB')
+    color_ramp.color_ramp.elements[0].color = (0.3, 0.3, 0.35, 1.0)  # 深灰色网格线
+    color_ramp.color_ramp.elements[0].position = 0.0
+    color_ramp.color_ramp.elements[1].color = (0.95, 0.95, 0.95, 1.0)  # 白色格子
+    color_ramp.color_ramp.elements[1].position = 0.15
+    color_ramp.location = (150, -425)
+    links.new(math_min.outputs['Value'], color_ramp.inputs['Fac'])
+    
+    # 连接到Emission材质（直接显示颜色，不受光照影响）
+    links.new(color_ramp.outputs['Color'], emission.inputs['Color'])
+    emission.inputs['Strength'].default_value = 2.0  # Emission强度（材质预览模式，避免过曝）
+    
+    return emission
+
+
+def get_scene_bounds():
+    """获取场景中所有物体的边界框"""
+    min_coords = [float('inf'), float('inf'), float('inf')]
+    max_coords = [float('-inf'), float('-inf'), float('-inf')]
+    
+    for obj in bpy.context.scene.objects:
+        if obj.type == 'MESH':
+            # 获取世界坐标下的边界框
+            for corner in obj.bound_box:
+                world_corner = obj.matrix_world @ Vector(corner)
+                for i in range(3):
+                    min_coords[i] = min(min_coords[i], world_corner[i])
+                    max_coords[i] = max(max_coords[i], world_corner[i])
+    
+    # 如果没有找到任何mesh，返回默认值
+    if min_coords[0] == float('inf'):
+        return ([-5, -5, 0], [5, 5, 3])
+    
+    return (min_coords, max_coords)
+
+
+def create_erp_camera(name="ERP_Camera"):
+    """创建ERP全景相机"""
+    # 创建相机数据
+    camera_data = bpy.data.cameras.new(name=name)
+    
+    # 设置为全景相机
+    camera_data.type = 'PANO'
+    
+    # 设置全景类型为等距圆柱投影（EEVEE和Cycles都支持）
+    # Blender 5.0 使用 panorama_type
+    if hasattr(camera_data, 'panorama_type'):
+        camera_data.panorama_type = 'EQUIRECTANGULAR'
+    # Cycles相机设置
+    if hasattr(camera_data, 'cycles'):
+        camera_data.cycles.panorama_type = 'EQUIRECTANGULAR'
+    
+    # 创建相机对象
+    camera_object = bpy.data.objects.new(name, camera_data)
+    
+    # 链接到场景
+    bpy.context.scene.collection.objects.link(camera_object)
+    
+    print(f"[INFO] 创建ERP相机: {name}")
+    
+    return camera_object
+
+
+def setup_camera(camera_object, position, rotation_euler=None, rotation_quat=None):
+    """设置相机位置和旋转（Euler 或 Quaternion）"""
+    # 设置位置
+    camera_object.location = Vector(position)
+    
+    # 设置旋转
+    if rotation_quat is not None:
+        # 使用四元数（推荐，避免Euler顺序/分解歧义）
+        camera_object.rotation_mode = 'QUATERNION'
+        camera_object.rotation_quaternion = Quaternion(rotation_quat)
+        print(f"[INFO] 相机位置: {position}")
+        print(f"[INFO] 相机旋转(Quaternion wxyz): {list(rotation_quat)}")
+    else:
+        # 使用欧拉角（Blender使用XYZ顺序的欧拉角）
+        camera_object.rotation_mode = 'XYZ'
+        camera_object.rotation_euler = Euler(rotation_euler, 'XYZ')
+        print(f"[INFO] 相机位置: {position}")
+        print(f"[INFO] 相机旋转(Euler XYZ, rad): {rotation_euler}")
+
+
+def setup_render_settings(resolution, engine, samples):
+    """设置渲染参数"""
+    scene = bpy.context.scene
+    
+    # 设置渲染引擎
+    scene.render.engine = engine
+    print(f"[INFO] 渲染引擎: {engine}")
+    
+    # 设置分辨率
+    scene.render.resolution_x = resolution[0]
+    scene.render.resolution_y = resolution[1]
+    scene.render.resolution_percentage = 100
+    print(f"[INFO] 分辨率: {resolution[0]}x{resolution[1]}")
+    
+    # 设置输出格式
+    scene.render.image_settings.file_format = 'PNG'
+    scene.render.image_settings.color_mode = 'RGB'
+    scene.render.image_settings.color_depth = '8'
+    
+    # 引擎特定设置
+    if engine == 'BLENDER_EEVEE':
+        # EEVEE设置
+        if hasattr(scene, 'eevee'):
+            # 设置采样数（如果属性存在）
+            if hasattr(scene.eevee, 'taa_render_samples'):
+                scene.eevee.taa_render_samples = samples
+            # 软阴影（Blender 5.0可能不支持）
+            if hasattr(scene.eevee, 'use_soft_shadows'):
+                scene.eevee.use_soft_shadows = True
+    elif engine == 'CYCLES':
+        # Cycles设置
+        scene.cycles.samples = samples
+        scene.cycles.use_denoising = True
+        
+        # 对于Emission材质，需要确保光线反弹足够
+        # 但Emission材质本身会发光，不需要太多反弹
+        scene.cycles.max_bounces = 4  # 减少反弹次数（Emission材质不需要太多）
+        scene.cycles.diffuse_bounces = 2
+        scene.cycles.glossy_bounces = 2
+        scene.cycles.transmission_bounces = 2
+        
+        # 尝试使用GPU
+        try:
+            bpy.context.preferences.addons['cycles'].preferences.compute_device_type = 'CUDA'
+            bpy.context.scene.cycles.device = 'GPU'
+            print("[INFO] 使用GPU渲染")
+        except:
+            print("[INFO] 使用CPU渲染")
+
+
+def setup_lighting(camera_position=None, scene_bounds=None):
+    """
+    设置照明（材质预览模式：仅使用强环境光，无其他光源，显示材质原始颜色和亮度）
+    
+    Args:
+        camera_position: 相机位置 (x, y, z)（未使用）
+        scene_bounds: 场景边界 (min, max)（未使用）
+    """
+    scene = bpy.context.scene
+    
+    # 添加环境光（材质预览模式）
+    world = bpy.data.worlds.new("World")
+    scene.world = world
+    world.use_nodes = True
+    
+    # 获取节点树
+    nodes = world.node_tree.nodes
+    links = world.node_tree.links
+    
+    # 清除默认节点
+    nodes.clear()
+    
+    # 创建背景节点 - 使用非常强的环境光（类似材质预览模式）
+    # 只使用环境光，无其他光源，确保材质显示原始颜色和亮度，无明暗变化
+    background = nodes.new('ShaderNodeBackground')
+    background.inputs['Color'].default_value = (1.0, 1.0, 1.0, 1.0)  # 白色背景
+    background.inputs['Strength'].default_value = 1.0  # 环境光强度（材质预览模式，避免过曝）
+    
+    # 创建输出节点
+    output = nodes.new('ShaderNodeOutputWorld')
+    
+    # 连接节点
+    links.new(background.outputs['Background'], output.inputs['Surface'])
+    
+    # === 不添加任何其他光源 ===
+    # 只使用环境光，确保整个场景光照完全均匀，无距离衰减，无明暗变化
+    # 这样材质会显示其原始颜色和亮度，就像Blender材质预览模式一样
+    
+    print("[INFO] 设置照明完成（材质预览模式：仅强环境光，无其他光源，显示材质原始颜色和亮度）")
+
+
+def setup_depth_pass():
+    """
+    设置深度渲染 pass（Blender 5.0+ API）
+    
+    在 Blender 中启用 Z pass，用于获取深度信息。
+    使用 Blender 5.0 新的 compositing_node_group API。
+    """
+    scene = bpy.context.scene
+    
+    # 启用 View Layer 的 Z pass
+    view_layer = bpy.context.view_layer
+    view_layer.use_pass_z = True
+    
+    # Blender 5.0: scene.node_tree 已移除，改用 compositing_node_group
+    # 创建新的 CompositorNodeTree 并赋给场景
+    tree = bpy.data.node_groups.new("DepthCompositor", "CompositorNodeTree")
+    scene.compositing_node_group = tree
+    nodes = tree.nodes
+    links = tree.links
+    
+    # 创建 Render Layers 节点
+    render_layers = nodes.new('CompositorNodeRLayers')
+    render_layers.location = (0, 300)
+    
+    # Blender 5.0: 用 NodeGroupOutput 替代 CompositorNodeComposite
+    output = nodes.new('NodeGroupOutput')
+    output.location = (400, 300)
+    tree.interface.new_socket(name="Image", in_out="OUTPUT", socket_type="NodeSocketColor")
+    
+    # 连接 RGB 输出
+    links.new(render_layers.outputs['Image'], output.inputs['Image'])
+    
+    # 创建 File Output 节点（用于深度 EXR）
+    file_output = nodes.new('CompositorNodeOutputFile')
+    file_output.location = (400, 0)
+    file_output.directory = ""  # 稍后在渲染时设置（Blender 5.0: 替代 base_path）
+    file_output.format.media_type = 'IMAGE'  # Blender 5.0: 必须先设 media_type
+    file_output.format.file_format = 'OPEN_EXR'
+    file_output.format.color_depth = '32'
+    file_output.format.exr_codec = 'ZIP'
+    
+    # Blender 5.0: file_output_items 替代 file_slots
+    file_output.file_output_items.clear()
+    file_output.file_output_items.new('FLOAT', "depth")
+    
+    # 连接深度输出
+    links.new(render_layers.outputs['Depth'], file_output.inputs['depth'])
+    
+    print("[INFO] 深度 pass 已启用（Blender 5.0 API）")
+    
+    return file_output
+
+
+def _convert_depth_exr_via_blender_api(exr_path, npy_path):
+    """使用 Blender 图像 API 将 EXR 转为 NPY（备用路径，不依赖 OpenEXR）。"""
+    import numpy as np
+    img = bpy.data.images.load(exr_path)
+    width = img.size[0]
+    height = img.size[1]
+    pixels = np.array(img.pixels[:])
+    pixels = pixels.reshape(height, width, -1)
+    depth = pixels[:, :, 0]
+    depth = np.flipud(depth)
+    unit_scale = bpy.context.scene.unit_settings.scale_length
+    depth_meters = depth * unit_scale
+    max_valid_depth = 1000.0
+    depth_meters[depth_meters > max_valid_depth] = np.nan
+    depth_meters[depth_meters <= 0] = np.nan
+    np.save(npy_path, depth_meters.astype(np.float32))
+    bpy.data.images.remove(img)
+    os.remove(exr_path)
+    print(f"[OK] 深度图保存（备用方法）: {npy_path}")
+
+
+def convert_depth_exr_to_npy(exr_path, npy_path):
+    """
+    将 Blender 渲染的深度 EXR 转换为 NPY 格式
+    
+    Blender ERP 相机的深度是 range depth（射线距离），单位为 Blender 单位（通常是米）
+    
+    Args:
+        exr_path: EXR 文件路径
+        npy_path: NPY 输出路径
+    """
+    import numpy as np
+    try:
+        import OpenEXR
+        import Imath
+        
+        # 打开 EXR 文件
+        exr_file = OpenEXR.InputFile(exr_path)
+        
+        # 获取图像尺寸
+        header = exr_file.header()
+        dw = header['dataWindow']
+        width = dw.max.x - dw.min.x + 1
+        height = dw.max.y - dw.min.y + 1
+        
+        # 读取深度通道
+        # Blender 深度 pass 保存在 'R'、'G'、'B' 或 'V' 通道
+        pt = Imath.PixelType(Imath.PixelType.FLOAT)
+        
+        # 尝试不同的通道名称
+        channel_names = ['depth.R', 'R', 'V', 'Z', 'depth.V']
+        depth_str = None
+        for ch in channel_names:
+            if ch in header['channels']:
+                depth_str = exr_file.channel(ch, pt)
+                print(f"[INFO] 使用深度通道: {ch}")
+                break
+        
+        if depth_str is None:
+            # 列出所有可用通道
+            available_channels = list(header['channels'].keys())
+            print(f"[WARN] 可用通道: {available_channels}")
+            # 尝试使用第一个通道
+            if available_channels:
+                depth_str = exr_file.channel(available_channels[0], pt)
+                print(f"[INFO] 使用通道: {available_channels[0]}")
+            else:
+                raise ValueError("无法找到深度通道")
+        
+        # 转换为 numpy 数组
+        depth = np.frombuffer(depth_str, dtype=np.float32)
+        depth = depth.reshape(height, width)
+        
+        # 获取场景单位比例（转换为米）
+        unit_scale = bpy.context.scene.unit_settings.scale_length
+        
+        # 将深度转换为米
+        # Blender 的深度值是场景单位，需要乘以 unit_scale 转换为米
+        depth_meters = depth * unit_scale
+        
+        # 处理无效深度（Blender 用非常大的值表示无穷远）
+        # 通常 > 1e9 的值表示背景/无穷远
+        max_valid_depth = 1000.0  # 1000 米以上视为无效
+        depth_meters[depth_meters > max_valid_depth] = np.nan
+        depth_meters[depth_meters <= 0] = np.nan
+        
+        # 保存为 NPY
+        np.save(npy_path, depth_meters.astype(np.float32))
+        
+        # 删除临时 EXR 文件
+        os.remove(exr_path)
+        
+        # 统计信息
+        valid_mask = np.isfinite(depth_meters)
+        if np.any(valid_mask):
+            print(f"[OK] 深度图保存: {npy_path}")
+            print(f"     形状: {depth_meters.shape}")
+            print(f"     深度范围: {np.nanmin(depth_meters):.3f} - {np.nanmax(depth_meters):.3f} 米")
+            print(f"     有效像素: {np.sum(valid_mask)} / {depth_meters.size} ({100*np.sum(valid_mask)/depth_meters.size:.1f}%)")
+        else:
+            print(f"[WARN] 深度图全部无效!")
+            
+    except ImportError:
+        print("[ERROR] 需要安装 OpenEXR 库: pip install OpenEXR")
+        print("[INFO] 尝试使用 Blender 内置方法...")
+        try:
+            _convert_depth_exr_via_blender_api(exr_path, npy_path)
+        except Exception as e:
+            print(f"[ERROR] 备用方法也失败: {e}")
+            print(f"[INFO] EXR 文件保留在: {exr_path}")
+    except Exception as e:
+        print(f"[WARN] OpenEXR 读取失败，尝试 Blender 内置方法: {e}")
+        try:
+            _convert_depth_exr_via_blender_api(exr_path, npy_path)
+        except Exception as e2:
+            print(f"[ERROR] 备用方法也失败: {e2}")
+            print(f"[INFO] EXR 文件保留在: {exr_path}")
+
+
+def render_and_save(output_path, render_depth=False, depth_output=None):
+    """
+    执行渲染并保存
+    
+    Args:
+        output_path: RGB 图像输出路径
+        render_depth: 是否渲染深度
+        depth_output: 深度图输出路径（.npy 格式）
+    """
+    # 确保输出目录存在
+    output_dir = os.path.dirname(output_path)
+    if output_dir and not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+    
+    # 设置输出路径
+    bpy.context.scene.render.filepath = output_path
+    
+    # 执行渲染
+    print(f"[INFO] 开始渲染...")
+    bpy.ops.render.render(write_still=True)
+
+    # 强校验：必须有实际输出图像，避免上游出现“returncode=0但无文件”
+    if (not os.path.exists(output_path)) or os.path.getsize(output_path) <= 0:
+        raise RuntimeError(f"渲染完成但输出图像不存在或为空: {output_path}")
+
+    print(f"[OK] 渲染完成: {output_path}")
+
+
+def save_pose(camera_object, output_path, frame_id=0, ref_position=None, ref_quaternion=None):
+    """
+    保存相机位姿（绝对位姿，兼容 ERPT 格式）
+    
+    输出格式：
+    - position: 相机中心在世界坐标系的绝对位置（米），[X右, Y上, Z前]
+    - rotation_quaternion: [w, x, y, z]，camera->world 旋转 (R_cw)
+    
+    核心公式：R_cw_erpt = T @ R_blender_obj @ M
+    - T: Blender世界(Y前Z上) -> 统一世界(Y上Z前) 坐标轴交换
+    - R_blender_obj: Blender相机的旋转矩阵（object local -> world）
+    - M: Blender相机本地(-Z前) -> ERPT相机(+Z前) Z轴翻转
+    
+    Args:
+        camera_object: Blender相机对象
+        output_path: 输出路径
+        frame_id: 帧序号
+        ref_position: （保留参数，当前未使用）
+        ref_quaternion: （保留参数，当前未使用）
+    """
+    from mathutils import Matrix
+    
+    # 获取当前相机的绝对位置和旋转（Blender坐标系：X右, Y前, Z上）
+    abs_position_blender = list(camera_object.location)
+    abs_quat_blender = camera_object.rotation_euler.to_quaternion()
+    
+    # === 位置转换 ===
+    # Blender世界(X右,Y前,Z上) -> 统一标准(X右,Y上,Z前)
+    abs_position_unified = [
+        abs_position_blender[0],   # X_unified = X_blender
+        abs_position_blender[2],   # Y_unified = Z_blender (上)
+        abs_position_blender[1]    # Z_unified = Y_blender (前)
+    ]
+    
+    # === 旋转转换 ===
+    # Blender object rotation matrix (local -> world in Blender coords)
+    R_obj_blender = abs_quat_blender.to_matrix()
+    
+    # T: Blender世界坐标 -> 统一世界坐标（交换Y和Z轴）
+    T_blender_to_unified = Matrix([
+        [1, 0, 0],  # X不变
+        [0, 0, 1],  # Y_unified = Z_blender
+        [0, 1, 0]   # Z_unified = Y_blender
+    ])
+    
+    # M: Blender相机本地坐标 -> ERPT相机坐标（翻转Z轴）
+    # Blender相机沿 -Z_local 看，ERPT相机沿 +Z_camera 看
+    # 因此 ERPT_Z = -Blender_Z_local，即 Z 轴翻转
+    M_cam = Matrix([
+        [1, 0,  0],
+        [0, 1,  0],
+        [0, 0, -1]
+    ])
+    
+    # 核心公式：R_cw_erpt = T @ R_obj_blender @ M
+    # 含义：ERPT相机坐标 -> (M) -> Blender本地 -> (R_obj) -> Blender世界 -> (T) -> 统一世界
+    R_cw_erpt = T_blender_to_unified @ R_obj_blender @ M_cam
+    
+    # 转换为四元数（cam_to_world，ERPT期望的格式）
+    quat_cw = R_cw_erpt.to_quaternion()
+    abs_quaternion_cw = [quat_cw.w, quat_cw.x, quat_cw.y, quat_cw.z]
+    
+    # === 输出 ===
+    # 绝对位姿，cam_to_world格式，兼容ERPT
+    pose_data = {
+        "frame_id": frame_id,
+        "position": abs_position_unified,
+        "rotation_quaternion": abs_quaternion_cw,
+        "camera_type": "erp_ray",
+        "coordinate_system": "right-handed, Y-up, Z-forward (cam_to_world)",
+        "render_method": "blender_cycles"
+    }
+    
+    # 保存JSON
+    with open(output_path, 'w') as f:
+        json.dump(pose_data, f, indent=2)
+
+    if (not os.path.exists(output_path)) or os.path.getsize(output_path) <= 0:
+        raise RuntimeError(f"位姿文件写入失败或为空: {output_path}")
+    
+    print(f"[OK] 位姿保存: {output_path}")
+    print(f"  Position (absolute, meters): {abs_position_unified}")
+    print(f"  Rotation (cam_to_world): {abs_quaternion_cw}")
+    
+    # 返回绝对位姿（统一标准坐标系，cam_to_world）
+    return abs_position_unified, abs_quaternion_cw
+
+
+def main():
+    # 解析参数
+    args = parse_args()
+    
+    # 解析相机位置
+    camera_pos = [float(x) for x in args.camera_pos.split(',')]
+    camera_rot = [float(x) for x in args.camera_rot.split(',')]
+    camera_rot_quat = None
+    if args.camera_rot_quat:
+        camera_rot_quat = [float(x) for x in args.camera_rot_quat.split(',')]
+    resolution = [int(x) for x in args.resolution.split(',')]
+    
+    # 解析参考帧位姿
+    ref_position = None
+    ref_quaternion = None
+    if args.ref_position:
+        ref_position = [float(x) for x in args.ref_position.split(',')]
+    if args.ref_quaternion:
+        ref_quaternion = [float(x) for x in args.ref_quaternion.split(',')]
+    
+    # 确定位姿输出路径
+    if args.pose_output:
+        pose_output = args.pose_output
+    else:
+        pose_output = os.path.splitext(args.output)[0] + '_pose.json'
+    
+    print("=" * 60)
+    print("Blender ERP渲染")
+    print("=" * 60)
+    
+    # 1. 清空场景
+    print("\n[1/6] 清空场景...")
+    clear_scene()
+    
+    # 2. 导入mesh
+    print("\n[2/6] 导入mesh...")
+    import_mesh(args.mesh)
+    
+    # 3. 创建ERP相机
+    print("\n[3/6] 创建ERP相机...")
+    camera = create_erp_camera()
+    setup_camera(camera, camera_pos, rotation_euler=camera_rot, rotation_quat=camera_rot_quat)
+    bpy.context.scene.camera = camera
+    
+    # 获取场景边界（用于灯光设置）
+    scene_bounds = get_scene_bounds()
+    print(f"[INFO] 场景边界: min={scene_bounds[0]}, max={scene_bounds[1]}")
+    
+    # 4. 设置渲染参数
+    print("\n[4/6] 设置渲染参数...")
+    setup_render_settings(resolution, args.engine, args.samples)
+    setup_lighting(camera_position=camera_pos, scene_bounds=scene_bounds)
+    
+    # 5. 渲染
+    print("\n[5/6] 渲染中...")
+    render_and_save(args.output)
+    
+    # 6. 保存位姿（相对于第一帧）
+    print("\n[6/6] 保存位姿...")
+    abs_pos, abs_quat = save_pose(
+        camera, 
+        pose_output, 
+        frame_id=args.frame_id,
+        ref_position=ref_position,
+        ref_quaternion=ref_quaternion
+    )
+    
+    # 输出绝对位姿供批量脚本使用
+    print(f"[ABS_POSE] {abs_pos[0]},{abs_pos[1]},{abs_pos[2]}|{abs_quat[0]},{abs_quat[1]},{abs_quat[2]},{abs_quat[3]}")
+    
+    print("\n" + "=" * 60)
+    print("渲染完成！")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()
+

pipelines/run_blend_pipeline.py

@@ -0,0 +1,1860 @@
+#!/usr/bin/env python3
+"""
+Blend 全流程 Pipeline v5（单 Blender 进程）
+
+v3 → v4 改进:
+  - Phase 0+1+2 全部在一个 Blender 进程内完成
+  - 不再导出 GLB（用 Blender scene.ray_cast 替代 trimesh）
+  - 不再每帧重启 Blender（同进程内移动相机 + 渲染）
+  - 去掉 trimesh 外部依赖
+
+v5 → v6 改进:
+  - 新增 GLB/GLTF 格式支持（--glb 参数）
+  - --blend / --glb 二选一，支持 .blend .glb .gltf 三种格式
+  - GLB 导入后与 .blend 流程完全统一
+
+对外接口 100% 兼容 v3/v5:
+  - 命令行参数完全一致（新增 --glb 为可选补充）
+  - 输出文件名完全一致（panorama_XXXX.png / _depth.npy / pose_XXXX.json）
+  - run_full_pipeline.py 零改动
+
+双模式运行:
+  1) python run_blend_pipeline.py --blender X --blend Y ...
+     python run_blend_pipeline.py --blender X --glb Y ...
+     → 检测到 --blender → 启动 blender --python THIS_FILE -- --blend/--glb Y ...
+  2) Blender 内部自动进入 in-process 模式
+     → Phase 0 (边界) + Phase 1 (撒点+过滤) + Phase 2 (边渲边选)
+"""
+
+# =====================================================================
+# 检测运行环境
+# =====================================================================
+try:
+    import bpy
+    from mathutils import Vector, Euler, Matrix
+    IN_BLENDER = True
+except ImportError:
+    IN_BLENDER = False
+
+import argparse
+import json
+import math
+import os
+import subprocess
+import sys
+import time
+import random as _random
+from pathlib import Path
+
+import numpy as np
+
+
+# =====================================================================
+# 常量
+# =====================================================================
+
+WARP_H = 128
+WARP_W = 256
+MARGIN = 0.5  # 距墙最小安全距离（防穿模）
+
+DEFAULT_STOP_GAIN = 0.08
+DEFAULT_OVERLAP_PENALTY = 0.5
+DEFAULT_MIN_DIST = 0.6
+DEFAULT_MIN_FRAMES = 5
+
+ROTATION_TYPES = {
+    "none":         [0.0, 0.0, 0.0],
+    "rotate_x_90":  [math.pi / 2, 0.0, 0.0],
+    "rotate_x_180": [math.pi, 0.0, 0.0],
+    "rotate_z_90":  [0.0, 0.0, math.pi / 2],
+}
+
+
+def get_camera_rot(rotation_type: str, frame_id: int):
+    if rotation_type == "random_yaw":
+        yaw = 0.0 if frame_id == 0 else _random.uniform(0, 2 * math.pi)
+        return [math.pi / 2, 0.0, yaw]
+    return list(ROTATION_TYPES[rotation_type])
+
+
+# =====================================================================
+# 参数解析（兼容两种模式）
+# =====================================================================
+
+def parse_args_python():
+    """Python 模式: 需要 --blender"""
+    parser = argparse.ArgumentParser(description="Blend Pipeline v5（边渲边选）")
+    parser.add_argument("--blender", type=str, required=True)
+    scene_grp = parser.add_mutually_exclusive_group(required=True)
+    scene_grp.add_argument("--blend", type=str, default=None,
+                           help=".blend 场景文件路径")
+    scene_grp.add_argument("--glb", type=str, default=None,
+                           help=".glb / .gltf 场景文件路径")
+    parser.add_argument("--output-dir", type=str, required=True)
+    parser.add_argument("--num-frames", type=int, default=30)
+    parser.add_argument("--render-depth", action="store_true")
+    parser.add_argument("--resolution", type=str, default="2048,1024")
+    parser.add_argument("--samples", type=int, default=128)
+    parser.add_argument("--engine", type=str, default="CYCLES")
+    parser.add_argument("--exposure", type=float, default=0.0)
+    parser.add_argument("--grid-spacing", type=float, default=0.5)
+    parser.add_argument("--camera-height", type=float, default=None)
+    parser.add_argument("--stop-gain", type=float, default=DEFAULT_STOP_GAIN)
+    parser.add_argument("--stop-score", type=float, default=-0.3)
+    parser.add_argument("--stop-delta", type=float, default=0.08)
+    parser.add_argument("--min-frames", type=int, default=DEFAULT_MIN_FRAMES)
+    parser.add_argument("--rotation-type", type=str, default="random_yaw",
+                        choices=["none", "rotate_x_90", "rotate_x_180",
+                                 "rotate_z_90", "random_yaw"])
+    parser.add_argument("--gain-curve", action="store_true", default=True)
+    parser.add_argument("--no-gain-curve", dest="gain_curve", action="store_false")
+    return parser.parse_args()
+
+
+def parse_args_blender():
+    """Blender 模式: 不需要 --blender"""
+    argv = sys.argv
+    if "--" in argv:
+        argv = argv[argv.index("--") + 1:]
+    else:
+        argv = []
+    parser = argparse.ArgumentParser()
+    scene_grp = parser.add_mutually_exclusive_group(required=True)
+    scene_grp.add_argument("--blend", type=str, default=None,
+                           help=".blend 场景文件路径")
+    scene_grp.add_argument("--glb", type=str, default=None,
+                           help=".glb / .gltf 场景文件路径")
+    parser.add_argument("--output-dir", type=str, required=True)
+    parser.add_argument("--num-frames", type=int, default=30)
+    parser.add_argument("--resolution", type=str, default="2048,1024")
+    parser.add_argument("--samples", type=int, default=128)
+    parser.add_argument("--engine", type=str, default="CYCLES")
+    parser.add_argument("--exposure", type=float, default=0.0)
+    parser.add_argument("--grid-spacing", type=float, default=0.5)
+    parser.add_argument("--camera-height", type=float, default=None)
+    parser.add_argument("--stop-gain", type=float, default=DEFAULT_STOP_GAIN)
+    parser.add_argument("--stop-score", type=float, default=-0.3)
+    parser.add_argument("--stop-delta", type=float, default=0.08)
+    parser.add_argument("--min-frames", type=int, default=DEFAULT_MIN_FRAMES)
+    parser.add_argument("--rotation-type", type=str, default="random_yaw",
+                        choices=["none", "rotate_x_90", "rotate_x_180",
+                                 "rotate_z_90", "random_yaw"])
+    parser.add_argument("--gain-curve", action="store_true", default=True)
+    parser.add_argument("--no-gain-curve", dest="gain_curve", action="store_false")
+    return parser.parse_args(argv)
+
+
+# #####################################################################
+#
+#  Python 模式入口: 启动单个 Blender 进程
+#
+# #####################################################################
+
+def main_python():
+    """Python 调用入口 → 启动一个 Blender 进程执行本脚本"""
+    args = parse_args_python()
+
+    # 判断场景格式
+    if args.blend:
+        scene_path = str(Path(args.blend).resolve())
+        scene_flag = "--blend"
+        scene_label = f"Blend: {scene_path}"
+    else:
+        scene_path = str(Path(args.glb).resolve())
+        scene_flag = "--glb"
+        scene_label = f"GLB:   {scene_path}"
+
+    output_dir = str(Path(args.output_dir).resolve())
+    os.makedirs(output_dir, exist_ok=True)
+
+    this_script = str(Path(__file__).resolve())
+
+    # 构建 Blender 命令（把参数透传，去掉 --blender 和 --render-depth）
+    cmd = [
+        args.blender, "--background",
+        "--python", this_script,
+        "--",
+        scene_flag, scene_path,
+        "--output-dir", output_dir,
+        "--num-frames", str(args.num_frames),
+        "--resolution", args.resolution,
+        "--samples", str(args.samples),
+        "--engine", args.engine,
+        "--exposure", str(args.exposure),
+        "--grid-spacing", str(args.grid_spacing),
+        "--stop-gain", str(args.stop_gain),
+        "--stop-score", str(args.stop_score),
+        "--stop-delta", str(args.stop_delta),
+        "--min-frames", str(args.min_frames),
+        "--rotation-type", args.rotation_type,
+    ]
+    if args.camera_height is not None:
+        cmd += ["--camera-height", str(args.camera_height)]
+    if not args.gain_curve:
+        cmd += ["--no-gain-curve"]
+
+    print("=" * 60)
+    print("ERPT Blend Pipeline v5（单进程边渲边选）")
+    print("=" * 60)
+    print(f"  {scene_label}")
+    print(f"  Output:     {output_dir}")
+    print(f"  Max frames: {args.num_frames}")
+
+    # 不设 timeout — 大场景渲染时间不可预测
+    proc = subprocess.run(cmd, text=True)
+    sys.exit(proc.returncode)
+
+
+# #####################################################################
+#
+#  Blender 模式: Phase 0 + 1 + 2 全部在 Blender 内部执行
+#
+# #####################################################################
+
+# =====================================================================
+# Phase 0: 加载场景 + 获取边界
+# =====================================================================
+
+def load_scene(scene_path):
+    """加载场景文件，支持 .blend / .glb / .gltf 三种格式。
+    启用所有 collection，返回 mesh AABB 边界 (bmin, bmax)。
+    """
+    ext = Path(scene_path).suffix.lower()
+    print(f"\n[Phase 0] 加载场景: {scene_path}  (格式: {ext})")
+
+    if ext == ".blend":
+        # ---- .blend 原有流程 ----
+        bpy.ops.wm.open_mainfile(filepath=scene_path)
+
+        # 启用所有 collection + 取消隐藏
+        def enable_all(lc):
+            lc.exclude = False
+            lc.hide_viewport = False
+            for c in lc.children:
+                enable_all(c)
+        enable_all(bpy.context.view_layer.layer_collection)
+
+        for obj in bpy.context.scene.objects:
+            if obj.type == 'MESH':
+                obj.hide_viewport = False
+                obj.hide_set(False)
+
+    elif ext in (".glb", ".gltf"):
+        # ---- GLB / GLTF 导入流程 ----
+        # 先清空默认场景（cube / lamp / camera）
+        bpy.ops.wm.read_factory_settings(use_empty=True)
+
+        import_kwargs = dict(filepath=scene_path)
+        # Blender 3.x+ 使用 import_scene.gltf
+        if hasattr(bpy.ops.import_scene, 'gltf'):
+            bpy.ops.import_scene.gltf(**import_kwargs)
+        else:
+            raise RuntimeError(
+                "当前 Blender 版本不支持 import_scene.gltf，"
+                "请升级到 Blender 3.0 及以上版本。"
+            )
+
+        # ��保所有导入对象可见
+        for obj in bpy.context.scene.objects:
+            if obj.type == 'MESH':
+                obj.hide_viewport = False
+                obj.hide_set(False)
+
+    else:
+        raise ValueError(
+            f"不支持的场景格式: {ext}，"
+            f"支持的格式: .blend / .glb / .gltf"
+        )
+
+    bpy.context.view_layer.update()
+
+    # 计算 mesh 边界（通用逻辑）
+    bmin = [float('inf')] * 3
+    bmax = [float('-inf')] * 3
+    n_mesh = 0
+    for obj in bpy.context.scene.objects:
+        if obj.type == 'MESH':
+            n_mesh += 1
+            for corner in obj.bound_box:
+                wc = obj.matrix_world @ Vector(corner)
+                for i in range(3):
+                    bmin[i] = min(bmin[i], wc[i])
+                    bmax[i] = max(bmax[i], wc[i])
+
+    if bmin[0] == float('inf'):
+        bmin, bmax = [-5, -5, 0], [5, 5, 3]
+
+    print(f"  Mesh 数量: {n_mesh}")
+    print(f"  边界 (Z-up): min=[{bmin[0]:.1f}, {bmin[1]:.1f}, {bmin[2]:.1f}]  "
+          f"max=[{bmax[0]:.1f}, {bmax[1]:.1f}, {bmax[2]:.1f}]")
+    return bmin, bmax
+
+
+# =====================================================================
+# Phase 1: 撒点 + 4 层 Blender ray_cast 过滤
+# =====================================================================
+
+def compute_camera_heights(floor_z, ceiling_z, manual_height=None, bmin=None, bmax=None):
+    """计算相机高度层
+
+    策略:
+      - 手动指定 → 只用该高度
+      - 多层建筑 → 每层铺固定高度 [0.5, 0.8, 1.2, 1.7, 2.1] + 动态顶层
+      - 单层高空间 → 2.5m 以下用固定高度，2.5m 以上阶梯递增:
+          +1.0m, +1.5m, +2.0m, +2.5m, +3.0m ...（间距逐步放大）
+          最后加动态顶层（天花板 -0.5m）
+    """
+    CEIL_CLEARANCE = 0.3    # 最高高度：离天花板 0.3m（保留 2.1m 层）
+    FIXED_HEIGHTS = [0.5, 0.8, 1.2, 1.7, 2.1]  # 2.5m 以下的固定高度
+
+    if manual_height is not None:
+        return [manual_height]
+
+    room_h = ceiling_z - floor_z
+    if room_h <= 0:
+        return [floor_z + 1.5]
+
+    def _stepped_heights_for_floor(fz, local_ceil):
+        """单层高度计算：固定 + 阶梯递增 + 动态顶层"""
+        heights = []
+        local_h = local_ceil - fz
+
+        # 2.5m 以下: 固定高度
+        for eye_h in FIXED_HEIGHTS:
+            z = fz + eye_h
+            if z < local_ceil - CEIL_CLEARANCE:
+                heights.append(z)
+
+        # 2.5m 以上: 阶梯递增（间距从 1.0m 逐步增大到 3.0m）
+        if local_h > 3.0:  # 层高 > 3m 才加中间高度
+            cur_h = FIXED_HEIGHTS[-1]  # 从 2.1m 开始
+            step = 1.0                  # 初始步长 1.0m
+            MAX_STEP = 3.0              # 最大步长 3.0m
+            STEP_GROW = 0.5             # 每次步长增加 0.5m
+
+            while True:
+                cur_h += step
+                z = fz + cur_h
+                if z >= local_ceil - CEIL_CLEARANCE:
+                    break
+                heights.append(z)
+                step = min(step + STEP_GROW, MAX_STEP)
+
+        # 动态顶层：天花板 - 0.5m（如果比最高已有高度至少高 0.5m）
+        top_z = local_ceil - CEIL_CLEARANCE
+        if heights:
+            if top_z > max(heights) + 0.5:
+                heights.append(top_z)
+        elif top_z > fz + 0.5:
+            heights.append(top_z)
+
+        return heights
+
+    # 先尝试用 Blender raycast 探测楼板
+    try:
+        floors = _detect_floor_levels(floor_z, ceiling_z, bmin, bmax)
+        if floors:
+            print(f"  [楼层检测] 发现 {len(floors)} 个楼层: "
+                  f"{[f'{z:.2f}m' for z in floors]}")
+            heights = []
+            for idx, fz in enumerate(floors):
+                # 每层的天花板 = 下一层楼板 或 全局天花板
+                if idx + 1 < len(floors):
+                    local_ceil = floors[idx + 1]
+                else:
+                    local_ceil = ceiling_z
+                heights.extend(_stepped_heights_for_floor(fz, local_ceil))
+
+            if heights:
+                result = sorted(set(round(h, 2) for h in heights))
+                # 打印高度分布
+                for h in result:
+                    rel = h - floors[0]
+                    print(f"    高度 Z={h:.2f}m (离地 {rel:.2f}m)")
+                return result
+        else:
+            print(f"  [楼层检测] 未检测到楼板，使用启发式")
+    except Exception as e:
+        print(f"  [楼层检测] 异常: {e}，使用启发式")
+
+    # fallback: 简单启发式（同样用阶梯递增）
+    h_list = _stepped_heights_for_floor(floor_z, ceiling_z)
+    return sorted(set(round(h, 2) for h in h_list)) if h_list else [floor_z + 1.5]
+
+
+def _detect_floor_levels(floor_z, ceiling_z, bmin=None, bmax=None):
+    """用 raycast 从上往下扫描，检测楼板位置
+
+    在 XY 平面采样若干点，每个点从顶部往下打射线，收集 hit 的 Z 坐标。
+    对 Z 坐标做聚类（间距 > 1.5m 算不同楼层），得到各楼层地面高度。
+
+    关键改进:
+    1. 采样范围按场景大小缩放（不只中心 ±2m）
+    2. 检测到楼板后验证上方有天花板（排除屋顶外表面）
+    """
+    scene = bpy.context.scene
+    depsgraph = bpy.context.evaluated_depsgraph_get()
+    dir_down = Vector((0, 0, -1))
+    dir_up = Vector((0, 0, 1))
+
+    # 用场景 AABB 的 XY 中心和范围
+    if bmin is not None and bmax is not None:
+        cx = (bmin[0] + bmax[0]) / 2
+        cy = (bmin[1] + bmax[1]) / 2
+        # 采样范围: 场景 XY 的 1/4 跨度，至少 2m，最多 20m
+        rx = min(20.0, max(2.0, (bmax[0] - bmin[0]) * 0.25))
+        ry = min(20.0, max(2.0, (bmax[1] - bmin[1]) * 0.25))
+    else:
+        cx, cy = 0.0, 0.0
+        rx, ry = 2.0, 2.0
+
+    hit_zs = []
+    # 3x3 网格采样，按场景大小缩放
+    offsets = []
+    for fx in [-1, 0, 1]:
+        for fy in [-1, 0, 1]:
+            offsets.append((fx * rx, fy * ry))
+
+    for dx, dy in offsets:
+        origin = Vector((cx + dx, cy + dy, ceiling_z + 1.0))
+        # 多次向下 raycast（穿透式：命中后从命中点下方继续）
+        cur_z = ceiling_z + 1.0
+        for _ in range(10):  # 最多穿 10 层
+            hit, loc, norm, *_ = scene.ray_cast(
+                depsgraph, Vector((cx + dx, cy + dy, cur_z)), dir_down)
+            if not hit:
+                break
+            # 法线朝上（Z 分量 > 0.5）→ 这是地板/楼板表面
+            if norm.z > 0.5:
+                hit_zs.append((loc.z, cx + dx, cy + dy))
+            cur_z = loc.z - 0.05  # 穿过这个表面继续往下
+
+    if not hit_zs:
+        return []
+
+    # 聚类: 排序后间距 > 1.5m 算不同楼层
+    hit_zs.sort(key=lambda t: t[0])
+    clusters = [[hit_zs[0]]]
+    for item in hit_zs[1:]:
+        if item[0] - clusters[-1][-1][0] > 1.5:
+            clusters.append([item])
+        else:
+            clusters[-1].append(item)
+
+    # 每个 cluster 验证: 楼板上方是否有天花板
+    MAX_CEILING_DIST = 30.0  # 最高天花板距离（超过说明是露天/屋顶外表面）
+    floors = []
+    for c in clusters:
+        fz = sorted(c, key=lambda t: t[0])[len(c) // 2][0]
+        if not (floor_z - 0.5 <= fz <= ceiling_z - 1.0):
+            continue
+
+        # 验证: 从该楼板上方 1m 处往上打射线，检查是否有天花板
+        n_has_ceiling = 0
+        n_tested = 0
+        for _, px, py in c:
+            test_origin = Vector((px, py, fz + 1.0))
+            hit_ceil, loc_ceil, norm_ceil, *_ = scene.ray_cast(
+                depsgraph, test_origin, dir_up)
+            n_tested += 1
+            if hit_ceil and (loc_ceil.z - fz) < MAX_CEILING_DIST:
+                n_has_ceiling += 1
+
+        # 过半采样点上方有天花板 → 真正的楼板
+        if n_tested > 0 and n_has_ceiling / n_tested >= 0.5:
+            floors.append(fz)
+        else:
+            print(f"    [楼层检测] Z={fz:.2f}m 上方无天花板"
+                  f"（{n_has_ceiling}/{n_tested}），排除（可能是屋顶外表面）")
+
+    return sorted(floors)
+
+
+def generate_candidate_grid(bmin, bmax, x_spacing, y_spacing, heights):
+    cx = (bmin[0] + bmax[0]) / 2
+    cy = (bmin[1] + bmax[1]) / 2
+    x_half = int((bmax[0] - cx - MARGIN) / x_spacing)
+    y_half = int((bmax[1] - cy - MARGIN) / y_spacing)
+
+    xy_offsets = []
+    for ix in range(-x_half, x_half + 1):
+        for iy in range(-y_half, y_half + 1):
+            x = cx + ix * x_spacing
+            y = cy + iy * y_spacing
+            if bmin[0] + MARGIN <= x <= bmax[0] - MARGIN and \
+               bmin[1] + MARGIN <= y <= bmax[1] - MARGIN:
+                xy_offsets.append((ix * ix + iy * iy, x, y))
+    xy_offsets.sort(key=lambda t: t[0])
+
+    candidates = []
+    for z in heights:
+        for _, x, y in xy_offsets:
+            candidates.append([float(x), float(y), float(z)])
+
+    n_xy = len(xy_offsets)
+    print(f"  网格: {n_xy}点/层 x {len(heights)}层 = {len(candidates)} 个候选")
+    print(f"    中心: ({cx:.1f}, {cy:.1f}), X间距={x_spacing:.1f}m, Y间距={y_spacing:.1f}m")
+    for i, z in enumerate(heights):
+        print(f"    第{i+1}层: Z={z:.2f}m")
+    return candidates
+
+
+def _build_26_directions():
+    """26 方向球面采样（mathutils.Vector）"""
+    dirs = []
+    for i in range(16):
+        a = i * (2 * math.pi / 16)
+        dirs.append(Vector((math.cos(a), math.sin(a), 0.0)))
+    elev = math.pi / 4
+    for i in range(5):
+        a = i * (2 * math.pi / 5)
+        dirs.append(Vector((math.cos(a) * math.cos(elev),
+                            math.sin(a) * math.cos(elev),
+                            math.sin(elev))))
+    for i in range(5):
+        a = i * (2 * math.pi / 5)
+        dirs.append(Vector((math.cos(a) * math.cos(elev),
+                            math.sin(a) * math.cos(elev),
+                            -math.sin(elev))))
+    return dirs
+
+
+def raycast_6layer_filter(candidates, room_height, min_wall_dist=1.0):
+    """7 层过滤 — 直接用 Blender scene.ray_cast（不需要 trimesh/GLB）
+
+    第 1 层: 室内检测（朝上朝下必须 hit）
+    第 2 层: 穿模检测（≥2 方向 < 0.2m）
+    第 3 层: 角落检测（>50% 水平方向 < 1.0m）
+    第 4 层: 包裹检测（hit_rate≥90% + cv<0.30 + max<8m）
+    第 5 层: 墙面间距（最近水平方向 < 0.3m → Blender 渲染会穿模）
+    第 6 层: 视野质量（<35% 方向有有效命中 → 太空旷或太闭塞）
+    第 7 层: 窄缝检测（对向方向距离之和 < 1.5m → 两面墙夹着）★ 新增
+
+    性能: 用第 1~4 层同样的 26 方向数据，第 5~7 层零额外射线开销
+    """
+    scene = bpy.context.scene
+    depsgraph = bpy.context.evaluated_depsgraph_get()
+
+    N = len(candidates)
+    max_up = max(5.0, room_height)
+    max_down = max(3.0, room_height)
+    dir_up = Vector((0, 0, 1))
+    dir_down = Vector((0, 0, -1))
+    DIRS_26 = _build_26_directions()
+    n26 = len(DIRS_26)
+
+    # 第 5 层阈值: 最近水平墙面距离
+    MIN_WALL_CLEARANCE = 0.3  # Blender 渲染安全距离
+
+    # 第 6 层阈值: 有效视野比例
+    VIEW_GOOD_MIN = 0.5    # 有效命中距离下限
+    VIEW_GOOD_MAX = 20.0   # 有效命中距离上限
+    VIEW_GOOD_RATIO = 0.35 # 至少 35% 方向有有效命中
+
+    # 第 7 层阈值: 窄缝检测（对向距离之和）
+    MIN_SLIT_WIDTH = 1.5   # 对向墙距之和 < 1.5m → 窄缝
+
+    passed = []
+    stats = {"无天花板": 0, "无地板": 0, "穿模": 0, "角落": 0,
+             "包裹": 0, "贴墙": 0, "视野差": 0, "窄缝": 0}
+
+    t0 = time.time()
+    log_interval = max(1, N // 10)
+
+    for idx, pos in enumerate(candidates):
+        if idx % log_interval == 0 and idx > 0:
+            print(f"    过滤进度: {idx}/{N} ({idx*100//N}%)", flush=True)
+
+        origin = Vector(pos)
+
+        # ---- 第 1 层: 室内检测（朝上朝下各 1 条射线）----
+        hit_up, loc_up, *_ = scene.ray_cast(depsgraph, origin, dir_up)
+        if not hit_up or (loc_up - origin).length > max_up:
+            stats["无天花板"] += 1
+            continue
+
+        hit_dn, loc_dn, *_ = scene.ray_cast(depsgraph, origin, dir_down)
+        if not hit_dn or (loc_dn - origin).length > max_down:
+            stats["无地板"] += 1
+            continue
+
+        # ---- 第 2~6 层: 26 方向球面采样 ----
+        dists = []
+        for d in DIRS_26:
+            hit, loc, *_ = scene.ray_cast(depsgraph, origin, d)
+            dists.append((loc - origin).length if hit else float('inf'))
+
+        # 第 2 层: 穿模（≥2 方向 < 0.2m → 在物体内部）
+        n_close = sum(1 for d in dists if d < 0.2)
+        if n_close >= 2:
+            stats["穿模"] += 1
+            continue
+
+        # 第 3 层: 角落（水平 16 方向中 > 一半 < 1.0m）
+        n_wall = sum(1 for d in dists[:16] if d < min_wall_dist)
+        if n_wall > 8:
+            stats["角落"] += 1
+            continue
+
+        # 第 4 层: 包裹（hit_rate≥90% + CV<0.30 + max<8m）
+        finite = [d for d in dists if d < float('inf')]
+        hit_rate = len(finite) / n26
+        if hit_rate >= 0.90 and len(finite) >= 2:
+            mean_d = sum(finite) / len(finite)
+            max_d = max(finite)
+            if mean_d > 0:
+                var = sum((d - mean_d) ** 2 for d in finite) / len(finite)
+                cv = var ** 0.5 / mean_d
+                if cv < 0.30 and max_d < 8.0:
+                    stats["包裹"] += 1
+                    continue
+
+        # 第 5 层: 墙面间距（水平 16 方向最近 hit < 0.3m → 贴墙）★ 新增
+        horiz_finite = [d for d in dists[:16] if d < float('inf')]
+        if horiz_finite and min(horiz_finite) < MIN_WALL_CLEARANCE:
+            stats["贴墙"] += 1
+            continue
+
+        # 第 6 层: 视野质量（有效方向太少 → 视野差）
+        n_good = sum(1 for d in dists
+                     if VIEW_GOOD_MIN <= d <= VIEW_GOOD_MAX)
+        good_ratio = n_good / n26
+        if good_ratio < VIEW_GOOD_RATIO:
+            stats["视野差"] += 1
+            continue
+
+        # 第 7 层: 窄缝检测（对向水平方向距离之和 < 1.5m → 两面墙夹着）
+        # 水平 16 方向中，方向 i 和方向 i+8 是对向的（0°↔180°, 22.5°↔202.5°...）
+        in_slit = False
+        for i in range(8):
+            d_fwd = dists[i] if dists[i] < float('inf') else 999
+            d_bwd = dists[i + 8] if dists[i + 8] < float('inf') else 999
+            if d_fwd + d_bwd < MIN_SLIT_WIDTH:
+                in_slit = True
+                break
+        if in_slit:
+            stats["窄缝"] += 1
+            continue
+
+        passed.append(pos)
+
+    dt = time.time() - t0
+    print(f"  过滤统计 ({dt:.1f}s): 总计={N}, 通过={len(passed)}")
+    for k, v in stats.items():
+        print(f"    ❌ {k}: {v} ({v * 100 // max(N, 1)}%)")
+    print(f"    阈值: 天花板<{max_up:.1f}m, 地板<{max_down:.1f}m, "
+          f"穿模<0.2m, 角落<{min_wall_dist:.1f}m, "
+          f"包裹: hit≥90%+cv<0.3+max<8m, "
+          f"贴墙<{MIN_WALL_CLEARANCE}m, "
+          f"视野: ≥{VIEW_GOOD_RATIO:.0%}方向 {VIEW_GOOD_MIN}-{VIEW_GOOD_MAX}m, "
+          f"窄缝<{MIN_SLIT_WIDTH}m")
+
+    if len(passed) < 5 and N > 20:
+        print(f"    [诊断] 通过率低 ({len(passed)}/{N})")
+
+    return passed
+
+
+def setup_erp_camera():
+    """创建 ERP 全景相机"""
+    for obj in list(bpy.context.scene.objects):
+        if obj.type == 'CAMERA':
+            bpy.data.objects.remove(obj, do_unlink=True)
+
+    cam_data = bpy.data.cameras.new("ERP_Camera")
+    cam_data.type = 'PANO'
+    if hasattr(cam_data, 'panorama_type'):
+        cam_data.panorama_type = 'EQUIRECTANGULAR'
+    if hasattr(cam_data, 'cycles'):
+        cam_data.cycles.panorama_type = 'EQUIRECTANGULAR'
+
+    cam_obj = bpy.data.objects.new("ERP_Camera", cam_data)
+    bpy.context.scene.collection.objects.link(cam_obj)
+    bpy.context.scene.camera = cam_obj
+    print(f"  创建 ERP 相机: {cam_obj.name}")
+    return cam_obj
+
+
+def enable_gpu():
+    try:
+        prefs = bpy.context.preferences.addons['cycles'].preferences
+        for dt in ['OPTIX', 'CUDA']:
+            try:
+                prefs.compute_device_type = dt
+                prefs.get_devices()
+                gpus = [d for d in prefs.devices if d.type == dt]
+                if gpus:
+                    for d in prefs.devices:
+                        d.use = (d.type == dt)
+                    bpy.context.scene.cycles.device = 'GPU'
+                    print(f"  GPU 渲染: {gpus[0].name} ({dt})")
+                    return True
+            except Exception:
+                continue
+        print("  [WARN] 无可用 GPU，使用 CPU 渲染")
+        bpy.context.scene.cycles.device = 'CPU'
+    except Exception as e:
+        print(f"  [ERROR] GPU 设置异常: {e}")
+    return False
+
+
+def setup_render_settings(resolution, engine, samples, exposure):
+    scene = bpy.context.scene
+    scene.render.engine = engine
+    scene.render.resolution_x = resolution[0]
+    scene.render.resolution_y = resolution[1]
+    scene.render.resolution_percentage = 100
+    scene.render.image_settings.file_format = 'PNG'
+    scene.render.image_settings.color_mode = 'RGB'
+    scene.render.image_settings.color_depth = '8'
+    scene.view_settings.exposure = exposure
+    # AgX（Blender 4+默认）对室内场景会严重压暗；改用 Standard 线性映射，
+    # 颜色准确且更亮，曝光完全由 exposure 参数控制。
+    scene.view_settings.view_transform = 'Standard'
+    scene.view_settings.look = 'None'
+
+    if engine == 'CYCLES':
+        scene.cycles.samples = samples
+        scene.cycles.use_denoising = True
+        scene.cycles.max_bounces = 12
+        scene.cycles.diffuse_bounces = 4
+        scene.cycles.glossy_bounces = 4
+        scene.cycles.transmission_bounces = 12
+        scene.cycles.transparent_max_bounces = 8
+        enable_gpu()
+
+    print(f"  渲染设置: {engine} {resolution[0]}x{resolution[1]} "
+          f"samples={samples} exposure={exposure} view_transform=Standard")
+
+
+def _world_has_effective_light(world) -> bool:
+    """判断 World 节点是否能产生有效的环境光（Strength > 0.05）。
+    GLB 导入的场景通常有一个 World 对象，但 Background Strength 可能为 0。
+    """
+    if world is None:
+        return False
+    if not world.use_nodes or world.node_tree is None:
+        # 没用节点系统：用旧 API 的纯色环境，认为有效
+        return True
+    for node in world.node_tree.nodes:
+        if node.type == 'BACKGROUND':
+            strength = node.inputs.get('Strength')
+            if strength is not None:
+                val = strength.default_value
+                # 如果有链接（HDR 贴图等），视为有效
+                if strength.is_linked or float(val) > 0.05:
+                    return True
+    return False
+
+
+def setup_lighting():
+    """仅在场景缺乏有效光照时补一个均匀环境光。
+    - 有可见灯光对象 → 保留原始
+    - World 有有效 Background Strength → 保留原始
+    - 否则：注入默认环境光（Strength=1.0）
+    """
+    scene = bpy.context.scene
+
+    has_lights = any(obj.type == 'LIGHT' for obj in bpy.data.objects if obj.visible_get())
+    has_world   = _world_has_effective_light(scene.world)
+
+    if has_lights or has_world:
+        print("  [光照] 保留场景原始光照")
+        return
+
+    print("  [光照] 场景无有效灯光，注入均匀环境光 (Strength=1.0)")
+    world = scene.world
+    if world is None:
+        world = bpy.data.worlds.new("World")
+        scene.world = world
+    world.use_nodes = True
+    nodes = world.node_tree.nodes
+    links = world.node_tree.links
+    nodes.clear()
+    bg = nodes.new('ShaderNodeBackground')
+    bg.inputs['Color'].default_value = (1.0, 1.0, 1.0, 1.0)
+    bg.inputs['Strength'].default_value = 1.0
+    out = nodes.new('ShaderNodeOutputWorld')
+    links.new(bg.outputs['Background'], out.inputs['Surface'])
+
+
+def setup_depth_pass():
+    """配置 compositor 深度输出（Blender 5.0 API）"""
+    scene = bpy.context.scene
+    bpy.context.view_layer.use_pass_z = True
+
+    tree = bpy.data.node_groups.new("DepthComp", "CompositorNodeTree")
+    scene.compositing_node_group = tree
+    nodes = tree.nodes
+    links = tree.links
+
+    rl = nodes.new('CompositorNodeRLayers')
+    rl.location = (0, 300)
+
+    group_out = nodes.new('NodeGroupOutput')
+    group_out.location = (400, 300)
+    tree.interface.new_socket(name="Image", in_out="OUTPUT",
+                              socket_type="NodeSocketColor")
+    links.new(rl.outputs['Image'], group_out.inputs['Image'])
+
+    fo = nodes.new('CompositorNodeOutputFile')
+    fo.location = (400, 0)
+    fo.directory = ""
+    fo.format.media_type = 'IMAGE'
+    fo.format.file_format = 'OPEN_EXR'
+    fo.format.color_depth = '32'
+    fo.format.exr_codec = 'ZIP'
+    fo.file_output_items.clear()
+    fo.file_output_items.new('FLOAT', "depth")
+    links.new(rl.outputs['Depth'], fo.inputs['depth'])
+
+    print(f"  深度 pass 已配置")
+    return fo
+
+
+# =====================================================================
+# 渲染 + 深度转换 + 位姿保存（同进程，只移动相机）
+# =====================================================================
+
+def convert_depth_exr_to_npy(exr_path, npy_path):
+    """EXR → NPY（Blender 内置 API，不依赖 OpenEXR 库）"""
+    img = bpy.data.images.load(exr_path)
+    w, h = img.size[0], img.size[1]
+    pixels = np.array(img.pixels[:]).reshape(h, w, -1)
+    depth = np.flipud(pixels[:, :, 0])
+
+    unit_scale = bpy.context.scene.unit_settings.scale_length
+    depth_m = depth * unit_scale
+    depth_m[(depth_m > 1000.0) | (depth_m <= 0)] = 0.0
+
+    np.save(npy_path, depth_m.astype(np.float32))
+    bpy.data.images.remove(img)
+    try:
+        os.remove(exr_path)
+    except OSError:
+        pass
+
+
+def render_frame_inprocess(cam_obj, frame_id, camera_pos, camera_rot,
+                           output_dir, depth_fo):
+    """同进程渲染一帧，返回 (rgb_path, depth_path, pose_path)"""
+    cam_obj.location = Vector(camera_pos)
+    cam_obj.rotation_euler = Euler(camera_rot, 'XYZ')
+
+    base = f"panorama_{frame_id:04d}"
+    rgb_path = os.path.join(output_dir, f"{base}.png")
+    depth_npy = os.path.join(output_dir, f"{base}_depth.npy")
+    pose_path = os.path.join(output_dir, f"pose_{frame_id:04d}.json")
+
+    bpy.context.scene.render.filepath = rgb_path
+
+    abs_dir = os.path.abspath(output_dir)
+    depth_fo.directory = abs_dir
+    depth_fo.file_name = base + "_"
+    depth_exr = os.path.join(abs_dir, base + "_depth.exr")
+
+    bpy.context.scene.frame_set(frame_id)
+    bpy.ops.render.render(write_still=True)
+
+    # 深度转换
+    if os.path.exists(depth_exr):
+        convert_depth_exr_to_npy(depth_exr, depth_npy)
+    else:
+        import glob
+        hits = glob.glob(os.path.join(abs_dir, f"*{base}*depth*.exr"))
+        if hits:
+            convert_depth_exr_to_npy(hits[0], depth_npy)
+        else:
+            print(f"    [WARN] 未找到深度 EXR: {depth_exr}")
+            depth_npy = None
+
+    # 位姿（与 render_erp_blender.py save_pose 完全一致的格式）
+    save_pose(cam_obj, pose_path, frame_id)
+
+    return rgb_path, depth_npy, pose_path
+
+
+def save_pose(camera_object, output_path, frame_id):
+    """保存位姿（绝对位姿，cam_to_world，兼容 ERPT）
+
+    格式与 render_erp_blender.py 的 save_pose 完全一致：
+      R_cw_erpt = T @ R_obj_blender @ M
+    """
+    unit_scale = bpy.context.scene.unit_settings.scale_length
+
+    abs_pos_b = list(camera_object.location)
+    abs_quat_b = camera_object.rotation_euler.to_quaternion()
+
+    # Blender(X右,Y前,Z上) → 统一(X右,Y上,Z前)
+    abs_pos_u = [
+        abs_pos_b[0] * unit_scale,   # X
+        abs_pos_b[2] * unit_scale,   # Y_unified = Z_blender
+        abs_pos_b[1] * unit_scale,   # Z_unified = Y_blender
+    ]
+
+    R_obj = abs_quat_b.to_matrix()
+    T = Matrix([[1, 0, 0], [0, 0, 1], [0, 1, 0]])
+    M = Matrix([[1, 0, 0], [0, 1, 0], [0, 0, -1]])
+    R_cw = T @ R_obj @ M
+    q = R_cw.to_quaternion()
+
+    pose_data = {
+        "frame_id": frame_id,
+        "position": abs_pos_u,
+        "rotation_quaternion": [q.w, q.x, q.y, q.z],
+        "camera_type": "erp_ray",
+        "coordinate_system": "right-handed, Y-up, Z-forward (cam_to_world)",
+        "render_method": "blender_cycles",
+    }
+    with open(output_path, 'w') as f:
+        json.dump(pose_data, f, indent=2)
+
+
+# =====================================================================
+# 选帧核心（向量化，内嵌）
+# =====================================================================
+
+def build_ray_directions(H=WARP_H, W=WARP_W):
+    """向量化构建 ERP 射线方向（Z-up）"""
+    i = np.arange(H, dtype=np.float64)
+    j = np.arange(W, dtype=np.float64)
+    phi = np.pi / 2 - np.pi * (i + 0.5) / H
+    theta = 2 * np.pi * (j + 0.5) / W
+    phi, theta = np.meshgrid(phi, theta, indexing='ij')
+    return np.stack([
+        np.cos(phi) * np.cos(theta),
+        np.cos(phi) * np.sin(theta),
+        np.sin(phi),
+    ], axis=-1)
+
+
+_ray_dirs_cache = {}
+
+
+def get_ray_dirs(H=WARP_H, W=WARP_W):
+    if (H, W) not in _ray_dirs_cache:
+        _ray_dirs_cache[(H, W)] = build_ray_directions(H, W)
+    return _ray_dirs_cache[(H, W)]
+
+
+def depth_to_3d_points(position, depth, ray_dirs, max_depth=None):
+    valid = depth > 0
+    if max_depth is not None:
+        valid &= (depth <= max_depth)
+    if not np.any(valid):
+        return np.empty((0, 3), dtype=np.float64)
+    pos = np.array(position, dtype=np.float64)
+    return (pos + ray_dirs * depth[..., np.newaxis])[valid]
+
+
+def project_points_to_coverage(pts, tgt_pos, H=WARP_H, W=WARP_W):
+    """把累积点云投影到候选位置的全景图，返回覆盖 mask。"""
+    if len(pts) == 0:
+        return np.zeros((H, W), dtype=bool)
+    tgt = np.array(tgt_pos, dtype=np.float64)
+    vecs = pts - tgt
+    x, y, z = vecs[:, 0], vecs[:, 1], vecs[:, 2]
+    r_xy = np.sqrt(x ** 2 + y ** 2)
+    phi = np.arctan2(z, r_xy)
+    theta = np.arctan2(y, x) % (2 * np.pi)
+    vi = np.clip(((np.pi / 2 - phi) / np.pi * H).astype(np.int32), 0, H - 1)
+    uj = np.clip((theta / (2 * np.pi) * W).astype(np.int32), 0, W - 1)
+    cov = np.zeros((H, W), dtype=bool)
+    cov[vi, uj] = True
+    pad = cov.copy()
+    pad[1:, :] |= cov[:-1, :]
+    pad[:-1, :] |= cov[1:, :]
+    pad[:, 1:] |= cov[:, :-1]
+    pad[:, :-1] |= cov[:, 1:]
+    return pad
+
+
+# ---- GPU 加速（延迟初始化，Phase 2 第一次选帧时检测）----
+_GPU_BACKEND = None
+_gpu_lib = None
+_gpu_checked = False
+
+def _init_gpu():
+    """延迟初始化 GPU，避免模块加载时显存冲突"""
+    global _GPU_BACKEND, _gpu_lib, _gpu_checked
+    if _gpu_checked:
+        return
+    _gpu_checked = True
+
+    try:
+        import torch
+        if torch.cuda.is_available():
+            _GPU_BACKEND = "torch"
+            _gpu_lib = torch
+            print(f"[GPU] torch {torch.__version__} (CUDA)，选帧将使用 GPU 加速")
+            return
+    except ImportError:
+        pass
+
+    try:
+        import cupy as cp
+        try:
+            cp.get_default_memory_pool().free_all_blocks()
+            cp.get_default_pinned_memory_pool().free_all_blocks()
+        except Exception:
+            pass
+        cp.zeros(1)
+        _GPU_BACKEND = "cupy"
+        _gpu_lib = cp
+        print(f"[GPU] cupy {cp.__version__}，选帧将使用 GPU 加速")
+        return
+    except Exception as e:
+        print(f"[Warning] cupy 初始化失败: {e}")
+
+    print("[CPU] 未检测到 torch/cupy，选帧使用 CPU")
+
+
+def _batch_coverage_gpu(pts_np, candidate_positions, remaining_indices, H, W):
+    """GPU 批量投影：逐候选在 GPU 上算覆盖数
+
+    返回: dict[ci] -> covered_pixels (int)
+    """
+    total_px = H * W
+    results = {}
+
+    if _GPU_BACKEND == "torch":
+        import torch
+        device = torch.device("cuda")
+        pts_gpu = torch.from_numpy(pts_np).double().to(device)
+        PI = torch.pi
+        TWO_PI = 2 * torch.pi
+
+        for ci in remaining_indices:
+            tgt = torch.tensor(candidate_positions[ci], dtype=torch.float64, device=device)
+            vecs = pts_gpu - tgt
+            x, y, z = vecs[:, 0], vecs[:, 1], vecs[:, 2]
+            r_xy = torch.sqrt(x ** 2 + y ** 2)
+            phi = torch.atan2(z, r_xy)
+            theta = torch.atan2(y, x) % TWO_PI
+            vi = torch.clamp(((PI / 2 - phi) / PI * H).long(), 0, H - 1)
+            uj = torch.clamp((theta / TWO_PI * W).long(), 0, W - 1)
+
+            flat = vi * W + uj
+            cov = torch.zeros(total_px, dtype=torch.bool, device=device)
+            cov[flat] = True
+            cov_2d = cov.view(H, W)
+            pad = cov_2d.clone()
+            pad[1:, :] |= cov_2d[:-1, :]
+            pad[:-1, :] |= cov_2d[1:, :]
+            pad[:, 1:] |= cov_2d[:, :-1]
+            pad[:, :-1] |= cov_2d[:, 1:]
+            results[ci] = int(pad.sum().item())
+
+    elif _GPU_BACKEND == "cupy":
+        import cupy as cp
+        pts_gpu = cp.asarray(pts_np, dtype=cp.float64)
+        PI = cp.pi
+        TWO_PI = 2 * cp.pi
+
+        for ci in remaining_indices:
+            tgt = cp.array(candidate_positions[ci], dtype=cp.float64)
+            vecs = pts_gpu - tgt
+            x, y, z = vecs[:, 0], vecs[:, 1], vecs[:, 2]
+            r_xy = cp.sqrt(x ** 2 + y ** 2)
+            phi = cp.arctan2(z, r_xy)
+            theta = cp.arctan2(y, x) % TWO_PI
+            vi = cp.clip(((PI / 2 - phi) / PI * H).astype(cp.int32), 0, H - 1)
+            uj = cp.clip((theta / TWO_PI * W).astype(cp.int32), 0, W - 1)
+
+            flat = vi * W + uj
+            cov = cp.zeros(total_px, dtype=cp.bool_)
+            cov[flat] = True
+            cov_2d = cov.reshape(H, W)
+            pad = cov_2d.copy()
+            pad[1:, :] |= cov_2d[:-1, :]
+            pad[:-1, :] |= cov_2d[1:, :]
+            pad[:, 1:] |= cov_2d[:, :-1]
+            pad[:, :-1] |= cov_2d[:, 1:]
+            results[ci] = int(cp.sum(pad))
+
+    return results
+
+
+def trim_depth(new_depth, new_pos, existing_pts, ray_dirs):
+    H, W = new_depth.shape
+    n_orig = int(np.sum(new_depth > 0))
+    if len(existing_pts) == 0:
+        return new_depth.copy(), n_orig, n_orig
+    cov = project_points_to_coverage(existing_pts, new_pos, H, W)
+    trimmed = new_depth.copy()
+    trimmed[cov] = 0
+    return trimmed, n_orig, int(np.sum(trimmed > 0))
+
+
+def load_depth_downsampled(path, H=WARP_H, W=WARP_W):
+    d = np.load(path).astype(np.float32)
+    d = np.nan_to_num(d, nan=0.0)
+    if d.shape == (H, W):
+        return d
+    try:
+        import cv2
+        return cv2.resize(d, (W, H), interpolation=cv2.INTER_AREA)
+    except ImportError:
+        h, w = d.shape
+        bh, bw = h // H, w // W
+        if bh < 1 or bw < 1:
+            r = np.zeros((H, W), dtype=np.float32)
+            r[:min(h, H), :min(w, W)] = d[:min(h, H), :min(w, W)]
+            return r
+        return d[:bh * H, :bw * W].reshape(H, bh, W, bw).mean(axis=(1, 3))
+
+
+def select_next_frame(candidates, selected_idx, selected_pos,
+                      all_pts, reachable=None):
+    """选下一帧：纯贪心，选 score 最高的候选
+
+    reachable: set of candidate indices，可达候选集合。
+               None = 不限制。
+    cupy 可用时自动 GPU 加速。
+    """
+    n = len(candidates)
+    H, W = WARP_H, WARP_W
+    total_px = H * W
+    overlap_penalty = DEFAULT_OVERLAP_PENALTY
+
+    remaining = []
+    for i in range(n):
+        if i in selected_idx:
+            continue
+        if reachable is not None and i not in reachable:
+            continue
+        remaining.append(i)
+
+    if not remaining:
+        return -1, 0.0, -999.0, 0
+
+    # ---- GPU 路径 ----
+    _init_gpu()
+    if _GPU_BACKEND and len(all_pts) > 0:
+        covered_map = _batch_coverage_gpu(all_pts, candidates, remaining, H, W)
+        scores = {}
+        for ci in remaining:
+            covered = covered_map.get(ci, 0)
+            new_r = (total_px - covered) / total_px
+            ovl_r = covered / total_px
+            scores[ci] = {
+                "gain": new_r,
+                "overlap": ovl_r,
+                "score": new_r - overlap_penalty * ovl_r,
+            }
+    else:
+        # ---- CPU 路径 ----
+        scores = {}
+        for ci in remaining:
+            cov = project_points_to_coverage(all_pts, candidates[ci], H, W)
+            covered = int(np.sum(cov))
+            new_r = (total_px - covered) / total_px
+            ovl_r = covered / total_px
+            scores[ci] = {
+                "gain": new_r,
+                "overlap": ovl_r,
+                "score": new_r - overlap_penalty * ovl_r,
+            }
+
+    best_ci, best_sc, best_g = -1, -999.0, 0.0
+    for ci in remaining:
+        if scores[ci]["score"] > best_sc:
+            best_sc = scores[ci]["score"]
+            best_ci = ci
+            best_g = scores[ci]["gain"]
+
+    return best_ci, best_g, best_sc, len(remaining)
+
+
+def compute_max_depth(candidates):
+    pos_arr = np.array(candidates)
+    diag = float(np.linalg.norm(pos_arr.max(0) - pos_arr.min(0)))
+    return diag * 1.5
+
+
+# =====================================================================
+# Phase 2: 边渲边选主循环
+# =====================================================================
+
+def run_phase2(cam_obj, candidates, mesh_center, output_dir,
+               max_frames, resolution, depth_fo, args):
+
+    ray_dirs = get_ray_dirs(WARP_H, WARP_W)
+    max_depth = compute_max_depth(candidates)
+
+    scene_diag = float(np.linalg.norm(
+        np.array(candidates).max(0) - np.array(candidates).min(0)))
+
+    selected_idx = set()
+    selected_pos = []
+    all_pts = np.empty((0, 3), dtype=np.float64)
+    pts_chunks = []
+    results = []
+
+    # 可达性
+    reachable = set()
+
+    stop_score = args.stop_score
+    stop_delta = args.stop_delta
+    min_frames = args.min_frames
+
+    # actual gain 历史
+    ACTUAL_GAIN_WINDOW = 3
+    ACTUAL_GAIN_FLOOR = args.stop_gain
+    actual_gain_history = []
+    delta_history = []
+    consecutive_skips = 0
+    MAX_CONSECUTIVE_SKIPS = 3
+
+    # ======== 楼层分组（候选按 Z 聚类）========
+    z_vals = sorted(set(round(c[2], 2) for c in candidates))
+    floors = [[z_vals[0]]]
+    for z in z_vals[1:]:
+        if z - floors[-1][-1] > 1.0:
+            floors.append([z])
+        else:
+            floors[-1].append(z)
+
+    # 每个候选标记楼层（找 Z 最近的楼层）
+    n_floors = len(floors)
+    floor_mids = [sum(f) / len(f) for f in floors]  # 每层的 Z 中心
+    candidate_floor = []
+    for c in candidates:
+        cz = c[2]
+        fi = min(range(n_floors), key=lambda i: abs(cz - floor_mids[i]))
+        candidate_floor.append(fi)
+
+    current_floor = 0
+
+    # 当前楼层的候选索引集合
+    def floor_set(fi):
+        return set(i for i, f in enumerate(candidate_floor) if f == fi)
+
+    floor_names = [f"楼层{i+1}(Z={min(f):.1f}~{max(f):.1f})" for i, f in enumerate(floors)]
+
+    print(f"\n{'='*60}")
+    print(f"[Phase 2] 边渲边选 (候选={len(candidates)}, 最多={max_frames}帧)")
+    print(f"{'='*60}")
+    print(f"  停止条件:")
+    print(f"    - 连续 {ACTUAL_GAIN_WINDOW} 帧 actual_gain < {ACTUAL_GAIN_FLOOR:.0%}")
+    print(f"    - predicted gain < {ACTUAL_GAIN_FLOOR:.0%} 且 score < {stop_score}")
+    print(f"    - (至少 {min_frames} 帧后才检查)")
+    print(f"  {n_floors} 个楼层: {floor_names}")
+    print(f"  高度层: {['%.2f' % z for z in z_vals]}")
+    print(f"  选帧策略: 楼层顺序 + 层内全局最优 (可达优先)")
+
+    t_total = time.time()
+
+    # 时间统计
+    time_select = 0.0
+    time_render = 0.0
+    time_depth = 0.0
+    time_reach = 0.0
+
+    for frame_count in range(max_frames):
+
+        # ======== 选位置 ========
+        t_sel = time.time()
+        if frame_count == 0:
+            # F0: XY 取第一楼层候选的几何中心，Z 取高度层中心
+            floor0_candidates = [(i, c) for i, c in enumerate(candidates)
+                                 if candidate_floor[i] == 0]
+            if floor0_candidates:
+                f0_pts = np.array([c for _, c in floor0_candidates])
+                xy_center = f0_pts[:, :2].mean(axis=0)  # XY 几何中心
+                floor0_zs = sorted(set(c[2] for _, c in floor0_candidates))
+                z_target = min(floor0_zs) + 1.2  # 楼板高度 + 1.7m ≈ 人眼高度
+                target = np.array([xy_center[0], xy_center[1], z_target])
+                dists_to_target = [np.linalg.norm(np.array(c) - target)
+                                   for _, c in floor0_candidates]
+                best_idx = int(np.argmin(dists_to_target))
+                ci = floor0_candidates[best_idx][0]
+            else:
+                mc = np.array(mesh_center, dtype=np.float64)
+                ci = int(np.argmin([np.linalg.norm(np.array(c) - mc)
+                                     for c in candidates]))
+            gain, score = 1.0, 1.0
+            print(f"\n  F{frame_count}: 选候选[{ci}] "
+                  f"(楼层中心, Z={candidates[ci][2]:.2f}m) "
+                  f"[{floor_names[current_floor]}]")
+        else:
+            # ---- 当前楼层内全局最优（所有高度自由竞争）----
+            cur_floor_ids = floor_set(current_floor)
+            # 限制 reachable 到当前楼层
+            floor_reachable = reachable & cur_floor_ids if reachable else set()
+
+            ci, gain, score, n_remain = select_next_frame(
+                candidates, selected_idx, selected_pos, all_pts,
+                reachable=floor_reachable if floor_reachable else cur_floor_ids)
+
+            expand = False
+            if ci < 0 or score < stop_score:
+                # 可达的不够好 → 当前楼层全局（含不可达）
+                ci2, gain2, score2, n2 = select_next_frame(
+                    candidates, selected_idx, selected_pos, all_pts,
+                    reachable=cur_floor_ids)
+                if ci2 >= 0 and (ci < 0 or score2 > score):
+                    ci, gain, score, n_remain = ci2, gain2, score2, n2
+                    expand = True
+
+            if ci < 0 or (score < stop_score and gain < ACTUAL_GAIN_FLOOR):
+                # 当前楼层拍满 → 换下一楼层
+                if ci >= 0:
+                    reason = f"predicted gain={gain:.1%} score={score:.3f}"
+                else:
+                    reason = "无可选候选"
+                current_floor += 1
+                if current_floor < n_floors:
+                    print(f"\n  F{frame_count}: {reason}"
+                          f" → {floor_names[current_floor-1]} 拍满,"
+                          f" 切换到 {floor_names[current_floor]}")
+                    continue
+                else:
+                    print(f"\n  F{frame_count}: {reason}"
+                          f" → 所有楼层拍满，停止")
+                    break
+
+            tag = "[扩展]" if expand else ""
+            print(f"\n  F{frame_count}: 选候选[{ci}]  "
+                  f"gain={gain:.1%}  score={score:.3f}  剩余={n_remain}"
+                  f"  [Z={candidates[ci][2]:.2f} {floor_names[current_floor]}"
+                  f" 可达={len(floor_reachable)}]{tag}")
+
+        pos = candidates[ci]
+        selected_idx.add(ci)
+        selected_pos.append(pos)
+        dt_sel = time.time() - t_sel
+        time_select += dt_sel
+        if frame_count > 0:
+            print(f"    [选帧 {dt_sel:.1f}s]")
+
+        # ======== 渲染 ========
+        cam_rot = get_camera_rot(args.rotation_type, frame_count)
+        print(f"    位置: [{pos[0]:.2f}, {pos[1]:.2f}, {pos[2]:.2f}]")
+        print(f"    渲染...", end="", flush=True)
+        t_r = time.time()
+
+        rgb_path, depth_path, pose_path = render_frame_inprocess(
+            cam_obj, frame_count, pos, cam_rot, output_dir, depth_fo)
+        dt_r = time.time() - t_r
+        time_render += dt_r
+        print(f" {dt_r:.1f}s")
+
+        # ======== depth → 3D 点云 ========
+        t_dep = time.time()
+        actual_gain = 1.0
+        delta_ratio = 1.0
+
+        if depth_path and os.path.exists(depth_path):
+            depth = load_depth_downsampled(depth_path, WARP_H, WARP_W)
+            total_px = WARP_H * WARP_W
+            n_valid = int(np.sum(depth > 0))
+            valid_ratio = n_valid / total_px
+
+            if frame_count == 0:
+                new_pts = depth_to_3d_points(pos, depth, ray_dirs, max_depth)
+                pts_chunks.append(new_pts)
+                all_pts = new_pts
+                actual_gain = valid_ratio
+                print(f"    depth: {n_valid}px ({valid_ratio:.0%} 有效)"
+                      f" → {len(new_pts)} 个 3D 点 (全部)")
+            else:
+                # ---- 质量检查 ----
+                MIN_VALID_RATIO = 0.30
+                if valid_ratio < MIN_VALID_RATIO:
+                    print(f"    depth: {n_valid}px ({valid_ratio:.0%} 有效)"
+                          f" < {MIN_VALID_RATIO:.0%} → 室外/空壳，跳过此帧")
+                    results.append({
+                        "frame_id": frame_count,
+                        "candidate_idx": ci,
+                        "position": pos,
+                        "gain": float(gain),
+                        "actual_gain": 0.0,
+                        "delta_ratio": 0.0,
+                        "score": float(score),
+                        "skipped": True,
+                        "skip_reason": f"valid_ratio={valid_ratio:.1%}",
+                    })
+                    for fp in [rgb_path, depth_path]:
+                        if fp and os.path.exists(fp):
+                            try:
+                                os.remove(fp)
+                            except OSError:
+                                pass
+                    consecutive_skips += 1
+                    if consecutive_skips >= MAX_CONSECUTIVE_SKIPS:
+                        # 连续空壳 → 当前楼层可能有问题，换层
+                        current_floor += 1
+                        consecutive_skips = 0
+                        if current_floor < n_floors:
+                            print(f"    连续 {MAX_CONSECUTIVE_SKIPS} 帧室外/空壳"
+                                  f" → 切换到 {floor_names[current_floor]}")
+                        else:
+                            print(f"    连续 {MAX_CONSECUTIVE_SKIPS} 帧室外/空壳"
+                                  f" → 所有楼层完成，停止")
+                            break
+                    time_depth += time.time() - t_dep
+                    continue
+
+                trimmed, n_orig, n_new = trim_depth(
+                    depth, pos, all_pts, ray_dirs)
+                new_pts = depth_to_3d_points(pos, trimmed, ray_dirs, max_depth)
+                pts_chunks.append(new_pts)
+                all_pts = np.concatenate(pts_chunks)
+                actual_gain = n_new / total_px
+                delta_ratio = (len(new_pts) / len(all_pts)
+                               if len(all_pts) > 0 else 1.0)
+                print(f"    depth: {n_valid}px ({valid_ratio:.0%} 有效)"
+                      f" → trim → {n_new}px 新增"
+                      f" → {len(new_pts)} 个新 3D 点 (delta)")
+                print(f"    累积点云: {len(all_pts)}")
+                print(f"    实际gain: {actual_gain:.1%}, "
+                      f"点云增量: {delta_ratio:.1%}")
+                consecutive_skips = 0
+        else:
+            print(f"    [Error] 无 depth 文件！")
+            break
+
+        results.append({
+            "frame_id": frame_count,
+            "candidate_idx": ci,
+            "position": pos,
+            "gain": float(gain),
+            "actual_gain": float(actual_gain),
+            "delta_ratio": float(delta_ratio),
+            "score": float(score),
+        })
+        time_depth += time.time() - t_dep
+
+        # ======== 更新可达性 ========
+        if IN_BLENDER:
+            t_reach = time.time()
+            scene = bpy.context.scene
+            depsgraph = bpy.context.evaluated_depsgraph_get()
+            n_new_reachable = 0
+            for ci_check in range(len(candidates)):
+                if ci_check in selected_idx or ci_check in reachable:
+                    continue
+                origin = Vector(pos)
+                target = Vector(candidates[ci_check])
+                direction = (target - origin).normalized()
+                dist_to_target = (target - origin).length
+
+                if dist_to_target < 0.1:
+                    reachable.add(ci_check)
+                    n_new_reachable += 1
+                    continue
+
+                hit, loc, *_ = scene.ray_cast(depsgraph, origin, direction)
+                if not hit or (loc - origin).length >= dist_to_target * 0.95:
+                    reachable.add(ci_check)
+                    n_new_reachable += 1
+
+            dt_reach = time.time() - t_reach
+            time_reach += dt_reach
+            print(f"    [可达性] 新增 {n_new_reachable} 个可达候选, "
+                  f"总可达 {len(reachable)} / {len(candidates)} "
+                  f"({dt_reach:.1f}s)")
+
+        # ======== 停止条件 ========
+        if frame_count > 0:
+            actual_gain_history.append(actual_gain)
+            delta_history.append(delta_ratio)
+
+        if frame_count > 0 and frame_count >= min_frames:
+            if len(actual_gain_history) >= ACTUAL_GAIN_WINDOW:
+                recent_gain = actual_gain_history[-ACTUAL_GAIN_WINDOW:]
+                recent_delta = delta_history[-ACTUAL_GAIN_WINDOW:]
+                gain_exhausted = all(g < ACTUAL_GAIN_FLOOR for g in recent_gain)
+                delta_exhausted = all(d < stop_delta for d in recent_delta)
+
+                if gain_exhausted or delta_exhausted:
+                    avg_g = sum(recent_gain) / len(recent_gain)
+                    avg_d = sum(recent_delta) / len(recent_delta)
+                    reason = ""
+                    if gain_exhausted:
+                        reason += f"actual_gain < {ACTUAL_GAIN_FLOOR:.0%} (平均 {avg_g:.1%})"
+                    if delta_exhausted:
+                        if reason:
+                            reason += " + "
+                        reason += f"delta < {stop_delta:.1%} (平均 {avg_d:.1%})"
+                    # 当前楼层拍满 → 换层
+                    current_floor += 1
+                    if current_floor < n_floors:
+                        print(f"    连续 {ACTUAL_GAIN_WINDOW} 帧 {reason}"
+                              f" → {floor_names[current_floor-1]} 拍满,"
+                              f" 切换到 {floor_names[current_floor]}")
+                    else:
+                        print(f"    连续 {ACTUAL_GAIN_WINDOW} 帧 {reason}"
+                              f" → 所有楼层拍满，停止")
+                        break
+
+    # ======== 补帧：确保总帧数满足 4n+1 ========
+    while len(results) > 1 and (len(results) - 1) % 4 != 0:
+        need = 4 - (len(results) - 1) % 4
+        frame_count = results[-1]["frame_id"] + 1
+        if frame_count >= max_frames + 3:
+            break
+        print(f"\n  [补帧] 当前 {len(results)} 帧，不满足 4n+1，需补 {need} 帧")
+
+        ci, gain, score, n_remain = select_next_frame(
+            candidates, selected_idx, selected_pos, all_pts, reachable=None)
+        if ci < 0:
+            print(f"    无可选候选，无法补帧")
+            break
+
+        pos = candidates[ci]
+        selected_idx.add(ci)
+        selected_pos.append(pos)
+
+        cam_rot = get_camera_rot(args.rotation_type, frame_count)
+        print(f"    补帧 F{frame_count}: 候选[{ci}] Z={pos[2]:.2f}m"
+              f" gain={gain:.1%} score={score:.3f}")
+        print(f"    渲染...", end="", flush=True)
+        t_r = time.time()
+        rgb_path, depth_path, pose_path = render_frame_inprocess(
+            cam_obj, frame_count, pos, cam_rot, output_dir, depth_fo)
+        dt_r = time.time() - t_r
+        time_render += dt_r
+        print(f" {dt_r:.1f}s")
+
+        actual_gain = 0.0
+        delta_ratio = 0.0
+        if depth_path and os.path.exists(depth_path):
+            depth = load_depth_downsampled(depth_path, WARP_H, WARP_W)
+            total_px = WARP_H * WARP_W
+            trimmed, n_orig, n_new = trim_depth(depth, pos, all_pts, ray_dirs)
+            new_pts = depth_to_3d_points(pos, trimmed, ray_dirs, max_depth)
+            pts_chunks.append(new_pts)
+            all_pts = np.concatenate(pts_chunks)
+            actual_gain = n_new / total_px
+            delta_ratio = len(new_pts) / len(all_pts) if len(all_pts) > 0 else 0
+            print(f"    depth: {n_new}px 新增, gain={actual_gain:.1%}")
+
+        results.append({
+            "frame_id": frame_count,
+            "candidate_idx": ci,
+            "position": pos,
+            "gain": float(gain),
+            "actual_gain": float(actual_gain),
+            "delta_ratio": float(delta_ratio),
+            "score": float(score),
+            "supplementary": True,
+        })
+
+    if len(results) > 1:
+        is_4n1 = (len(results) - 1) % 4 == 0
+        print(f"\n  帧数检查: {len(results)} 帧"
+              f" {'✓ 满足 4n+1' if is_4n1 else '✗ 不满足 4n+1'}")
+
+    dt = time.time() - t_total
+    time_other = dt - time_select - time_render - time_depth - time_reach
+    print(f"\n  {'─'*50}")
+    print(f"  共 {len(results)} 帧, {dt:.1f}s ({dt/60:.1f}min)")
+    print(f"  耗时分布:")
+    print(f"    选帧:   {time_select:.1f}s ({time_select/max(dt,1)*100:.0f}%)"
+          f"  — 点云投影评估候选")
+    print(f"    渲染:   {time_render:.1f}s ({time_render/max(dt,1)*100:.0f}%)"
+          f"  — Blender Cycles GPU")
+    print(f"    深度:   {time_depth:.1f}s ({time_depth/max(dt,1)*100:.0f}%)"
+          f"  — depth→点云+trim")
+    print(f"    可达性: {time_reach:.1f}s ({time_reach/max(dt,1)*100:.0f}%)"
+          f"  — raycast 扫描")
+    if time_other > 1:
+        print(f"    其他:   {time_other:.1f}s ({time_other/max(dt,1)*100:.0f}%)")
+
+    return results
+
+
+# =====================================================================
+# 自动曝光
+# =====================================================================
+
+def auto_adjust_exposure(cam_obj, test_pos, output_dir, depth_fo, initial_exposure):
+    """F0 位置低采样快速渲一帧，分析亮度，自动调整 exposure。
+
+    目标：有效像素平均亮度 ≈ 120/255。
+    过曝 (>200): 降 EV
+    欠曝 (<40):  升 EV
+    正常 (40~200): 不动
+    """
+    TARGET_MEAN = 120.0
+    scene = bpy.context.scene
+    original_samples = scene.cycles.samples
+
+    # 低采样快速测试
+    scene.cycles.samples = 16
+    test_path = os.path.join(output_dir, "_exposure_test.png")
+    scene.render.filepath = test_path
+
+    cam_obj.location = Vector(test_pos)
+    cam_obj.rotation_euler = Euler((math.pi / 2, 0, 0), 'XYZ')
+
+    print(f"\n[自动曝光] 测试渲染 (16 samples, exposure={initial_exposure:.1f})...",
+          end="", flush=True)
+    t0 = time.time()
+    bpy.ops.render.render(write_still=True)
+    print(f" {time.time() - t0:.1f}s")
+
+    # 分析亮度
+    img = bpy.data.images.load(test_path)
+    w, h = img.size[0], img.size[1]
+    pixels = np.array(img.pixels[:]).reshape(h, w, -1)
+    rgb = pixels[:, :, :3]
+    brightness = (0.299 * rgb[:,:,0] + 0.587 * rgb[:,:,1] + 0.114 * rgb[:,:,2]) * 255
+
+    # 只看非纯黑像素（排除天空/无效区域）
+    valid_mask = brightness > 1.0
+    n_valid = int(np.sum(valid_mask))
+    if n_valid > 0:
+        mean_b = float(np.mean(brightness[valid_mask]))
+        # 过曝比例（亮度 > 250 的像素占比）
+        overexposed = float(np.sum(brightness[valid_mask] > 250)) / n_valid
+        # 欠曝比例（亮度 < 10 的像素占比）
+        underexposed = float(np.sum(brightness[valid_mask] < 10)) / n_valid
+    else:
+        mean_b = 0.0
+        overexposed = 0.0
+        underexposed = 1.0
+
+    bpy.data.images.remove(img)
+    try:
+        os.remove(test_path)
+    except OSError:
+        pass
+
+    print(f"  亮度分析: 平均={mean_b:.0f}/255, "
+          f"过曝={overexposed:.0%}, 欠曝={underexposed:.0%}, "
+          f"有效像素={n_valid}/{h*w}")
+
+    # 调整
+    new_exposure = initial_exposure
+    if mean_b < 1.0:
+        new_exposure = initial_exposure + 4.0
+        print(f"  [严重欠曝] exposure: {initial_exposure:.1f} → {new_exposure:.1f} (+4.0 EV)")
+    elif mean_b < 40:
+        ev_adj = min(4.0, math.log2(TARGET_MEAN / max(mean_b, 1.0)))
+        new_exposure = initial_exposure + ev_adj + 1.0  # 额外 +1
+        print(f"  [欠曝] exposure: {initial_exposure:.1f} → {new_exposure:.1f} (+{ev_adj:.1f} EV)")
+    elif mean_b > 200:
+        ev_adj = max(-4.0, math.log2(TARGET_MEAN / mean_b))
+        new_exposure = initial_exposure + ev_adj
+        print(f"  [过曝] exposure: {initial_exposure:.1f} → {new_exposure:.1f} ({ev_adj:.1f} EV)")
+    elif overexposed > 0.3:
+        # 平均还行但大面积过曝
+        new_exposure = initial_exposure - 1.5
+        print(f"  [局部过曝 {overexposed:.0%}] exposure: {initial_exposure:.1f} → {new_exposure:.1f} (-1.5 EV)")
+    else:
+        print(f"  [正常] 曝光无需调整")
+
+    # 限幅
+    new_exposure = max(-2.0, min(12.0, new_exposure))
+
+    scene.view_settings.exposure = new_exposure
+    scene.cycles.samples = original_samples
+    return new_exposure
+
+
+# =====================================================================
+# 有效天花板检测（忽略塔尖/天线等异常高点）
+# =====================================================================
+
+def _detect_effective_ceiling(bmin, bmax, floor_z, ceiling_z_raw):
+    """用 raycast 从多个 XY 采样点往上打，统计天花板高度的 75% 分位数。
+
+    塔尖、天线等只有少量采样点能 hit 到，被分位数过滤掉。
+    """
+    scene = bpy.context.scene
+    depsgraph = bpy.context.evaluated_depsgraph_get()
+    dir_up = Vector((0, 0, 1))
+
+    cx = (bmin[0] + bmax[0]) / 2
+    cy = (bmin[1] + bmax[1]) / 2
+    x_range = bmax[0] - bmin[0]
+    y_range = bmax[1] - bmin[1]
+
+    # 5x5 网格采样
+    ceil_hits = []
+    for ix in range(5):
+        for iy in range(5):
+            x = bmin[0] + x_range * (ix + 0.5) / 5
+            y = bmin[1] + y_range * (iy + 0.5) / 5
+            origin = Vector((x, y, floor_z + 0.5))
+            hit, loc, *_ = scene.ray_cast(depsgraph, origin, dir_up)
+            if hit:
+                ceil_hits.append(loc.z)
+
+    if not ceil_hits:
+        print(f"  [天花板] 无 hit，使用 AABB: {ceiling_z_raw:.2f}m")
+        return ceiling_z_raw
+
+    ceil_hits.sort()
+    # 75% 分位数：忽略最高的 25%（塔尖/天线）
+    p75_idx = int(len(ceil_hits) * 0.75)
+    effective_ceil = ceil_hits[min(p75_idx, len(ceil_hits) - 1)]
+
+    # 至少保留 AABB 高度的合理范围（不能比中位数还低太多）
+    median_ceil = ceil_hits[len(ceil_hits) // 2]
+    effective_ceil = max(effective_ceil, median_ceil)
+
+    # 不能比最低的 hit 还低（安全下限）
+    effective_ceil = max(effective_ceil, floor_z + 2.5)
+
+    if effective_ceil < ceiling_z_raw - 1.0:
+        print(f"  [天花板] AABB={ceiling_z_raw:.2f}m → 有效={effective_ceil:.2f}m"
+              f" (忽略 {ceiling_z_raw - effective_ceil:.1f}m 塔尖/天线)")
+    else:
+        print(f"  [天花板] {effective_ceil:.2f}m")
+
+    return effective_ceil
+
+
+# =====================================================================
+# Blender 模式主函数
+# =====================================================================
+
+def main_blender():
+    args = parse_args_blender()
+
+    # 统一 scene_path
+    if args.blend:
+        scene_path = os.path.abspath(args.blend)
+    else:
+        scene_path = os.path.abspath(args.glb)
+
+    output_dir = os.path.abspath(args.output_dir)
+    resolution = tuple(int(x) for x in args.resolution.split(","))
+    os.makedirs(output_dir, exist_ok=True)
+    sel_dir = os.path.join(output_dir, "frame_selection")
+    os.makedirs(sel_dir, exist_ok=True)
+
+    scene_ext = Path(scene_path).suffix.lower()
+
+    print("=" * 60)
+    print("ERPT Blend Pipeline v5（单进程边渲边选）")
+    print("=" * 60)
+    print(f"  Scene:      {scene_path}  [{scene_ext}]")
+    print(f"  Output:     {output_dir}")
+    print(f"  Max frames: {args.num_frames}")
+    print(f"  Resolution: {resolution[0]}x{resolution[1]}")
+    t_start = time.time()
+
+    # ===== Phase 0: 加载场景 =====
+    bmin, bmax = load_scene(scene_path)
+
+    # ===== 渲染设置（只做一次） =====
+    print(f"\n[Setup] 渲染配置")
+    cam_obj = setup_erp_camera()
+    setup_render_settings(resolution, args.engine, args.samples, args.exposure)
+    setup_lighting()
+    depth_fo = setup_depth_pass()
+
+    # ===== Phase 1: 撒点 + 过滤 =====
+    print(f"\n{'='*60}")
+    print("[Phase 1] 多层撒点 + 4层过滤")
+    print(f"{'='*60}")
+
+    floor_z_raw, ceiling_z_raw = bmin[2], bmax[2]
+
+    # 有效天花板检测：用 raycast 忽略塔尖等异常高点
+    ceiling_z = _detect_effective_ceiling(bmin, bmax, floor_z_raw, ceiling_z_raw)
+    floor_z = floor_z_raw
+
+    heights = compute_camera_heights(floor_z, ceiling_z, args.camera_height,
+                                      bmin=bmin, bmax=bmax)
+    print(f"  场景 Z 范围: {floor_z:.2f} ~ {ceiling_z:.2f}m (总高 {ceiling_z - floor_z:.2f}m)")
+    print(f"  相机层数: {len(heights)}")
+    for i, z in enumerate(heights):
+        print(f"    第{i+1}层: Z={z:.2f}m (离地 {z - floor_z:.2f}m)")
+
+    x_range = bmax[0] - bmin[0]
+    y_range = bmax[1] - bmin[1]
+    n_layers = len(heights)
+    scene_diag = math.sqrt(x_range ** 2 + y_range ** 2)
+
+    x_sp = max(0.5, x_range / 20)
+    y_sp = max(0.5, y_range / 20)
+    nx = max(1, int((x_range - 2 * MARGIN) / args.grid_spacing))
+    ny = max(1, int((y_range - 2 * MARGIN) / args.grid_spacing))
+    total_user = nx * ny * n_layers
+
+    if total_user <= 10000:
+        x_sp = args.grid_spacing
+        y_sp = args.grid_spacing
+        print(f"  间距: {args.grid_spacing}m (候选≈{total_user}个)")
+    else:
+        nx_auto = max(1, int((x_range - 2 * MARGIN) / x_sp))
+        ny_auto = max(1, int((y_range - 2 * MARGIN) / y_sp))
+        total_auto = nx_auto * ny_auto * n_layers
+        print(f"  [自适应] 场景 {x_range:.0f}x{y_range:.0f}m, "
+              f"X间距={x_sp:.1f}m, Y间距={y_sp:.1f}m "
+              f"(候选≈{total_auto})")
+
+    candidates = generate_candidate_grid(bmin, bmax, x_sp, y_sp, heights)
+    if not candidates:
+        print("  [Error] 没有候选点")
+        sys.exit(1)
+
+    room_height = ceiling_z - floor_z
+    candidates = raycast_6layer_filter(candidates, room_height)
+    if not candidates:
+        print("  [Warning] 全部被过滤，使用 mesh 中心")
+        cx = (bmin[0] + bmax[0]) / 2
+        cy = (bmin[1] + bmax[1]) / 2
+        candidates = [[cx, cy, heights[0]]]
+
+    np.save(os.path.join(sel_dir, "candidates_filtered.npy"),
+            np.array(candidates))
+
+    # ===== 自动曝光：用候选中心点快速测试 =====
+    mesh_center = [(bmin[0] + bmax[0]) / 2,
+                   (bmin[1] + bmax[1]) / 2,
+                   (bmin[2] + bmax[2]) / 2]
+    # 选最靠近中心的候选作为测试点
+    mc = np.array(mesh_center)
+    test_dists = [np.linalg.norm(np.array(c) - mc) for c in candidates]
+    test_pos = candidates[int(np.argmin(test_dists))]
+    final_exposure = auto_adjust_exposure(cam_obj, test_pos, output_dir, depth_fo, args.exposure)
+
+    # ===== Phase 2: 边渲边选 =====
+    results = run_phase2(
+        cam_obj, candidates, mesh_center, output_dir,
+        args.num_frames, resolution, depth_fo, args)
+
+    # ===== 保存选帧摘要 =====
+    summary = {
+        "scene": os.path.basename(scene_path),
+        "scene_format": scene_ext,
+        "total_frames": len(results),
+        "candidates_count": len(candidates),
+        "frames": [{
+            "frame_id": r["frame_id"],
+            "position": r["position"],
+            "gain": r["gain"],
+            "actual_gain": r["actual_gain"],
+            "delta_ratio": r["delta_ratio"],
+            "score": r["score"],
+        } for r in results],
+    }
+    with open(os.path.join(sel_dir, "selected_frames.json"), "w") as f:
+        json.dump(summary, f, indent=2, ensure_ascii=False)
+
+    dt = time.time() - t_start
+    print(f"\n{'='*60}")
+    print(f"完成! {len(results)} 帧, {dt:.1f}s ({dt/60:.1f}min)")
+    print(f"{'='*60}")
+    print(f"输出目录: {output_dir}/")
+    for r in results:
+        fid = r["frame_id"]
+        print(f"  panorama_{fid:04d}.png  +  _depth.npy  +  pose_{fid:04d}.json")
+
+
+# =====================================================================
+# 入口
+# =====================================================================
+
+if __name__ == "__main__":
+    if IN_BLENDER:
+        main_blender()
+    else:
+        main_python()

pipelines/run_full_pipeline.py

@@ -0,0 +1,1036 @@
+#!/usr/bin/env python3
+"""
+全流程 Pipeline: .blend/.glb/.gltf/.ply → 边渲边选 → ERPT Warp
+
+支持六种模式:
+
+1. 单 Blend 场景:
+    python run_full_pipeline.py \
+        --blender /path/to/blender \
+        --blend /path/to/scene.blend \
+        --scene-name my_scene \
+        --output-root ./dataset
+
+2. 批量 Blend（扫描 input-dir 下所有 .blend）:
+    python run_full_pipeline.py \
+        --blender /path/to/blender \
+        --input-dir /path/to/blend_files/ \
+        --output-root ./dataset
+
+3. 单 GLB/GLTF 场景:
+    python run_full_pipeline.py \
+        --blender /path/to/blender \
+        --glb /path/to/scene.glb \
+        --scene-name my_scene \
+        --output-root ./dataset
+
+4. 批量 GLB（扫描 input-dir 下所有 .glb/.gltf）:
+    python run_full_pipeline.py \
+        --blender /path/to/blender \
+        --input-dir /path/to/glb_files/ \
+        --output-root ./dataset
+
+5. 单 PLY 场景（无需 Blender）:
+    python run_full_pipeline.py \
+        --ply /path/to/scene.ply \
+        --scene-name my_scene \
+        --output-root ./dataset
+
+6. 批量 PLY（扫描 input-dir 下所有 .ply）:
+    python run_full_pipeline.py \
+        --input-dir /path/to/ply_files/ \
+        --output-root ./dataset
+
+    加 --dry-run 预览要跑哪些场景
+    已跑完的场景自动跳过（--no-skip-done 强制重跑）
+"""
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+
+def run_step1_blend_pipeline(
+    blender_exe: str,
+    scene_path: str,
+    temp_dir: str,
+    num_frames: int,
+    resolution: str,
+    samples: int,
+    engine: str,
+    exposure: float,
+    grid_spacing: float,
+    camera_height,
+    stop_gain: float,
+    stop_score: float,
+    stop_delta: float,
+    min_frames: int,
+    rotation_type: str = "random_yaw",
+    gain_curve: bool = True,
+    scene_flag: str = "--blend",
+) -> int:
+    """步骤 1 (Blend/GLB): 调 run_blend_pipeline.py 边渲边选。
+    scene_flag: "--blend" 或 "--glb"
+    """
+    script = Path(__file__).parent / "run_blend_pipeline.py"
+    if not script.exists():
+        raise FileNotFoundError(f"找不到 run_blend_pipeline.py: {script}")
+
+    cmd = [
+        sys.executable, str(script),
+        "--blender", blender_exe,
+        scene_flag, scene_path,
+        "--output-dir", temp_dir,
+        "--num-frames", str(num_frames),
+        "--render-depth",
+        "--resolution", resolution,
+        "--samples", str(samples),
+        "--engine", engine,
+        "--exposure", str(exposure),
+        "--grid-spacing", str(grid_spacing),
+        "--stop-gain", str(stop_gain),
+        "--stop-score", str(stop_score),
+        "--stop-delta", str(stop_delta),
+        "--min-frames", str(min_frames),
+        "--rotation-type", rotation_type,
+    ]
+    if camera_height is not None:
+        cmd += ["--camera-height", str(camera_height)]
+    if not gain_curve:
+        cmd += ["--no-gain-curve"]
+
+    print(f"\n{'='*60}")
+    print("[Step 1] 边渲边选 (Blender Cycles)")
+    print(f"{'='*60}")
+
+    proc = subprocess.run(cmd, text=True)
+    if proc.returncode != 0:
+        print(f"  [Error] run_blend_pipeline 退出码: {proc.returncode}")
+        return proc.returncode
+
+    n = sum(1 for f in Path(temp_dir).glob("panorama_*.png"))
+    print(f"  渲染完成: {n} 帧")
+    return 0
+
+
+def run_step1_ply_pipeline(
+    ply_path: str,
+    temp_dir: str,
+    num_frames: int,
+    resolution: str,
+    grid_spacing: float,
+    camera_height,
+    stop_gain: float,
+    stop_score: float,
+    stop_delta: float,
+    min_frames: int,
+    rotation_type: str = "random_yaw",
+    point_size: float = 2.0,
+    z_up: bool = True,
+) -> int:
+    """步骤 1 (PLY): 调 run_ply_pipeline.py 边渲边选（无需 Blender）"""
+    script = Path(__file__).parent / "run_ply_pipeline.py"
+    if not script.exists():
+        raise FileNotFoundError(f"找不到 run_ply_pipeline.py: {script}")
+
+    cmd = [
+        sys.executable, str(script),
+        "--ply", ply_path,
+        "--output-dir", temp_dir,
+        "--num-frames", str(num_frames),
+        "--resolution", resolution,
+        "--grid-spacing", str(grid_spacing),
+        "--stop-gain", str(stop_gain),
+        "--stop-score", str(stop_score),
+        "--stop-delta", str(stop_delta),
+        "--min-frames", str(min_frames),
+        "--rotation-type", rotation_type,
+        "--point-size", str(point_size),
+    ]
+    if camera_height is not None:
+        cmd += ["--camera-height", str(camera_height)]
+    if not z_up:
+        cmd += ["--no-z-up"]
+
+    print(f"\n{'='*60}")
+    print("[Step 1] 边渲边选 (PLY 点云)")
+    print(f"{'='*60}")
+
+    proc = subprocess.run(cmd, text=True)
+    if proc.returncode != 0:
+        print(f"  [Error] run_ply_pipeline 退出码: {proc.returncode}")
+        return proc.returncode
+
+    n = sum(1 for f in Path(temp_dir).glob("panorama_*.png"))
+    print(f"  渲染完成: {n} 帧")
+    return 0
+
+
+def run_step1_hm3d_pipeline(
+    blender_exe: str,
+    scene_path: str,
+    temp_dir: str,
+    num_frames: int,
+    resolution: str,
+    samples: int,
+    engine: str,
+    exposure: float,
+    grid_spacing: float,
+    camera_height,
+    stop_gain: float,
+    stop_score: float,
+    stop_delta: float,
+    min_frames: int,
+    rotation_type: str = "random_yaw",
+    gain_curve: bool = True,
+) -> int:
+    """步骤 1 (HM3D GLB): 调 run_hm3d_pipeline.py 边渲边选。"""
+    script = Path(__file__).parent / "run_hm3d_pipeline.py"
+    if not script.exists():
+        raise FileNotFoundError(f"找不到 run_hm3d_pipeline.py: {script}")
+
+    cmd = [
+        sys.executable, str(script),
+        "--blender", blender_exe,
+        "--glb", scene_path,
+        "--output-dir", temp_dir,
+        "--num-frames", str(num_frames),
+        "--render-depth",
+        "--resolution", resolution,
+        "--samples", str(samples),
+        "--engine", engine,
+        "--exposure", str(exposure),
+        "--grid-spacing", str(grid_spacing),
+        "--stop-gain", str(stop_gain),
+        "--stop-score", str(stop_score),
+        "--stop-delta", str(stop_delta),
+        "--min-frames", str(min_frames),
+        "--rotation-type", rotation_type,
+        "--hm3d", "True",
+    ]
+    if camera_height is not None:
+        cmd += ["--camera-height", str(camera_height)]
+    if not gain_curve:
+        cmd += ["--no-gain-curve"]
+
+    print(f"\n{'='*60}")
+    print("[Step 1] 边渲边选 (HM3D GLB)")
+    print(f"{'='*60}")
+
+    proc = subprocess.run(cmd, text=True)
+    if proc.returncode != 0:
+        print(f"  [Error] run_hm3d_pipeline 退出码: {proc.returncode}")
+        return proc.returncode
+
+    n = sum(1 for f in Path(temp_dir).rglob("panorama_*.png"))
+    print(f"  渲染完成: {n} 帧")
+    return 0
+
+
+def run_step2_organize_hm3d(temp_dir: str, scene_dir: str) -> int:
+    """步骤 2 (HM3D): 整理多空间目录结构
+
+    temp_dir 里有:
+        frame_selection/
+        space_00/ (panorama_*.png, *_depth.npy, pose_*.json)
+        space_01/
+        ...
+
+    整理成（每个 space 一个独立目录）:
+        scene_dir/space_00/input/   → 中心帧 RGB + depth + 所有 pose
+        scene_dir/space_00/output/  → 所有帧 RGB + depth（GT 真值）
+        scene_dir/space_01/input/
+        scene_dir/space_01/output/
+        ...
+        scene_dir/frame_selection/  → 选帧信息
+    """
+    temp = Path(temp_dir)
+
+    print(f"\n{'='*60}")
+    print("[Step 2] 整理目录结构 (HM3D 多空间)")
+    print(f"{'='*60}")
+
+    space_dirs = sorted(
+        [d for d in temp.iterdir() if d.is_dir() and d.name.startswith("space_")]
+    )
+    if not space_dirs:
+        print("  [Error] 没有找到 space_XX 目录")
+        return 1
+
+    print(f"  共 {len(space_dirs)} 个空间")
+
+    for space_d in space_dirs:
+        space_name = space_d.name
+
+        rgb_files = sorted(space_d.glob("panorama_*.png"))
+        if not rgb_files:
+            print(f"  {space_name}: 无渲染结果，跳过")
+            continue
+
+        n_frames = len(rgb_files)
+        out_space_dir = Path(scene_dir) / space_name
+        inp_dir = out_space_dir / "input"
+        out_dir = out_space_dir / "output"
+        inp_dir.mkdir(parents=True, exist_ok=True)
+        out_dir.mkdir(parents=True, exist_ok=True)
+
+        for rgb_path in rgb_files:
+            shutil.copy2(str(rgb_path), str(out_dir / rgb_path.name))
+            depth_path = space_d / rgb_path.name.replace(".png", "_depth.npy")
+            if depth_path.exists():
+                shutil.copy2(str(depth_path), str(out_dir / depth_path.name))
+
+        center_rgb = space_d / "panorama_0000.png"
+        center_depth = space_d / "panorama_0000_depth.npy"
+        if center_rgb.exists():
+            shutil.copy2(str(center_rgb), str(inp_dir / center_rgb.name))
+        if center_depth.exists():
+            shutil.copy2(str(center_depth), str(inp_dir / center_depth.name))
+
+        n_pose = 0
+        for pose_path in sorted(space_d.glob("pose_*.json")):
+            shutil.copy2(str(pose_path), str(inp_dir / pose_path.name))
+            n_pose += 1
+
+        print(f"  {space_name}: {n_frames} 帧 → output/, 中心帧 + {n_pose} pose → input/")
+
+    sel_dir = Path(scene_dir) / "frame_selection"
+    sel_dir.mkdir(parents=True, exist_ok=True)
+
+    sel_json = temp / "frame_selection" / "selected_frames.json"
+    if sel_json.exists():
+        shutil.copy2(str(sel_json), str(sel_dir / "selected_frames.json"))
+
+    cand_npy = temp / "frame_selection" / "candidates_filtered.npy"
+    if cand_npy.exists():
+        shutil.copy2(str(cand_npy), str(sel_dir / "candidates_filtered.npy"))
+
+    return 0
+
+
+def run_step2_organize(temp_dir: str, scene_dir: str) -> int:
+    """步骤 2: 整理目录结构
+
+    temp_dir 里有:
+        panorama_0000.png, panorama_0000_depth.npy, pose_0000.json, ...
+
+    整理成:
+        scene_dir/input/   → 中心帧 RGB + depth + 所��� pose（供 ERPT warp 使用）
+        scene_dir/output/  → 所有帧 RGB + depth（GT 真值）
+    """
+    temp = Path(temp_dir)
+    inp_dir = Path(scene_dir) / "input"
+    out_dir = Path(scene_dir) / "output"
+    inp_dir.mkdir(parents=True, exist_ok=True)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    print(f"\n{'='*60}")
+    print("[Step 2] 整理目录结构")
+    print(f"{'='*60}")
+
+    # 找所有帧
+    rgb_files = sorted(temp.glob("panorama_*.png"))
+    if not rgb_files:
+        print("  [Error] 没有找到渲染的全景图")
+        return 1
+
+    n_frames = len(rgb_files)
+    print(f"  共 {n_frames} 帧")
+
+    # output/: 复制所有帧的 RGB + depth（GT 真值）
+    for rgb_path in rgb_files:
+        shutil.copy2(str(rgb_path), str(out_dir / rgb_path.name))
+        # depth
+        depth_path = temp / rgb_path.name.replace(".png", "_depth.npy")
+        if depth_path.exists():
+            shutil.copy2(str(depth_path), str(out_dir / depth_path.name))
+
+    print(f"  output/: {n_frames} 帧 RGB + depth")
+
+    # input/: 中心帧 RGB + depth + 所有 pose
+    center_rgb = temp / "panorama_0000.png"
+    center_depth = temp / "panorama_0000_depth.npy"
+
+    if center_rgb.exists():
+        shutil.copy2(str(center_rgb), str(inp_dir / center_rgb.name))
+    if center_depth.exists():
+        shutil.copy2(str(center_depth), str(inp_dir / center_depth.name))
+
+    # 所有 pose
+    n_pose = 0
+    for pose_path in sorted(temp.glob("pose_*.json")):
+        shutil.copy2(str(pose_path), str(inp_dir / pose_path.name))
+        n_pose += 1
+
+    print(f"  input/: 中心帧 + {n_pose} 个 pose")
+
+    # 复制选帧信息（供参考）
+    sel_dir = inp_dir / "frame_selection"
+    sel_dir.mkdir(parents=True, exist_ok=True)
+
+    sel_json = temp / "frame_selection" / "selected_frames.json"
+    if sel_json.exists():
+        shutil.copy2(str(sel_json), str(sel_dir / "selected_frames.json"))
+
+    cand_npy = temp / "frame_selection" / "candidates_filtered.npy"
+    if cand_npy.exists():
+        shutil.copy2(str(cand_npy), str(sel_dir / "candidates_filtered.npy"))
+
+    # 增益曲线（从 selected_frames.json 读数据，用 PIL 画）
+    if sel_json.exists():
+        try:
+            draw_gain_curve(str(sel_dir / "selected_frames.json"),
+                            str(sel_dir / "gain_curve.jpg"))
+            print(f"  增益曲线: {sel_dir}/gain_curve.jpg")
+        except Exception as e:
+            print(f"  [跳过] 画增益曲线失败: {e}")
+
+    return 0
+
+
+def draw_gain_curve(json_path, output_path):
+    """画增益曲线（优先 matplotlib，fallback PIL）"""
+    with open(json_path) as f:
+        data = json.load(f)
+
+    frames = [fr for fr in data["frames"] if not fr.get("skipped")]
+    if len(frames) < 2:
+        return
+
+    fids = [fr["frame_id"] for fr in frames]
+    pred_gains = [fr["gain"] for fr in frames]
+    actual_gains = [fr["actual_gain"] for fr in frames]
+    scores = [fr["score"] for fr in frames]
+    deltas = [fr["delta_ratio"] for fr in frames]
+
+    try:
+        import matplotlib
+        matplotlib.use('Agg')
+        import matplotlib.pyplot as plt
+
+        fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(10, 6), sharex=True)
+
+        ax1.plot(fids, pred_gains, 'o-', color='#2196F3', label='predicted', markersize=3, linewidth=1.5)
+        ax1.plot(fids, actual_gains, 'o-', color='#FF9800', label='actual', markersize=3, linewidth=1.5)
+        ax1.axhline(y=0.05, color='red', linestyle='--', alpha=0.5, label='stop_gain=5%')
+        ax1.set_ylabel('gain')
+        ax1.set_ylim(-0.05, 1.05)
+        ax1.legend(loc='upper right', fontsize=9)
+        ax1.set_title(f'Gain Curve ({len(frames)} frames)', fontsize=11)
+        ax1.grid(True, alpha=0.3)
+        # 标注首末值
+        ax1.annotate(f'{actual_gains[0]:.0%}', (fids[0], actual_gains[0]),
+                     textcoords="offset points", xytext=(5, 5), fontsize=7, color='#FF9800')
+        ax1.annotate(f'{actual_gains[-1]:.0%}', (fids[-1], actual_gains[-1]),
+                     textcoords="offset points", xytext=(-25, 5), fontsize=7, color='#FF9800')
+
+        ax2.plot(fids, scores, 'D-', color='#4CAF50', label='score', markersize=3, linewidth=1.5)
+        ax2.plot(fids, deltas, 's-', color='#9C27B0', label='delta', markersize=2, linewidth=1.2)
+        ax2.axhline(y=-0.33, color='red', linestyle='--', alpha=0.5, label='stop_score=-0.33')
+        ax2.axhline(y=0.01, color='#9C27B0', linestyle=':', alpha=0.4, label='stop_delta=1%')
+        ax2.set_ylabel('value')
+        ax2.set_xlabel('frame')
+        ax2.legend(loc='upper right', fontsize=9)
+        ax2.grid(True, alpha=0.3)
+        # 标注首末值
+        ax2.annotate(f'{deltas[0]:.1%}', (fids[0], deltas[0]),
+                     textcoords="offset points", xytext=(5, 5), fontsize=7, color='#9C27B0')
+        ax2.annotate(f'{deltas[-1]:.1%}', (fids[-1], deltas[-1]),
+                     textcoords="offset points", xytext=(-25, -10), fontsize=7, color='#9C27B0')
+
+        plt.tight_layout()
+        plt.savefig(output_path, dpi=150, bbox_inches='tight')
+        plt.close()
+        return
+
+    except ImportError:
+        pass
+
+    # ---- fallback: PIL ----
+    try:
+        from PIL import Image, ImageDraw, ImageFont
+
+        W, H = 800, 500
+        ML, MR, MT, MB = 50, 20, 30, 25
+        MID = H // 2
+        pw = W - ML - MR
+
+        img = Image.new("RGB", (W, H), "white")
+        draw = ImageDraw.Draw(img)
+        try:
+            font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 9)
+        except Exception:
+            font = ImageFont.load_default()
+
+        n = len(frames)
+
+        def px(i, v, y0, y1, vmin, vmax):
+            x = ML + int(i / max(n-1,1) * pw)
+            y = y0 + int((1 - (v-vmin)/(vmax-vmin)) * (y1-y0))
+            return x, max(y0, min(y1, y))
+
+        def line(pts, color, y0, y1, vmin, vmax):
+            for j in range(len(pts)-1):
+                draw.line([px(j,pts[j],y0,y1,vmin,vmax), px(j+1,pts[j+1],y0,y1,vmin,vmax)], fill=color, width=2)
+
+        line(pred_gains, "#2196F3", MT, MID-5, 0, 1.05)
+        line(actual_gains, "#FF9800", MT, MID-5, 0, 1.05)
+        line(scores, "#4CAF50", MID+10, H-MB, -0.6, 1.05)
+        line(deltas, "#9C27B0", MID+10, H-MB, -0.6, 1.05)
+
+        draw.text((ML, MT-12), f"Gain ({n} frames)", fill="black", font=font)
+        draw.text((ML, MID+2), "Score / Delta", fill="black", font=font)
+        img.save(output_path, quality=90)
+
+    except ImportError:
+        pass
+
+
+def run_step3_erpt_warp_hm3d(scene_dir: str, device: str = "cuda") -> int:
+    """步骤 3 (HM3D): 对每个空间调 run_pipeline.py 执行 ERPT warp
+
+    遍历 scene_dir/space_XX/input/，对帧数 >= 2 的空间生成 warp 文件
+    """
+    script = Path(__file__).parent / "run_pipeline.py"
+    if not script.exists():
+        raise FileNotFoundError(f"找不到 run_pipeline.py: {script}")
+
+    print(f"\n{'='*60}")
+    print("[Step 3] ERPT Warp (HM3D 多空间)")
+    print(f"{'='*60}")
+
+    scene_path = Path(scene_dir)
+    space_dirs = sorted(
+        [d for d in scene_path.iterdir()
+         if d.is_dir() and d.name.startswith("space_")]
+    )
+
+    if not space_dirs:
+        print("  [Error] 没有找到 space_XX 目录")
+        return 1
+
+    total_ret = 0
+    n_warped = 0
+    n_skipped = 0
+
+    for space_d in space_dirs:
+        inp_dir = space_d / "input"
+        if not inp_dir.exists():
+            continue
+
+        n_poses = len(list(inp_dir.glob("pose_*.json")))
+        if n_poses < 2:
+            print(f"  {space_d.name}: {n_poses} pose，跳过 warp")
+            n_skipped += 1
+            continue
+
+        print(f"\n  [{space_d.name}] ERPT Warp ({n_poses} poses)...")
+
+        cmd = [
+            sys.executable, str(script),
+            "--stage", "warp_only",
+            "--data_dir", str(inp_dir),
+            "--output_dir", str(inp_dir),
+            "--device", device,
+            "--center_frame", "0",
+        ]
+
+        proc = subprocess.run(cmd, text=True)
+        if proc.returncode != 0:
+            print(f"    [Error] {space_d.name} warp 失败 (退出码: {proc.returncode})")
+            total_ret = proc.returncode
+            continue
+
+        warp_rgb_dir = inp_dir / "warp_rgb"
+        warp_depth_dir = inp_dir / "warp_depth"
+        keep_suffixes = ("_rgb.png", "_mask.png", "_depth_range.npy")
+
+        n_moved = 0
+        for subdir in [warp_rgb_dir, warp_depth_dir]:
+            if subdir.exists():
+                for f in subdir.iterdir():
+                    if f.is_file() and any(f.name.endswith(s) for s in keep_suffixes):
+                        shutil.move(str(f), str(inp_dir / f.name))
+                        n_moved += 1
+                shutil.rmtree(str(subdir), ignore_errors=True)
+
+        n_warped += 1
+        print(f"    warp 文件: {n_moved} 个")
+
+    print(f"\n  Warp 完成: {n_warped} 个空间, 跳过 {n_skipped} 个")
+    return total_ret
+
+
+def run_step3_erpt_warp(scene_dir: str, device: str = "cuda") -> int:
+    """步骤 3: 调 run_pipeline.py 执行 ERPT warp
+
+    读取 scene_dir/input/ 里的中心帧 + pose → 生成 warp 文件
+    warp 文件直接写到 input/ 目录
+    """
+    script = Path(__file__).parent / "run_pipeline.py"
+    if not script.exists():
+        raise FileNotFoundError(f"找不到 run_pipeline.py: {script}")
+
+    inp_dir = Path(scene_dir) / "input"
+
+    print(f"\n{'='*60}")
+    print("[Step 3] ERPT Warp")
+    print(f"{'='*60}")
+
+    cmd = [
+        sys.executable, str(script),
+        "--stage", "warp_only",
+        "--data_dir", str(inp_dir),
+        "--output_dir", str(inp_dir),
+        "--device", device,
+        "--center_frame", "0",
+    ]
+
+    proc = subprocess.run(cmd, text=True)
+    if proc.returncode != 0:
+        print(f"  [Error] run_pipeline 退出码: {proc.returncode}")
+        return proc.returncode
+
+    # 把 warp 子目录里需要的文件提到 input/ 根目录
+    # 只保留: _rgb.png, _mask.png, _depth_range.npy
+    warp_rgb_dir = inp_dir / "warp_rgb"
+    warp_depth_dir = inp_dir / "warp_depth"
+    keep_suffixes = ("_rgb.png", "_mask.png", "_depth_range.npy")
+
+    n_moved = 0
+    for subdir in [warp_rgb_dir, warp_depth_dir]:
+        if subdir.exists():
+            for f in subdir.iterdir():
+                if f.is_file() and any(f.name.endswith(s) for s in keep_suffixes):
+                    shutil.move(str(f), str(inp_dir / f.name))
+                    n_moved += 1
+            # 删除整个子目录（包含不需要的 flow/weight_sum/comparison 等）
+            shutil.rmtree(str(subdir), ignore_errors=True)
+
+    print(f"  warp 文件已移到 input/: {n_moved} 个")
+    return 0
+
+
+def is_already_done(output_root, scene_name):
+    """检查是否已经跑完"""
+    sel_path = os.path.join(
+        output_root, scene_name, "input", "frame_selection",
+        "selected_frames.json")
+    if not os.path.exists(sel_path):
+        # 也检查 input/ 下直接放的
+        sel_path = os.path.join(output_root, scene_name, "input",
+                                "selected_frames.json")
+        if not os.path.exists(sel_path):
+            return False
+    try:
+        with open(sel_path) as f:
+            data = json.load(f)
+        return data.get("total_frames", 0) > 0
+    except Exception:
+        return False
+
+
+def find_glb_files(input_dir):
+    """递归查找所有 .glb / .gltf 文件，返回 [(glb_path, scene_name), ...]
+
+    scene_name 取文件名（不含扩展名），或第一级子目录名（如有子目录）。
+    """
+    input_dir = os.path.abspath(input_dir)
+    glb_files = []
+    for root, dirs, files in os.walk(input_dir):
+        for f in files:
+            if f.lower().endswith(".glb") or f.lower().endswith(".gltf"):
+                glb_path = os.path.join(root, f)
+                rel = os.path.relpath(root, input_dir)
+                if rel == ".":
+                    scene_name = os.path.splitext(f)[0]
+                else:
+                    scene_name = rel.split(os.sep)[0]
+                glb_files.append((glb_path, scene_name))
+    glb_files.sort(key=lambda x: x[1])
+    return glb_files
+
+
+def find_blend_files(input_dir):
+    """递归查找所有 .blend 文件，返回 [(blend_path, scene_name), ...]
+    
+    scene_name 取 input_dir 下的第一级子目录名（scene_indoor_XXXX），
+    不管 .blend 文件嵌套了几层。
+    
+    例如:
+      input_dir = /path/to/dataset/indoor
+      .blend 在 /path/to/dataset/indoor/scene_indoor_0001/1407m1/xxx.blend
+      → scene_name = scene_indoor_0001
+    """
+    input_dir = os.path.abspath(input_dir)
+    blend_files = []
+    for root, dirs, files in os.walk(input_dir):
+        for f in files:
+            if f.endswith(".blend"):
+                blend_path = os.path.join(root, f)
+                rel = os.path.relpath(root, input_dir)
+                scene_name = rel.split(os.sep)[0]
+                blend_files.append((blend_path, scene_name))
+    blend_files.sort(key=lambda x: x[1])
+    return blend_files
+
+
+def find_ply_files(input_dir):
+    """递归查找所有 .ply 文件，返回 [(ply_path, scene_name), ...]
+
+    scene_name 取文件名（不含扩展名），或第一级子目录名（如有子目录）。
+    """
+    input_dir = os.path.abspath(input_dir)
+    ply_files = []
+    for root, dirs, files in os.walk(input_dir):
+        for f in files:
+            if f.lower().endswith(".ply"):
+                ply_path = os.path.join(root, f)
+                rel = os.path.relpath(root, input_dir)
+                if rel == ".":
+                    scene_name = os.path.splitext(f)[0]
+                else:
+                    scene_name = rel.split(os.sep)[0]
+                ply_files.append((ply_path, scene_name))
+    ply_files.sort(key=lambda x: x[1])
+    return ply_files
+
+
+def run_single_scene(args, scene_path, scene_name, scene_type="blend"):
+    """跑单个场景，返回 0=成功 / 非0=失败
+
+    scene_type: "blend" | "glb" | "hm3d" | "ply"
+    """
+    output_root = str(Path(args.output_root).resolve())
+    scene_dir = os.path.join(output_root, scene_name)
+    temp_dir = os.path.join(scene_dir, "_render_temp")
+    os.makedirs(scene_dir, exist_ok=True)
+
+    type_labels = {
+        "blend": ".blend (Blender Cycles)",
+        "glb":   ".glb/.gltf (Blender Cycles)",
+        "hm3d":  ".glb/.gltf (HM3D 渲染)",
+        "ply":   ".ply (点云渲染)",
+    }
+    type_label = type_labels.get(scene_type, scene_type)
+    print("=" * 60)
+    print(f"全流程 Pipeline: {type_label} → 边渲边选 → ERPT Warp")
+    print("=" * 60)
+    print(f"  Scene:  {scene_name}")
+    print(f"  Input:  {scene_path}")
+    print(f"  Output: {scene_dir}/")
+    t_start = time.time()
+
+    # Step 1
+    if scene_type == "hm3d":
+        ret = run_step1_hm3d_pipeline(
+            blender_exe=args.blender,
+            scene_path=scene_path,
+            temp_dir=temp_dir,
+            num_frames=args.num_frames,
+            resolution=args.resolution,
+            samples=args.samples,
+            engine=args.engine,
+            exposure=args.exposure,
+            grid_spacing=args.grid_spacing,
+            camera_height=args.camera_height,
+            stop_gain=args.stop_gain,
+            stop_score=args.stop_score,
+            stop_delta=args.stop_delta,
+            min_frames=args.min_frames,
+            rotation_type=args.rotation_type,
+            gain_curve=getattr(args, "gain_curve", True),
+        )
+    elif scene_type in ("blend", "glb"):
+        scene_flag = "--blend" if scene_type == "blend" else "--glb"
+        ret = run_step1_blend_pipeline(
+            blender_exe=args.blender,
+            scene_path=scene_path,
+            temp_dir=temp_dir,
+            num_frames=args.num_frames,
+            resolution=args.resolution,
+            samples=args.samples,
+            engine=args.engine,
+            exposure=args.exposure,
+            grid_spacing=args.grid_spacing,
+            camera_height=args.camera_height,
+            stop_gain=args.stop_gain,
+            stop_score=args.stop_score,
+            stop_delta=args.stop_delta,
+            min_frames=args.min_frames,
+            rotation_type=args.rotation_type,
+            gain_curve=getattr(args, "gain_curve", True),
+            scene_flag=scene_flag,
+        )
+    else:
+        ret = run_step1_ply_pipeline(
+            ply_path=scene_path,
+            temp_dir=temp_dir,
+            num_frames=args.num_frames,
+            resolution=args.resolution,
+            grid_spacing=args.grid_spacing,
+            camera_height=args.camera_height,
+            stop_gain=args.stop_gain,
+            stop_score=args.stop_score,
+            stop_delta=args.stop_delta,
+            min_frames=args.min_frames,
+            rotation_type=args.rotation_type,
+            point_size=getattr(args, "point_size", 2.0),
+            z_up=getattr(args, "z_up", True),
+        )
+
+    if ret != 0:
+        print(f"[Error] Step 1 失败")
+        return ret
+
+    # Step 2
+    if scene_type == "hm3d":
+        ret = run_step2_organize_hm3d(temp_dir, scene_dir)
+    else:
+        ret = run_step2_organize(temp_dir, scene_dir)
+    if ret != 0:
+        print(f"[Error] Step 2 失败")
+        return ret
+
+    # Step 3
+    if not args.skip_warp:
+        if scene_type == "hm3d":
+            ret = run_step3_erpt_warp_hm3d(scene_dir, device=args.device)
+        else:
+            ret = run_step3_erpt_warp(scene_dir, device=args.device)
+        if ret != 0:
+            print(f"[Error] Step 3 失败")
+
+    # 清理
+    if os.path.exists(temp_dir):
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+    dt = time.time() - t_start
+    print(f"\n{'='*60}")
+    print(f"完成! {scene_name}, {dt:.1f}s ({dt/60:.1f}min)")
+    print(f"{'='*60}")
+    return 0
+
+
+def run_single(args):
+    """单场景模式（blend、glb、hm3d 或 ply）"""
+    if args.ply:
+        ply_path = str(Path(args.ply).resolve())
+        scene_name = args.scene_name or Path(args.ply).stem
+        ret = run_single_scene(args, ply_path, scene_name, scene_type="ply")
+    elif args.hm3d:
+        glb_path = str(Path(args.hm3d).resolve())
+        scene_name = args.scene_name or Path(args.hm3d).stem
+        ret = run_single_scene(args, glb_path, scene_name, scene_type="hm3d")
+    elif args.glb:
+        glb_path = str(Path(args.glb).resolve())
+        scene_name = args.scene_name or Path(args.glb).stem
+        ret = run_single_scene(args, glb_path, scene_name, scene_type="glb")
+    else:
+        blend_path = str(Path(args.blend).resolve())
+        scene_name = args.scene_name or Path(args.blend).stem
+        ret = run_single_scene(args, blend_path, scene_name, scene_type="blend")
+    if ret != 0:
+        sys.exit(1)
+
+
+def run_batch(args):
+    """批量模式（自动检测 .blend / .glb / .gltf / .ply）"""
+    input_dir_abs = os.path.abspath(args.input_dir)
+    if not os.path.isdir(input_dir_abs):
+        print(f"[Error] --input-dir 目录不存在: {input_dir_abs}")
+        print(f"        (原始参数: {args.input_dir})")
+        sys.exit(1)
+
+    # 没有 --blender → 只能跑 PLY
+    if not getattr(args, "blender", None):
+        scene_files = find_ply_files(args.input_dir)
+        scene_type = "ply"
+        ext_label = ".ply"
+    else:
+        # 有 blender：优先 .blend，其次 .glb/.gltf (HM3D)，最后 .ply
+        scene_files = find_blend_files(args.input_dir)
+        scene_type = "blend"
+        ext_label = ".blend"
+        if not scene_files:
+            scene_files = find_glb_files(args.input_dir)
+            scene_type = "hm3d"  # 默认使用 HM3D 渲染管线
+            ext_label = ".glb/.gltf (HM3D)"
+        if not scene_files:
+            scene_files = find_ply_files(args.input_dir)
+            scene_type = "ply"
+            ext_label = ".ply"
+
+    if not scene_files:
+        print(f"[Error] 在 {args.input_dir} 下没找到 {ext_label} 文件")
+        sys.exit(1)
+
+    output_root = str(Path(args.output_root).resolve())
+
+    print(f"{'='*60}")
+    print(f"批量处理模式 ({ext_label})")
+    print(f"{'='*60}")
+    print(f"  输入目录: {args.input_dir}")
+    print(f"  输出目录: {output_root}")
+    print(f"  找到 {len(scene_files)} 个 {ext_label} 文件")
+    # input(f"  按 Enter 键继续，或 Ctrl+C 取消...")
+    
+    to_run = []
+    skipped = []
+    for scene_path, scene_name in scene_files:
+        if args.skip_done and is_already_done(output_root, scene_name):
+            skipped.append((scene_path, scene_name))
+        else:
+            to_run.append((scene_path, scene_name))
+
+    if skipped:
+        print(f"  跳过 {len(skipped)} 个已完成:")
+        for _, sn in skipped:
+            print(f"    ✓ {sn}")
+
+    print(f"  待处理 {len(to_run)} 个:")
+    for bp, sn in to_run:
+        print(f"    → {sn}  ({os.path.basename(bp)})")
+
+    if args.dry_run:
+        print(f"\n[Dry run] 不实际运行")
+        return
+
+    if not to_run:
+        print(f"\n全部已完成!")
+        return
+
+    t_all = time.time()
+    success = []
+    failed = []
+
+    for idx, (scene_path, scene_name) in enumerate(to_run):
+        print(f"\n{'='*60}")
+        print(f"[{idx+1}/{len(to_run)}] {scene_name}")
+        print(f"{'='*60}")
+
+        t_scene = time.time()
+        try:
+            ret = run_single_scene(args, scene_path, scene_name, scene_type)
+            dt = time.time() - t_scene
+            if ret == 0:
+                success.append((scene_name, dt))
+                print(f"\n  ✓ {scene_name} ({dt:.0f}s)")
+            else:
+                failed.append((scene_name, f"exit code {ret}"))
+                print(f"\n  ✗ {scene_name} 失败 ({dt:.0f}s)")
+        except Exception as e:
+            dt = time.time() - t_scene
+            failed.append((scene_name, str(e)))
+            print(f"\n  ✗ {scene_name} 异常: {e} ({dt:.0f}s)")
+
+    dt_all = time.time() - t_all
+    print(f"\n{'='*60}")
+    print(f"批量处理完成")
+    print(f"{'='*60}")
+    print(f"  总耗时: {dt_all:.0f}s ({dt_all/60:.1f}min = {dt_all/3600:.1f}h)")
+    print(f"  成功: {len(success)} 个")
+    for sn, dt in success:
+        print(f"    ✓ {sn} ({dt:.0f}s)")
+    if failed:
+        print(f"  失败: {len(failed)} 个")
+        for sn, reason in failed:
+            print(f"    ✗ {sn}: {reason}")
+    if skipped:
+        print(f"  跳过: {len(skipped)} 个 (已完成)")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="全流程: .blend/.glb/.ply → 边渲边选 → ERPT Warp"
+    )
+
+    # 输入（四种模式互斥）
+    input_group = parser.add_mutually_exclusive_group()
+    input_group.add_argument("--blend", type=str, default=None,
+                             help=".blend 场景文件路径（单 Blend 场景模式）")
+    input_group.add_argument("--glb", type=str, default=None,
+                             help=".glb / .gltf 场景文件路径（单 GLB 场景模式）")
+    input_group.add_argument("--hm3d", type=str, default=None,
+                             help=".glb / .gltf 场景文件路径（单 HM3D 场景模式）")
+    input_group.add_argument("--ply", type=str, default=None,
+                             help=".ply 场景文件路径（单 PLY 场景模式）")
+
+    parser.add_argument("--input-dir", type=str, default=None,
+                        help="包含场景文件的根目录（批量模式，自动检测 .blend/.glb/.ply）")
+    parser.add_argument("--scene-name", type=str, default=None,
+                        help="场景名（默认从文件名提取）")
+    parser.add_argument("--output-root", type=str, default="./dataset",
+                        help="输出根目录（默认 ./dataset）")
+
+    # Blender 参数（仅 Blend/GLB/HM3D 模式需要）
+    parser.add_argument("--blender", type=str, default=None,
+                        help="Blender 可执行文件路径（Blend/GLB/HM3D 模式必须）")
+    parser.add_argument("--samples", type=int, default=128)
+    parser.add_argument("--engine", type=str, default="CYCLES")
+    parser.add_argument("--exposure", type=float, default=0.0)
+    parser.add_argument("--gain-curve", action="store_true", default=True,
+                        help="画增益曲线 (默认开启)")
+    parser.add_argument("--no-gain-curve", dest="gain_curve", action="store_false")
+
+    # PLY 参数（仅 PLY 模式）
+    parser.add_argument("--point-size", type=float, default=2.0,
+                        help="点云渲染点径（像素），PLY 模式有效（默认 2.0）")
+    parser.add_argument("--z-up", action="store_true", default=True,
+                        help="PLY 坐标系为 Z-up（默认 True）")
+    parser.add_argument("--no-z-up", dest="z_up", action="store_false",
+                        help="PLY 坐标系为 Y-up（已是 ERPT_native，不转换）")
+
+    # 通用渲染参数
+    parser.add_argument("--num-frames", type=int, default=30)
+    parser.add_argument("--resolution", type=str, default="2048,1024")
+
+    # 选帧参数
+    parser.add_argument("--grid-spacing", type=float, default=0.5)
+    parser.add_argument("--camera-height", type=float, default=None)
+    parser.add_argument("--stop-gain", type=float, default=0.08)
+    parser.add_argument("--stop-score", type=float, default=-0.3)
+    parser.add_argument("--stop-delta", type=float, default=0.08)
+    parser.add_argument("--min-frames", type=int, default=5)
+    parser.add_argument("--rotation-type", type=str, default="random_yaw",
+                        choices=["none", "rotate_x_90", "rotate_x_180",
+                                 "rotate_z_90", "random_yaw"])
+
+    # ERPT 参数
+    parser.add_argument("--device", type=str, default="cuda")
+    parser.add_argument("--skip-warp", action="store_true",
+                        help="只做步骤 1+2，跳过 ERPT warp")
+
+    # 批量模式参数
+    parser.add_argument("--skip-done", action="store_true", default=True,
+                        help="跳过已跑完的场景（默认开启）")
+    parser.add_argument("--no-skip-done", action="store_true",
+                        help="强制重跑所有场景")
+    parser.add_argument("--dry-run", action="store_true",
+                        help="只列出要跑的场景，不实际运行")
+
+    args = parser.parse_args()
+
+    if args.no_skip_done:
+        args.skip_done = False
+
+    # 校验 Blend/GLB/HM3D 模式必须提供 --blender
+    if (args.blend or args.glb or args.hm3d) and not args.blender:
+        parser.error("--blend / --glb / --hm3d 模式必须同时提供 --blender 可执行文件路径")
+
+    # 模式判定
+    if args.input_dir:
+        run_batch(args)
+    elif args.blend or args.glb or args.hm3d or args.ply:
+        run_single(args)
+    else:
+        parser.error("必须指定 --blend / --glb / --hm3d / --ply（单场景）或 --input-dir（批量）")
+
+
+if __name__ == "__main__":
+    main()

pipelines/run_pipeline.py

@@ -0,0 +1,500 @@
+#!/usr/bin/env python3
+"""
+ERPT Pipeline 主入口（Forward Warp，深度估计可选）
+
+使用方法：
+    # 默认：使用已有深度真值做 warp（不加载深度估计权重）
+    python run_pipeline.py --stage warp_only --data_dir /path/to/scene
+
+    # 强制完整流程（深度估计 + warp）
+    python run_pipeline.py --stage all
+
+    # 仅深度估计
+    python run_pipeline.py --stage depth_only
+"""
+
+import argparse
+import re
+import time
+from pathlib import Path
+from typing import Dict, Any, List, Optional
+
+import yaml
+import numpy as np
+import torch
+import cv2
+
+# 添加模块路径
+import sys
+sys.path.insert(0, str(Path(__file__).parent))
+
+# Warp 相关（始终加载）
+from core.erp_warp import warp_erp_to_target, WarpResult, create_comparison_image
+from utils.io_utils import load_image, save_image, load_json, save_json, save_depth
+from utils.pose_utils import Pose, load_pose
+
+# 深度估计相关（延迟加载，仅 depth_only / all 模式才 import）
+_depth_modules_loaded = False
+
+
+def _load_depth_modules():
+    """延迟加载深度估计模块（避免 warp_only 模式加载大模型权重）"""
+    global _depth_modules_loaded
+    if _depth_modules_loaded:
+        return
+    global build_icosahedron_slices, extract_all_tangents, compute_coverage_mask
+    global estimate_all_tangent_depths
+    global fuse_tangent_depths_to_erp, save_depth_visualization, visualize_depth
+
+    from core.tangent_extraction import (
+        build_icosahedron_slices,
+        extract_all_tangents,
+        compute_coverage_mask,
+    )
+    from core.depth_estimation import estimate_all_tangent_depths
+    from core.depth_fusion import (
+        fuse_tangent_depths_to_erp,
+        save_depth_visualization,
+        visualize_depth,
+    )
+    _depth_modules_loaded = True
+    print("[Depth] 深度估计模块已加载")
+
+
+# =============================================================================
+# 数据发现
+# =============================================================================
+
+def discover_image_files(directory: Path) -> dict:
+    """自动发现目录中的全景图文件"""
+    image_extensions = ['.png', '.jpg', '.jpeg', '.PNG', '.JPG', '.JPEG']
+    image_files = []
+    for ext in image_extensions:
+        image_files.extend(directory.glob(f"*{ext}"))
+    image_files = sorted(image_files)
+    if not image_files:
+        return {}
+
+    result = {}
+    for img_path in image_files:
+        stem = img_path.stem
+        match = re.search(r'[_-](\d+)$', stem)
+        if match:
+            result[int(match.group(1))] = img_path
+            continue
+        if stem.isdigit():
+            result[int(stem)] = img_path
+
+    if not result:
+        for idx, img_path in enumerate(image_files):
+            result[idx] = img_path
+
+    return result
+
+
+def discover_pose_files(directory: Path) -> dict:
+    """自动发现目录中的位姿文件"""
+    pose_files = sorted(directory.glob("*.json"))
+    result = {}
+    for pose_path in pose_files:
+        stem = pose_path.stem
+        if stem in ['meta', 'config', 'stats', 'cameras', 'render_meta', 'description']:
+            continue
+        match = re.search(r'[_-](\d+)$', stem)
+        if match:
+            result[int(match.group(1))] = pose_path
+            continue
+        if stem.isdigit():
+            result[int(stem)] = pose_path
+
+    return result
+
+
+# =============================================================================
+# 配置加载
+# =============================================================================
+
+def load_config(config_path: Path) -> Dict[str, Any]:
+    with open(config_path, "r", encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def resolve_paths(cfg: Dict[str, Any], config_dir: Path) -> Dict[str, Any]:
+    """解析相对路径为绝对路径"""
+    data_cfg = cfg.get("data", {})
+    for key in ["data_dir", "output_dir", "depth_dir"]:
+        if key in data_cfg and data_cfg[key]:
+            path = Path(data_cfg[key])
+            if not path.is_absolute():
+                data_cfg[key] = str(config_dir / path)
+
+    depth_pro_cfg = cfg.get("depth_pro", {})
+    if "repo_dir" in depth_pro_cfg and depth_pro_cfg["repo_dir"]:
+        rp = Path(depth_pro_cfg["repo_dir"])
+        if not rp.is_absolute():
+            depth_pro_cfg["repo_dir"] = str(config_dir / rp)
+
+    cfg["_project_root"] = str(config_dir)
+    return cfg
+
+
+# =============================================================================
+# 深度估计流程（仅 all / depth_only 模式调用）
+# =============================================================================
+
+def run_depth_pipeline(
+    center_rgb: np.ndarray,
+    cfg: Dict[str, Any],
+    device: torch.device,
+    output_dir: Path,
+    erp_h: int,
+    erp_w: int,
+    frame_id: int = 0,
+) -> np.ndarray:
+    """运行深度估计全流程：切片 -> 推理 -> 融合"""
+    _load_depth_modules()
+
+    depth_out_dir = output_dir / "depth_erp"
+    depth_out_dir.mkdir(parents=True, exist_ok=True)
+
+    # --- Step 1: 构建切片规格 ---
+    print(f"\n{'='*60}")
+    print(f"[Step 1] Building tangent slices (frame {frame_id})")
+    print(f"{'='*60}")
+
+    if "erp" not in cfg:
+        cfg["erp"] = {}
+    cfg["erp"]["height"] = erp_h
+    cfg["erp"]["width"] = erp_w
+
+    slices = build_icosahedron_slices(cfg)
+    print(f"  Total slices: {len(slices)}")
+    for s in slices:
+        if s.slice_type != "face":
+            print(f"    {s.slice_id}: type={s.slice_type}, fov={s.fov_deg:.1f}°")
+
+    coverage_mask, coverage_stats = compute_coverage_mask(slices, erp_h, erp_w, device)
+    print(f"  Coverage: {coverage_stats['total_coverage']:.2f}%")
+
+    dbg_dir = output_dir / "debug"
+    dbg_dir.mkdir(parents=True, exist_ok=True)
+    save_image(np.stack([coverage_mask] * 3, axis=-1), dbg_dir / "coverage_mask.png")
+
+    # --- Step 2: 提取切片 ---
+    print(f"\n{'='*60}")
+    print(f"[Step 2] Extracting tangent slices (frame {frame_id})")
+    print(f"{'='*60}")
+
+    t0 = time.time()
+    tangent_rgbs = extract_all_tangents(center_rgb, slices, device)
+    print(f"  Extracted {len(tangent_rgbs)} slices in {time.time()-t0:.2f}s")
+
+    if cfg.get("run", {}).get("save_intermediates", False):
+        tangent_dir = output_dir / "tangents"
+        tangent_dir.mkdir(parents=True, exist_ok=True)
+        for slice_id, rgb in tangent_rgbs.items():
+            save_image(rgb, tangent_dir / f"{slice_id}_rgb.png")
+
+    # --- Step 3: Depth Pro 推理 ---
+    print(f"\n{'='*60}")
+    print(f"[Step 3] Running Depth Pro inference (frame {frame_id})")
+    print(f"{'='*60}")
+
+    dp_cfg = cfg.get("depth_pro", {})
+    if not bool(dp_cfg.get("enabled", True)):
+        print("  [Warning] Depth Pro disabled, using dummy depth")
+        tangent_depths = {}
+        for sid, rgb in tangent_rgbs.items():
+            tangent_depths[sid] = np.full(rgb.shape[:2], 5.0, dtype=np.float32)
+    else:
+        t0 = time.time()
+        tangent_depths = estimate_all_tangent_depths(
+            tangent_rgbs, slices, cfg, device,
+        )
+        print(f"  Estimated {len(tangent_depths)} depths in {time.time()-t0:.2f}s")
+
+    if cfg.get("run", {}).get("save_intermediates", False):
+        tangent_dir = output_dir / "tangents"
+        for sid, depth in tangent_depths.items():
+            save_depth(depth, tangent_dir / f"{sid}_depth.npy")
+
+    # --- Step 4: 融合到 ERP ---
+    print(f"\n{'='*60}")
+    print(f"[Step 4] Fusing tangent depths to ERP (frame {frame_id})")
+    print(f"{'='*60}")
+
+    t0 = time.time()
+    depth_erp, weight_sum, valid_mask = fuse_tangent_depths_to_erp(
+        tangent_depths, slices, cfg, device,
+        debug_dir=dbg_dir if cfg.get("run", {}).get("save_intermediates", False) else None,
+    )
+    print(f"  Fused in {time.time()-t0:.2f}s")
+
+    valid_ratio = np.sum(valid_mask > 0) / (erp_h * erp_w)
+    valid_depths = depth_erp[np.isfinite(depth_erp) & (depth_erp > 0)]
+    if len(valid_depths) > 0:
+        print(f"  Valid depth ratio: {valid_ratio * 100:.2f}%")
+        print(f"  Depth range: [{valid_depths.min():.2f}, {valid_depths.max():.2f}] m")
+
+    # --- Step 5: 保存结果 ---
+    save_depth(depth_erp, depth_out_dir / f"depth_{frame_id:04d}.npy")
+    save_depth_visualization(depth_erp, depth_out_dir / f"depth_{frame_id:04d}_vis.png")
+    cv2.imwrite(str(depth_out_dir / f"depth_{frame_id:04d}_valid_mask.png"), valid_mask * 255)
+
+    return depth_erp
+
+
+# =============================================================================
+# Warp 流程
+# =============================================================================
+
+def run_warp_pipeline(
+    center_rgb: np.ndarray,
+    depth_erp: np.ndarray,
+    center_frame: int,
+    image_files: dict,
+    pose_files: dict,
+    cfg: Dict[str, Any],
+    device: torch.device,
+    output_dir: Path,
+    erp_h: int,
+    erp_w: int,
+) -> None:
+    """运行 warp 全流程：遍历目标帧，执行 forward splatting"""
+    warp_cfg = cfg.get("warp", {})
+    output_depth = bool(warp_cfg.get("output_depth", True))
+
+    # 确定目标帧列表
+    available_targets = sorted([fid for fid in pose_files.keys() if fid != center_frame])
+
+    cfg_targets = warp_cfg.get("target_frames", None)
+    if cfg_targets is not None and cfg_targets != "auto":
+        cfg_set = set(int(t) for t in cfg_targets)
+        target_frames = [fid for fid in available_targets if fid in cfg_set]
+    else:
+        target_frames = available_targets
+
+    print(f"\n{'='*60}")
+    print(f"[Warp] Forward splatting from frame {center_frame}")
+    print(f"{'='*60}")
+    print(f"  Method: {warp_cfg.get('method', 'softmax_splatting')}")
+    print(f"  Available targets with pose: {available_targets}")
+    print(f"  Will warp: {target_frames}")
+
+    # 加载中心帧位姿
+    if center_frame not in pose_files:
+        print(f"  [Error] Center pose not found for frame {center_frame}")
+        return
+    src_pose = load_pose(pose_files[center_frame])
+    print(f"  Source pose: position={src_pose.position.tolist()}")
+
+    # 输出目录
+    warp_rgb_dir = output_dir / "warp_rgb"
+    warp_rgb_dir.mkdir(parents=True, exist_ok=True)
+    if output_depth:
+        warp_depth_dir = output_dir / "warp_depth"
+        warp_depth_dir.mkdir(parents=True, exist_ok=True)
+
+    total_warp = len(target_frames)
+    for idx, tgt_id in enumerate(target_frames):
+        if tgt_id not in pose_files:
+            print(f"  [{idx+1}/{total_warp}] Frame {tgt_id}: pose not found, skip")
+            continue
+
+        tgt_pose = load_pose(pose_files[tgt_id])
+        print(f"  [{idx+1}/{total_warp}] Frame {center_frame} -> {tgt_id} ...", end="", flush=True)
+
+        t0 = time.time()
+        result = warp_erp_to_target(
+            src_rgb=center_rgb,
+            src_depth=depth_erp,
+            src_pose=src_pose,
+            tgt_pose=tgt_pose,
+            cfg=cfg,
+            device=device,
+        )
+        dt = time.time() - t0
+
+        valid_pct = result.valid_mask.sum() / result.valid_mask.size * 100
+        print(f" done ({dt:.2f}s, valid={valid_pct:.1f}%)")
+
+        prefix = f"pano{center_frame:04d}_to_pano{tgt_id:04d}"
+
+        # 保存 warped RGB
+        save_image(result.warped_rgb, warp_rgb_dir / f"{prefix}_rgb.png")
+
+        # 保存 valid mask
+        cv2.imwrite(str(warp_rgb_dir / f"{prefix}_mask.png"), result.valid_mask * 255)
+
+        # 保存 warped depth
+        if output_depth and result.warped_depth is not None:
+            save_depth(result.warped_depth, warp_depth_dir / f"{prefix}_depth_range.npy")
+
+    print(f"  Warp complete. Output saved to: {warp_rgb_dir}")
+
+
+# =============================================================================
+# 主函数
+# =============================================================================
+
+def main():
+    _script_dir = Path(__file__).parent
+    _default_config = _script_dir / "config.yaml"
+
+    parser = argparse.ArgumentParser(description="ERPT Pipeline")
+    parser.add_argument("--config", type=str,
+                        default=str(_default_config) if _default_config.exists() else None,
+                        help="Config file path")
+    parser.add_argument("--data_dir", type=str, default=None,
+                        help="Data directory (overrides config)")
+    parser.add_argument("--output_dir", type=str, default=None,
+                        help="Output directory (overrides config)")
+    parser.add_argument("--device", type=str, default="cuda")
+    parser.add_argument("--stage", type=str, default="warp_only",
+                        choices=["all", "depth_only", "warp_only"])
+    parser.add_argument("--center_frame", type=int, default=None,
+                        help="Center frame ID (overrides config)")
+    args = parser.parse_args()
+
+    # 加载配置
+    if args.config:
+        config_path = Path(args.config)
+        cfg = load_config(config_path)
+        cfg = resolve_paths(cfg, config_path.parent)
+    else:
+        cfg = {
+            "data": {},
+            "erp": {"auto_size": True},
+            "tangent": {},
+            "depth_pro": {"enabled": True, "precision": "fp16", "pass_f_px": True},
+            "fusion": {"blend_mode": "multiband", "output_scale": 1.10, "k": 4},
+            "run": {"save_intermediates": False},
+        }
+
+    # 命令行覆盖
+    if args.data_dir:
+        cfg["data"]["data_dir"] = str(Path(args.data_dir).resolve())
+    if args.output_dir:
+        cfg["data"]["output_dir"] = args.output_dir
+
+    data_dir = Path(cfg["data"].get("data_dir", "inputs"))
+    output_dir = Path(cfg["data"].get("output_dir", "outputs"))
+
+    device = torch.device(args.device if torch.cuda.is_available() or args.device == "cpu" else "cpu")
+    print(f"Using device: {device}")
+
+    center_frame = args.center_frame or int(cfg.get("warp", {}).get("center_frame", 0))
+
+    print(f"\n{'='*60}")
+    print("ERPT Pipeline")
+    print(f"{'='*60}")
+    print(f"Stage: {args.stage}")
+    print(f"Data dir: {data_dir}")
+    print(f"Output dir: {output_dir}")
+
+    t_start = time.time()
+
+    # --- 加载数据 ---
+    print(f"\n{'='*60}")
+    print("[Loading data]")
+    print(f"{'='*60}")
+
+    image_files = discover_image_files(data_dir)
+    pose_files = discover_pose_files(data_dir)
+    print(f"  Found {len(image_files)} images, {len(pose_files)} poses")
+
+    if not image_files:
+        raise FileNotFoundError(f"No image files found in: {data_dir}")
+
+    if center_frame not in image_files:
+        center_frame = sorted(image_files.keys())[0]
+        print(f"  Using frame {center_frame} as center")
+
+    center_rgb = load_image(image_files[center_frame])
+    print(f"  Center image: {image_files[center_frame].name}")
+    print(f"  Shape: {center_rgb.shape}")
+
+    erp_cfg = cfg.get("erp", {})
+    if bool(erp_cfg.get("auto_size", True)):
+        erp_h, erp_w = center_rgb.shape[:2]
+        print(f"  Auto size: {erp_w}x{erp_h}")
+    else:
+        erp_h = int(erp_cfg.get("height", 2048))
+        erp_w = int(erp_cfg.get("width", 4096))
+
+    # --- 深度加载 / 估计 ---
+    depth_erp = None
+
+    if args.stage == "all":
+        print(f"\n  [Stage: all] 强制执行深度估计")
+        depth_erp = run_depth_pipeline(
+            center_rgb, cfg, device, output_dir, erp_h, erp_w, center_frame,
+        )
+
+    elif args.stage == "depth_only":
+        depth_erp = run_depth_pipeline(
+            center_rgb, cfg, device, output_dir, erp_h, erp_w, center_frame,
+        )
+
+    elif args.stage == "warp_only":
+        # 搜索已有深度（真值 > 已估计结果），不回退到深度估计
+        depth_candidates = []
+
+        if center_frame in image_files:
+            stem = image_files[center_frame].stem
+            depth_candidates.append(data_dir / f"{stem}_depth.npy")
+            depth_candidates.append(data_dir / f"{stem}_depth.exr")
+            depth_candidates.append(data_dir / f"{stem}.npy")
+        depth_candidates.append(data_dir / f"depth_{center_frame:04d}.npy")
+        depth_candidates.append(output_dir / "depth_erp" / f"depth_{center_frame:04d}.npy")
+
+        for dp in depth_candidates:
+            if dp.exists():
+                if dp.suffix == ".exr":
+                    depth_erp = cv2.imread(str(dp), cv2.IMREAD_ANYCOLOR | cv2.IMREAD_ANYDEPTH)
+                    if depth_erp is not None and depth_erp.ndim == 3:
+                        depth_erp = depth_erp[:, :, 0]
+                    depth_erp = depth_erp.astype(np.float32) if depth_erp is not None else None
+                else:
+                    depth_erp = np.load(str(dp)).astype(np.float32)
+                if depth_erp is not None:
+                    print(f"  Loaded depth from {dp}")
+                    break
+
+        # 尺寸校验
+        if depth_erp is not None and depth_erp.shape != (erp_h, erp_w):
+            old_shape = depth_erp.shape
+            depth_erp = cv2.resize(depth_erp, (erp_w, erp_h), interpolation=cv2.INTER_LINEAR)
+            print(f"  [Warning] Depth resized: {old_shape} -> ({erp_h}, {erp_w})")
+
+        # 没找到深度 → 报错（不回退到深度估计）
+        if depth_erp is None:
+            tried = "\n    ".join(str(p) for p in depth_candidates)
+            raise FileNotFoundError(
+                f"[warp_only] 未找到深度文件，无法执行 warp。\n"
+                f"已搜索路径:\n    {tried}\n"
+                f"如需深度估计请使用 --stage all"
+            )
+
+    # --- Warp 阶段 ---
+    warp_cfg = cfg.get("warp", {})
+    warp_enabled = bool(warp_cfg.get("enabled", True))
+
+    if args.stage in ("all", "warp_only") and warp_enabled:
+        run_warp_pipeline(
+            center_rgb, depth_erp, center_frame,
+            image_files, pose_files,
+            cfg, device, output_dir, erp_h, erp_w,
+        )
+
+    # --- 完成 ---
+    total_time = time.time() - t_start
+    print(f"\n{'='*60}")
+    print("Pipeline Complete")
+    print(f"{'='*60}")
+    print(f"Total time: {total_time:.2f}s")
+    print(f"Output saved to: {output_dir}")
+
+
+if __name__ == "__main__":
+    main()

pipelines/run_ply_pipeline.py

@@ -0,0 +1,1967 @@
+#!/usr/bin/env python3
+"""
+PLY 全流程 Pipeline（纯 Python，无需 Blender）
+
+从 .ply 点云/网格文件出发，完成：
+  Phase 0: 加载场景 + 获取 AABB 边界
+  Phase 1: 多高度层撒点 + 7 层过滤（trimesh ray_cast 替代 bpy）
+  Phase 2: 边渲边选（Open3D ERP 点云渲染 + 深度图）
+
+输出格式与 run_blend_pipeline.py 完全一致:
+  panorama_XXXX.png   + panorama_XXXX_depth.npy  + pose_XXXX.json
+
+坐标系: ERPT_native 右手系 [X右, Y上, Z前]
+  PLY 坐标系通常为 Z-up，渲染前统一转换为 Y-up。
+
+运行:
+    python run_ply_pipeline.py \\
+        --ply /path/to/scene.ply \\
+        --output-dir /path/to/output \\
+        --num-frames 30 \\
+        --resolution 2048,1024
+
+依赖:
+    pip install open3d trimesh numpy opencv-python pillow
+"""
+
+import argparse
+import json
+import math
+import os
+import random as _random
+import sys
+import time
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+import trimesh
+import open3d as o3d
+import cv2
+
+# ── GPU 支持检测 ──────────────────────────────────────────────────────────────
+try:
+    import torch
+    import torch.nn.functional as _F
+    _CUDA_AVAILABLE = torch.cuda.is_available()
+    _TORCH_DEVICE = torch.device("cuda") if _CUDA_AVAILABLE else torch.device("cpu")
+    if _CUDA_AVAILABLE:
+        print(f"[GPU] CUDA 可用: {torch.cuda.get_device_name(0)}")
+    else:
+        print("[GPU] CUDA 不可用，使用 CPU 渲染")
+except ImportError:
+    torch = None
+    _CUDA_AVAILABLE = False
+    _TORCH_DEVICE = None
+    print("[GPU] torch 未安装，使用 CPU 渲染")
+
+
+WARP_H = 128
+WARP_W = 256
+MARGIN = 0.2          # 距边界最小安全距离（PLY 场景通常比 blend 精度低，稍微宽松）
+
+DEFAULT_STOP_GAIN = 0.08
+DEFAULT_OVERLAP_PENALTY = 0.5
+DEFAULT_MIN_DIST = 0.6
+DEFAULT_MIN_FRAMES = 5
+
+ROTATION_TYPES = {
+    "none":         [0.0, 0.0, 0.0],
+    "rotate_x_90":  [math.pi / 2, 0.0, 0.0],
+    "rotate_x_180": [math.pi, 0.0, 0.0],
+    "rotate_z_90":  [0.0, 0.0, math.pi / 2],
+}
+
+
+def get_camera_rot(rotation_type: str, frame_id: int):
+    if rotation_type == "random_yaw":
+        yaw = 0.0 if frame_id == 0 else _random.uniform(0, 2 * math.pi)
+        return [math.pi / 2, 0.0, yaw]
+    return list(ROTATION_TYPES[rotation_type])
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="PLY Pipeline（边渲边选）")
+    parser.add_argument("--ply", type=str, required=True,
+                        help=".ply 文件路径")
+    parser.add_argument("--output-dir", type=str, required=True,
+                        help="输出目录")
+    parser.add_argument("--num-frames", type=int, default=30)
+    parser.add_argument("--resolution", type=str, default="2048,1024",
+                        help="渲染分辨率 width,height")
+    parser.add_argument("--grid-spacing", type=float, default=0.5,
+                        help="候选点网格间距（米）")
+    parser.add_argument("--camera-height", type=float, default=None,
+                        help="固定相机高度（米），None=自动多层")
+    parser.add_argument("--stop-gain", type=float, default=DEFAULT_STOP_GAIN)
+    parser.add_argument("--stop-score", type=float, default=-0.3)
+    parser.add_argument("--stop-delta", type=float, default=0.08)
+    parser.add_argument("--min-frames", type=int, default=DEFAULT_MIN_FRAMES)
+    parser.add_argument("--rotation-type", type=str, default="random_yaw",
+                        choices=["none", "rotate_x_90", "rotate_x_180",
+                                 "rotate_z_90", "random_yaw"])
+    parser.add_argument("--point-size", type=float, default=2.0,
+                        help="点云渲染点径（像素）")
+    parser.add_argument("--z-up", action="store_true", default=True,
+                        help="PLY 坐标系为 Z-up（默认 True，转为 Y-up）")
+    parser.add_argument("--no-z-up", dest="z_up", action="store_false")
+    return parser.parse_args()
+
+
+def load_ply_scene(ply_path: str, z_up: bool = True):
+    """加载 PLY，可选将 Z-up 转为 Y-up（ERPT_native）
+
+    PLY 常见坐标系:
+      Z-up:  X右, Y前, Z上  → 转换: X'=X, Y'=Z, Z'=Y（ERPT_native）
+      Y-up:  X右, Y上, Z前  → 直接使用
+
+    Returns:
+        mesh_or_pc: trimesh 对象（Mesh 或 PointCloud）
+        pts_world:  np.ndarray (N,3) Y-up 世界点坐标
+        bmin, bmax: AABB (3,) float
+        is_mesh:    bool, True=Trimesh Mesh（支持 ray_cast）
+        faces:      np.ndarray (F,3) int 或 None（纯点云时为 None）
+    """
+    print(f"\n[Phase 0] 加载场景: {ply_path}")
+    scene_or_mesh = trimesh.load(ply_path, process=False, force=None)
+
+    # trimesh 可能返回 Scene（多个 mesh 合并）
+    if isinstance(scene_or_mesh, trimesh.Scene):
+        mesh = trimesh.util.concatenate(
+            [g for g in scene_or_mesh.geometry.values()
+             if isinstance(g, trimesh.Trimesh)]
+        )
+        is_mesh = True
+    elif isinstance(scene_or_mesh, trimesh.Trimesh):
+        mesh = scene_or_mesh
+        is_mesh = True
+    elif isinstance(scene_or_mesh, trimesh.PointCloud):
+        mesh = scene_or_mesh
+        is_mesh = False
+    else:
+        # 尝试强制为 PointCloud
+        mesh = trimesh.load(ply_path, process=False, force='mesh')
+        is_mesh = isinstance(mesh, trimesh.Trimesh)
+
+    # 获取顶点坐标和面数据
+    pts_raw = np.array(mesh.vertices, dtype=np.float64)
+    faces = np.array(mesh.faces, dtype=np.int32) if is_mesh else None
+
+    print(f"  点数: {len(pts_raw)}, 面数: {len(faces) if faces is not None else 0}, is_mesh={is_mesh}")
+
+    # 坐标系转换 Z-up → Y-up（ERPT_native）
+    if z_up:
+        pts_world = pts_raw[:, [0, 2, 1]].copy()
+    else:
+        pts_world = pts_raw.copy()
+
+    bmin = pts_world.min(axis=0)
+    bmax = pts_world.max(axis=0)
+
+    print(f"  AABB (Y-up): min=[{bmin[0]:.2f}, {bmin[1]:.2f}, {bmin[2]:.2f}]  "
+          f"max=[{bmax[0]:.2f}, {bmax[1]:.2f}, {bmax[2]:.2f}]")
+
+    return mesh, pts_world, bmin, bmax, is_mesh, faces
+
+
+class RayCaster:
+    """封装 trimesh RayMeshIntersector，提供与 Blender ray_cast 相同的接口。
+
+    对于纯点云（非 mesh）场景，降级为"无碰撞"模式（所有射线无 hit），
+    只能依靠 AABB 做粗略过滤。
+    """
+
+    def __init__(self, mesh, pts_world: np.ndarray, bmin, bmax,
+                 is_mesh: bool, z_up: bool = True):
+        self.is_mesh = is_mesh
+        self.pts_world = pts_world
+        self.bmin = np.array(bmin)
+        self.bmax = np.array(bmax)
+        self.z_up = z_up
+        self._intersector = None
+
+        if is_mesh and isinstance(mesh, trimesh.Trimesh):
+            if z_up:
+                # 需要把 mesh 顶点也转为 Y-up
+                verts = np.array(mesh.vertices, dtype=np.float64)
+                verts_yup = verts[:, [0, 2, 1]]
+                import copy
+                m2 = copy.deepcopy(mesh)
+                m2.vertices = verts_yup
+                self._intersector = trimesh.ray.ray_pyembree.RayMeshIntersector(m2) \
+                    if hasattr(trimesh.ray, 'ray_pyembree') \
+                    else trimesh.ray.ray_triangle.RayMeshIntersector(m2)
+            else:
+                self._intersector = trimesh.ray.ray_pyembree.RayMeshIntersector(mesh) \
+                    if hasattr(trimesh.ray, 'ray_pyembree') \
+                    else trimesh.ray.ray_triangle.RayMeshIntersector(mesh)
+            print("  [RayCaster] 使用 trimesh RayMeshIntersector")
+        else:
+            print("  [RayCaster] 非 Mesh 场景，使用 AABB 降级模式")
+
+    def cast_ray(self, origin: np.ndarray, direction: np.ndarray):
+        """单条射线，返回 (hit: bool, dist: float)
+
+        hit=True 时 dist 为交点距离（米）。
+        hit=False 时 dist=inf。
+        """
+        if self._intersector is None:
+            return False, float('inf')
+
+        o = np.array(origin, dtype=np.float64)[np.newaxis]  # (1,3)
+        d = np.array(direction, dtype=np.float64)[np.newaxis]
+        d = d / (np.linalg.norm(d) + 1e-12)
+
+        try:
+            locs, idx_ray, idx_tri = self._intersector.intersects_location(
+                o, d, multiple_hits=True)
+        except Exception:
+            return False, float('inf')
+
+        if len(locs) == 0:
+            return False, float('inf')
+
+        dists = np.linalg.norm(locs - origin, axis=1)
+        # 过滤极近距离（防止自交）
+        valid = dists > 1e-4
+        if not np.any(valid):
+            return False, float('inf')
+
+        min_dist = float(dists[valid].min())
+        return True, min_dist
+
+    def cast_rays_batch(self, origin: np.ndarray,
+                        directions: np.ndarray) -> np.ndarray:
+        """批量射线，返回 dist 数组 (N,)，无 hit 为 inf。"""
+        if self._intersector is None:
+            return np.full(len(directions), float('inf'))
+
+        origins = np.tile(origin[np.newaxis], (len(directions), 1))
+        dirs = directions / (np.linalg.norm(directions, axis=1, keepdims=True) + 1e-12)
+
+        try:
+            locs, idx_ray, idx_tri = self._intersector.intersects_location(
+                origins, dirs, multiple_hits=True)
+        except Exception:
+            return np.full(len(directions), float('inf'))
+
+        dists_out = np.full(len(directions), float('inf'))
+        if len(locs) == 0:
+            return dists_out
+
+        # 每条射线取最近交点
+        for i, (loc, ir) in enumerate(zip(locs, idx_ray)):
+            d = float(np.linalg.norm(loc - origin))
+            if d > 1e-4 and d < dists_out[ir]:
+                dists_out[ir] = d
+
+        return dists_out
+
+
+def compute_camera_heights(floor_y: float, ceiling_y: float,
+                           manual_height=None):
+    """计算相机高度层（Y-up 坐标系，Y=高度）"""
+    CEIL_CLEARANCE = 0.3
+    FIXED_HEIGHTS = [0.5, 0.8, 1.2, 1.7, 2.1]
+
+    if manual_height is not None:
+        return [manual_height]
+
+    room_h = ceiling_y - floor_y
+    if room_h <= 0:
+        return [floor_y + 1.5]
+
+    heights = []
+    for eye_h in FIXED_HEIGHTS:
+        z = floor_y + eye_h
+        if z < ceiling_y - CEIL_CLEARANCE:
+            heights.append(z)
+
+    if room_h > 3.0:
+        cur_h = FIXED_HEIGHTS[-1]
+        step = 1.0
+        while True:
+            cur_h += step
+            z = floor_y + cur_h
+            if z >= ceiling_y - CEIL_CLEARANCE:
+                break
+            heights.append(z)
+            step = min(step + 0.5, 3.0)
+
+    top_y = ceiling_y - CEIL_CLEARANCE
+    if heights and top_y > max(heights) + 0.5:
+        heights.append(top_y)
+    elif not heights and top_y > floor_y + 0.5:
+        heights.append(top_y)
+
+    return sorted(set(round(h, 2) for h in heights)) if heights else [floor_y + 1.5]
+
+
+def generate_candidate_grid(bmin, bmax, x_spacing, z_spacing, heights):
+    """生成候选点网格（Y-up 坐标系：X=右, Y=高, Z=前）
+
+    heights 是 Y 方向的高度值列表。
+    """
+    cx = (bmin[0] + bmax[0]) / 2
+    cz = (bmin[2] + bmax[2]) / 2
+
+    x_half = int((bmax[0] - cx - MARGIN) / x_spacing)
+    z_half = int((bmax[2] - cz - MARGIN) / z_spacing)
+
+    xz_offsets = []
+    for ix in range(-x_half, x_half + 1):
+        for iz in range(-z_half, z_half + 1):
+            x = cx + ix * x_spacing
+            z = cz + iz * z_spacing
+            if (bmin[0] + MARGIN <= x <= bmax[0] - MARGIN and
+                    bmin[2] + MARGIN <= z <= bmax[2] - MARGIN):
+                xz_offsets.append((ix * ix + iz * iz, x, z))
+    xz_offsets.sort(key=lambda t: t[0])
+
+    candidates = []
+    for y in heights:
+        for _, x, z in xz_offsets:
+            candidates.append([float(x), float(y), float(z)])
+
+    n_xz = len(xz_offsets)
+    print(f"  网格: {n_xz}点/层 x {len(heights)}层 = {len(candidates)} 个候选")
+    return candidates
+
+
+def _build_26_directions_yup():
+    """26 方向球面采样（Y-up 坐标系：水平面=XZ，竖直=Y）"""
+    dirs = []
+    # 水平 16 方向（XZ 平面）
+    for i in range(16):
+        a = i * (2 * math.pi / 16)
+        dirs.append(np.array([math.cos(a), 0.0, math.sin(a)]))
+    # 上方 5 方向
+    elev = math.pi / 4
+    for i in range(5):
+        a = i * (2 * math.pi / 5)
+        dirs.append(np.array([
+            math.cos(a) * math.cos(elev),
+            math.sin(elev),
+            math.sin(a) * math.cos(elev),
+        ]))
+    # 下方 5 方向
+    for i in range(5):
+        a = i * (2 * math.pi / 5)
+        dirs.append(np.array([
+            math.cos(a) * math.cos(elev),
+            -math.sin(elev),
+            math.sin(a) * math.cos(elev),
+        ]))
+    return dirs
+
+
+def raycast_filter(candidates, raycaster: RayCaster, room_height: float,
+                   min_wall_dist: float = 1.0):
+    """7 层候选点过滤（Y-up 坐标系）
+
+    第 1 层: 室内检测（朝+Y/-Y 各一条射线，距离合理）
+    第 2 层: 穿模检测（≥2 方向 < 0.2m）
+    第 3 层: 角落检测（>50% 水平方向 < 1.0m）
+    第 4 层: 包裹检测（hit_rate≥90% + CV<0.30 + max<8m）
+    第 5 层: 贴墙检测（水平 16 方向最近 < 0.3m）
+    第 6 层: 视野质量（有效命中比例 < 35%）
+    第 7 层: 窄缝检测（对向水平距离之和 < 1.5m）
+
+    非 Mesh 场景（降级模式）：跳过射线过滤，仅做 AABB 内判断。
+    """
+    if raycaster._intersector is None:
+        print("  [过滤] 非 Mesh 场景，跳过射线过滤，返回所有 AABB 内候选")
+        bmin, bmax = raycaster.bmin, raycaster.bmax
+        passed = [c for c in candidates
+                  if all(bmin[i] + MARGIN <= c[i] <= bmax[i] - MARGIN
+                         for i in [0, 2])]
+        print(f"  过滤统计: 总计={len(candidates)}, 通过={len(passed)}")
+        return passed
+
+    DIRS_26 = _build_26_directions_yup()
+    n26 = len(DIRS_26)
+
+    dir_up = np.array([0.0, 1.0, 0.0])
+    dir_down = np.array([0.0, -1.0, 0.0])
+    max_up = max(5.0, room_height)
+    max_down = max(3.0, room_height)
+
+    MIN_WALL_CLEARANCE = 0.3
+    VIEW_GOOD_MIN = 0.5
+    VIEW_GOOD_MAX = 20.0
+    VIEW_GOOD_RATIO = 0.35
+    MIN_SLIT_WIDTH = 1.5
+
+    N = len(candidates)
+    passed = []
+    stats = {"无天花板": 0, "无地板": 0, "穿模": 0, "角落": 0,
+             "包裹": 0, "贴墙": 0, "视野差": 0, "窄缝": 0}
+
+    t0 = time.time()
+    log_interval = max(1, N // 10)
+
+    for idx, pos in enumerate(candidates):
+        if idx % log_interval == 0 and idx > 0:
+            print(f"    过滤进度: {idx}/{N} ({idx*100//N}%)", flush=True)
+
+        origin = np.array(pos, dtype=np.float64)
+
+        # 第 1 层: 室内检测（Y-up：朝上=+Y，朝下=-Y）
+        hit_up, d_up = raycaster.cast_ray(origin, dir_up)
+        if not hit_up or d_up > max_up:
+            stats["无天花板"] += 1
+            continue
+
+        hit_dn, d_dn = raycaster.cast_ray(origin, dir_down)
+        if not hit_dn or d_dn > max_down:
+            stats["无地板"] += 1
+            continue
+
+        # 第 2~7 层: 26 方向采样
+        dists = raycaster.cast_rays_batch(origin, np.array(DIRS_26))
+
+        # 第 2 层: 穿模
+        n_close = int(np.sum(dists < 0.2))
+        if n_close >= 2:
+            stats["穿模"] += 1
+            continue
+
+        # 第 3 层: 角落（水平 16 方向）
+        n_wall = int(np.sum(dists[:16] < min_wall_dist))
+        if n_wall > 8:
+            stats["角落"] += 1
+            continue
+
+        # 第 4 层: 包裹
+        finite = dists[np.isfinite(dists)]
+        hit_rate = len(finite) / n26
+        if hit_rate >= 0.90 and len(finite) >= 2:
+            mean_d = float(finite.mean())
+            max_d = float(finite.max())
+            if mean_d > 0:
+                cv = float(finite.std()) / mean_d
+                if cv < 0.30 and max_d < 8.0:
+                    stats["包裹"] += 1
+                    continue
+
+        # 第 5 层: 贴墙
+        horiz_finite = dists[:16][np.isfinite(dists[:16])]
+        if len(horiz_finite) > 0 and float(horiz_finite.min()) < MIN_WALL_CLEARANCE:
+            stats["贴墙"] += 1
+            continue
+
+        # 第 6 层: 视野质量
+        n_good = int(np.sum((dists >= VIEW_GOOD_MIN) & (dists <= VIEW_GOOD_MAX)))
+        if n_good / n26 < VIEW_GOOD_RATIO:
+            stats["视野差"] += 1
+            continue
+
+        # 第 7 层: 窄缝
+        in_slit = False
+        for i in range(8):
+            d_fwd = dists[i] if np.isfinite(dists[i]) else 999
+            d_bwd = dists[i + 8] if np.isfinite(dists[i + 8]) else 999
+            if d_fwd + d_bwd < MIN_SLIT_WIDTH:
+                in_slit = True
+                break
+        if in_slit:
+            stats["窄缝"] += 1
+            continue
+
+        passed.append(pos)
+
+    dt = time.time() - t0
+    print(f"  过滤统计 ({dt:.1f}s): 总计={N}, 通过={len(passed)}")
+    for k, v in stats.items():
+        if v > 0:
+            print(f"    ❌ {k}: {v} ({v * 100 // max(N, 1)}%)")
+
+    return passed
+
+
+def _euler_to_rotation_matrix(rx: float, ry: float, rz: float) -> np.ndarray:
+    """XYZ 欧拉角 → 旋转矩阵（用于 ERP 相机朝向，Y-up 坐标系）"""
+    cx, sx = math.cos(rx), math.sin(rx)
+    cy, sy = math.cos(ry), math.sin(ry)
+    cz, sz = math.cos(rz), math.sin(rz)
+
+    Rx = np.array([[1, 0, 0], [0, cx, -sx], [0, sx, cx]])
+    Ry = np.array([[cy, 0, sy], [0, 1, 0], [-sy, 0, cy]])
+    Rz = np.array([[cz, -sz, 0], [sz, cz, 0], [0, 0, 1]])
+    return Rz @ Ry @ Rx
+
+
+def render_erp_pointcloud(pts_world: np.ndarray,
+                          cam_pos: np.ndarray,
+                          cam_rot_euler: list,
+                          width: int,
+                          height: int,
+                          point_size: float = 2.0):
+    """将点云渲染为 ERP 全景图（等距圆柱投影）
+
+    算法:
+      1. 将所有世界点变换到相机坐标系
+      2. 计算每个点的方位角 (lon) 和仰角 (lat)（Y-up 右手系）
+      3. 投影到 ERP 像素坐标
+      4. 用 Z-buffer 填充 RGB + depth 图，splat_radius=point_size
+
+    坐标系 (ERPT_native, Y-up):
+      相机前向 = +Z_cam, 上方 = +Y_cam, 右方 = +X_cam
+      lon = atan2(x_cam, z_cam)  （正前方=0，右=+）
+      lat = atan2(y_cam, sqrt(x^2+z^2))（上=+π/2）
+
+    Returns:
+        rgb   : np.ndarray (H, W, 3) uint8
+        depth : np.ndarray (H, W) float32，range depth（米），0=无效
+    """
+    o3d = o3d
+
+    cam_pos = np.array(cam_pos, dtype=np.float64)
+    # 旋转矩阵：world → camera
+    # 相机默认朝向 +Z，根据欧拉角旋转
+    R_cw = _euler_to_rotation_matrix(*cam_rot_euler)  # cam_to_world
+    R_wc = R_cw.T  # world_to_cam
+
+    # 变换点云到相机坐标系
+    vecs = pts_world - cam_pos  # (N, 3)
+    pts_cam = (R_wc @ vecs.T).T  # (N, 3)
+
+    x_c = pts_cam[:, 0]
+    y_c = pts_cam[:, 1]
+    z_c = pts_cam[:, 2]
+
+    # 计算经纬度（ERPT_native 约定）
+    lon = np.arctan2(x_c, z_c)                          # [-π, π]
+    r_xz = np.sqrt(x_c ** 2 + z_c ** 2)
+    lat = np.arctan2(y_c, r_xz)                         # [-π/2, π/2]
+
+    # 转为像素坐标
+    u = ((lon / (2 * math.pi) + 0.5) * width).astype(np.float32)
+    v = ((0.5 - lat / math.pi) * height).astype(np.float32)
+    u = np.clip(u, 0, width - 1).astype(np.int32)
+    v = np.clip(v, 0, height - 1).astype(np.int32)
+
+    # range depth = 射线距离（米）
+    dist = np.sqrt(x_c ** 2 + y_c ** 2 + z_c ** 2).astype(np.float32)
+
+    # 尝试获取点云颜色
+    has_colors = hasattr(pts_world, '_colors')
+    colors_rgb = None
+
+    # 初始化图像缓冲区
+    rgb_buf = np.zeros((height, width, 3), dtype=np.uint8)
+    depth_buf = np.full((height, width), np.inf, dtype=np.float32)
+
+    # Z-buffer 渲染（每点 splat_radius 像素）
+    radius = max(1, int(round(point_size / 2)))
+
+    # 为效率起见，用 numpy 向量化做单像素填充，然后 dilate
+    # 先做精确 Z-buffer（单像素）
+    for i in np.argsort(dist)[::-1]:    # 从远到近，近的覆盖远的
+        ui, vi = u[i], v[i]
+        di = dist[i]
+        if di <= 0 or not np.isfinite(di):
+            continue
+        if di < depth_buf[vi, ui]:
+            depth_buf[vi, ui] = di
+            if colors_rgb is not None:
+                rgb_buf[vi, ui] = colors_rgb[i]
+            else:
+                # 无颜色时用伪彩色（深度着色）
+                c = int(np.clip(255 * (1.0 - di / 20.0), 0, 255))
+                rgb_buf[vi, ui] = [c, c, c]
+
+    # 如果有 Open3D 点云颜色，补充颜色
+    # （此处暂用灰度，完整颜色在下方 _render_with_colors 中处理）
+    depth_out = np.where(np.isfinite(depth_buf), depth_buf, 0.0).astype(np.float32)
+    return rgb_buf, depth_out
+
+
+def _gpu_align_u(u_ref, u_other, W: int):
+    """把 u_other 对齐到与 u_ref 最近的 ERP 循环副本（GPU tensor）"""
+    half_w = float(W) / 2.0
+    diff = u_other - u_ref
+    u_other = torch.where(diff >  half_w, u_other - W, u_other)
+    u_other = torch.where(diff < -half_w, u_other + W, u_other)
+    return u_other
+
+
+def _gpu_raster_batch(u0, v0, u1, v1, u2, v2,
+                      c0, c1, c2, d0b, d1b, d2b,
+                      rgb_flat, depth_flat, H: int, W: int):
+    """完全向量化批量光栅化（无 Python for 循环）。
+
+    将所有三角面的包围盒像素展开成一个大 tensor，一次性完成
+    重心坐标计算和 scatter_reduce Z-buffer 写入。
+
+    Args:
+        u0/v0, u1/v1, u2/v2: (B,) float32，三顶点 ERP 像素坐标
+        c0/c1/c2:            (B,3) float32，三顶点颜色 [0,255]
+        d0b/d1b/d2b:         (B,) float32，三顶点距离
+        rgb_flat:   (H*W, 3) 输出颜色缓冲（就地修改）
+        depth_flat: (H*W,)   输出深度缓冲（就地修改）
+    """
+    dev = u0.device
+
+    # ── 包围盒 ──────────────────────────────────────────────────────────────
+    u_lo = torch.clamp(torch.floor(torch.minimum(torch.minimum(u0, u1), u2)).long(), 0, W - 1)
+    u_hi = torch.clamp(torch.ceil (torch.maximum(torch.maximum(u0, u1), u2)).long(), 0, W - 1)
+    v_lo = torch.clamp(torch.floor(torch.minimum(torch.minimum(v0, v1), v2)).long(), 0, H - 1)
+    v_hi = torch.clamp(torch.ceil (torch.maximum(torch.maximum(v0, v1), v2)).long(), 0, H - 1)
+
+    du = u_hi - u_lo + 1
+    dv = v_hi - v_lo + 1
+    bbox_px = du * dv
+
+    # 过滤退化面 & 超大面
+    valid = (u_hi >= u_lo) & (v_hi >= v_lo) & (bbox_px <= 128 * 128)
+    if not valid.any():
+        return
+
+    idx = valid.nonzero(as_tuple=False).squeeze(1)
+    u0v = u0[idx]; v0v = v0[idx]
+    u1v = u1[idx]; v1v = v1[idx]
+    u2v = u2[idx]; v2v = v2[idx]
+    c0v = c0[idx]; c1v = c1[idx]; c2v = c2[idx]
+    d0v = d0b[idx]; d1v = d1b[idx]; d2v = d2b[idx]
+    u_lv = u_lo[idx]; u_hv = u_hi[idx]
+    v_lv = v_lo[idx]; v_hv = v_hi[idx]
+    duv = u_hv - u_lv + 1
+    dvv = v_hv - v_lv + 1
+    npx = duv * dvv
+
+    Bp = int(npx.sum().item())
+    if Bp == 0:
+        return
+
+    # ── 展开：repeat_interleave 把面 id 重复 npx[i] 次 ──────────────────────
+    face_id = torch.repeat_interleave(
+        torch.arange(len(idx), device=dev, dtype=torch.long), npx)
+
+    cumsum = torch.zeros(len(idx) + 1, dtype=torch.long, device=dev)
+    cumsum[1:] = torch.cumsum(npx, 0)
+    local_flat = torch.arange(Bp, device=dev, dtype=torch.long) - cumsum[face_id]
+
+    local_u = local_flat % duv[face_id]
+    local_v = local_flat // duv[face_id]
+
+    uu = (u_lv[face_id] + local_u).float()
+    vv = (v_lv[face_id] + local_v).float()
+
+    # ── 重心坐标（完全向量化） ───────────────────────────────────────────────
+    ax = u0v[face_id]; ay = v0v[face_id]
+    bx = u1v[face_id]; by = v1v[face_id]
+    cx = u2v[face_id]; cy = v2v[face_id]
+
+    denom = (by - cy) * (ax - cx) + (cx - bx) * (ay - cy)
+    safe  = denom.abs() > 1e-8
+    inv_d = torch.where(safe, 1.0 / denom, torch.zeros_like(denom))
+    w0 = ((by - cy) * (uu - cx) + (cx - bx) * (vv - cy)) * inv_d
+    w1 = ((cy - ay) * (uu - cx) + (ax - cx) * (vv - cy)) * inv_d
+    w2 = 1.0 - w0 - w1
+
+    inside = safe & (w0 >= -0.01) & (w1 >= -0.01) & (w2 >= -0.01)
+    if not inside.any():
+        return
+
+    fi  = face_id[inside]
+    uui = uu[inside].long()
+    vvi = vv[inside].long()
+    w0i = w0[inside]; w1i = w1[inside]; w2i = w2[inside]
+
+    # ── Z-buffer scatter_reduce(amin) ───────────────────────────────────────
+    di  = w0i * d0v[fi] + w1i * d1v[fi] + w2i * d2v[fi]
+    lin = vvi * W + uui
+    depth_flat.scatter_reduce_(0, lin, di, reduce='amin', include_self=True)
+
+    # ── 颜色写入（near-wins） ────────────────────────────────────────────────
+    cur_d  = depth_flat[lin]
+    winner = (di - cur_d).abs() < 1e-4
+    w0e = w0i[winner].unsqueeze(1)
+    w1e = w1i[winner].unsqueeze(1)
+    w2e = w2i[winner].unsqueeze(1)
+    fie = fi[winner]
+    col_i = torch.clamp(w0e * c0v[fie] + w1e * c1v[fie] + w2e * c2v[fie], 0, 255)
+    rgb_flat.scatter_(0, lin[winner].unsqueeze(1).expand(-1, 3), col_i)
+
+
+def _gpu_raster_mesh(u_f, v_f, dist, col_t, f_t,
+                     rgb_flat, depth_flat, H: int, W: int,
+                     batch_size: int = 65536):
+    """ERP 网格光栅化主流程（含接缝三副本 + OOM 自动降级）。
+
+    操作 rgb_flat / depth_flat 缓冲（就地修改）。
+    """
+    d0t = dist[f_t[:, 0]]; d1t = dist[f_t[:, 1]]; d2t = dist[f_t[:, 2]]
+    avg_d = (d0t + d1t + d2t) / 3.0
+    order = torch.argsort(avg_d, descending=True)
+    f_ord = f_t[order]
+    d0t, d1t, d2t = dist[f_ord[:, 0]], dist[f_ord[:, 1]], dist[f_ord[:, 2]]
+    c0t = col_t[f_ord[:, 0]]; c1t = col_t[f_ord[:, 1]]; c2t = col_t[f_ord[:, 2]]
+    u0r = u_f[f_ord[:, 0]]; u1r = u_f[f_ord[:, 1]]; u2r = u_f[f_ord[:, 2]]
+    v0r = v_f[f_ord[:, 0]]; v1r = v_f[f_ord[:, 1]]; v2r = v_f[f_ord[:, 2]]
+
+    valid_f = (d0t > 1e-4) & (d1t > 1e-4) & (d2t > 1e-4)
+    f_idx = valid_f.nonzero(as_tuple=False).squeeze(1)
+
+    def _process_batch(bi):
+        u0b = u0r[bi]; v0b = v0r[bi]
+        u1b = _gpu_align_u(u0b, u1r[bi], W)
+        u2b = _gpu_align_u(u0b, u2r[bi], W)
+        v1b = v1r[bi]; v2b = v2r[bi]
+        c0b = c0t[bi]; c1b = c1t[bi]; c2b = c2t[bi]
+        d0b_ = d0t[bi]; d1b_ = d1t[bi]; d2b_ = d2t[bi]
+        # 三副本 concat：主 + 左(u-W) + 右(u+W)，一次送入减少 kernel launch
+        _gpu_raster_batch(
+            torch.cat([u0b, u0b - W, u0b + W]),
+            torch.cat([v0b, v0b,     v0b    ]),
+            torch.cat([u1b, u1b - W, u1b + W]),
+            torch.cat([v1b, v1b,     v1b    ]),
+            torch.cat([u2b, u2b - W, u2b + W]),
+            torch.cat([v2b, v2b,     v2b    ]),
+            torch.cat([c0b, c0b, c0b]),
+            torch.cat([c1b, c1b, c1b]),
+            torch.cat([c2b, c2b, c2b]),
+            torch.cat([d0b_, d0b_, d0b_]),
+            torch.cat([d1b_, d1b_, d1b_]),
+            torch.cat([d2b_, d2b_, d2b_]),
+            rgb_flat, depth_flat, H, W,
+        )
+
+    try:
+        _process_batch(f_idx)
+    except torch.cuda.OutOfMemoryError:
+        torch.cuda.empty_cache()
+        print(f"  [WARN] OOM（{len(f_idx)} 面），自动降级分批 batch={batch_size}")
+        for start in range(0, len(f_idx), batch_size):
+            _process_batch(f_idx[start: start + batch_size])
+
+
+def _gpu_splat_pointcloud(u_f, v_f, dist, col_t,
+                          rgb_flat, depth_flat, H: int, W: int,
+                          point_size: float = 2.0):
+    """点云 scatter Z-buffer splatting（就地修改 rgb_flat / depth_flat）"""
+    valid  = dist > 1e-4
+    u_i    = torch.clamp(u_f[valid].long(), 0, W - 1)
+    v_i    = torch.clamp(v_f[valid].long(), 0, H - 1)
+    dist_v = dist[valid]
+    col_v  = col_t[valid]
+    lin    = v_i * W + u_i
+    radius = max(0, int(round(point_size / 2)) - 1)
+
+    if radius == 0:
+        depth_flat.scatter_reduce_(0, lin, dist_v, reduce='amin', include_self=True)
+        sort_idx = torch.argsort(dist_v)
+        rgb_flat.scatter_(0, lin[sort_idx].unsqueeze(1).expand(-1, 3), col_v[sort_idx])
+    else:
+        for dr in range(-radius, radius + 1):
+            for dc in range(-radius, radius + 1):
+                v_nb = torch.clamp(v_i + dr, 0, H - 1)
+                u_nb = torch.clamp(u_i + dc, 0, W - 1)
+                depth_flat.scatter_reduce_(0, v_nb * W + u_nb, dist_v,
+                                           reduce='amin', include_self=True)
+        sort_idx = torch.argsort(dist_v, descending=True)
+        for dr in range(-radius, radius + 1):
+            for dc in range(-radius, radius + 1):
+                v_nb = torch.clamp(v_i[sort_idx] + dr, 0, H - 1)
+                u_nb = torch.clamp(u_i[sort_idx] + dc, 0, W - 1)
+                rgb_flat.scatter_(0, (v_nb * W + u_nb).unsqueeze(1).expand(-1, 3),
+                                  col_v[sort_idx])
+
+
+def _gpu_fill_holes(rgb_2d, depth_out):
+    """GPU 空洞填充：大核 max_pool2d + 残余小孔迭代收尾。
+
+    Args:
+        rgb_2d:    (H,W,3) float32 GPU tensor
+        depth_out: (H,W)   float32 GPU tensor（0=空洞）
+
+    Returns:
+        rgb_2d: (H,W,3) float32，填充后
+    """
+    hole = (depth_out == 0)
+    if not hole.any():
+        return rgb_2d
+
+    fill_radius = 32
+    k = fill_radius * 2 + 1   # 65
+
+    rgb_f   = rgb_2d.permute(2, 0, 1).unsqueeze(0).float()       # (1,3,H,W)
+    valid_m = (~hole).float().unsqueeze(0).unsqueeze(0)           # (1,1,H,W)
+
+    rgb_masked = rgb_f * valid_m
+    expanded   = _F.max_pool2d(rgb_masked, kernel_size=k, stride=1, padding=fill_radius)
+    valid_exp  = _F.max_pool2d(valid_m,    kernel_size=k, stride=1, padding=fill_radius) > 0
+
+    fill_mask = hole.unsqueeze(0).unsqueeze(0) & valid_exp
+    rgb_f = torch.where(fill_mask.expand_as(rgb_f), expanded, rgb_f)
+
+    # 残余大孔洞：最多 8 轮 3×3 迭代收尾
+    hole2 = hole & ~fill_mask.squeeze(0).squeeze(0)
+    if hole2.any():
+        valid_f2 = (~hole2).float().unsqueeze(0).unsqueeze(0)
+        rgb_f2   = rgb_f
+        for _ in range(8):
+            if not hole2.any():
+                break
+            r2m  = rgb_f2 * valid_f2
+            exp2 = _F.max_pool2d(r2m,     kernel_size=3, stride=1, padding=1)
+            vd2  = _F.max_pool2d(valid_f2, kernel_size=3, stride=1, padding=1) > 0
+            nw2  = hole2.unsqueeze(0).unsqueeze(0) & vd2
+            if not nw2.any():
+                break
+            rgb_f2   = torch.where(nw2.expand_as(rgb_f2), exp2, rgb_f2)
+            valid_f2 = torch.where(nw2, torch.ones_like(valid_f2), valid_f2)
+            hole2    = hole2 & ~nw2.squeeze(0).squeeze(0)
+        rgb_f = rgb_f2
+
+    return rgb_f.squeeze(0).permute(1, 2, 0)   # (H,W,3)
+
+
+def _render_erp_gpu(pts_world: np.ndarray,
+                    colors_world,
+                    cam_pos,
+                    R_wc: np.ndarray,
+                    width: int,
+                    height: int,
+                    faces: np.ndarray = None,
+                    point_size: float = 2.0,
+                    batch_size: int = 65536) -> tuple:
+    """GPU（CUDA）加速的 ERP 全景渲染。
+
+    所有计算在 GPU tensor 上完成：
+      1. 顶点变换 + ERP 投影（全量向量化）
+      2. 网格/点云光栅化（委托给共享辅助函数）
+      3. 空洞填充：max_pool2d 大核膨胀（纯 GPU，无 cv2）
+
+    Returns:
+        rgb   (H, W, 3) uint8 numpy
+        depth (H, W)    float32 numpy
+    """
+    dev = _TORCH_DEVICE
+
+    # ── 1. 顶点变换到相机坐标系 ──────────────────────────────────────────────
+    pts = torch.from_numpy(pts_world.astype(np.float32)).to(dev)
+    cp  = torch.from_numpy(cam_pos.astype(np.float32)).to(dev)
+    R   = torch.from_numpy(R_wc.astype(np.float32)).to(dev)
+
+    pts_cam = (R @ (pts - cp).T).T
+    x_c, y_c, z_c = pts_cam[:, 0], pts_cam[:, 1], pts_cam[:, 2]
+
+    # ── 2. ERP 投影 ──────────────────────────────────────────────────────────
+    lon  = torch.atan2(x_c, z_c)
+    r_xz = torch.sqrt(x_c ** 2 + z_c ** 2)
+    lat  = torch.atan2(y_c, r_xz)
+    u_f  = (lon  / (2 * math.pi) + 0.5) * width
+    v_f  = (0.5  - lat / math.pi) * height
+    dist = torch.sqrt(x_c ** 2 + y_c ** 2 + z_c ** 2)
+
+    # ── 3. 顶点颜色 ──────────────────────────────────────────────────────────
+    if colors_world is not None:
+        col_np = colors_world if colors_world.dtype == np.uint8 \
+            else (np.clip(colors_world, 0, 1) * 255).astype(np.uint8)
+        col_t = torch.from_numpy(col_np.astype(np.float32)).to(dev)
+    else:
+        d_norm = torch.clamp(dist / max(float(dist.max()), 1.0), 0, 1)
+        g = torch.clamp((1.0 - d_norm) * 200 + 30, 0, 255)
+        col_t = g.unsqueeze(1).expand(-1, 3)
+
+    H, W = height, width
+    INF  = 1e9
+    rgb_flat   = torch.zeros(H * W, 3, dtype=torch.float32, device=dev)
+    depth_flat = torch.full((H * W,), INF, dtype=torch.float32, device=dev)
+
+    # ── 4. 光栅化 ────────────────────────────────────────────────────────────
+    if faces is not None and len(faces) > 0:
+        f_t = torch.from_numpy(faces.astype(np.int64)).to(dev)
+        _gpu_raster_mesh(u_f, v_f, dist, col_t, f_t,
+                         rgb_flat, depth_flat, H, W, batch_size)
+    else:
+        _gpu_splat_pointcloud(u_f, v_f, dist, col_t,
+                              rgb_flat, depth_flat, H, W, point_size)
+
+    # ── 5. reshape ───────────────────────────────────────────────────────────
+    depth_2d  = depth_flat.reshape(H, W)
+    rgb_2d    = rgb_flat.reshape(H, W, 3)
+    depth_out = torch.where(depth_2d < INF / 2, depth_2d, torch.zeros_like(depth_2d))
+
+    # ── 6. 空洞填充 ──────────────────────────────────────────────────────────
+    if faces is not None and len(faces) > 0:
+        rgb_2d = _gpu_fill_holes(rgb_2d, depth_out)
+
+    # ── 7. 回传 numpy ──────────��─────────────────────────────────────────────
+    rgb_np   = rgb_2d.clamp(0, 255).byte().cpu().numpy()
+    depth_np = depth_out.cpu().numpy().astype(np.float32)
+    return rgb_np, depth_np
+
+
+def render_erp_batch_gpu(pts_world: np.ndarray,
+                         colors_world,
+                         cam_poses: list,
+                         cam_rots: list,
+                         width: int,
+                         height: int,
+                         faces: np.ndarray = None,
+                         point_size: float = 2.0) -> list:
+    """并行批量渲染多个相机视角（共用同一场景，减少重复数据传输）。
+
+    将场景数据（pts_world, colors_world, faces）只上传一次到 GPU，
+    然后依次渲染 len(cam_poses) 个视角，显著减少 PCIe 传输开销。
+
+    Args:
+        cam_poses: list of [x, y, z]，各帧相机位置
+        cam_rots:  list of [rx, ry, rz]，各帧相机欧拉角
+
+    Returns:
+        list of (rgb_np, depth_np) 与输入顺序对应
+    """
+    if not (_CUDA_AVAILABLE and torch is not None):
+        return [
+            render_erp_from_ply(pts_world, colors_world, pos, rot,
+                                 width, height, point_size, faces)
+            for pos, rot in zip(cam_poses, cam_rots)
+        ]
+
+    dev = _TORCH_DEVICE
+
+    # ── 场景数据上传（只做一次）──────────────────────────────────────────────
+    pts_t = torch.from_numpy(pts_world.astype(np.float32)).to(dev)
+
+    if colors_world is not None:
+        col_np = colors_world if colors_world.dtype == np.uint8 \
+            else (np.clip(colors_world, 0, 1) * 255).astype(np.uint8)
+        col_t_scene = torch.from_numpy(col_np.astype(np.float32)).to(dev)
+    else:
+        col_t_scene = None
+
+    f_t = None
+    if faces is not None and len(faces) > 0:
+        f_t = torch.from_numpy(faces.astype(np.int64)).to(dev)
+
+    # ── 逐帧渲染（场景数据复用）──────────────────────────────────────────────
+    results = []
+    for cam_pos, cam_rot in zip(cam_poses, cam_rots):
+        cam_pos_np = np.array(cam_pos, dtype=np.float64)
+        R_wc = _euler_to_rotation_matrix(*cam_rot).T
+
+        cp = torch.from_numpy(cam_pos_np.astype(np.float32)).to(dev)
+        R  = torch.from_numpy(R_wc.astype(np.float32)).to(dev)
+
+        pts_cam = (R @ (pts_t - cp).T).T
+        x_c, y_c, z_c = pts_cam[:, 0], pts_cam[:, 1], pts_cam[:, 2]
+        lon  = torch.atan2(x_c, z_c)
+        r_xz = torch.sqrt(x_c ** 2 + z_c ** 2)
+        lat  = torch.atan2(y_c, r_xz)
+        u_f  = (lon  / (2 * math.pi) + 0.5) * width
+        v_f  = (0.5  - lat / math.pi) * height
+        dist = torch.sqrt(x_c ** 2 + y_c ** 2 + z_c ** 2)
+
+        if col_t_scene is None:
+            d_norm = torch.clamp(dist / max(float(dist.max()), 1.0), 0, 1)
+            g = torch.clamp((1.0 - d_norm) * 200 + 30, 0, 255)
+            col_frame = g.unsqueeze(1).expand(-1, 3)
+        else:
+            col_frame = col_t_scene
+
+        try:
+            rgb_np, depth_np = _render_erp_gpu_from_projected(
+                u_f, v_f, dist, col_frame, f_t, width, height, point_size)
+        except Exception as e:
+            print(f"  [WARN] batch GPU 渲染帧失败，回退单帧: {e}")
+            rgb_np, depth_np = _render_erp_gpu(
+                pts_world, colors_world, cam_pos_np, R_wc,
+                width, height, faces=faces, point_size=point_size)
+        results.append((rgb_np, depth_np))
+
+    return results
+
+
+def _render_erp_gpu_from_projected(
+        u_f, v_f, dist, col_t, f_t,
+        width: int, height: int, point_size: float = 2.0) -> tuple:
+    """内部函数：从已投影的 GPU tensor 直接光栅化，省去重复的顶点变换。
+
+    Args:
+        u_f, v_f:  (N,) float32 GPU tensor，ERP 像素浮点坐标
+        dist:      (N,) float32 GPU tensor，各顶点到相机距离
+        col_t:     (N,3) float32 GPU tensor，顶点颜色 [0,255]
+        f_t:       (F,3) int64  GPU tensor 或 None
+        width, height: 输出分辨率
+    """
+    dev = u_f.device
+    H, W = height, width
+    INF  = 1e9
+
+    rgb_flat   = torch.zeros(H * W, 3, dtype=torch.float32, device=dev)
+    depth_flat = torch.full((H * W,), INF, dtype=torch.float32, device=dev)
+
+    if f_t is not None and len(f_t) > 0:
+        _gpu_raster_mesh(u_f, v_f, dist, col_t, f_t,
+                         rgb_flat, depth_flat, H, W)
+    else:
+        _gpu_splat_pointcloud(u_f, v_f, dist, col_t,
+                              rgb_flat, depth_flat, H, W, point_size)
+
+    depth_2d  = depth_flat.reshape(H, W)
+    rgb_2d    = rgb_flat.reshape(H, W, 3)
+    depth_out = torch.where(depth_2d < INF / 2, depth_2d, torch.zeros_like(depth_2d))
+
+    if f_t is not None and len(f_t) > 0:
+        rgb_2d = _gpu_fill_holes(rgb_2d, depth_out)
+
+    rgb_np   = rgb_2d.clamp(0, 255).byte().cpu().numpy()
+    depth_np = depth_out.cpu().numpy().astype(np.float32)
+    return rgb_np, depth_np
+
+
+def render_erp_from_ply(pts_world: np.ndarray,
+                        colors_world,
+                        cam_pos: list,
+                        cam_rot_euler: list,
+                        width: int,
+                        height: int,
+                        point_size: float = 2.0,
+                        faces: np.ndarray = None):
+    """带颜色的 ERP 全景图渲染（自动 dispatch 到 GPU/CPU）
+
+    Args:
+        pts_world:     (N,3) float64，Y-up 世界坐标
+        colors_world:  (N,3) uint8 或 float32，RGB 颜色，None=伪彩
+        cam_pos:       [x, y, z] 相机位置（Y-up）
+        cam_rot_euler: [rx, ry, rz] 相机欧拉角（弧度）
+        width, height: 输出分辨率
+        point_size:    splat 直径（像素），仅纯点云模式有效
+        faces:         (F,3) int，三角面顶点索引；有面时走面光栅化
+
+    Returns:
+        rgb:   (H, W, 3) uint8
+        depth: (H, W) float32，range depth（米），0=无效
+    """
+    cam_pos = np.array(cam_pos, dtype=np.float64)
+    R_cw = _euler_to_rotation_matrix(*cam_rot_euler)
+    R_wc = R_cw.T
+
+    # ── GPU dispatch ──────────────────────────────────────────────────────
+    if _CUDA_AVAILABLE and torch is not None:
+        try:
+            return _render_erp_gpu(pts_world, colors_world,
+                                   cam_pos, R_wc,
+                                   width, height,
+                                   faces=faces, point_size=point_size)
+        except Exception as _gpu_err:
+            print(f"  [WARN] GPU 渲染失败，回退 CPU: {_gpu_err}")
+
+    # ── CPU 路径 ──────────────────────────────────────────────────────────
+    # 所有顶点变换到相机坐标系
+    vecs = pts_world - cam_pos
+    pts_cam = (R_wc @ vecs.T).T  # (N, 3)
+
+    x_c = pts_cam[:, 0].astype(np.float32)
+    y_c = pts_cam[:, 1].astype(np.float32)
+    z_c = pts_cam[:, 2].astype(np.float32)
+
+    # ERP 投影：每顶点 → (u_f, v_f, dist)
+    lon = np.arctan2(x_c, z_c)
+    r_xz = np.sqrt(x_c ** 2 + z_c ** 2)
+    lat = np.arctan2(y_c, r_xz)
+    u_f = (lon / (2 * math.pi) + 0.5) * width    # float 像素坐标
+    v_f = (0.5 - lat / math.pi) * height
+    dist = np.sqrt(x_c ** 2 + y_c ** 2 + z_c ** 2)
+
+    # 顶点颜色
+    if colors_world is not None:
+        col_all = colors_world
+        if col_all.dtype != np.uint8:
+            col_all = (np.clip(col_all, 0, 1) * 255).astype(np.uint8)
+    else:
+        d_norm = np.clip(dist / max(float(dist.max()), 1.0), 0, 1)
+        g = np.clip((1.0 - d_norm) * 200 + 30, 0, 255).astype(np.uint8)
+        col_all = np.stack([g, g, g], axis=1)
+
+    rgb_buf = np.zeros((height, width, 3), dtype=np.uint8)
+    depth_buf = np.full((height, width), np.inf, dtype=np.float32)
+
+    if faces is not None and len(faces) > 0:
+        # ── 网格模式：三角面光栅化 ──────────────────────────────────────
+        f = faces.astype(np.int32)
+        d0, d1, d2 = dist[f[:, 0]], dist[f[:, 1]], dist[f[:, 2]]
+        face_dist = (d0 + d1 + d2) / 3.0
+        valid_face = (d0 > 1e-4) & (d1 > 1e-4) & (d2 > 1e-4)
+        f = f[valid_face]
+        face_dist = face_dist[valid_face]
+
+        # 从远到近排序，近面覆盖远面
+        order = np.argsort(face_dist)[::-1]
+        f = f[order]
+        face_dist = face_dist[order]
+
+        c0s = col_all[f[:, 0]].astype(np.float32)
+        c1s = col_all[f[:, 1]].astype(np.float32)
+        c2s = col_all[f[:, 2]].astype(np.float32)
+        d0s = dist[f[:, 0]]
+        d1s = dist[f[:, 1]]
+        d2s = dist[f[:, 2]]
+
+        # 三顶点的 ERP 浮点坐标
+        u0s_raw = u_f[f[:, 0]]
+        u1s_raw = u_f[f[:, 1]]
+        u2s_raw = u_f[f[:, 2]]
+        v0s = v_f[f[:, 0]]
+        v1s = v_f[f[:, 1]]
+        v2s = v_f[f[:, 2]]
+
+        def _raster_triangle(u0v, v0v, u1v, v1v, u2v, v2v,
+                             c0, c1, c2, dep0, dep1, dep2):
+            """将单个三角面光栅化写入 rgb_buf / depth_buf（闭包）"""
+            v_min = max(0, int(math.floor(min(v0v, v1v, v2v))))
+            v_max = min(height - 1, int(math.ceil(max(v0v, v1v, v2v))))
+            u_min = max(0, int(math.floor(min(u0v, u1v, u2v))))
+            u_max = min(width - 1, int(math.ceil(max(u0v, u1v, u2v))))
+            if v_max < v_min or u_max < u_min:
+                return
+            vs_arr = np.arange(v_min, v_max + 1)
+            us_arr = np.arange(u_min, u_max + 1)
+            uu, vv = np.meshgrid(us_arr, vs_arr)
+            uu = uu.flatten().astype(np.float32)
+            vv = vv.flatten().astype(np.float32)
+            denom = ((v1v - v2v) * (u0v - u2v) + (u2v - u1v) * (v0v - v2v))
+            if abs(denom) < 1e-8:
+                return
+            inv_d = 1.0 / denom
+            w0 = ((v1v - v2v) * (uu - u2v) + (u2v - u1v) * (vv - v2v)) * inv_d
+            w1 = ((v2v - v0v) * (uu - u2v) + (u0v - u2v) * (vv - v2v)) * inv_d
+            w2 = 1.0 - w0 - w1
+            inside = (w0 >= -0.01) & (w1 >= -0.01) & (w2 >= -0.01)
+            if not inside.any():
+                return
+            uu_in = uu[inside].astype(np.int32)
+            vv_in = vv[inside].astype(np.int32)
+            w0_in = w0[inside][:, None]
+            w1_in = w1[inside][:, None]
+            w2_in = w2[inside][:, None]
+            di = w0_in[:, 0] * dep0 + w1_in[:, 0] * dep1 + w2_in[:, 0] * dep2
+            ci_rgb = np.clip(w0_in * c0 + w1_in * c1 + w2_in * c2, 0, 255).astype(np.uint8)
+            closer = di < depth_buf[vv_in, uu_in]
+            if closer.any():
+                depth_buf[vv_in[closer], uu_in[closer]] = di[closer]
+                rgb_buf[vv_in[closer], uu_in[closer]] = ci_rgb[closer]
+
+        half_w = width / 2.0
+
+        for i in range(len(f)):
+            u0v, v0v = float(u0s_raw[i]), float(v0s[i])
+            u1v, v1v = float(u1s_raw[i]), float(v1s[i])
+            u2v, v2v = float(u2s_raw[i]), float(v2s[i])
+            c0, c1, c2 = c0s[i], c1s[i], c2s[i]
+            dep0, dep1, dep2 = float(d0s[i]), float(d1s[i]), float(d2s[i])
+
+            # 检测是否跨越 ERP 左右边界（u 坐标差 > width/2）
+            us_tri = np.array([u0v, u1v, u2v])
+            u_span = float(us_tri.max() - us_tri.min())
+
+            if u_span > half_w:
+                # 跨边界：以 u0 为基准，把 u1/u2 对齐到与 u0 最近的循环副本
+                def _align(u_ref, u_other):
+                    diff = u_other - u_ref
+                    if diff > half_w:
+                        return u_other - width
+                    elif diff < -half_w:
+                        return u_other + width
+                    return u_other
+
+                u1_a = _align(u0v, u1v)
+                u2_a = _align(u0v, u2v)
+
+                # 主渲染（对齐后坐标，_raster_triangle 内部 clip 到 [0, width-1]）
+                _raster_triangle(u0v, v0v, u1_a, v1v, u2_a, v2v, c0, c1, c2, dep0, dep1, dep2)
+                # 循环副本（偏移 ±width 处理左右两侧黑边）
+                _raster_triangle(u0v - width, v0v, u1_a - width, v1v, u2_a - width, v2v,
+                                 c0, c1, c2, dep0, dep1, dep2)
+                _raster_triangle(u0v + width, v0v, u1_a + width, v1v, u2_a + width, v2v,
+                                 c0, c1, c2, dep0, dep1, dep2)
+            else:
+                _raster_triangle(u0v, v0v, u1v, v1v, u2v, v2v, c0, c1, c2, dep0, dep1, dep2)
+
+    else:
+        # ── 纯点云模式：Z-buffer Splatting ────────────────────────────
+        valid_mask = dist > 1e-4
+        u_i = np.clip(u_f.astype(np.int32), 0, width - 1)[valid_mask]
+        v_i = np.clip(v_f.astype(np.int32), 0, height - 1)[valid_mask]
+        dist_v = dist[valid_mask]
+        col_v = col_all[valid_mask]
+
+        order = np.argsort(dist_v)[::-1]
+        radius = max(0, int(round(point_size / 2)) - 1)
+
+        if radius == 0:
+            near_order = np.argsort(dist_v)
+            for idx in near_order:
+                vi, ui, di = v_i[idx], u_i[idx], dist_v[idx]
+                if di < depth_buf[vi, ui]:
+                    depth_buf[vi, ui] = di
+                    rgb_buf[vi, ui] = col_v[idx]
+        else:
+            for idx in order:
+                vi, ui, di = int(v_i[idx]), int(u_i[idx]), float(dist_v[idx])
+                if not np.isfinite(di):
+                    continue
+                v0 = max(0, vi - radius)
+                v1 = min(height, vi + radius + 1)
+                u0 = max(0, ui - radius)
+                u1 = min(width, ui + radius + 1)
+                region = depth_buf[v0:v1, u0:u1]
+                mask = di < region
+                region[mask] = di
+                depth_buf[v0:v1, u0:u1] = region
+                rgb_region = rgb_buf[v0:v1, u0:u1]
+                rgb_region[mask] = col_v[idx]
+                rgb_buf[v0:v1, u0:u1] = rgb_region
+
+    depth_out = np.where(np.isfinite(depth_buf), depth_buf, 0.0).astype(np.float32)
+
+    # ── 空洞填充：迭代最近邻复制，每轮向外扩 1 像素，不修改已有有效像素 ──────
+    if faces is not None and len(faces) > 0:
+        hole_mask = (depth_out == 0)  # True=空洞
+        if hole_mask.any():
+            kernel = np.ones((3, 3), np.uint8)
+            valid_u8 = (~hole_mask).astype(np.uint8)
+            for _ in range(32):
+                if not hole_mask.any():
+                    break
+                dilated_valid = cv2.dilate(valid_u8, kernel)
+                newly = hole_mask & (dilated_valid > 0)
+                if not newly.any():
+                    break
+                for c in range(3):
+                    src = rgb_buf[:, :, c]
+                    # dilate 在 valid 区域的颜色，传播到邻近空洞（取邻域最大值近似最近邻）
+                    expanded = cv2.dilate(src * valid_u8, kernel)
+                    rgb_buf[:, :, c] = np.where(newly, expanded, src)
+                hole_mask[newly] = False
+                valid_u8[newly] = 1
+
+    return rgb_buf, depth_out
+
+
+def _extract_ply_colors(mesh_or_pc) -> Optional[np.ndarray]:
+    """尝试从 trimesh 对象中提取顶点颜色 (N,3) uint8"""
+    try:
+        if isinstance(mesh_or_pc, trimesh.Trimesh):
+            if mesh_or_pc.visual is not None:
+                if hasattr(mesh_or_pc.visual, 'vertex_colors'):
+                    vc = mesh_or_pc.visual.vertex_colors
+                    if vc is not None and len(vc) > 0:
+                        return np.array(vc[:, :3], dtype=np.uint8)
+        elif isinstance(mesh_or_pc, trimesh.PointCloud):
+            if mesh_or_pc.colors is not None and len(mesh_or_pc.colors) > 0:
+                return np.array(mesh_or_pc.colors[:, :3], dtype=np.uint8)
+    except Exception as e:
+        print(f"  [WARN] 提取颜色失败: {e}")
+    return None
+
+
+def save_pose(cam_pos_yup: list, cam_rot_euler: list,
+              output_path: str, frame_id: int):
+    """保存位姿 JSON（ERPT 格式，Y-up 坐标系，cam_to_world）
+
+    cam_pos_yup: [x, y, z]，Y-up 世界坐标（已是 ERPT_native）
+    cam_rot_euler: [rx, ry, rz] 弧度，XYZ 顺序
+    """
+    R_cw = _euler_to_rotation_matrix(*cam_rot_euler)
+
+    # 旋转矩阵 → 四元数（XYZW 顺序，转为 WXYZ）
+    # Shepperd 方法
+    m = R_cw
+    t = m[0, 0] + m[1, 1] + m[2, 2]
+    if t > 0:
+        s = 0.5 / math.sqrt(t + 1.0)
+        w = 0.25 / s
+        x = (m[2, 1] - m[1, 2]) * s
+        y = (m[0, 2] - m[2, 0]) * s
+        z = (m[1, 0] - m[0, 1]) * s
+    elif m[0, 0] > m[1, 1] and m[0, 0] > m[2, 2]:
+        s = 2.0 * math.sqrt(1.0 + m[0, 0] - m[1, 1] - m[2, 2])
+        w = (m[2, 1] - m[1, 2]) / s
+        x = 0.25 * s
+        y = (m[0, 1] + m[1, 0]) / s
+        z = (m[0, 2] + m[2, 0]) / s
+    elif m[1, 1] > m[2, 2]:
+        s = 2.0 * math.sqrt(1.0 + m[1, 1] - m[0, 0] - m[2, 2])
+        w = (m[0, 2] - m[2, 0]) / s
+        x = (m[0, 1] + m[1, 0]) / s
+        y = 0.25 * s
+        z = (m[1, 2] + m[2, 1]) / s
+    else:
+        s = 2.0 * math.sqrt(1.0 + m[2, 2] - m[0, 0] - m[1, 1])
+        w = (m[1, 0] - m[0, 1]) / s
+        x = (m[0, 2] + m[2, 0]) / s
+        y = (m[1, 2] + m[2, 1]) / s
+        z = 0.25 * s
+
+    pose_data = {
+        "frame_id": frame_id,
+        "position": [float(v) for v in cam_pos_yup],
+        "rotation_quaternion": [float(w), float(x), float(y), float(z)],
+        "camera_type": "erp_ray",
+        "coordinate_system": "right-handed, Y-up, Z-forward (cam_to_world)",
+        "render_method": "ply_erp",
+    }
+    with open(output_path, 'w') as f:
+        json.dump(pose_data, f, indent=2)
+
+
+def build_ray_directions(H=WARP_H, W=WARP_W):
+    """ERP 射线方向（Y-up 坐标系）"""
+    i = np.arange(H, dtype=np.float64)
+    j = np.arange(W, dtype=np.float64)
+    lat = np.pi / 2 - np.pi * (i + 0.5) / H   # [-π/2, π/2]
+    lon = 2 * np.pi * (j + 0.5) / W             # [0, 2π]
+    lat, lon = np.meshgrid(lat, lon, indexing='ij')
+    r_xz = np.cos(lat)
+    return np.stack([
+        r_xz * np.sin(lon),   # X
+        np.sin(lat),           # Y (up)
+        r_xz * np.cos(lon),   # Z (front)
+    ], axis=-1)
+
+
+_ray_dirs_cache = {}
+
+
+def get_ray_dirs(H=WARP_H, W=WARP_W):
+    if (H, W) not in _ray_dirs_cache:
+        _ray_dirs_cache[(H, W)] = build_ray_directions(H, W)
+    return _ray_dirs_cache[(H, W)]
+
+
+def depth_to_3d_points(position, depth, ray_dirs, max_depth=None):
+    valid = depth > 0
+    if max_depth is not None:
+        valid &= (depth <= max_depth)
+    if not np.any(valid):
+        return np.empty((0, 3), dtype=np.float64)
+    pos = np.array(position, dtype=np.float64)
+    return (pos + ray_dirs * depth[..., np.newaxis])[valid]
+
+
+def project_points_to_coverage(pts, tgt_pos, H=WARP_H, W=WARP_W):
+    if len(pts) == 0:
+        return np.zeros((H, W), dtype=bool)
+    tgt = np.array(tgt_pos, dtype=np.float64)
+    vecs = pts - tgt
+    x, y, z = vecs[:, 0], vecs[:, 1], vecs[:, 2]
+    r_xz = np.sqrt(x ** 2 + z ** 2)
+    lat = np.arctan2(y, r_xz)
+    lon = np.arctan2(x, z) % (2 * np.pi)
+    vi = np.clip(((np.pi / 2 - lat) / np.pi * H).astype(np.int32), 0, H - 1)
+    uj = np.clip((lon / (2 * np.pi) * W).astype(np.int32), 0, W - 1)
+    cov = np.zeros((H, W), dtype=bool)
+    cov[vi, uj] = True
+    pad = cov.copy()
+    pad[1:, :] |= cov[:-1, :]
+    pad[:-1, :] |= cov[1:, :]
+    pad[:, 1:] |= cov[:, :-1]
+    pad[:, :-1] |= cov[:, 1:]
+    return pad
+
+
+def select_next_frame(candidates, selected_idx, selected_pos, all_pts,
+                      reachable=None):
+    n = len(candidates)
+    H, W = WARP_H, WARP_W
+    total_px = H * W
+    overlap_penalty = DEFAULT_OVERLAP_PENALTY
+
+    remaining = []
+    for i in range(n):
+        if i in selected_idx:
+            continue
+        if reachable is not None and i not in reachable:
+            continue
+        remaining.append(i)
+
+    if not remaining:
+        return -1, 0.0, -999.0, 0
+
+    scores = {}
+    for ci in remaining:
+        cov = project_points_to_coverage(all_pts, candidates[ci], H, W)
+        covered = int(np.sum(cov))
+        new_r = (total_px - covered) / total_px
+        ovl_r = covered / total_px
+        scores[ci] = {
+            "gain": new_r,
+            "overlap": ovl_r,
+            "score": new_r - overlap_penalty * ovl_r,
+        }
+
+    best_ci, best_sc, best_g = -1, -999.0, 0.0
+    for ci in remaining:
+        if scores[ci]["score"] > best_sc:
+            best_sc = scores[ci]["score"]
+            best_ci = ci
+            best_g = scores[ci]["gain"]
+
+    return best_ci, best_g, best_sc, len(remaining)
+
+
+def compute_max_depth(candidates):
+    pos_arr = np.array(candidates)
+    diag = float(np.linalg.norm(pos_arr.max(0) - pos_arr.min(0)))
+    return diag * 1.5
+
+
+def load_depth_downsampled(path, H=WARP_H, W=WARP_W):
+    d = np.load(path).astype(np.float32)
+    d = np.nan_to_num(d, nan=0.0)
+    if d.shape == (H, W):
+        return d
+    try:
+        return cv2.resize(d, (W, H), interpolation=cv2.INTER_AREA)
+    except Exception:
+        h, w = d.shape
+        bh, bw = h // H, w // W
+        if bh < 1 or bw < 1:
+            r = np.zeros((H, W), dtype=np.float32)
+            r[:min(h, H), :min(w, W)] = d[:min(h, H), :min(w, W)]
+            return r
+        return d[:bh * H, :bw * W].reshape(H, bh, W, bw).mean(axis=(1, 3))
+
+
+def trim_depth(new_depth, new_pos, existing_pts, ray_dirs):
+    n_orig = int(np.sum(new_depth > 0))
+    if len(existing_pts) == 0:
+        return new_depth.copy(), n_orig, n_orig
+    cov = project_points_to_coverage(existing_pts, new_pos,
+                                     new_depth.shape[0], new_depth.shape[1])
+    trimmed = new_depth.copy()
+    trimmed[cov] = 0
+    return trimmed, n_orig, int(np.sum(trimmed > 0))
+
+
+def update_reachability(current_pos: np.ndarray, candidates, selected_idx,
+                        reachable: set, raycaster: RayCaster):
+    """从当前位置出发，检测哪些候选点可达（无遮挡直线视线）"""
+    if raycaster._intersector is None:
+        # 非 Mesh：所有候选都"可达"
+        for ci, c in enumerate(candidates):
+            if ci not in selected_idx:
+                reachable.add(ci)
+        return 0
+
+    n_new = 0
+    for ci, cand in enumerate(candidates):
+        if ci in selected_idx or ci in reachable:
+            continue
+        target = np.array(cand, dtype=np.float64)
+        dist_to_target = float(np.linalg.norm(target - current_pos))
+        if dist_to_target < 0.1:
+            reachable.add(ci)
+            n_new += 1
+            continue
+        direction = (target - current_pos) / dist_to_target
+        hit, hit_dist = raycaster.cast_ray(current_pos, direction)
+        if not hit or hit_dist >= dist_to_target * 0.95:
+            reachable.add(ci)
+            n_new += 1
+
+    return n_new
+
+
+def run_phase2(pts_world: np.ndarray,
+               colors_world,
+               faces,
+               candidates,
+               mesh_center,
+               raycaster: RayCaster,
+               output_dir: str,
+               max_frames: int,
+               resolution,
+               args):
+    """边选帧边渲染主循环（PLY 版本，逻辑与 Blender 版本对齐）"""
+    W_render, H_render = resolution
+    ray_dirs = get_ray_dirs(WARP_H, WARP_W)
+    max_depth = compute_max_depth(candidates)
+
+    selected_idx = set()
+    selected_pos = []
+    all_pts = np.empty((0, 3), dtype=np.float64)
+    pts_chunks = []
+    results = []
+    reachable = set()
+
+    stop_score = args.stop_score
+    stop_delta = args.stop_delta
+    min_frames = args.min_frames
+
+    ACTUAL_GAIN_WINDOW = 3
+    ACTUAL_GAIN_FLOOR = args.stop_gain
+    actual_gain_history = []
+    delta_history = []
+
+    # ── 异步 I/O 线程池：写盘与 GPU 渲染并行 ─────────────────────────────
+    _io_executor = ThreadPoolExecutor(max_workers=2)
+    _pending_io  = []   # list of Future，用于等待上一帧写盘完成
+
+    def _save_frame_async(rgb, depth, rgb_path, depth_npy, pos, cam_rot,
+                          pose_path, frame_id):
+        """在线程池中异步保存 PNG + npy + json"""
+        def _do_save():
+            cv2.imwrite(rgb_path, cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR))
+            np.save(depth_npy, depth.astype(np.float32))
+            save_pose(pos, cam_rot, pose_path, frame_id)
+        return _io_executor.submit(_do_save)
+    consecutive_skips = 0
+    MAX_CONSECUTIVE_SKIPS = 3
+
+    # 楼层分组（按 Y 坐标聚类）
+    y_vals = sorted(set(round(c[1], 2) for c in candidates))
+    floors = [[y_vals[0]]]
+    for y in y_vals[1:]:
+        if y - floors[-1][-1] > 1.0:
+            floors.append([y])
+        else:
+            floors[-1].append(y)
+
+    n_floors = len(floors)
+    floor_mids = [sum(f) / len(f) for f in floors]
+    candidate_floor = [
+        min(range(n_floors), key=lambda i: abs(c[1] - floor_mids[i]))
+        for c in candidates
+    ]
+    current_floor = 0
+
+    def floor_set(fi):
+        return set(i for i, f in enumerate(candidate_floor) if f == fi)
+
+    floor_names = [f"楼层{i+1}(Y={min(f):.1f}~{max(f):.1f})" for i, f in enumerate(floors)]
+
+    print(f"\n{'='*60}")
+    print(f"[Phase 2] 边渲边选 (候选={len(candidates)}, 最多={max_frames}帧)")
+    print(f"{'='*60}")
+    print(f"  {n_floors} 个楼层: {floor_names}")
+
+    t_total = time.time()
+    time_select = time_render = time_depth = time_reach = 0.0
+
+    for frame_count in range(max_frames):
+
+        # ---- 选位置 ----
+        t_sel = time.time()
+        if frame_count == 0:
+            floor0_cands = [(i, c) for i, c in enumerate(candidates)
+                            if candidate_floor[i] == 0]
+            if floor0_cands:
+                f0_pts = np.array([c for _, c in floor0_cands])
+                xz_center = np.array([f0_pts[:, 0].mean(), f0_pts[:, 2].mean()])
+                floor0_ys = sorted(set(c[1] for _, c in floor0_cands))
+                y_target = min(floor0_ys) + 1.2
+                target = np.array([xz_center[0], y_target, xz_center[1]])
+                dists = [np.linalg.norm(np.array(c) - target)
+                         for _, c in floor0_cands]
+                ci = floor0_cands[int(np.argmin(dists))][0]
+            else:
+                mc = np.array(mesh_center, dtype=np.float64)
+                ci = int(np.argmin([np.linalg.norm(np.array(c) - mc)
+                                    for c in candidates]))
+            gain, score = 1.0, 1.0
+            print(f"\n  F{frame_count}: 选候选[{ci}] (楼层中心, Y={candidates[ci][1]:.2f}m) "
+                  f"[{floor_names[current_floor]}]")
+        else:
+            cur_floor_ids = floor_set(current_floor)
+            floor_reachable = reachable & cur_floor_ids if reachable else set()
+
+            ci, gain, score, n_remain = select_next_frame(
+                candidates, selected_idx, selected_pos, all_pts,
+                reachable=floor_reachable if floor_reachable else cur_floor_ids)
+
+            expand = False
+            if ci < 0 or score < stop_score:
+                ci2, gain2, score2, n2 = select_next_frame(
+                    candidates, selected_idx, selected_pos, all_pts,
+                    reachable=cur_floor_ids)
+                if ci2 >= 0 and (ci < 0 or score2 > score):
+                    ci, gain, score, n_remain = ci2, gain2, score2, n2
+                    expand = True
+
+            if ci < 0 or (score < stop_score and gain < ACTUAL_GAIN_FLOOR):
+                reason = "无可选候选" if ci < 0 else f"gain={gain:.1%} score={score:.3f}"
+                current_floor += 1
+                if current_floor < n_floors:
+                    print(f"\n  F{frame_count}: {reason}"
+                          f" → 切换到 {floor_names[current_floor]}")
+                    continue
+                else:
+                    print(f"\n  F{frame_count}: {reason} → 所有楼层拍满，停止")
+                    break
+
+            tag = "[扩展]" if expand else ""
+            print(f"\n  F{frame_count}: 选候选[{ci}]  "
+                  f"gain={gain:.1%}  score={score:.3f}  剩余={n_remain}"
+                  f"  [Y={candidates[ci][1]:.2f} {floor_names[current_floor]}]{tag}")
+
+        pos = candidates[ci]
+        selected_idx.add(ci)
+        selected_pos.append(pos)
+        dt_sel = time.time() - t_sel
+        time_select += dt_sel
+
+        # ---- 渲染（GPU 共享场景数据，减少重复上传）----
+        cam_rot = get_camera_rot(args.rotation_type, frame_count)
+        base = f"panorama_{frame_count:04d}"
+        rgb_path = os.path.join(output_dir, f"{base}.png")
+        depth_npy = os.path.join(output_dir, f"{base}_depth.npy")
+        pose_path = os.path.join(output_dir, f"pose_{frame_count:04d}.json")
+
+        print(f"    位置: [{pos[0]:.2f}, {pos[1]:.2f}, {pos[2]:.2f}]")
+        print(f"    渲染...", end="", flush=True)
+        t_r = time.time()
+
+        # 等待上一帧异步 I/O 完成（保证不超过 2 帧待写）
+        while len(_pending_io) >= 2:
+            _pending_io.pop(0).result()
+
+        # 使用 render_erp_batch_gpu：场景数据只上传一次
+        batch_results = render_erp_batch_gpu(
+            pts_world, colors_world,
+            cam_poses=[pos],
+            cam_rots=[cam_rot],
+            width=W_render,
+            height=H_render,
+            faces=faces,
+            point_size=args.point_size,
+        )
+        rgb, depth = batch_results[0]
+
+        # 异步写盘（与下一帧 GPU 渲染并行）
+        fut = _save_frame_async(
+            rgb, depth, rgb_path, depth_npy,
+            pos, cam_rot, pose_path, frame_count)
+        _pending_io.append(fut)
+
+        dt_r = time.time() - t_r
+        time_render += dt_r
+        print(f" {dt_r:.1f}s")
+
+        # ---- depth → 3D 点云 ----
+        t_dep = time.time()
+        actual_gain = 1.0
+        delta_ratio = 1.0
+
+        # 直接使用内存中的 depth（depth_npy 由异步线程写入，可能尚未落盘）
+        _d = depth.astype(np.float32)
+        _d = np.nan_to_num(_d, nan=0.0)
+        if _d.shape == (WARP_H, WARP_W):
+            depth_small = _d
+        else:
+            try:
+                depth_small = cv2.resize(_d, (WARP_W, WARP_H), interpolation=cv2.INTER_AREA)
+            except Exception:
+                h, w = _d.shape
+                bh, bw = h // WARP_H, w // WARP_W
+                if bh < 1 or bw < 1:
+                    depth_small = np.zeros((WARP_H, WARP_W), dtype=np.float32)
+                    depth_small[:min(h, WARP_H), :min(w, WARP_W)] = _d[:min(h, WARP_H), :min(w, WARP_W)]
+                else:
+                    depth_small = _d[:bh*WARP_H, :bw*WARP_W].reshape(WARP_H, bh, WARP_W, bw).mean(axis=(1, 3))
+        total_px = WARP_H * WARP_W
+        n_valid = int(np.sum(depth_small > 0))
+        valid_ratio = n_valid / total_px
+
+        if frame_count == 0:
+            new_pts = depth_to_3d_points(pos, depth_small, ray_dirs, max_depth)
+            pts_chunks.append(new_pts)
+            all_pts = new_pts
+            actual_gain = valid_ratio
+            print(f"    depth: {n_valid}px ({valid_ratio:.0%} 有效)"
+                  f" → {len(new_pts)} 个 3D 点 (全部)")
+        else:
+            MIN_VALID_RATIO = 0.10   # PLY 点云空洞较多，阈值适当降低
+            if valid_ratio < MIN_VALID_RATIO:
+                print(f"    depth: {n_valid}px ({valid_ratio:.0%} 有效) < "
+                      f"{MIN_VALID_RATIO:.0%} → 跳过此帧")
+                results.append({
+                    "frame_id": frame_count,
+                    "candidate_idx": ci,
+                    "position": pos,
+                    "gain": float(gain),
+                    "actual_gain": 0.0,
+                    "delta_ratio": 0.0,
+                    "score": float(score),
+                    "skipped": True,
+                    "skip_reason": f"valid_ratio={valid_ratio:.1%}",
+                })
+                for fp in [rgb_path, depth_npy]:
+                    if os.path.exists(fp):
+                        try:
+                            os.remove(fp)
+                        except OSError:
+                            pass
+                consecutive_skips += 1
+                if consecutive_skips >= MAX_CONSECUTIVE_SKIPS:
+                    current_floor += 1
+                    consecutive_skips = 0
+                    if current_floor < n_floors:
+                        print(f"    连续 {MAX_CONSECUTIVE_SKIPS} 帧空洞"
+                              f" → 切换到 {floor_names[current_floor]}")
+                    else:
+                        print(f"    连续 {MAX_CONSECUTIVE_SKIPS} 帧空洞，停止")
+                        break
+                time_depth += time.time() - t_dep
+                continue
+
+            trimmed, n_orig, n_new = trim_depth(depth_small, pos, all_pts, ray_dirs)
+            new_pts = depth_to_3d_points(pos, trimmed, ray_dirs, max_depth)
+            pts_chunks.append(new_pts)
+            all_pts = np.concatenate(pts_chunks)
+            actual_gain = n_new / total_px
+            delta_ratio = len(new_pts) / len(all_pts) if len(all_pts) > 0 else 1.0
+            print(f"    depth: {n_valid}px ({valid_ratio:.0%} 有效)"
+                  f" → trim → {n_new}px 新增 → {len(new_pts)} 个新 3D 点")
+            print(f"    累积点云: {len(all_pts)}, 实际gain: {actual_gain:.1%}")
+            consecutive_skips = 0
+
+        time_depth += time.time() - t_dep
+
+        results.append({
+            "frame_id": frame_count,
+            "candidate_idx": ci,
+            "position": pos,
+            "gain": float(gain),
+            "actual_gain": float(actual_gain),
+            "delta_ratio": float(delta_ratio),
+            "score": float(score),
+        })
+
+        # ---- 可达性更新 ----
+        t_reach = time.time()
+        n_new_r = update_reachability(
+            np.array(pos), candidates, selected_idx, reachable, raycaster)
+        dt_reach = time.time() - t_reach
+        time_reach += dt_reach
+        print(f"    [可达性] 新增 {n_new_r} 个，总 {len(reachable)}/{len(candidates)} "
+              f"({dt_reach:.1f}s)")
+
+        # ---- 停止条件 ----
+        if frame_count > 0:
+            actual_gain_history.append(actual_gain)
+            delta_history.append(delta_ratio)
+
+        if frame_count > 0 and frame_count >= min_frames:
+            if len(actual_gain_history) >= ACTUAL_GAIN_WINDOW:
+                recent_gain = actual_gain_history[-ACTUAL_GAIN_WINDOW:]
+                recent_delta = delta_history[-ACTUAL_GAIN_WINDOW:]
+                gain_exhausted = all(g < ACTUAL_GAIN_FLOOR for g in recent_gain)
+                delta_exhausted = all(d < stop_delta for d in recent_delta)
+
+                if gain_exhausted or delta_exhausted:
+                    current_floor += 1
+                    if current_floor < n_floors:
+                        reason = (f"gain<{ACTUAL_GAIN_FLOOR:.0%}" if gain_exhausted
+                                  else f"delta<{stop_delta:.0%}")
+                        print(f"    连续 {ACTUAL_GAIN_WINDOW} 帧 {reason}"
+                              f" → 切换到 {floor_names[current_floor]}")
+                    else:
+                        print(f"    所有楼层拍满，停止")
+                        break
+
+    # 补帧：确保 4n+1
+    while len(results) > 1 and (len(results) - 1) % 4 != 0:
+        frame_count = results[-1]["frame_id"] + 1
+        if frame_count >= max_frames + 3:
+            break
+        print(f"\n  [补帧] 当前 {len(results)} 帧，需补至 4n+1")
+        ci, gain, score, n_remain = select_next_frame(
+            candidates, selected_idx, selected_pos, all_pts, reachable=None)
+        if ci < 0:
+            break
+
+        pos = candidates[ci]
+        selected_idx.add(ci)
+        selected_pos.append(pos)
+
+        cam_rot = get_camera_rot(args.rotation_type, frame_count)
+        base = f"panorama_{frame_count:04d}"
+        rgb_path = os.path.join(output_dir, f"{base}.png")
+        depth_npy = os.path.join(output_dir, f"{base}_depth.npy")
+
+        batch_res = render_erp_batch_gpu(
+            pts_world, colors_world,
+            cam_poses=[pos], cam_rots=[cam_rot],
+            width=W_render, height=H_render,
+            faces=faces, point_size=args.point_size,
+        )
+        rgb, depth = batch_res[0]
+        try:
+            cv2.imwrite(rgb_path, cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR))
+        except Exception:
+            from PIL import Image
+            Image.fromarray(rgb).save(rgb_path)
+        np.save(depth_npy, depth.astype(np.float32))
+        save_pose(pos, cam_rot, os.path.join(output_dir, f"pose_{frame_count:04d}.json"),
+                  frame_count)
+
+        depth_small = load_depth_downsampled(depth_npy, WARP_H, WARP_W)
+        trimmed, n_orig, n_new = trim_depth(depth_small, pos, all_pts, ray_dirs)
+        new_pts = depth_to_3d_points(pos, trimmed, ray_dirs, max_depth)
+        pts_chunks.append(new_pts)
+        all_pts = np.concatenate(pts_chunks)
+        actual_gain = n_new / total_px
+        results.append({
+            "frame_id": frame_count,
+            "candidate_idx": ci,
+            "position": pos,
+            "gain": float(gain),
+            "actual_gain": float(actual_gain),
+            "delta_ratio": float(len(new_pts) / max(len(all_pts), 1)),
+            "score": float(score),
+            "supplementary": True,
+        })
+        print(f"    补帧 F{frame_count}: gain={actual_gain:.1%}")
+
+    # ── 等待所有异步 I/O 完成，关闭线程池 ────────────────────────────────
+    for fut in _pending_io:
+        try:
+            fut.result()
+        except Exception as e:
+            print(f"  [WARN] 异步写盘失败: {e}")
+    _io_executor.shutdown(wait=False)
+
+    dt = time.time() - t_total
+    print(f"\n  {'─'*50}")
+    print(f"  共 {len(results)} 帧, {dt:.1f}s ({dt/60:.1f}min)")
+    print(f"  耗时: 选帧={time_select:.1f}s  渲染={time_render:.1f}s  "
+          f"深度={time_depth:.1f}s  可达={time_reach:.1f}s")
+    return results
+
+
+def main():
+    args = parse_args()
+
+    ply_path = str(Path(args.ply).resolve())
+    output_dir = str(Path(args.output_dir).resolve())
+    resolution = tuple(int(x) for x in args.resolution.split(","))
+    os.makedirs(output_dir, exist_ok=True)
+    sel_dir = os.path.join(output_dir, "frame_selection")
+    os.makedirs(sel_dir, exist_ok=True)
+
+    print("=" * 60)
+    print("ERPT PLY Pipeline（边渲边选）")
+    print("=" * 60)
+    print(f"  PLY:        {ply_path}")
+    print(f"  Output:     {output_dir}")
+    print(f"  Max frames: {args.num_frames}")
+    print(f"  Resolution: {resolution[0]}x{resolution[1]}")
+    t_start = time.time()
+
+    # ===== Phase 0: 加载场景 =====
+    mesh_obj, pts_world, bmin, bmax, is_mesh, faces = load_ply_scene(
+        ply_path, z_up=args.z_up)
+
+    # 提取颜色
+    colors_world = _extract_ply_colors(mesh_obj)
+    if colors_world is not None:
+        print(f"  颜色: {len(colors_world)} 个顶点颜色")
+    else:
+        print(f"  颜色: 无顶点颜色，使用深度伪彩")
+
+    # 构建射线检测器
+    raycaster = RayCaster(mesh_obj, pts_world, bmin, bmax, is_mesh, z_up=args.z_up)
+
+    # ===== Phase 1: 撒点 + 过滤 =====
+    print(f"\n{'='*60}")
+    print("[Phase 1] 多层撒点 + 7 层过滤")
+    print(f"{'='*60}")
+
+    # Y-up 坐标系：Y=高度，floor=bmin[1]，ceiling=bmax[1]
+    floor_y = float(bmin[1])
+    ceiling_y = float(bmax[1])
+    print(f"  场景 Y 范围: {floor_y:.2f} ~ {ceiling_y:.2f}m (总高 {ceiling_y-floor_y:.2f}m)")
+
+    heights = compute_camera_heights(floor_y, ceiling_y, args.camera_height)
+    print(f"  相机高度层: {[f'{h:.2f}m' for h in heights]}")
+
+    x_range = float(bmax[0] - bmin[0])
+    z_range = float(bmax[2] - bmin[2])
+    x_sp = args.grid_spacing
+    z_sp = args.grid_spacing
+
+    # 候选点过多时自适应增大间距
+    n_xy = max(1, int((x_range - 2 * MARGIN) / x_sp)) * \
+           max(1, int((z_range - 2 * MARGIN) / z_sp))
+    total_est = n_xy * len(heights)
+    if total_est > 10000:
+        scale = math.sqrt(total_est / 10000)
+        x_sp = min(x_sp * scale, x_range / 4)
+        z_sp = min(z_sp * scale, z_range / 4)
+        print(f"  [自适应] 候选≈{total_est}个，间距调整为 X={x_sp:.1f}m Z={z_sp:.1f}m")
+
+    candidates = generate_candidate_grid(bmin, bmax, x_sp, z_sp, heights)
+    if not candidates:
+        print("  [Error] 没有候选点")
+        sys.exit(1)
+
+    room_height = ceiling_y - floor_y
+    candidates = raycast_filter(candidates, raycaster, room_height)
+    if not candidates:
+        print("  [Warning] 全部被过滤，使用 AABB 中心")
+        cx = float((bmin[0] + bmax[0]) / 2)
+        cy = float(heights[0])
+        cz = float((bmin[2] + bmax[2]) / 2)
+        candidates = [[cx, cy, cz]]
+
+    np.save(os.path.join(sel_dir, "candidates_filtered.npy"),
+            np.array(candidates))
+    print(f"  最终候选点: {len(candidates)} 个")
+
+    mesh_center = [
+        float((bmin[0] + bmax[0]) / 2),
+        float((bmin[1] + bmax[1]) / 2),
+        float((bmin[2] + bmax[2]) / 2),
+    ]
+
+    # ===== Phase 2: 边渲边选 =====
+    results = run_phase2(
+        pts_world=pts_world,
+        colors_world=colors_world,
+        faces=faces,
+        candidates=candidates,
+        mesh_center=mesh_center,
+        raycaster=raycaster,
+        output_dir=output_dir,
+        max_frames=args.num_frames,
+        resolution=resolution,
+        args=args,
+    )
+
+    # ===== 保存选帧摘要 =====
+    summary = {
+        "scene": os.path.basename(ply_path),
+        "total_frames": len(results),
+        "candidates_count": len(candidates),
+        "frames": [{
+            "frame_id": r["frame_id"],
+            "position": r["position"],
+            "gain": r["gain"],
+            "actual_gain": r["actual_gain"],
+            "delta_ratio": r["delta_ratio"],
+            "score": r["score"],
+        } for r in results if not r.get("skipped")],
+    }
+    with open(os.path.join(sel_dir, "selected_frames.json"), "w") as f:
+        json.dump(summary, f, indent=2, ensure_ascii=False)
+
+    dt = time.time() - t_start
+    print(f"\n{'='*60}")
+    print(f"完成! {len(results)} 帧, {dt:.1f}s ({dt/60:.1f}min)")
+    print(f"{'='*60}")
+    print(f"输出目录: {output_dir}/")
+    for r in results:
+        if not r.get("skipped"):
+            fid = r["frame_id"]
+            print(f"  panorama_{fid:04d}.png  +  _depth.npy  +  pose_{fid:04d}.json")
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,15 @@
+numpy>=1.24
+scipy
+pandas
+pyyaml
+pillow
+matplotlib
+scikit-learn
+torch
+torchvision
+opencv-python
+open3d
+trimesh
+tqdm
+jsonschema
+

results/README.md

@@ -0,0 +1,13 @@
+# Results Directory
+
+Generated CSV summaries should be written here or under `outputs/<run_name>/results/`.
+
+Recommended filenames:
+
+- `coverage_main.csv`
+- `oracle_validation.csv`
+- `lambda_sweep.csv`
+- `cross_source.csv`
+- `audit_50_frames.csv`
+- `runtime_scaling.csv`
+

scripts/_common.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import binascii
+import csv
+import json
+import math
+import shutil
+import struct
+import zlib
+from pathlib import Path
+from typing import Any, Iterable
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+def ensure_dir(path: str | Path) -> Path:
+    out = Path(path)
+    out.mkdir(parents=True, exist_ok=True)
+    return out
+
+
+def read_json(path: str | Path) -> Any:
+    with Path(path).open("r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def write_json(path: str | Path, obj: Any) -> None:
+    path = Path(path)
+    ensure_dir(path.parent)
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(obj, f, indent=2, sort_keys=True)
+        f.write("\n")
+
+
+def read_jsonl(path: str | Path) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    with Path(path).open("r", encoding="utf-8") as f:
+        for line_no, line in enumerate(f, start=1):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rows.append(json.loads(line))
+            except json.JSONDecodeError as exc:
+                raise ValueError(f"Invalid JSONL at {path}:{line_no}: {exc}") from exc
+    return rows
+
+
+def write_jsonl(path: str | Path, rows: Iterable[dict[str, Any]]) -> None:
+    path = Path(path)
+    ensure_dir(path.parent)
+    with path.open("w", encoding="utf-8") as f:
+        for row in rows:
+            f.write(json.dumps(row, sort_keys=True))
+            f.write("\n")
+
+
+def write_csv(path: str | Path, rows: list[dict[str, Any]], fieldnames: list[str] | None = None) -> None:
+    path = Path(path)
+    ensure_dir(path.parent)
+    if fieldnames is None:
+        keys: list[str] = []
+        for row in rows:
+            for key in row:
+                if key not in keys:
+                    keys.append(key)
+        fieldnames = keys
+    with path.open("w", encoding="utf-8", newline="") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        for row in rows:
+            writer.writerow(row)
+
+
+def _table_fieldnames(rows: list[dict[str, Any]], fieldnames: list[str] | None = None) -> list[str]:
+    if fieldnames is not None:
+        return fieldnames
+    keys: list[str] = []
+    for row in rows:
+        for key in row:
+            if key not in keys:
+                keys.append(key)
+    return keys
+
+
+def write_markdown_table(path: str | Path, rows: list[dict[str, Any]], fieldnames: list[str] | None = None) -> None:
+    path = Path(path)
+    ensure_dir(path.parent)
+    fieldnames = _table_fieldnames(rows, fieldnames)
+    with path.open("w", encoding="utf-8") as f:
+        f.write("| " + " | ".join(fieldnames) + " |\n")
+        f.write("| " + " | ".join(["---"] * len(fieldnames)) + " |\n")
+        for row in rows:
+            f.write("| " + " | ".join(str(row.get(name, "")) for name in fieldnames) + " |\n")
+
+
+def _latex_escape(value: Any) -> str:
+    text = str(value)
+    return (
+        text.replace("\\", "\\textbackslash{}")
+        .replace("&", "\\&")
+        .replace("%", "\\%")
+        .replace("$", "\\$")
+        .replace("#", "\\#")
+        .replace("_", "\\_")
+        .replace("{", "\\{")
+        .replace("}", "\\}")
+    )
+
+
+def write_latex_table(
+    path: str | Path,
+    rows: list[dict[str, Any]],
+    fieldnames: list[str] | None = None,
+    caption: str = "Table-ready experiment results.",
+    label: str = "tab:cmevs_results",
+) -> None:
+    path = Path(path)
+    ensure_dir(path.parent)
+    fieldnames = _table_fieldnames(rows, fieldnames)
+    align = "l" * len(fieldnames)
+    with path.open("w", encoding="utf-8") as f:
+        f.write("\\begin{table}[t]\n")
+        f.write("\\centering\n")
+        f.write(f"\\caption{{{_latex_escape(caption)}}}\n")
+        safe_label = str(label).replace("{", "").replace("}", "")
+        f.write(f"\\label{{{safe_label}}}\n")
+        f.write(f"\\begin{{tabular}}{{{align}}}\n")
+        f.write("\\toprule\n")
+        f.write(" & ".join(_latex_escape(name) for name in fieldnames) + " \\\\\n")
+        f.write("\\midrule\n")
+        for row in rows:
+            f.write(" & ".join(_latex_escape(row.get(name, "")) for name in fieldnames) + " \\\\\n")
+        f.write("\\bottomrule\n")
+        f.write("\\end{tabular}\n")
+        f.write("\\end{table}\n")
+
+
+def copy_file(src: str | Path, dst: str | Path) -> None:
+    dst = Path(dst)
+    ensure_dir(dst.parent)
+    shutil.copy2(src, dst)
+
+
+def candidate_by_id(candidates: Iterable[dict[str, Any]]) -> dict[str, dict[str, Any]]:
+    return {str(row["candidate_id"]): row for row in candidates}
+
+
+def valid_candidates(candidates: Iterable[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [row for row in candidates if bool(row.get("valid", True))]
+
+
+def cell_set(candidate: dict[str, Any]) -> set[str]:
+    return {str(cell) for cell in candidate.get("covered_cells", [])}
+
+
+def universe_cells(candidates: Iterable[dict[str, Any]]) -> set[str]:
+    cells: set[str] = set()
+    for candidate in candidates:
+        if bool(candidate.get("valid", True)):
+            cells.update(cell_set(candidate))
+    return cells
+
+
+def selected_ids(selected_doc: dict[str, Any]) -> list[str]:
+    return [str(row["candidate_id"]) for row in selected_doc.get("selected_viewpoints", [])]
+
+
+def safe_div(num: float, den: float) -> float:
+    return 0.0 if den == 0 else num / den
+
+
+def pearson(xs: list[float], ys: list[float]) -> float:
+    if len(xs) != len(ys) or len(xs) < 2:
+        return float("nan")
+    mx = sum(xs) / len(xs)
+    my = sum(ys) / len(ys)
+    num = sum((x - mx) * (y - my) for x, y in zip(xs, ys))
+    vx = sum((x - mx) ** 2 for x in xs)
+    vy = sum((y - my) ** 2 for y in ys)
+    if vx <= 0.0 or vy <= 0.0:
+        return float("nan")
+    return num / math.sqrt(vx * vy)
+
+
+def _png_chunk(kind: bytes, payload: bytes) -> bytes:
+    return (
+        struct.pack(">I", len(payload))
+        + kind
+        + payload
+        + struct.pack(">I", binascii.crc32(kind + payload) & 0xFFFFFFFF)
+    )
+
+
+def write_solid_png(path: str | Path, width: int, height: int, rgb: tuple[int, int, int]) -> None:
+    path = Path(path)
+    ensure_dir(path.parent)
+    raw = bytearray()
+    row = bytes(rgb) * width
+    for _ in range(height):
+        raw.append(0)
+        raw.extend(row)
+    ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
+    data = zlib.compress(bytes(raw), level=9)
+    with path.open("wb") as f:
+        f.write(b"\x89PNG\r\n\x1a\n")
+        f.write(_png_chunk(b"IHDR", ihdr))
+        f.write(_png_chunk(b"IDAT", data))
+        f.write(_png_chunk(b"IEND", b""))
+
+
+def write_npy_f4(path: str | Path, height: int, width: int, value: float) -> None:
+    path = Path(path)
+    ensure_dir(path.parent)
+    header = "{'descr': '<f4', 'fortran_order': False, 'shape': (%d, %d), }" % (height, width)
+    header_bytes = header.encode("latin1")
+    prefix_len = 6 + 2 + 2
+    padding = 16 - ((prefix_len + len(header_bytes) + 1) % 16)
+    header_bytes += b" " * padding + b"\n"
+    row = struct.pack("<" + "f" * width, *([float(value)] * width))
+    with path.open("wb") as f:
+        f.write(b"\x93NUMPY")
+        f.write(b"\x01\x00")
+        f.write(struct.pack("<H", len(header_bytes)))
+        f.write(header_bytes)
+        for _ in range(height):
+            f.write(row)

scripts/audit_quality.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from _common import read_json, write_csv
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Audit generated CM-EVS render artifacts.")
+    parser.add_argument("--render-dir", type=Path, required=True)
+    parser.add_argument("--metadata", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--limit", type=int, default=50)
+    return parser.parse_args()
+
+
+def has_magic(path: Path, magic: bytes) -> bool:
+    if not path.exists():
+        return False
+    with path.open("rb") as f:
+        return f.read(len(magic)) == magic
+
+
+def main() -> None:
+    args = parse_args()
+    selected_doc = read_json(args.metadata)
+    rows = []
+    for item in selected_doc.get("selected_viewpoints", [])[: args.limit]:
+        cid = str(item["candidate_id"])
+        rank = int(item["rank"])
+        stem = f"{rank:03d}_{cid}"
+        rgb = args.render_dir / f"{stem}_rgb.png"
+        depth = args.render_dir / f"{stem}_depth.npy"
+        pose = args.render_dir / f"{stem}_pose.json"
+        pose_ok = False
+        if pose.exists():
+            try:
+                read_json(pose)
+                pose_ok = True
+            except Exception:
+                pose_ok = False
+        rows.append(
+            {
+                "candidate_id": cid,
+                "rank": rank,
+                "rgb_exists": rgb.exists(),
+                "rgb_png_magic": has_magic(rgb, b"\x89PNG\r\n\x1a\n"),
+                "depth_exists": depth.exists(),
+                "depth_npy_magic": has_magic(depth, b"\x93NUMPY"),
+                "pose_exists": pose.exists(),
+                "pose_json_valid": pose_ok,
+                "passed": rgb.exists() and depth.exists() and pose_ok,
+            }
+        )
+    write_csv(args.output, rows)
+    print(f"Wrote {args.output}")
+
+
+if __name__ == "__main__":
+    main()