# Benchmark100 多视角非正交 Mesh 评估集中文交接说明

这份文件是给另一个 Codex 或研究同学接手使用的中文入口。评估集已经准备在本机磁盘上，核心目标是比较不同方法在“输入 2/4/6/8 张非正交图片，输出 3D mesh，再用 20 个保留测试视角评估”的表现。

## 一句话入口

主清单文件：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/benchmark_manifest_v0.json
```

渲染好的输入/测试视角：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/rendered_benchmark_v0
```

各方法生成的 100 个 mesh：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/method_eval
```

可视化网页：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/report/benchmark100_case_browser_zh.html
http://38.94.129.6:8768/report/benchmark100_case_browser_zh.html
```

网页版中文交接说明：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/report/benchmark100_evalset_handoff_zh.html
http://38.94.129.6:8768/report/benchmark100_evalset_handoff_zh.html
```

## 数据集内容

本评估集名为 `nonorthogonal_mesh_benchmark_v0`，创建日期为 2026-07-16，固定随机种子为 `20260716`。

对象组成：

- 共 100 个对象。
- 50 个来自 GSO。
- 50 个来自 Toys4K。
- 每个对象都有 GT mesh。
- 每个对象都有 2、4、6、8 四组非正交输入视角。
- 每个对象都有 20 个独立保留测试视角。

相机策略：

- 输入视角不是 TRELLIS 原本偏好的正交视图，而是随机的非正交、类似 turntable 的透视相机。
- 测试视角独立生成，不和输入视角重合。
- 渲染前把 mesh 归一化到单位包围球。
- 输入图和测试图默认分辨率是 512。

## 主清单结构

读取主清单：

```python
import json
from pathlib import Path

manifest_path = Path("/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/benchmark_manifest_v0.json")
manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
objects = manifest["objects"]
```

注意：这个文件里对象列表字段叫 `objects`，不是 `cases`。如果代码写成 `manifest["cases"]`，会读不到数据。

每个 object 的关键字段：

- `benchmark_id`：评估集内部 ID，例如 `gso_000`、`toys4k_034`。
- `dataset`：`GSO` 或 `Toys4K`。
- `object_id`：原始数据集对象名。
- `gt_mesh`：GT mesh 的原始来源，有些是 `zip://...!/...` 形式。
- `has_gt_mesh`：是否有 GT mesh，本评估集应为 true。
- `input_protocols`：输入视角配置，键是 `"2"`、`"4"`、`"6"`、`"8"`。
- `eval_views`：20 个保留测试视角配置。

## 输入图和测试图在哪里

每个对象的渲染目录格式：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/rendered_benchmark_v0/<benchmark_id>
```

例如：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/rendered_benchmark_v0/gso_000
```

其中：

- `input_2/000.png`、`input_2/001.png`：2 视角输入。
- `input_4/*.png`：4 视角输入。
- `input_6/*.png`：6 视角输入。
- `input_8/*.png`：8 视角输入。
- `eval_20/*.png`：20 个测试视角 GT 渲染图。
- 每个目录下的 `transforms.json` 保存相机参数。

## GT mesh 在哪里

GSO 原始清单里的 GT mesh 可能写成：

```text
zip:///data/jiachen/GSO/google_scanned_objects.zip!.../meshes/model.obj
```

这种 `zip://` 路径不能直接被普通 OBJ 加载器读取。为了方便评测，已经有解压后的可直接读取版本，通常在：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/rendered_benchmark_v0/_extracted_gso/<object_id>/meshes/model.obj
```

Toys4K 的评测用 OBJ 通常在：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/rendered_benchmark_v0/_extracted_gso/_sanitized_ply/<benchmark_id>.obj
```

如果想稳定拿到当前评测实际使用的 GT mesh 路径，优先读：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/rendered_benchmark_v0/render_summary.json
```

这里每条记录有 `benchmark_id`、`protocol`、`mesh_path`、`output`、`frames` 等字段。

## 各方法输出 mesh 在哪里

方法输出根目录：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/method_eval
```

常用方法目录：

- `trellis_protocol2_all100`
- `trellis_protocol4_all100`
- `trellis_protocol6_all100`
- `trellis_protocol8_all100`
- `trellis2_protocol2_all100`
- `trellis2_protocol4_all100`
- `trellis2_protocol6_all100`
- `trellis2_protocol8_all100`
- `reconviagen_protocol2_all100`
- `reconviagen_protocol4_all100`
- `reconviagen_protocol6_all100`
- `reconviagen_protocol8_all100`
- `tripo_direct_protocol2_all100`
- `tripo_direct_protocol4_all100`
- `tripo_direct_protocol6_all100`
- `tripo_direct_protocol8_all100`
- `tripo_gpt_ortho_protocol2_all100`
- `tripo_gpt_ortho_protocol4_all100`
- `tripo_gpt_ortho_protocol6_all100`
- `tripo_gpt_ortho_protocol8_all100`

单个输出 mesh 的路径模式：

```text
<method_dir>/<benchmark_id>_input<N>/mesh_raw.obj
```

例如：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/method_eval/trellis2_protocol4_all100/gso_000_input4/mesh_raw.obj
```

每个 case 旁边通常还有：

```text
result.json
```

里面记录了 mesh 路径、耗时、方法元信息等。

## 评测结果在哪里

完整 2/4/6/8 输入视角矩阵聚合：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/method_eval/benchmark100_full_matrix_aggregate.json
```

早期 2/4 输入聚合：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/method_eval/benchmark100_eval_aggregate.json
```

单方法逐 case 评测：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/method_eval/<method_dir>/geometry_eval.json
```

如果已经补过拓扑指标，常见文件名为：

```text
geometry_eval_topology.json
```

## 当前评测指标

几何指标：

- `chamfer_mean`：预测 mesh 和 GT mesh 双向最近邻距离均值，越低越好。
- `hausdorff_approx`：近似最大表面误差，越低越好。
- `precision_1pct/2pct/5pct/10pct`：预测表面点有多少落在 GT 附近，越高越好。
- `recall_1pct/2pct/5pct/10pct`：GT 表面点有多少被预测覆盖，越高越好。
- `fscore_1pct/2pct/5pct/10pct`：precision 和 recall 的调和平均，越高越好。
- `bbox_diag_ratio`：预测和 GT 尺度是否接近。
- `surface_area_ratio`、`volume_ratio_abs`：表面积和体积尺度关系。

拓扑/复杂度指标：

- `watertight`：是否水密，越高越好。
- `winding_consistent`：面朝向是否一致，越高越好。
- `topology_valid`：拓扑是否有效，越高越好。
- `boundary_edges`：边界边数量，越低越好。
- `nonmanifold_edges`：非流形边数量，越低越好。
- `pred_faces`、`pred_vertices`：面片数和顶点数，通常越低越轻量，但不能脱离几何质量单独看。

图像视角指标计划中包括：

- PSNR
- SSIM
- LPIPS
- DreamSim 或 CLIP similarity

## “为什么加载不了”的常见原因

1. 把主清单里的 `zip://...!...` 当作普通路径传给 OBJ 加载器。
   - 解决：用 `_extracted_gso` 下的解压后路径，或从 `render_summary.json` 读取实际 `mesh_path`。

2. 用浏览器直接打开本地 HTML，导致 OBJ/JS 资源因为路径或跨域策略加载失败。
   - 解决：使用正在运行的报告服务访问，例如 `http://38.94.129.6:8768/report/benchmark100_case_browser_zh.html`。

3. 从另一个工作目录运行脚本时，相对路径失效。
   - 解决：优先使用本文列出的绝对路径。

4. 代码假设字段叫 `cases`。
   - 解决：主清单对象列表字段是 `objects`；方法输出 summary 里才常见 `cases`。

5. OBJ 材质/贴图路径没有跟着移动。
   - 解决：不要单独搬一个 OBJ 文件；如果要复制 GT mesh，连同同级 `materials`、`meshes`、`textures` 或相关贴图一起复制。方法输出的 `mesh_raw.obj` 通常是纯几何，较少依赖贴图。

6. TRELLIS.2 的 raw OBJ 太大，浏览器首次加载慢或看起来卡住。
   - 解决：先用 TRELLIS 或 ReconViaGen 的 OBJ 验证 viewer 正常，再切 TRELLIS.2；必要时用简化 mesh 或只打开单个 case，不要一次性批量加载。

7. 报告服务没有运行，外部 URL 会打不开。
   - 解决：在本机检查 8768 端口是否有报告服务；如果没有，从 `/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs` 作为根目录启动静态服务。

## OBJ 加载失败时的最小排查顺序

先确认网页服务是否通：

```bash
python3 - <<'PY'
import urllib.request
url = "http://38.94.129.6:8768/report/benchmark100_case_browser_zh.html"
with urllib.request.urlopen(url, timeout=5) as resp:
    print(resp.status, resp.getheader("content-type"))
PY
```

再确认某个 OBJ 文件真实存在：

```bash
test -f /home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/method_eval/trellis2_protocol4_all100/gso_000_input4/mesh_raw.obj
```

最后确认网页里的相对 OBJ URL 能从服务读到：

```bash
python3 - <<'PY'
import urllib.request
url = "http://38.94.129.6:8768/data_survey/method_eval/trellis2_protocol4_all100/gso_000_input4/mesh_raw.obj"
with urllib.request.urlopen(url, timeout=10) as resp:
    print(resp.status, resp.getheader("content-type"), resp.read(32))
PY
```

如果前两个成功、第三个失败，通常是报告服务根目录不对；当前页面假设服务根目录是：

```text
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs
```

## 给另一个 Codex 的建议提示词

可以直接把下面这段发给另一个 Codex：

```text
请使用本机已有的 Benchmark100 多视角非正交 mesh 评估集。主清单在：
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/benchmark_manifest_v0.json

注意主清单对象列表字段是 objects，不是 cases。每个对象有 2/4/6/8 四组非正交输入视角，渲染图在：
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/rendered_benchmark_v0/<benchmark_id>/input_<N>

20 个测试视角在：
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/rendered_benchmark_v0/<benchmark_id>/eval_20

各方法生成的 mesh 在：
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/method_eval/<method_dir>/<benchmark_id>_input<N>/mesh_raw.obj

完整评测聚合结果在：
/home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/method_eval/benchmark100_full_matrix_aggregate.json

如果 GT mesh 的路径是 zip:// 形式，不要直接用普通 OBJ loader 读取；优先用 rendered_benchmark_v0/render_summary.json 中的 mesh_path 或 _extracted_gso 目录下的解压版本。

请先做三步自检：
1. 读取 benchmark_manifest_v0.json，确认 objects 数量是 100。
2. 检查任意一个 case 的 input_2 和 eval_20 图片数量。
3. 检查任意一个方法输出 mesh_raw.obj 是否存在，例如 trellis2_protocol4_all100/gso_000_input4/mesh_raw.obj。

如果要看网页，请打开中文浏览器：
http://38.94.129.6:8768/report/benchmark100_case_browser_zh.html
```

## 快速自检

可以用下面几条检查数据是否还在：

```bash
test -f /home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/benchmark_manifest_v0.json
test -d /home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/rendered_benchmark_v0
test -d /home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/method_eval/trellis2_protocol4_all100
test -f /home/jiachen/TRELLIS/experiments/nonorthogonal_gpt_orthoview/outputs/data_survey/method_eval/benchmark100_full_matrix_aggregate.json
```