# Build It · 五步

一张照片 → 每个像素离相机多远 → 变成三维点。

---

## 代码只有两个文件

| 文件                               | 里面有什么             |
| -------------------------------- | ----------------- |
| [code/main.py](code/main.py)     | 五步的全部函数           |
| [code/models.py](code/models.py) | 加载真模型，只有 Step 5 用 |

---

## 先跑起来：不用数据、不用权重

要 numpy 和 torch。两条命令：

```bash
cd code
python demo.py
```

会看到：

```
对齐后  AbsRel = 0.0573   delta<1.25 = 0.9771
还原出  a = 0.778   b = 0.496   （造预测时设的是 a=0.8, b=0.4）
点云 9216 个点，已写到当前目录的 out.ply
```

`code/demo.py` 就是下面这十几行，五步全在里面：

```python
from main import (synthetic_scene, synth_pred_from_gt, align_scale_shift,
                  abs_rel_error, delta_accuracy, point_cloud_to_xyz_rgb, write_ply)

rgb, gt, meta = synthetic_scene()              # Step 4：深度有精确真值的小场景
pred = synth_pred_from_gt(gt)                  # 假装它是"相对深度模型"的输出（不是米）

aligned, a, b = align_scale_shift(pred, gt, return_coeffs=True)      # Step 2
print(abs_rel_error(aligned, gt), delta_accuracy(aligned, gt))       # Step 1
print(a, b)

pts, cols = point_cloud_to_xyz_rgb(gt, rgb)    # Step 3
write_ply("out.ply", pts, cols)
```

跑出来的 `out.ply` 用 CloudCompare 或 MeshLab 打开，转一圈。

下面五步，讲的就是这段代码里的每一块。

---

## Step 1 · 两把尺子

```
AbsRel  = mean( |d_pred − d_gt| / d_gt )                 越低越好
δ<1.25  = max(pred/gt, gt/pred) < 1.25 的像素比例         越高越好
```

**为什么两个都要**：`AbsRel` 是均值，一个离群像素就能拉爆。

```
pred = [100, 2]   gt = [1, 2]
不 mask：AbsRel = 49.5      mask 掉第一个：AbsRel = 0.0
```

**两个定义细节**：阈值是**严格小于**（刚好等于 1.25 不算通过）；mask 的语义是 **`True` = 保留**。

`apply_mask()` 会自动排除无效像素：真值里 `<=0`、`NaN`、`Inf`、超量程的都丢。
预测值只丢 `NaN`/`Inf`，**不按符号筛**——相对深度模型的原始输出可以是负数，按符号筛会把一大片有效数据整片丢掉。

---

## Step 2 · 先校准，再量

相对深度没有单位，每张图自己一套刻度。直接跟米比，**算出来的是刻度差，不是模型误差**。

所以先拟合 `a·pred + b = target`：

```
a = Cov(p, t) / Var(p)          b = mean(t) − a·mean(p)
```

上面那段代码里 `a≈0.78, b≈0.50` 就是它算出来的——场景是故意按 `a=0.8, b=0.4` 造的，对得上。

**为什么只用一个尺度因子不够**：如果预测只差尺度（`pred = 3·gt`），比值 `gt/pred` 是常数，一个 `s` 就够。如果还带平移（`pred = gt + 2`），比值 `gt/(gt+2)` **随 gt 变**，没有任何一个 `s` 能同时校正所有像素。所以必须两个自由度。

**对齐修刻度，不修精度**：预测里加了噪声，对齐完噪声还在。上面 `AbsRel` 不是 0，就是因为造预测时加了噪声。

---

## Step 3 · 深度图变点云

三行，全部内容：

```
X = (u − cx) · d / fx
Y = (v − cy) · d / fy
Z = d
```

没有标定就假设一个视场角：`intrinsics_from_fov(H, W, 60)`。注意主点是 `(W−1)/2`，`W=640` 时是 **319.5**，不是 320。

**怎么确认写对了**：做往返检验——像素 → 3D → 投影回像素，看回没回原地。

它抓的是**实现错误**（忘了减 `cx`、u/v 轴转置）。它**抓不到内参本身错**：正反都用同一套错内参时，照样自洽。

![室内照片、深度图与点云](figures/pointcloud_indoor.png)

**但记住**：这张点云的内参是假设的。所以**形状对、尺度未知**——转起来像个房间是真的，"那面墙在三米"是假的。只能看，不能量。

---

## Step 4 · 为什么要有合成场景

因为"模型跑通了"和"评测代码写对了"是两件事。真实数据上没有绝对可靠的真值，你分不清那个误差是模型的还是你的代码的。

合成场景的深度是**几何算出来的**，所以能精确核对：真值跟自己比必须是 0，方块必须恒 1.5 m，后墙必须真的存在，地板必须越靠下越近。

![合成场景四格](figures/synthetic_scene.png)

看 **colorbar**：右上真值是 **1.5–5.0 m**；左下那个"模型输出"只有 **1.3–3.3**，跟真值不是一个刻度——这就是 Step 2 要处理的尺度错位；右下过了对齐之后变成 **1.5–5.0**，对上了。

把同一个场景用 Step 3 的公式摊成点云，就是这个样子：

![合成场景的点云](figures/synthetic_pointcloud.png)

右图能直接核对三件事：**后墙是一整块平面**（深度恒 5.0），**地板是一个斜面**（越靠下越近），**红色方块悬在 1.5 m**——墙上那块矩形空白就是方块挡住的位置，那里的深度是方块的 1.5，不是墙的 5.0。

因为真值是几何算出来的，这些都能一眼对上。真实照片上没有这种"标准答案"，所以先拿合成场景把代码钉死。

### 课程原文那段

`code/main.py` 里还留着一个 `synthetic_depth()`，逐字照抄课程原文：

```python
def synthetic_depth(size=96):
    yy, xx = np.meshgrid(np.arange(size), np.arange(size), indexing="ij")
    depth = 1.0 + (yy / size) * 4.0
    mask = (np.abs(xx - size / 2) < size / 6) & (np.abs(yy - size * 0.6) < size / 6)
    depth[mask] = 2.0
    return depth.astype(np.float32)

gt = torch.from_numpy(synthetic_depth(96))
pred = gt + 0.3 * torch.randn_like(gt)
aligned = align_scale_shift(pred, gt)
print(abs_rel_error(pred, gt), abs_rel_error(aligned, gt))
```

留着它，是因为它跟上面那个 `synthetic_scene()` 有三处不一样，每一处都值得知道。

**一、地板方向是反的。** 这段上沿 1.0 m、下沿 4.958 m。真实地面从站着的高度看，画面**下沿最近**。

**二、线性梯度不是相机看到的样子。** 针孔相机看地面，深度对行号是 `h·fy/(v−cy)`，一条双曲线，不是直线。

**三、`pred = gt + 0.3·randn` 里没有尺度差也没有平移差**，所以 Step 2 的对齐几乎无事可做。同一个场景，两种造预测的方式，对齐前后：

| 怎么造 pred | AbsRel | δ<1.25 |
|---|---|---|
| 课程：`gt + 0.3·randn` | 0.1014 → 0.0987 | 0.8962 → 0.9095 |
| 副本：先按 a=0.8、b=0.4 拧掉，再加同样的噪声 | 0.1403 → 0.0800 | 0.8537 → 0.9481 |

第一行几乎没动——本来就没东西可对齐。第二行才是 Step 2 真正在干的事。

**所以**：跑课程那段能看到数字，但看不到"对齐"这件事的意义。要演示 Step 2，得用 `synth_pred_from_gt()`。

---

## Step 5 · 真模型（要权重）

```python
from models import load_da_v2
depth = load_da_v2(模型目录)(img)     # img 是 PIL.Image，depth 是 (H, W)
```

**权重已经放在 `data/models/DA-V2-Small/` 里了，你只需要加一张照片**——随便一张 jpg 或 png 丢进 `data/`，然后：

```bash
python main.py --steps 5
```

CPU 上大约 0.6 秒出结果，深度图写到 `outputs/figures/`。没照片或没权重都不报错，会打印"跳过"然后正常结束。

**这个输出不是米。** Depth Anything V2 输出的是**逆深度**：**数值越大越近**。

![照片与深度图](figures/depth_map_example.png)

桌面前沿最蓝（最近），后墙橙红（较远）。colorbar 上的 1.0–4.5 只是这张图内部的相对数值，**不能跟别的深度图比亮度**——每张图各自归一化。要比，先做 Step 2 的对齐，而且得有真值。

---

## 三句话

1. 模型给的是**顺序**不是米 → 报数字之前先对齐，而且要有真值。
2. 点云只要三行公式 → 但尺度来自你假设的内参，只能看不能量。
3. 评测代码要先立起来 → 合成场景的精确真值就是干这个的。
