first commit

.gitattributes

@@ -33,3 +33,5 @@ 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
+*.axmodel filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,2 @@
+results/**
+datasets/**

README.md

@@ -1,3 +1,104 @@
 ---
 license: mit
 ---
+
+# DepthART (AX650 Relative Depth Estimation)
+
+DepthART is a family of relative depth estimation models based on selective state
+spaces (Selective Scan). This repository provides the ONNX model of the `small / 448`
+variant, an `axmodel` compiled for **AX650**, and tools for host ONNX inference, board
+axmodel inference, and model rewriting.
+
+The model outputs **affine-invariant relative depth**: larger values mean closer,
+smaller values mean farther. It does not directly produce metric depth; align it with
+ground truth depth using a global scale/offset before use.
+
+## Single-image result
+
+Left: input image; right: relative depth output by the model (INFERNO colormap,
+stretched to the 2%–98% percentile range).
+
+![DepthART single-image inference result](host_depth.jpg)
+
+## Repository contents
+
+| Path | Description |
+| --- | --- |
+| `models/relative_s_448_default.onnx` | Original FP32 ONNX model, containing the custom op `com.depthart::SelectiveScan` |
+| `models/relative_s_448_default_ax650.axmodel` | Compiled AX650 model |
+| `src/infer/depthart_infer_onnx.py` | Host ONNX inference (rewrites `SelectiveScan` automatically) |
+| `src/infer/depthart_infer_axmodel.py` | AX650 board axmodel inference (standalone script) |
+| `src/tool/depthart_export_axonnx.py` | Rewrites `SelectiveScan` into a pure ONNX subgraph that pulsar2 can compile |
+| `src/tool/compare_onnx_axmodel.py`, `compare_depth_outputs.py` | Numerical comparison of outputs from different backends |
+| `src/tool/evaluate_nyu654_depth.py` | Accuracy evaluation on the NYU Depth V2 eigen test split |
+| `host.jpg`, `host_depth.jpg` | Single-image example input and side-by-side visualization result |
+
+## Model interface
+
+### ONNX
+
+| Item | Value |
+| --- | --- |
+| Input | `image` `[1, 3, 448, 448]` float32, NCHW, RGB |
+| Output | `depth` `[1, 1, 448, 448]` float32, relative depth (larger = closer) |
+
+## AX650 board inference
+
+The script `src/infer/depthart_infer_axmodel.py` does not depend on other scripts in
+the repository. For deployment, just place the following files in the same directory
+on the board:
+
+```text
+relative_s_448_default_ax650.axmodel
+depthart_infer_axmodel.py
+images or image directory to test
+```
+
+Board runtime requires `axengine`.
+
+### Single-image validation
+
+```bash
+python3 depthart_infer_axmodel.py \
+    --axmodel relative_s_448_default_ax650.axmodel \
+    --image ./host.jpg \
+    --output ./results/ax_single
+```
+
+Outputs `results/ax_single/host_depth.jpg` (side-by-side visualization) and
+`host_depth.npy`; the console prints depth statistics, NPU inference time, CPU
+processing time, and per-stage timings. A single image is the first inference and
+includes runtime first-execution overhead; use dataset mode for performance evaluation.
+
+### Dataset inference
+
+By default, fast mode only measures `read / preprocess / npu` and skips depth
+restoration, visualization, and file writing, for performance testing:
+
+```bash
+python3 depthart_infer_axmodel.py \
+    --axmodel relative_s_448_default_ax650.axmodel \
+    --dataset ./images \
+    --output ./results/board
+```
+
+Full output (depth restoration, visualization, summary NPZ), for accuracy evaluation:
+
+```bash
+python3 depthart_infer_axmodel.py \
+    --axmodel relative_s_448_default_ax650.axmodel \
+    --dataset ./images \
+    --output ./results/board_full \
+    --full-output \
+    --dump-npz ./results/board_full/raw_outputs.npz
+```
+
+Image-by-image comparison against the host ONNX baseline summary NPZ:
+
+```bash
+python3 depthart_infer_axmodel.py \
+    --axmodel relative_s_448_default_ax650.axmodel \
+    --dataset ./images \
+    --output ./results/board_check \
+    --ref-npz ./results/onnx_full/raw_outputs.npz
+```

config.json

@@ -0,0 +1,53 @@
+{
+  "model_type": "ONNX",
+  "npu_mode": "NPU3",
+  "input": "onnx/relative_s_448_default_axonnx_t4.onnx",
+  "output_dir": "./output_axonnx_t4",
+  "output_name": "relative_s_448_default_ax650_t4.axmodel",
+  "quant": {
+    "input_configs": [
+      {
+        "tensor_name": "DEFAULT",
+        "calibration_dataset": "/data/datasets/coco2017val_500_calibration_dataset.tar",
+        "calibration_size": 8,
+        "calibration_mean": [
+          123.675,
+          116.28,
+          103.53
+        ],
+        "calibration_std": [
+          58.395,
+          57.12,
+          57.375
+        ]
+      }
+    ],
+    "calibration_method": "Percentile",
+    "precision_analysis": true,
+    "precision_analysis_method": "EndToEnd",
+    "conv_bias_data_type": "FP32",
+    "layer_configs": [
+      {
+        "start_tensor_names": [
+          "DEFAULT"
+        ],
+        "end_tensor_names": [
+          "DEFAULT"
+        ],
+        "data_type": "U16"
+      }
+    ]
+  },
+  "input_processors": [
+    {
+      "tensor_name": "DEFAULT",
+      "tensor_format": "RGB",
+      "src_format": "RGB",
+      "src_dtype": "U8",
+      "src_layout": "NCHW"
+    }
+  ],
+  "compiler": {
+    "check": 0
+  }
+}

models/relative_s_448_default.onnx

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

models/relative_s_448_default_ax650.axmodel

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

src/infer/depthart_infer_axmodel.py

@@ -0,0 +1,639 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+DepthART 相对深度 axmodel 板端推理（AX650 + axengine）。
+
+随板部署文件（建议放在同一目录）：
+    relative_s_448_default_ax650.axmodel
+    depthart_infer_axmodel.py
+    待测图片或图片目录
+
+模型接口（以运行时 get_inputs/get_outputs 实际返回为准）：
+    input  [1, 3, 448, 448] uint8 NCHW RGB
+    depth  [1, 1, 448, 448] float32 仿射不变相对深度，数值越大表示越近
+
+预处理按编译配置 config_axonnx.json 的 input_processors 执行：tensor_format=RGB、
+src_dtype=U8、mean/std 为 0-255 域的 ImageNet 值，归一化由编译前端完成。因此板端
+送 0-255 原始 RGB 像素即可，不要再做 /255 或减均值。若 axmodel 输入为 FP32（编译
+时未配置 input_processors），脚本默认改为 /255 + ImageNet mean/std，与 ONNX 基准
+一致；可用 --input-norm 显式覆盖。
+
+深度还原使用与 ONNX 脚本一致的 bilinear + align_corners=True（linspace + remap），
+保证板端与开发机基准可以逐像素对比。
+
+板端计时分为 NPU（session.run）和 CPU（读取、预处理、输出提取/校验、后处理、
+可视化、写盘），两者分别统计，避免弱 CPU 上的后处理掩盖真实 NPU 性能。
+
+单图模式：打印深度统计、NPU/CPU 各阶段耗时，保存并排可视化，不产出评测文件。
+数据集模式：tqdm 进度 + npu_timing.json；默认快速模式只统计读取/预处理/NPU，
+--full-output 才做深度还原、可视化、原始 NPZ 和图片写盘。
+
+板端用法（所有路径均为必填）：
+    # 单图验证
+    python3 depthart_infer_axmodel.py --axmodel relative_s_448_default_ax650.axmodel \
+        --image ./host.jpg --output ./results/ax_single
+
+    # 数据集快速性能模式
+    python3 depthart_infer_axmodel.py --axmodel relative_s_448_default_ax650.axmodel \
+        --dataset ./images --output ./results/board
+
+    # 数据集完整输出（原始深度 NPZ、可视化和大图深度）
+    python3 depthart_infer_axmodel.py --axmodel relative_s_448_default_ax650.axmodel \
+        --dataset ../../test_depth --output ./results/board_full --full-output
+
+    # 与开发机 ONNX 基准对比（--ref-npz 指向 ONNX 脚本的汇总 NPZ）
+    python3 depthart_infer_axmodel.py --axmodel relative_s_448_default_ax650.axmodel \
+        --dataset ../../test_depth --output ./results/board_check --ref-npz ./onnx_npz
+
+开发机用法（仅用于脚本语法/参数检查，实际推理需要板端 axengine）：
+    ../../venv/bin/python src/infer/depthart_infer_axmodel.py \
+        --axmodel output_axonnx3/relative_s_448_default_ax650.axmodel \
+        --dataset /path/images --output results/axmodel_board --limit 50
+
+诊断：
+    --debug     打印输入/输出 tensor 的 shape、dtype、min、max、mean、nan 计数
+    --dump-npz  单图时为 .npz 文件路径；数据集时为汇总 .npz 文件路径，
+                保存 names/depths/original_sizes，不再每张图一个小文件
+    --npz-chunk 数据集模式下每 N 张切一个文件（xxx_0000.npz 等），
+                0 表示全部写入同一个文件
+    --ref-npz   单图时为参考 .npz，数据集时为参考汇总 .npz（按 names 匹配），
+                报告 max/mean/p99 绝对误差、cosine 以及 scale-shift 对齐后误差
+"""
+
+import argparse
+import json
+import logging
+import time
+from pathlib import Path
+
+import cv2
+import numpy as np
+from tqdm import tqdm
+
+MEAN = np.array([0.485, 0.456, 0.406], dtype=np.float32)
+STD = np.array([0.229, 0.224, 0.225], dtype=np.float32)
+EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.tif', '.tiff'}
+STAGES = ('read', 'preprocess', 'npu', 'diagnostics',
+          'postprocess', 'visualize', 'write', 'total')
+
+
+def meta_type(meta):
+    value = getattr(meta, 'type', None)
+    if value is None:
+        value = getattr(meta, 'dtype', '')
+    return str(value).lower()
+
+
+def input_spec(meta):
+    """从运行时输入元信息推导尺寸、layout 和 dtype，不依赖固定名称。"""
+    try:
+        shape = [int(v) for v in meta.shape]
+    except (TypeError, ValueError):
+        raise ValueError(f'输入必须是静态 4D NCHW/NHWC: {meta.name} {meta.shape}')
+    if len(shape) != 4 or any(v <= 0 for v in shape):
+        raise ValueError(f'输入必须是静态 4D NCHW/NHWC: {meta.name} {meta.shape}')
+    if shape[0] != 1:
+        raise ValueError(f'仅支持 batch=1: {meta.name} {meta.shape}')
+    if shape[1] == 3:
+        layout, size = 'NCHW', (shape[2], shape[3])
+    elif shape[3] == 3:
+        layout, size = 'NHWC', (shape[1], shape[2])
+    else:
+        raise ValueError(f'输入必须含 3 通道: {meta.name} {meta.shape}')
+    type_name = meta_type(meta)
+    if 'float16' in type_name or 'fp16' in type_name:
+        dtype = np.float16
+    elif 'float' in type_name or 'fp32' in type_name:
+        dtype = np.float32
+    elif 'uint8' in type_name or type_name.endswith('u8'):
+        dtype = np.uint8
+    elif 'int8' in type_name or type_name.endswith('s8'):
+        dtype = np.int8
+    else:
+        raise ValueError(f'不支持的输入类型: {meta.name} {type_name!r}')
+    return size, layout, dtype
+
+
+def preprocess(image, size, color_order, layout, dtype, norm_mode):
+    """按编译契约生成输入 tensor。
+
+    uint8 直送路径沿用官方 axmodel 流程，在 uint8 域直接 resize；ImageNet
+    归一化路径严格按 ONNX 基准的顺序（float 域 /255 -> resize -> mean/std）。
+    """
+    target_h, target_w = size
+    if color_order == 'rgb':
+        image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+    if norm_mode == 'imagenet':
+        canvas = image.astype(np.float32) / 255.0
+        canvas = cv2.resize(canvas, (target_w, target_h),
+                            interpolation=cv2.INTER_CUBIC)
+        canvas = (canvas - MEAN) / STD
+    elif dtype != np.uint8:
+        canvas = cv2.resize(image.astype(np.float32), (target_w, target_h),
+                            interpolation=cv2.INTER_CUBIC)
+    else:
+        canvas = cv2.resize(image, (target_w, target_h),
+                            interpolation=cv2.INTER_CUBIC).astype(np.float32)
+    if dtype == np.uint8:
+        canvas = np.clip(np.rint(canvas), 0, 255).astype(np.uint8)
+    elif dtype == np.int8:
+        raise ValueError('当前脚本不支持 INT8 输入：缺少反量化 scale/zero-point')
+    else:
+        canvas = canvas.astype(dtype)
+    tensor = canvas.transpose(2, 0, 1) if layout == 'NCHW' else canvas
+    return np.ascontiguousarray(tensor[None])
+
+
+def select_output(outputs, metas, input_size):
+    """axmodel 输出名可能被编译器改写：先按名字，再按 shape 回退。"""
+    if not isinstance(outputs, (list, tuple)):
+        outputs = [outputs]
+    if len(outputs) != len(metas):
+        raise ValueError(f'输出数量不一致: run 返回 {len(outputs)}，'
+                         f'接口声明 {len(metas)}')
+    for index, meta in enumerate(metas):
+        if 'depth' in str(meta.name).lower():
+            return outputs[index], str(meta.name)
+    candidates = []
+    for index, array in enumerate(outputs):
+        shape = np.asarray(array).shape
+        if len(shape) == 4 and shape[1] == 1 and tuple(shape[2:]) == tuple(input_size):
+            candidates.append(index)
+        elif len(shape) == 3 and tuple(shape[1:]) == tuple(input_size):
+            candidates.append(index)
+    if len(candidates) != 1:
+        actual = [(m.name, np.asarray(o).shape) for m, o in zip(metas, outputs)]
+        raise ValueError(f'无法按 name 或 shape 唯一匹配 depth 输出；实际输出: {actual}')
+    return outputs[candidates[0]], str(metas[candidates[0]].name)
+
+
+def read_depth(raw, input_size):
+    array = np.asarray(raw)
+    if array.ndim == 4 and array.shape[1] == 1:
+        array = array[0]
+    if array.ndim == 3 and array.shape[0] == 1:
+        array = array[0]
+    if array.shape != tuple(input_size):
+        raise ValueError(f'depth 输出无效: shape={array.shape}，'
+                         f'期望 {tuple(input_size)}')
+    if not np.issubdtype(array.dtype, np.floating):
+        raise ValueError(f'depth 输出应为浮点，实际 dtype={array.dtype}，'
+                         '整数输出需要已知反量化参数')
+    array = array.astype(np.float32, copy=False)
+    if not np.isfinite(array).all():
+        raise ValueError('depth 输出包含 nan/inf')
+    if float(array.std()) < 1e-6:
+        logging.warning('depth 输出近似常数（std=%.3g）：请检查输入归一化/颜色顺序'
+                        '是否与编译配置的 input_processors 一致。', float(array.std()))
+    return np.ascontiguousarray(array)
+
+
+def restore_depth(depth, original_size):
+    """按官方推理的 bilinear + align_corners=True 还原到原图尺寸。"""
+    height, width = original_size
+    src_h, src_w = depth.shape
+    if (src_h, src_w) == (height, width):
+        return depth.copy()
+    xs = np.linspace(0.0, src_w - 1, width, dtype=np.float32)
+    ys = np.linspace(0.0, src_h - 1, height, dtype=np.float32)
+    map_x, map_y = np.meshgrid(xs, ys)
+    return cv2.remap(depth, map_x, map_y, interpolation=cv2.INTER_LINEAR,
+                     borderMode=cv2.BORDER_REPLICATE)
+
+
+def visualize(image, depth):
+    finite = depth[np.isfinite(depth)]
+    low, high = np.percentile(finite, (2, 98))
+    value = np.clip((depth - low) / max(float(high - low), 1e-6), 0, 1)
+    colored = cv2.applyColorMap((value * 255).astype(np.uint8), cv2.COLORMAP_INFERNO)
+    panel = np.concatenate((image, colored), axis=1)
+    legend = np.full((56, panel.shape[1], 3), 255, dtype=np.uint8)
+    ramp = np.tile(np.linspace(0, 255, max(panel.shape[1] - 20, 1),
+                               dtype=np.uint8), (12, 1))
+    legend[5:17, 10:10 + ramp.shape[1]] = cv2.applyColorMap(ramp, cv2.COLORMAP_INFERNO)
+    cv2.putText(legend, f'Image | Relative depth (2-98%): {low:.3f} -> {high:.3f}',
+                (10, 42), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (30, 30, 30), 1, cv2.LINE_AA)
+    return np.concatenate((panel, legend), axis=0)
+
+
+def log_tensor(name, value):
+    logging.info('%s: shape=%s dtype=%s min=%.6g max=%.6g mean=%.6g nan=%d inf=%d',
+                 name, value.shape, value.dtype, float(np.min(value)),
+                 float(np.max(value)), float(np.mean(value)),
+                 int(np.isnan(value).sum()), int(np.isinf(value).sum()))
+
+
+def compare_arrays(depth, expected, source='', preprocessing=''):
+    expected = np.asarray(expected)
+    if expected.ndim == 4 and expected.shape[1] == 1:
+        expected = expected[0]
+    if expected.shape != depth.shape:
+        raise ValueError(f'参考 depth shape 不符: {expected.shape} vs {depth.shape} ({source})')
+    if not np.isfinite(expected).all():
+        raise ValueError(f'参考 depth 含 nan/inf: {source}')
+    actual64 = depth.astype(np.float64).ravel()
+    expected64 = expected.astype(np.float64).ravel()
+    diff = np.abs(actual64 - expected64)
+    cosine = float(np.dot(actual64, expected64)
+                   / (np.linalg.norm(actual64) * np.linalg.norm(expected64) + 1e-12))
+    # 相对深度存在全局 scale/offset 漂移，对齐后误差更能反映结构偏差。
+    slope, offset = np.polyfit(expected64, actual64, 1)
+    aligned = np.abs(actual64 - (slope * expected64 + offset))
+    metrics = {'cosine': cosine,
+               'max_abs': float(diff.max()),
+               'mean_abs': float(diff.mean()),
+               'p99_abs': float(np.percentile(diff, 99)),
+               'scale': float(slope), 'offset': float(offset),
+               'aligned_mean_abs': float(aligned.mean()),
+               'aligned_p99_abs': float(np.percentile(aligned, 99)),
+               'reference_preprocessing': preprocessing}
+    logging.info('参考对比: %s', metrics)
+    return metrics
+
+
+def compare_reference(depth, reference_path):
+    with np.load(reference_path, allow_pickle=False) as reference:
+        if 'depth' not in reference:
+            raise ValueError(f'参考 NPZ 缺少 depth: {reference_path}')
+        expected = np.asarray(reference['depth'])
+        preprocessing = (str(reference['preprocessing'])
+                         if 'preprocessing' in reference else '')
+    return compare_arrays(depth, expected, str(reference_path), preprocessing)
+
+
+def load_reference_dataset(path):
+    """读取汇总 NPZ，返回 {name: depth}。"""
+    path = Path(path)
+    if path.is_file():
+        with np.load(path, allow_pickle=False) as ref:
+            if 'depths' not in ref or 'names' not in ref:
+                raise ValueError(f'汇总 NPZ 需要 names/depths: {path}')
+            return {str(n): d for n, d in zip(ref['names'], ref['depths'])}
+    raise ValueError(f'数据集模式 --ref-npz 需要汇总 NPZ 文件: {path}')
+
+
+def preprocessing_description(color_order, norm_mode):
+    norm = ('imagenet' if norm_mode == 'imagenet' else 'raw-0-255')
+    return f'color={color_order}; resize=stretch; norm={norm}'
+
+
+def save_raw_npz(path, depth, original_size, input_size, color_order, norm_mode):
+    # 板端 CPU 弱，savez_compressed 的 DEFLATE 对 float32 收益极小却耗时明显，用未压缩保存。
+    np.savez(path, depth=depth,
+             original_size=np.array(original_size, dtype=np.int32),
+             input_size=np.array(input_size, dtype=np.int32),
+             preprocessing=preprocessing_description(color_order, norm_mode))
+
+
+def flush_dataset_npz(path, records, chunk_index, input_size, color_order, norm_mode):
+    """把缓冲区写成汇总 NPZ：names / depths / original_sizes。
+
+    板端弱 CPU 上 DEFLATE 对 float32 收益极小却耗时明显，这里保持未压缩。
+    chunk_index 为 None 时写入 path 本身，否则按 chunk 编号追加后缀。
+    """
+    if not records:
+        return
+    target = path if chunk_index is None else path.with_name(
+        f'{path.stem}_{chunk_index:04d}{path.suffix}')
+    target.parent.mkdir(parents=True, exist_ok=True)
+    np.savez(
+        target,
+        names=np.array([r[0] for r in records]),
+        depths=np.stack([r[1] for r in records]),
+        original_sizes=np.array([r[2] for r in records], dtype=np.int32),
+        input_size=np.array(input_size, dtype=np.int32),
+        preprocessing=preprocessing_description(color_order, norm_mode))
+
+
+def collect_images(dataset):
+    paths = sorted(p for p in dataset.rglob('*')
+                   if p.is_file() and p.suffix.lower() in EXTENSIONS)
+    if not paths:
+        raise ValueError(f'目录中没有图片: {dataset}')
+    return paths
+
+
+def summarize(samples):
+    result = {}
+    for stage in STAGES:
+        values = np.array([sample[stage] for sample in samples], dtype=np.float64)
+        result[stage] = {'mean_ms': float(values.mean()),
+                         'p50_ms': float(np.percentile(values, 50)),
+                         'p90_ms': float(np.percentile(values, 90)),
+                         'p99_ms': float(np.percentile(values, 99))}
+    return result
+
+
+def run_single(session, input_meta, output_metas, input_size, layout, dtype,
+               norm_mode, args):
+    stem = args.image.stem
+    timings = dict.fromkeys(STAGES, 0.0)
+    total_start = time.perf_counter()
+
+    start = time.perf_counter()
+    image = cv2.imread(str(args.image), cv2.IMREAD_COLOR)
+    if image is None:
+        raise ValueError(f'读取图片失败: {args.image}')
+    timings['read'] = (time.perf_counter() - start) * 1000
+
+    start = time.perf_counter()
+    tensor = preprocess(image, input_size, args.color_order, layout, dtype, norm_mode)
+    timings['preprocess'] = (time.perf_counter() - start) * 1000
+
+    start = time.perf_counter()
+    outputs = session.run(None, {input_meta.name: tensor})
+    timings['npu'] = (time.perf_counter() - start) * 1000
+
+    start = time.perf_counter()
+    raw, output_name = select_output(outputs, output_metas, input_size)
+    depth = read_depth(raw, input_size)
+    comparison = None
+    if args.debug:
+        log_tensor(input_meta.name, tensor)
+        log_tensor('depth', depth)
+    if args.ref_npz:
+        comparison = compare_reference(depth, args.ref_npz)
+    timings['diagnostics'] = (time.perf_counter() - start) * 1000
+
+    start = time.perf_counter()
+    restored = restore_depth(depth, image.shape[:2])
+    timings['postprocess'] = (time.perf_counter() - start) * 1000
+
+    start = time.perf_counter()
+    panel = visualize(image, restored)
+    timings['visualize'] = (time.perf_counter() - start) * 1000
+
+    start = time.perf_counter()
+    args.output.mkdir(parents=True, exist_ok=True)
+    image_path = args.output / f'{stem}_depth.jpg'
+    if not cv2.imwrite(str(image_path), panel, [cv2.IMWRITE_JPEG_QUALITY, 90]):
+        raise OSError(f'保存可视化失败: {image_path}')
+    np.save(str(args.output / f'{stem}_depth.npy'), restored)
+    npz_path = None
+    if args.dump_npz:
+        npz_path = Path(args.dump_npz)
+        npz_path.parent.mkdir(parents=True, exist_ok=True)
+        save_raw_npz(npz_path, depth, image.shape[:2], input_size,
+                     args.color_order, norm_mode)
+    timings['write'] = (time.perf_counter() - start) * 1000
+    timings['total'] = (time.perf_counter() - total_start) * 1000
+
+    cpu_ms = (timings['read'] + timings['preprocess'] + timings['diagnostics']
+              + timings['postprocess'] + timings['visualize'] + timings['write'])
+    logging.info('深度（模型分辨率）: min=%.4f max=%.4f mean=%.4f p50=%.4f',
+                 float(depth.min()), float(depth.max()), float(depth.mean()),
+                 float(np.percentile(depth, 50)))
+    logging.info('深度（原图分辨率）: min=%.4f max=%.4f mean=%.4f',
+                 float(restored.min()), float(restored.max()), float(restored.mean()))
+    logging.info('输出绑定: %s', output_name)
+    logging.info('NPU 推理: %.2f ms；CPU 处理: %.2f ms；端到端: %.2f ms'
+                 '（单图为首次推理，含运行时首次执行开销；性能请用数据集模式）',
+                 timings['npu'], cpu_ms, timings['total'])
+    logging.info('各阶段耗时: %s',
+                 '  '.join(f'{key}={value:.2f} ms' for key, value in timings.items()))
+    if comparison is not None:
+        logging.info('参考对比结果: %s', comparison)
+    logging.info('结果目录: %s（可视化 %s%s）', args.output, image_path.name,
+                 f'，原始 NPZ {npz_path.name}' if npz_path else '')
+
+
+def run_dataset(session, input_meta, output_metas, input_size, layout, dtype,
+                norm_mode, runtime_version, args):
+    images = collect_images(args.dataset)
+    if args.limit is not None:
+        images = images[:args.limit]
+    args.output.mkdir(parents=True, exist_ok=True)
+    full_output = args.full_output
+    if full_output:
+        logging.warning('--full-output: CPU 侧深度还原、可视化与写盘会拉高端到端耗时，'
+                        '不能只看 NPU 时间。')
+    else:
+        logging.info('数据集快速模式：只统计 read/preprocess/npu，'
+                     '跳过深度还原、可视化和结果写盘。')
+    ref_map = load_reference_dataset(args.ref_npz) if args.ref_npz else None
+    preprocessing = preprocessing_description(args.color_order, norm_mode)
+    dump_path = Path(args.dump_npz) if args.dump_npz else None
+    if dump_path is not None and dump_path.is_dir():
+        raise ValueError('数据集模式 --dump-npz 请传 .npz 文件路径，'
+                         '不再按目录为每张图生成小文件')
+    dump_records, dump_chunk = [], 0
+
+    first = cv2.imread(str(images[0]), cv2.IMREAD_COLOR)
+    if first is None:
+        raise ValueError(f'读取图片失败: {images[0]}')
+    warm = preprocess(first, input_size, args.color_order, layout, dtype, norm_mode)
+    warmup_ms = 0.0
+    if args.warmup:
+        start = time.perf_counter()
+        for _ in range(args.warmup):
+            session.run(None, {input_meta.name: warm})
+        warmup_ms = (time.perf_counter() - start) * 1000
+
+    samples = []
+    sample_info = []
+    for path in tqdm(images, desc='AX 相对深度', unit='image'):
+        relative = path.relative_to(args.dataset)
+        timings = dict.fromkeys(STAGES, 0.0)
+        total_start = time.perf_counter()
+
+        start = time.perf_counter()
+        image = cv2.imread(str(path), cv2.IMREAD_COLOR)
+        if image is None:
+            raise ValueError(f'读取图片失败: {path}')
+        timings['read'] = (time.perf_counter() - start) * 1000
+
+        start = time.perf_counter()
+        tensor = preprocess(image, input_size, args.color_order, layout, dtype, norm_mode)
+        timings['preprocess'] = (time.perf_counter() - start) * 1000
+
+        start = time.perf_counter()
+        outputs = session.run(None, {input_meta.name: tensor})
+        timings['npu'] = (time.perf_counter() - start) * 1000
+
+        start = time.perf_counter()
+        raw, output_name = select_output(outputs, output_metas, input_size)
+        depth = read_depth(raw, input_size)
+        comparison = None
+        if args.debug and path == images[0]:
+            log_tensor(input_meta.name, tensor)
+            log_tensor('depth', depth)
+        if dump_path is not None:
+            dump_records.append((str(relative), depth,
+                                 np.array(image.shape[:2], dtype=np.int32)))
+            if args.npz_chunk and len(dump_records) >= args.npz_chunk:
+                flush_dataset_npz(dump_path, dump_records, dump_chunk,
+                                  input_size, args.color_order, norm_mode)
+                dump_records.clear()
+                dump_chunk += 1
+        if ref_map is not None:
+            key = str(relative)
+            if key not in ref_map:
+                raise ValueError(f'参考 NPZ 缺少样本: {key}')
+            comparison = compare_arrays(depth, ref_map[key],
+                                        f'{args.ref_npz}:{key}', preprocessing)
+        timings['diagnostics'] = (time.perf_counter() - start) * 1000
+
+        restored = None
+        if full_output:
+            start = time.perf_counter()
+            restored = restore_depth(depth, image.shape[:2])
+            timings['postprocess'] = (time.perf_counter() - start) * 1000
+            start = time.perf_counter()
+            panel = visualize(image, restored)
+            timings['visualize'] = (time.perf_counter() - start) * 1000
+            start = time.perf_counter()
+            prefix = args.output / relative
+            prefix.parent.mkdir(parents=True, exist_ok=True)
+            if not cv2.imwrite(str(prefix) + '.depth.jpg', panel,
+                               [cv2.IMWRITE_JPEG_QUALITY, 90]):
+                raise OSError(f'保存可视化失败: {prefix}.depth.jpg')
+            timings['write'] = (time.perf_counter() - start) * 1000
+        timings['total'] = (time.perf_counter() - total_start) * 1000
+
+        samples.append(timings)
+        sample_info.append({'name': str(relative),
+                            'original_size': list(image.shape[:2]),
+                            'depth_min': float((restored if restored is not None
+                                                else depth).min()),
+                            'depth_max': float((restored if restored is not None
+                                                else depth).max()),
+                            'timing_ms': timings,
+                            'reference_comparison': comparison})
+
+    if dump_path is not None:
+        flush_dataset_npz(dump_path, dump_records,
+                          None if not args.npz_chunk else dump_chunk,
+                          input_size, args.color_order, norm_mode)
+
+    stats = summarize(samples)
+    total_ms = sum(sample['total'] for sample in samples)
+    cpu_stages = ('read', 'preprocess', 'diagnostics', 'postprocess', 'visualize', 'write')
+    cpu_total_ms = sum(stats[stage]['mean_ms'] for stage in cpu_stages)
+    report = {'model': str(Path(args.axmodel).resolve()),
+              'runtime': runtime_version,
+              'task': 'relative-depth',
+              'input_name': input_meta.name, 'output_name': output_name,
+              'input_size': list(input_size), 'input_layout': layout,
+              'input_dtype': np.dtype(dtype).name,
+              'color_order': args.color_order,
+              'preprocessing': preprocessing_description(args.color_order, norm_mode),
+              'batch_size': 1, 'sample_count': len(samples),
+              'full_output': full_output, 'warmup_count': args.warmup,
+              'warmup_ms': warmup_ms, 'total_ms': total_ms,
+              'fps': len(samples) * 1000 / total_ms,
+              'npu_mean_ms': stats['npu']['mean_ms'],
+              'cpu_total_mean_ms': cpu_total_ms,
+              'timing_scope': 'npu=仅 session.run；cpu=读取+预处理+输出提取/校验+'
+                              '诊断+后处理+可视化+写盘；total=单样本端到端。排除'
+                              '模型加载、session 初始化和 warmup。快速模式的 '
+                              'postprocess/visualize/write 记为 0。',
+              'stages': stats, 'samples': sample_info}
+    with (args.output / 'npu_timing.json').open('w', encoding='utf-8') as file:
+        json.dump(report, file, ensure_ascii=False, indent=2, allow_nan=False)
+    for stage, values in stats.items():
+        logging.info('%s: mean=%.2f p50=%.2f p90=%.2f p99=%.2f ms',
+                     stage, values['mean_ms'], values['p50_ms'],
+                     values['p90_ms'], values['p99_ms'])
+    logging.info('%d 张图片，NPU mean=%.2f ms，CPU mean=%.2f ms，'
+                 'total=%.2f s，FPS=%.3f，结果目录: %s',
+                 len(samples), stats['npu']['mean_ms'], cpu_total_ms,
+                 total_ms / 1000, report['fps'], args.output)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='DepthART 相对深度 axmodel 板端推理（AX650）',
+        formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__)
+    parser.add_argument('--axmodel', type=Path, required=True, help='编译后的 axmodel')
+    source = parser.add_mutually_exclusive_group(required=True)
+    source.add_argument('--image', type=Path, help='单张图片')
+    source.add_argument('--dataset', type=Path, help='图片目录（递归）')
+    parser.add_argument('--output', type=Path, required=True, help='结果目录')
+    parser.add_argument('--color-order', choices=('rgb', 'bgr'), default='rgb',
+                        help='rgb=与官方预处理一致（BGR->RGB）；bgr=按编译配置'
+                             'input_processors.src_format 直送')
+    parser.add_argument('--input-norm', choices=('auto', 'raw', 'imagenet'),
+                        default='auto',
+                        help='auto=U8 送 0-255、浮点用 ImageNet mean/std；'
+                             'raw=直送 0-255；imagenet=/255+mean/std（仅浮点输入）')
+    parser.add_argument('--warmup', type=int, default=3,
+                        help='数据集模式 warmup 次数，默认 3')
+    parser.add_argument('--limit', type=int, help='数据集模式只处理前 N 张')
+    parser.add_argument('--full-output', action='store_true',
+                        help='数据集模式执行完整后处理、可视化和结果写盘（含 NPZ）')
+    parser.add_argument('--debug', action='store_true', help='打印输入/输出统计')
+    parser.add_argument('--dump-npz',
+                        help='单图：NPZ 文件；数据集：汇总 NPZ 文件（names/depths/original_sizes）')
+    parser.add_argument('--npz-chunk', type=int, default=0,
+                        help='数据集模式每 N 张切一个 NPZ 文件，0 表示全部写入一个文件')
+    parser.add_argument('--ref-npz', type=Path, help='参考 NPZ 文件或目录')
+    args = parser.parse_args()
+    logging.basicConfig(level=logging.INFO, format='%(message)s')
+    if args.warmup < 0:
+        parser.error('--warmup 不能为负数')
+    if args.npz_chunk < 0:
+        parser.error('--npz-chunk 不能为负数')
+    if args.limit is not None and args.limit < 1:
+        parser.error('--limit 必须为正数')
+    if args.image:
+        if not args.image.is_file():
+            parser.error(f'--image 不是文件: {args.image}')
+        if args.ref_npz and not args.ref_npz.is_file():
+            parser.error('单图模式 --ref-npz 必须是文件')
+        if args.limit is not None or args.full_output:
+            logging.warning('单图模式忽略 --limit/--full-output')
+    else:
+        if not args.dataset.is_dir():
+            parser.error(f'--dataset 不是目录: {args.dataset}')
+
+    try:
+        import axengine
+    except ImportError as error:
+        raise SystemExit('未找到 axengine：该脚本需在板端运行（pip 安装 axengine/'
+                         'pyaxengine 后重试）') from error
+
+    session = axengine.InferenceSession(str(args.axmodel))
+    inputs = session.get_inputs()
+    output_metas = session.get_outputs()
+    logging.info('模型输入: %s', [(m.name, m.shape, meta_type(m)) for m in inputs])
+    logging.info('模型输出: %s', [(m.name, m.shape, meta_type(m)) for m in output_metas])
+    if len(inputs) != 1:
+        raise ValueError(f'模型应有 1 个输入，实际 '
+                         f'{[(m.name, m.shape) for m in inputs]}')
+    input_meta = inputs[0]
+    input_size, layout, dtype = input_spec(input_meta)
+    if dtype == np.int8:
+        raise ValueError('当前脚本不支持 INT8 输入（缺少反量化参数）；请把编译配置的 '
+                         'input_processors.src_dtype 设为 U8 后重编译')
+
+    if args.input_norm == 'auto':
+        norm_mode = 'raw' if dtype == np.uint8 else 'imagenet'
+    else:
+        norm_mode = args.input_norm
+    if dtype == np.uint8 and norm_mode == 'imagenet':
+        raise ValueError('输入类型为 uint8，不能在推理时做 ImageNet 归一化；'
+                         '归一化必须由编译前端 input_processors 或校准口径保证')
+    if dtype != np.uint8 and norm_mode == 'raw':
+        logging.warning('输入为浮点但按 0-255 直送（--input-norm raw），'
+                        '仅用于诊断，需与编译前端/校准口径一致。')
+
+    logging.info('batch=1，输入尺寸: %s，layout=%s，dtype=%s，颜色顺序=%s，'
+                 '预处理=%s，resize=stretch', input_size, layout,
+                 np.dtype(dtype).name, args.color_order,
+                 'ImageNet mean/std (/255)' if norm_mode == 'imagenet'
+                 else '0-255 原始像素')
+    if dtype == np.uint8 and norm_mode == 'raw':
+        logging.info('提示：uint8 输入按编译契约送 0-255；ImageNet 归一化应由 '
+                     'config_axonnx.json 的 input_processors 在模型内完成。')
+
+    runtime_version = getattr(axengine, '__version__', 'unknown')
+    if args.image:
+        run_single(session, input_meta, output_metas, input_size, layout, dtype,
+                   norm_mode, args)
+    else:
+        run_dataset(session, input_meta, output_metas, input_size, layout, dtype,
+                    norm_mode, runtime_version, args)
+
+
+if __name__ == '__main__':
+    main()

src/infer/depthart_infer_onnx.py

@@ -0,0 +1,721 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+DepthART 相对深度 ONNX 推理（开发机 FP32 基准）。
+
+模型接口（脚本按实际 ONNX 读取并校验）：
+    input  [1, 3, 448, 448] float32 NCHW RGB
+    depth  [1, 1, 448, 448] float32 仿射不变相对深度，数值越大表示越近
+
+预处理按官方相对深度推理流程：BGR->RGB，直接拉伸到 448x448（INTER_CUBIC），
+/255 后按 ImageNet mean/std 归一化。归一化必须保留，否则输出会退化。
+
+自定义算子：
+    relative_s_448_default.onnx 含 com.depthart::SelectiveScan（官方只提供
+    TensorRT 插件），onnxruntime 无法直接加载。本脚本在内存中把每个
+    SelectiveScan 改写为等价的纯 ONNX 子图（Loop + 逐 t 递归），语义与官方
+    reference 实现一致（含 delta_bias/softplus、按组 repeat_interleave）。
+    改写后整模型输出与 PyTorch 参考的最大绝对误差约 5e-5。
+    --save-rewritten 可导出改写后的标准 ONNX 便于排查。
+    注意：pulsar2 不支持 Loop，要编译 axmodel 请用
+    src/tool/depthart_export_axonnx.py 生成分块并行扫描版本。
+
+单图模式：打印深度统计和各阶段耗时，保存并排可视化，不产出评测文件。
+数据集模式：tqdm 进度 + onnx_timing.json；默认快速模式只统计读取/预处理/推理，
+--full-output 才做深度还原、可视化、原始 NPZ 和图片写盘。
+
+用法（在 hs/DepthART 目录下执行）：
+    # 单图验证，输出 results/onnx_demo/xxx_depth.jpg
+    ../../venv/bin/python src/infer/depthart_infer_onnx.py --image /path/a.jpg --output results/onnx_demo
+
+    # 指定其他尺寸/变的模型
+    ../../venv/bin/python src/infer/depthart_infer_onnx.py --model onnx/relative_b_448_default.onnx --image /path/a.jpg
+
+    # 数据集快速性能模式
+    ../../venv/bin/python src/infer/depthart_infer_onnx.py --dataset /path/images --output results/onnx_dataset --limit 50
+
+    # 数据集完整输出（可视化 + 汇总 NPZ）
+    ../../venv/bin/python src/infer/depthart_infer_onnx.py --dataset ../../datasets/hs_ai_tv/test_depth \
+    --output results/onnx_full --full-output --dump-npz results/onnx_full/raw_outputs.npz
+
+    # 与参考原始输出对比（单图，--ref-npz 指向单图 NPZ）
+    ../../venv/bin/python src/infer/depthart_infer_onnx.py --image /path/a.jpg --output results/onnx_check --ref-npz results/onnx_demo/a.jpg.npz
+
+    # 导出改写后的标准 ONNX（保留原始文件不变）
+    ../../venv/bin/python src/infer/depthart_infer_onnx.py --image /path/a.jpg --save-rewritten results/relative_s_448_default_std.onnx
+
+诊断：
+    --debug     打印输入/输出 tensor 的 shape、dtype、min、max、mean、nan 计数，
+                以及自定义算子的改写数量
+    --dump-npz  单图时为 .npz 文件路径；数据集时为汇总 .npz 文件路径，
+                保存 names/depths/original_sizes，不再每张图一个小文件
+    --npz-chunk 数据集模式下每 N 张切一个文件（xxx_0000.npz 等），
+                0 表示全部写入同一个文件
+    --ref-npz   单图时为参考 .npz，数据集时为参考汇总 .npz（按 names 匹配），
+                报告 max/mean/p99 绝对误差、cosine 以及 scale-shift 对齐后误差
+"""
+
+import argparse
+import json
+import logging
+import time
+from pathlib import Path
+
+import cv2
+import numpy as np
+import onnx
+import onnxruntime as ort
+from onnx import helper, numpy_helper, TensorProto
+from tqdm import tqdm
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_MODEL = PROJECT_ROOT / 'onnx' / 'relative_s_448_default.onnx'
+MEAN = np.array([0.485, 0.456, 0.406], dtype=np.float32)
+STD = np.array([0.229, 0.224, 0.225], dtype=np.float32)
+EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.tif', '.tiff'}
+STAGES = ('read', 'preprocess', 'inference', 'diagnostics',
+          'postprocess', 'visualize', 'write', 'total')
+
+SCAN_DOMAIN = 'com.depthart'
+SCAN_OP = 'SelectiveScan'
+
+
+# ---------------------------------------------------------------------------
+# 自定义算子改写：com.depthart::SelectiveScan -> 纯 ONNX
+# ---------------------------------------------------------------------------
+
+class _ScanGraph:
+    """为一个 SelectiveScan 节点生成改写子图。
+
+    语义（与官方 reference 一致，u 为 [B, D, L]）：
+        delta = softplus(delta + delta_bias)            # 可选前两项
+        transition = exp(delta_t * A)                   # [B, D, N]
+        state_t = transition * state_{t-1}
+                  + delta_t * B_t * u_t                 # B/C 按组 repeat_interleave
+        y_t = sum_n(state_t * C_t) + D * u_t
+    组映射：group = channel // (D / G)，即把 [B, G, N, L] 的每个组连续复制
+    D/G 次到 [B, D, N, L]。
+    """
+
+    def __init__(self, prefix):
+        self.prefix = prefix
+        self.nodes = []
+        self.inits = []
+        self._cache = {}
+
+    def const(self, name, value):
+        tensor_name = f'{self.prefix}_{name}'
+        if tensor_name not in self._cache:
+            self.inits.append(numpy_helper.from_array(np.asarray(value), tensor_name))
+            self._cache[tensor_name] = True
+        return tensor_name
+
+    def node(self, op, inputs, outputs, **kwargs):
+        self.nodes.append(helper.make_node(op, inputs, outputs, **kwargs))
+        return outputs[0]
+
+    def build(self, u, delta, a, b, c, d, bias, attrs, out_name):
+        p = self.prefix
+        one = self.const('one', np.array([1], dtype=np.int64))
+
+        # delta (+ bias) -> softplus
+        dt = delta
+        if bias is not None:
+            bias3 = self.node('Unsqueeze', [bias, self.const('uax02', [0, 2])], [f'{p}_bias3'])
+            dt = self.node('Add', [delta, bias3], [f'{p}_dt_bias'])
+        if int(attrs.get('delta_softplus', 0)):
+            dt = self.node('Softplus', [dt], [f'{p}_dt_softplus'])
+
+        # 形状：D = u.shape[1]，G = B.shape[1]，gs = D / G，L = u.shape[2]
+        u_shape = self.node('Shape', [u], [f'{p}_u_shape'])
+        b_shape = self.node('Shape', [b], [f'{p}_b_shape'])
+        d_vec = self.node('Gather', [u_shape, self.const('i1', [1])], [f'{p}_d'], axis=0)
+        l_vec = self.node('Gather', [u_shape, self.const('i2', [2])], [f'{p}_l'], axis=0)
+        g_vec = self.node('Gather', [b_shape, self.const('i1b', [1])], [f'{p}_g'], axis=0)
+        n_vec = self.node('Gather', [b_shape, self.const('i2b', [2])], [f'{p}_n'], axis=0)
+        l_vec_b = self.node('Gather', [b_shape, self.const('i3b', [3])], [f'{p}_lb'], axis=0)
+        gs_vec = self.node('Div', [d_vec, g_vec], [f'{p}_gs'])
+        l_scalar = self.node('Gather', [b_shape, self.const('i3s', 3)], [f'{p}_l_scalar'], axis=0)
+
+        def expand_groups(x, tag):
+            # [B,G,N,L] -> [B,G,1,N,L] -> [B,G,gs,N,L] -> [B,D,N,L]
+            x5 = self.node('Unsqueeze', [x, self.const(f'{tag}_uax', [2])], [f'{p}_{tag}_x5'])
+            target5 = self.node('Concat', [one, g_vec, gs_vec, n_vec, l_vec_b],
+                                [f'{p}_{tag}_target5'], axis=0)
+            expanded = self.node('Expand', [x5, target5], [f'{p}_{tag}_expanded'])
+            target4 = self.node('Concat', [one, d_vec, n_vec, l_vec],
+                                [f'{p}_{tag}_target4'], axis=0)
+            return self.node('Reshape', [expanded, target4], [f'{p}_{tag}_4d'])
+
+        b_full = expand_groups(b, 'b')
+        c_full = expand_groups(c, 'c')
+
+        # 初始状态 [1, D, N]
+        state_shape = self.node('Concat', [one, d_vec, n_vec], [f'{p}_state_shape'], axis=0)
+        state0 = self.node('ConstantOfShape', [state_shape], [f'{p}_state0'],
+                           value=helper.make_tensor('value', TensorProto.FLOAT, [1], [0.0]))
+
+        # Loop body：按时间步推进状态，扫描输出自动在轴 0 堆叠
+        bp = f'{p}_body'
+        body_inputs = [helper.make_tensor_value_info(bp + '_iter', TensorProto.INT64, []),
+                       helper.make_tensor_value_info(bp + '_cond', TensorProto.BOOL, []),
+                       helper.make_tensor_value_info(bp + '_state', TensorProto.FLOAT, None)]
+        body_outputs = [helper.make_tensor_value_info(bp + '_cond_out', TensorProto.BOOL, []),
+                        helper.make_tensor_value_info(bp + '_state_out', TensorProto.FLOAT, None),
+                        helper.make_tensor_value_info(bp + '_y', TensorProto.FLOAT, None)]
+        body = _ScanGraph.body_graph(p, bp, u, dt, b_full, c_full, a, d, body_inputs, body_outputs)
+
+        final_state = f'{p}_final_state'
+        y_seq = f'{p}_y_seq'
+        self.node('Loop', [l_scalar, self.const('cond', np.array(True)), state0],
+                  [final_state, y_seq], body=body, name=f'{p}_loop')
+        # y_seq: [L,1,D,1] -> [1,D,L]
+        y_sq = self.node('Squeeze', [y_seq, self.const('sq_axes', [1, 3])], [f'{p}_y_sq'])
+        y_tr = self.node('Transpose', [y_sq], [f'{p}_y_tr'], perm=[1, 0])
+        self.node('Unsqueeze', [y_tr, self.const('uax_out', [0])], [out_name])
+
+    @staticmethod
+    def body_graph(p, bp, u, dt, b_full, c_full, a, d, body_inputs, body_outputs):
+        """构造 Loop body；外层张量通过闭包名字被 body 引用。"""
+        g = _ScanGraph(p)
+        iter_name, cond_name, state_name = (x.name for x in body_inputs)
+        cond_out, state_out, y_out = (x.name for x in body_outputs)
+
+        u_t = g.node('Gather', [u, iter_name], [bp + '_u_t'], axis=2)          # [1,D]
+        dt_t = g.node('Gather', [dt, iter_name], [bp + '_dt_t'], axis=2)       # [1,D]
+        b_t = g.node('Gather', [b_full, iter_name], [bp + '_b_t'], axis=3)     # [1,D,N]
+        c_t = g.node('Gather', [c_full, iter_name], [bp + '_c_t'], axis=3)     # [1,D,N]
+        dt3 = g.node('Unsqueeze', [dt_t, g.const('uax2', [2])], [bp + '_dt3'])
+        u3 = g.node('Unsqueeze', [u_t, g.const('uax2b', [2])], [bp + '_u3'])
+        a3 = g.node('Unsqueeze', [a, g.const('uax0', [0])], [bp + '_a3'])
+        trans = g.node('Exp', [g.node('Mul', [dt3, a3], [bp + '_dt_a'])], [bp + '_trans'])
+        state_keep = g.node('Mul', [trans, state_name], [bp + '_state_keep'])
+        bu = g.node('Mul', [g.node('Mul', [dt3, u3], [bp + '_dt_u']), b_t], [bp + '_dt_u_b'])
+        state_new = g.node('Add', [state_keep, bu], [bp + '_state_new'])
+        y = g.node('ReduceSum', [g.node('Mul', [state_new, c_t], [bp + '_state_c']),
+                                 g.const('rs_axes', [2])], [bp + '_y_val'], keepdims=0)
+        if d is not None:
+            y = g.node('Add', [y, g.node('Mul', [d, u_t], [bp + '_d_u'])], [bp + '_y_d'])
+        y3 = g.node('Unsqueeze', [y, g.const('uax2c', [2])], [bp + '_y3'])
+        g.node('Identity', [cond_name], [cond_out])
+        g.node('Identity', [state_new], [state_out])
+        g.node('Identity', [y3], [y_out])
+        return helper.make_graph(g.nodes, bp + '_graph', body_inputs, body_outputs,
+                                 initializer=g.inits)
+
+
+def _static_rank(value_info_map, name):
+    info = value_info_map.get(name)
+    if info is None or not info.type.HasField('tensor_type'):
+        return None
+    return len(info.type.tensor_type.shape.dim)
+
+
+def rewrite_selective_scan(model):
+    """把 com.depthart::SelectiveScan 替换成纯 ONNX 子图，返回替换数量。
+
+    仅处理 domain 为 com.depthart、op_type 为 SelectiveScan 的节点；
+    其余自定义 domain 节点保持原样，由调用方检查后报错。
+    """
+    try:
+        inferred = onnx.shape_inference.infer_shapes(model)
+        shape_map = {v.name: v for v in list(inferred.graph.value_info)
+                     + list(inferred.graph.input) + list(inferred.graph.output)}
+    except Exception as error:  # 自定义算子会阻断部分形状推导，不影响 4D B/C 的常规情形
+        logging.warning('形状推导失败，按 4D B/C 处理: %s', error)
+        shape_map = {}
+    new_nodes, extra_inits, count = [], [], 0
+    for node in model.graph.node:
+        if node.domain != SCAN_DOMAIN or node.op_type != SCAN_OP:
+            new_nodes.append(node)
+            continue
+        count += 1
+        prefix = f'depthart_scan_{count - 1}'
+        if not 5 <= len(node.input) <= 7:
+            raise ValueError(f'{node.name}: 期望 5~7 个输入，实际 {len(node.input)}')
+        u, delta, a, b, c = node.input[:5]
+        d = node.input[5] if len(node.input) > 5 and node.input[5] else None
+        bias = node.input[6] if len(node.input) > 6 and node.input[6] else None
+        # 3D 的 B/C 按 [B,N,L] 处理，补一个 group 轴
+        if _static_rank(shape_map, b) == 3:
+            b4 = prefix + '_b4'
+            new_nodes.append(helper.make_node('Unsqueeze', [b, prefix + '_uax_g'],
+                                              [b4], name=prefix + '_b_unsqueeze'))
+            extra_inits.append(numpy_helper.from_array(np.array([1], dtype=np.int64),
+                                                       prefix + '_uax_g'))
+            b = b4
+        if _static_rank(shape_map, c) == 3:
+            c4 = prefix + '_c4'
+            new_nodes.append(helper.make_node('Unsqueeze', [c, prefix + '_uax_g2'],
+                                              [c4], name=prefix + '_c_unsqueeze'))
+            extra_inits.append(numpy_helper.from_array(np.array([1], dtype=np.int64),
+                                                       prefix + '_uax_g2'))
+            c = c4
+        attrs = {item.name: item.i for item in node.attribute}
+        graph = _ScanGraph(prefix)
+        graph.build(u, delta, a, b, c, d, bias, attrs, node.output[0])
+        new_nodes.extend(graph.nodes)
+        extra_inits.extend(graph.inits)
+
+    if count:
+        del model.graph.node[:]
+        model.graph.node.extend(new_nodes)
+        model.graph.initializer.extend(extra_inits)
+    return count
+
+
+def unsupported_custom_ops(model):
+    return [(n.domain, n.op_type, n.name) for n in model.graph.node
+            if n.domain not in ('', 'ai.onnx') and n.domain != SCAN_DOMAIN]
+
+
+def create_session(model_path, save_rewritten=None):
+    """加载 ONNX；存在 SelectiveScan 时先在内存中改写成标准 ONNX。"""
+    model = onnx.load(str(model_path))
+    scan_count = rewrite_selective_scan(model)
+    if scan_count:
+        logging.info('检测到 %d 个 %s::%s，已改写为等价纯 ONNX 子图（Loop）',
+                     scan_count, SCAN_DOMAIN, SCAN_OP)
+    remaining = unsupported_custom_ops(model)
+    if remaining:
+        raise ValueError(f'模型仍含未支持的自定义算子: {remaining[:5]}')
+    if save_rewritten is not None:
+        save_rewritten.parent.mkdir(parents=True, exist_ok=True)
+        onnx.save(model, str(save_rewritten))
+        logging.info('已保存改写后的标准 ONNX: %s', save_rewritten)
+    if scan_count:
+        return ort.InferenceSession(model.SerializeToString()), scan_count
+    return ort.InferenceSession(str(model_path)), 0
+
+
+# ---------------------------------------------------------------------------
+# 预处理 / 后处理
+# ---------------------------------------------------------------------------
+
+def check_interface(session):
+    inputs, outputs = session.get_inputs(), session.get_outputs()
+    logging.info('模型输入: %s', [(m.name, m.shape, m.type) for m in inputs])
+    logging.info('模型输出: %s', [(m.name, m.shape, m.type) for m in outputs])
+    if len(inputs) != 1:
+        raise ValueError(f'模型应有 1 个输入，实际 {[(m.name, m.shape) for m in inputs]}')
+    meta = inputs[0]
+    shape = list(meta.shape)
+    if len(shape) != 4 or not all(isinstance(v, int) and v > 0 for v in shape):
+        raise ValueError(f'输入必须是静态 4D NCHW: {meta.name} {meta.shape}')
+    if shape[0] != 1 or shape[1] != 3:
+        raise ValueError(f'仅支持 [1,3,H,W] 输入: {meta.name} {meta.shape}')
+    if 'float' not in meta.type:
+        raise ValueError(f'当前实现要求 float32 输入: {meta.name} {meta.type}')
+    depth_metas = [m for m in outputs if 'depth' in m.name.lower()] or outputs
+    if len(depth_metas) != 1:
+        raise ValueError(f'无法确定 depth 输出: {[(m.name, m.shape) for m in outputs]}')
+    return meta.name, (shape[2], shape[3]), depth_metas[0].name
+
+
+def preprocess(image, size):
+    target_h, target_w = size
+    rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB).astype(np.float32) / 255.0
+    resized = cv2.resize(rgb, (target_w, target_h), interpolation=cv2.INTER_CUBIC)
+    normalized = (resized - MEAN) / STD
+    tensor = normalized.transpose(2, 0, 1)
+    return np.ascontiguousarray(tensor[None])
+
+
+def read_depth(raw, input_size):
+    array = np.asarray(raw)
+    if array.ndim == 4 and array.shape[1] == 1:
+        array = array[0]
+    if array.ndim == 3 and array.shape[0] == 1:
+        array = array[0]
+    if array.ndim != 2 or array.shape != tuple(input_size):
+        raise ValueError(f'depth 输出无效: shape={array.shape}，期望 {tuple(input_size)}')
+    if array.dtype != np.float32:
+        raise ValueError(f'depth 输出必须是 float32: {array.dtype}')
+    if not np.isfinite(array).all():
+        raise ValueError('depth 输出包含 nan/inf')
+    return array
+
+
+def restore_depth(depth, original_size):
+    """按官方推理的 bilinear + align_corners=True 还原到原图尺寸。"""
+    height, width = original_size
+    src_h, src_w = depth.shape
+    if (src_h, src_w) == (height, width):
+        return depth.copy()
+    xs = np.linspace(0.0, src_w - 1, width, dtype=np.float32)
+    ys = np.linspace(0.0, src_h - 1, height, dtype=np.float32)
+    map_x, map_y = np.meshgrid(xs, ys)
+    return cv2.remap(depth, map_x, map_y, interpolation=cv2.INTER_LINEAR,
+                     borderMode=cv2.BORDER_REPLICATE)
+
+
+def visualize(image, depth):
+    finite = depth[np.isfinite(depth)]
+    low, high = np.percentile(finite, (2, 98))
+    value = np.clip((depth - low) / max(float(high - low), 1e-6), 0, 1)
+    colored = cv2.applyColorMap((value * 255).astype(np.uint8), cv2.COLORMAP_INFERNO)
+    panel = np.concatenate((image, colored), axis=1)
+    legend = np.full((56, panel.shape[1], 3), 255, dtype=np.uint8)
+    ramp = np.tile(np.linspace(0, 255, max(panel.shape[1] - 20, 1),
+                               dtype=np.uint8), (12, 1))
+    legend[5:17, 10:10 + ramp.shape[1]] = cv2.applyColorMap(ramp, cv2.COLORMAP_INFERNO)
+    cv2.putText(legend, f'Image | Relative depth (2-98%): {low:.3f} -> {high:.3f}',
+                (10, 42), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (30, 30, 30), 1, cv2.LINE_AA)
+    return np.concatenate((panel, legend), axis=0)
+
+
+def log_tensor(name, value):
+    logging.info('%s: shape=%s dtype=%s min=%.6g max=%.6g mean=%.6g nan=%d inf=%d',
+                 name, value.shape, value.dtype, float(np.min(value)),
+                 float(np.max(value)), float(np.mean(value)),
+                 int(np.isnan(value).sum()), int(np.isinf(value).sum()))
+
+
+def compare_arrays(depth, expected, source=''):
+    expected = np.asarray(expected)
+    if expected.ndim == 4 and expected.shape[1] == 1:
+        expected = expected[0]
+    if expected.shape != depth.shape:
+        raise ValueError(f'参考 depth shape 不符: {expected.shape} vs {depth.shape} ({source})')
+    if not np.isfinite(expected).all():
+        raise ValueError(f'参考 depth 含 nan/inf: {source}')
+    actual64 = depth.astype(np.float64).ravel()
+    expected64 = expected.astype(np.float64).ravel()
+    diff = np.abs(actual64 - expected64)
+    cosine = float(np.dot(actual64, expected64)
+                   / (np.linalg.norm(actual64) * np.linalg.norm(expected64) + 1e-12))
+    # 相对深度存在全局 scale/offset 漂移，对齐后误差更能反映结构偏差。
+    slope, offset = np.polyfit(expected64, actual64, 1)
+    aligned = np.abs(actual64 - (slope * expected64 + offset))
+    metrics = {'cosine': cosine,
+               'max_abs': float(diff.max()),
+               'mean_abs': float(diff.mean()),
+               'p99_abs': float(np.percentile(diff, 99)),
+               'scale': float(slope), 'offset': float(offset),
+               'aligned_mean_abs': float(aligned.mean()),
+               'aligned_p99_abs': float(np.percentile(aligned, 99))}
+    logging.info('参考对比: %s', metrics)
+    return metrics
+
+
+def compare_reference(depth, reference_path):
+    with np.load(reference_path, allow_pickle=False) as reference:
+        if 'depth' not in reference:
+            raise ValueError(f'参考 NPZ 缺少 depth: {reference_path}')
+        expected = np.asarray(reference['depth'])
+    return compare_arrays(depth, expected, str(reference_path))
+
+
+def load_reference_dataset(path):
+    """读取汇总 NPZ，返回 {name: depth}。"""
+    path = Path(path)
+    if path.is_file():
+        with np.load(path, allow_pickle=False) as ref:
+            if 'depths' not in ref or 'names' not in ref:
+                raise ValueError(f'汇总 NPZ 需要 names/depths: {path}')
+            return {str(n): d for n, d in zip(ref['names'], ref['depths'])}
+    raise ValueError(f'数据集模式 --ref-npz 需要汇总 NPZ 文件: {path}')
+
+
+def save_raw_npz(path, depth, original_size, input_size):
+    np.savez_compressed(path, depth=depth,
+                        original_size=np.array(original_size, dtype=np.int32),
+                        input_size=np.array(input_size, dtype=np.int32),
+                        preprocessing='RGB /255 + ImageNet mean/std; resize=stretch')
+
+
+def flush_dataset_npz(path, records, chunk_index, input_size, preprocessing):
+    """把缓冲区写成汇总 NPZ：names / depths / original_sizes。
+
+    chunk_index 为 None 时写入 path 本身，否则按 chunk 编号追加后缀。
+    """
+    if not records:
+        return
+    target = path if chunk_index is None else path.with_name(
+        f'{path.stem}_{chunk_index:04d}{path.suffix}')
+    target.parent.mkdir(parents=True, exist_ok=True)
+    np.savez_compressed(
+        target,
+        names=np.array([r[0] for r in records]),
+        depths=np.stack([r[1] for r in records]),
+        original_sizes=np.array([r[2] for r in records], dtype=np.int32),
+        input_size=np.array(input_size, dtype=np.int32),
+        preprocessing=preprocessing)
+
+
+def collect_images(dataset):
+    paths = sorted(p for p in dataset.rglob('*')
+                   if p.is_file() and p.suffix.lower() in EXTENSIONS)
+    if not paths:
+        raise ValueError(f'目录中没有图片: {dataset}')
+    return paths
+
+
+def summarize(samples):
+    result = {}
+    for stage in STAGES:
+        values = np.array([sample[stage] for sample in samples], dtype=np.float64)
+        result[stage] = {'mean_ms': float(values.mean()),
+                         'p50_ms': float(np.percentile(values, 50)),
+                         'p90_ms': float(np.percentile(values, 90)),
+                         'p99_ms': float(np.percentile(values, 99))}
+    return result
+
+
+# ---------------------------------------------------------------------------
+# 推理流程
+# ---------------------------------------------------------------------------
+
+def run_single(session, input_name, output_name, input_size, args):
+    stem = args.image.stem
+    timings = dict.fromkeys(STAGES, 0.0)
+    total_start = time.perf_counter()
+
+    start = time.perf_counter()
+    image = cv2.imread(str(args.image), cv2.IMREAD_COLOR)
+    if image is None:
+        raise ValueError(f'读取图片失败: {args.image}')
+    timings['read'] = (time.perf_counter() - start) * 1000
+
+    start = time.perf_counter()
+    tensor = preprocess(image, input_size)
+    timings['preprocess'] = (time.perf_counter() - start) * 1000
+
+    start = time.perf_counter()
+    raw = session.run([output_name], {input_name: tensor})[0]
+    timings['inference'] = (time.perf_counter() - start) * 1000
+    depth = read_depth(raw, input_size)
+
+    start = time.perf_counter()
+    comparison = None
+    if args.debug:
+        log_tensor(input_name, tensor)
+        log_tensor('depth', depth)
+    if args.ref_npz:
+        comparison = compare_reference(depth, args.ref_npz)
+    timings['diagnostics'] = (time.perf_counter() - start) * 1000
+
+    start = time.perf_counter()
+    restored = restore_depth(depth, image.shape[:2])
+    timings['postprocess'] = (time.perf_counter() - start) * 1000
+
+    start = time.perf_counter()
+    panel = visualize(image, restored)
+    timings['visualize'] = (time.perf_counter() - start) * 1000
+
+    start = time.perf_counter()
+    args.output.mkdir(parents=True, exist_ok=True)
+    image_path = args.output / f'{stem}_depth.jpg'
+    if not cv2.imwrite(str(image_path), panel):
+        raise OSError(f'保存可视化失败: {image_path}')
+    np.save(str(args.output / f'{stem}_depth.npy'), restored)
+    npz_path = None
+    if args.dump_npz:
+        npz_path = Path(args.dump_npz)
+        npz_path.parent.mkdir(parents=True, exist_ok=True)
+        save_raw_npz(npz_path, depth, image.shape[:2], input_size)
+    timings['write'] = (time.perf_counter() - start) * 1000
+    timings['total'] = (time.perf_counter() - total_start) * 1000
+
+    logging.info('深度（模型分辨率）: min=%.4f max=%.4f mean=%.4f p50=%.4f',
+                 float(depth.min()), float(depth.max()), float(depth.mean()),
+                 float(np.percentile(depth, 50)))
+    logging.info('深度（原图分辨率）: min=%.4f max=%.4f mean=%.4f',
+                 float(restored.min()), float(restored.max()), float(restored.mean()))
+    logging.info('各阶段耗时: %s',
+                 '  '.join(f'{key}={value:.2f} ms' for key, value in timings.items()))
+    logging.info('结果目录: %s（可视化 %s%s）', args.output, image_path.name,
+                 f'，原始 NPZ {npz_path.name}' if npz_path else '')
+
+
+def run_dataset(session, input_name, output_name, input_size, args):
+    images = collect_images(args.dataset)
+    if args.limit is not None:
+        images = images[:args.limit]
+    args.output.mkdir(parents=True, exist_ok=True)
+    full_output = args.full_output
+    if full_output:
+        logging.warning('--full-output: CPU 侧深度还原、可视化与写盘会拉高端到端耗时，'
+                        '不能只看 inference 时间。')
+    else:
+        logging.info('数据集快速模式：只统计 read/preprocess/inference，'
+                     '跳过深度还原、可视化和结果写盘。')
+    ref_map = load_reference_dataset(args.ref_npz) if args.ref_npz else None
+
+    preprocessing = 'RGB /255 + ImageNet mean/std; resize=stretch'
+    dump_path = Path(args.dump_npz) if args.dump_npz else None
+    if dump_path is not None and dump_path.is_dir():
+        raise ValueError('数据集模式 --dump-npz 请传 .npz 文件路径，'
+                         '不再按目录为每张图生成小文件')
+    dump_records, dump_chunk = [], 0
+
+    warmup_ms = 0.0
+    if args.warmup:
+        first = cv2.imread(str(images[0]), cv2.IMREAD_COLOR)
+        if first is None:
+            raise ValueError(f'读取图片失败: {images[0]}')
+        warm = preprocess(first, input_size)
+        start = time.perf_counter()
+        for _ in range(args.warmup):
+            session.run([output_name], {input_name: warm})
+        warmup_ms = (time.perf_counter() - start) * 1000
+
+    samples, sample_info = [], []
+    for index, path in enumerate(tqdm(images, desc='ONNX 相对深度', unit='image')):
+        relative = path.relative_to(args.dataset)
+        timings = dict.fromkeys(STAGES, 0.0)
+        total_start = time.perf_counter()
+
+        start = time.perf_counter()
+        image = cv2.imread(str(path), cv2.IMREAD_COLOR)
+        if image is None:
+            raise ValueError(f'读取图片失败: {path}')
+        timings['read'] = (time.perf_counter() - start) * 1000
+
+        start = time.perf_counter()
+        tensor = preprocess(image, input_size)
+        timings['preprocess'] = (time.perf_counter() - start) * 1000
+
+        start = time.perf_counter()
+        raw = session.run([output_name], {input_name: tensor})[0]
+        timings['inference'] = (time.perf_counter() - start) * 1000
+        depth = read_depth(raw, input_size)
+
+        start = time.perf_counter()
+        comparison = None
+        if args.debug and index == 0:
+            log_tensor(input_name, tensor)
+            log_tensor('depth', depth)
+        if dump_path is not None:
+            dump_records.append((str(relative), depth,
+                                 np.array(image.shape[:2], dtype=np.int32)))
+            if args.npz_chunk and len(dump_records) >= args.npz_chunk:
+                flush_dataset_npz(dump_path, dump_records, dump_chunk,
+                                  input_size, preprocessing)
+                dump_records.clear()
+                dump_chunk += 1
+        if ref_map is not None:
+            key = str(relative)
+            if key not in ref_map:
+                raise ValueError(f'参考 NPZ 缺少样本: {key}')
+            comparison = compare_arrays(depth, ref_map[key], f'{args.ref_npz}:{key}')
+        timings['diagnostics'] = (time.perf_counter() - start) * 1000
+
+        restored = None
+        if full_output:
+            start = time.perf_counter()
+            restored = restore_depth(depth, image.shape[:2])
+            timings['postprocess'] = (time.perf_counter() - start) * 1000
+            start = time.perf_counter()
+            panel = visualize(image, restored)
+            timings['visualize'] = (time.perf_counter() - start) * 1000
+            start = time.perf_counter()
+            prefix = args.output / relative
+            prefix.parent.mkdir(parents=True, exist_ok=True)
+            np.save(str(prefix) + '.depth.npy', restored)
+            if not cv2.imwrite(str(prefix) + '.depth.jpg', panel):
+                raise OSError(f'保存可视化失败: {prefix}.depth.jpg')
+            timings['write'] = (time.perf_counter() - start) * 1000
+        timings['total'] = (time.perf_counter() - total_start) * 1000
+
+        samples.append(timings)
+        sample_info.append({'name': str(relative),
+                            'original_size': list(image.shape[:2]),
+                            'depth_min': float((restored if restored is not None else depth).min()),
+                            'depth_max': float((restored if restored is not None else depth).max()),
+                            'timing_ms': timings,
+                            'reference_comparison': comparison})
+
+    if dump_path is not None:
+        flush_dataset_npz(dump_path, dump_records,
+                          None if not args.npz_chunk else dump_chunk,
+                          input_size, preprocessing)
+
+    stats = summarize(samples)
+    total_ms = sum(sample['total'] for sample in samples)
+    report = {'model': str(args.model.resolve()),
+              'runtime': 'onnxruntime ' + ort.__version__,
+              'providers': session.get_providers(),
+              'task': 'relative-depth',
+              'custom_ops_rewritten': args.scan_count,
+              'input_name': input_name, 'output_name': output_name,
+              'input_size': list(input_size), 'input_layout': 'NCHW',
+              'preprocessing': 'RGB /255 + ImageNet mean/std; resize=stretch',
+              'batch_size': 1, 'sample_count': len(samples),
+              'full_output': full_output, 'warmup_count': args.warmup,
+              'warmup_ms': warmup_ms, 'total_ms': total_ms,
+              'fps': len(samples) * 1000 / total_ms,
+              'timing_scope': '样本 read 至 write，包含 diagnostics；排除模型加载、'
+                              'session 初始化、自定义算子改写、warmup、进度条和最终性能 JSON 写盘。'
+                              '快速模式的 postprocess/visualize/write 记为 0。',
+              'stages': stats, 'samples': sample_info}
+    with (args.output / 'onnx_timing.json').open('w', encoding='utf-8') as file:
+        json.dump(report, file, ensure_ascii=False, indent=2, allow_nan=False)
+    for stage, values in stats.items():
+        logging.info('%s: mean=%.2f p50=%.2f p90=%.2f p99=%.2f ms',
+                     stage, values['mean_ms'], values['p50_ms'],
+                     values['p90_ms'], values['p99_ms'])
+    logging.info('%d 张图片，total=%.2f s，FPS=%.3f，结果目录: %s',
+                 len(samples), total_ms / 1000, report['fps'], args.output)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='DepthART 相对深度 ONNX 推理',
+        formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__)
+    parser.add_argument('--model', type=Path, default=DEFAULT_MODEL,
+                        help=f'FP32 ONNX 模型，默认 {DEFAULT_MODEL.relative_to(PROJECT_ROOT)}')
+    source = parser.add_mutually_exclusive_group(required=True)
+    source.add_argument('--image', type=Path, help='单张图片')
+    source.add_argument('--dataset', type=Path, help='图片目录（递归）')
+    parser.add_argument('--output', type=Path,
+                        default=PROJECT_ROOT / 'results' / 'onnx',
+                        help='结果目录，默认 results/onnx')
+    parser.add_argument('--warmup', type=int, default=3,
+                        help='数据集模式首次输入 warmup 次数，默认 3')
+    parser.add_argument('--limit', type=int, help='数据集模式只处理前 N 张')
+    parser.add_argument('--full-output', action='store_true',
+                        help='数据集模式执行完整后处理、可视化和结果写盘')
+    parser.add_argument('--debug', action='store_true', help='打印输入/输出统计')
+    parser.add_argument('--dump-npz',
+                        help='单图：NPZ 文件；数据集：汇总 NPZ 文件（names/depths/original_sizes）')
+    parser.add_argument('--npz-chunk', type=int, default=0,
+                        help='数据集模式每 N 张切一个 NPZ 文件，0 表示全部写入一个文件')
+    parser.add_argument('--ref-npz', type=Path,
+                        help='单图：参考 NPZ 文件；数据集：参考汇总 NPZ 文件')
+    parser.add_argument('--save-rewritten', type=Path,
+                        help='保存去除自定义算子后的标准 ONNX（不影响原模型）')
+    args = parser.parse_args()
+    logging.basicConfig(level=logging.INFO, format='%(message)s')
+    if args.warmup < 0:
+        parser.error('--warmup 不能为负数')
+    if args.limit is not None and args.limit < 1:
+        parser.error('--limit 必须为正数')
+    if args.npz_chunk < 0:
+        parser.error('--npz-chunk 不能为负数')
+    if not args.model.is_file():
+        parser.error(f'--model 不存在: {args.model}')
+    if args.image:
+        if not args.image.is_file():
+            parser.error(f'--image 不是文件: {args.image}')
+        if args.ref_npz and not args.ref_npz.is_file():
+            parser.error('单图模式 --ref-npz 必须是文件')
+        if args.limit is not None or args.full_output:
+            logging.warning('单图模式忽略 --limit/--full-output')
+    else:
+        if not args.dataset.is_dir():
+            parser.error(f'--dataset 不是目录: {args.dataset}')
+
+    session, args.scan_count = create_session(args.model, args.save_rewritten)
+    input_name, input_size, output_name = check_interface(session)
+    logging.info('batch=1���输入尺寸: %s，预处理: RGB /255 + ImageNet mean/std（stretch）',
+                 input_size)
+
+    if args.image:
+        run_single(session, input_name, output_name, input_size, args)
+    else:
+        run_dataset(session, input_name, output_name, input_size, args)
+
+
+if __name__ == '__main__':
+    main()

src/tool/compare_depth_outputs.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+DepthART 两路深度输出的相关性/一致性对比。
+
+支持三种输入格式，自动识别：
+    - 汇总 NPZ（names/depths），如 ONNX 脚本 --dump-npz 生成的文件
+    - 分块汇总目录（*.npz 中含 names/depths）
+    - 旧的逐图 NPZ 目录（<图片名>.npz 中含 depth）
+
+指标（逐图计算后汇总 mean/p50/p90/min）：
+    pearson      皮尔逊相关系数
+    spearman     斯皮尔曼秩相关
+    cosine       余弦相似度
+    mae / rmse   原始量纲误差
+    aligned_*    最小二乘 scale-shift 对齐后的误差
+    rel_error    mae / mean(|ref|)
+
+用法：
+    ../../venv/bin/python src/tool/compare_depth_outputs.py \
+        --ref results/nyu654/fp32/npz --pred results/nyu654/axmodel \
+        --out results/nyu654/eval/corr_fp32_axmodel.json
+"""
+
+import argparse
+import json
+from pathlib import Path
+
+import numpy as np
+from scipy.stats import spearmanr
+from tqdm import tqdm
+
+
+def load_predictions(path):
+    path = Path(path)
+    if path.is_file():
+        files = [path]
+    elif path.is_dir():
+        files = sorted(path.glob('*.npz'))
+        if not files:
+            raise ValueError(f'目录中没有 NPZ: {path}')
+    else:
+        raise FileNotFoundError(f'路径不存在: {path}')
+
+    preds = {}
+    for fp in files:
+        with np.load(fp, allow_pickle=False) as data:
+            if 'depths' in data and 'names' in data:
+                for name, depth in zip(data['names'], data['depths']):
+                    preds[str(name)] = np.asarray(depth)
+            elif 'depth' in data:
+                preds[fp.name[:-len('.npz')]] = np.asarray(data['depth'])
+            else:
+                raise ValueError(f'无法识别的 NPZ: {fp}')
+    return preds
+
+
+def compare(ref, pred):
+    a = np.asarray(ref, dtype=np.float64).ravel()
+    b = np.asarray(pred, dtype=np.float64).ravel()
+    if a.shape != b.shape:
+        raise ValueError(f'shape 不一致: {a.shape} vs {b.shape}')
+    diff = b - a
+    mae = float(np.mean(np.abs(diff)))
+    rmse = float(np.sqrt(np.mean(diff ** 2)))
+    cosine = float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b) + 1e-12))
+    pearson = float(np.corrcoef(a, b)[0, 1])
+    spearman = float(spearmanr(a, b).statistic)
+    slope, offset = np.polyfit(a, b, 1)
+    aligned = b - (slope * a + offset)
+    return {
+        'pearson': pearson,
+        'spearman': spearman,
+        'cosine': cosine,
+        'mae': mae,
+        'rmse': rmse,
+        'rel_error': mae / (np.mean(np.abs(a)) + 1e-12),
+        'scale': float(slope),
+        'offset': float(offset),
+        'aligned_mae': float(np.mean(np.abs(aligned))),
+        'aligned_rmse': float(np.sqrt(np.mean(aligned ** 2))),
+    }
+
+
+def summarize(rows):
+    keys = ('pearson', 'spearman', 'cosine', 'rel_error', 'aligned_rmse')
+    out = {}
+    for k in keys:
+        values = np.array([r[k] for r in rows])
+        out[k] = {'mean': float(values.mean()), 'p50': float(np.percentile(values, 50)),
+                  'p90': float(np.percentile(values, 90)), 'min': float(values.min())}
+    return out
+
+
+def main():
+    parser = argparse.ArgumentParser(description='两路深度输出相关性对比')
+    parser.add_argument('--ref', required=True, help='参考输出（基准后端）')
+    parser.add_argument('--pred', required=True, help='待比较输出')
+    parser.add_argument('--out', help='结果 JSON 路径')
+    args = parser.parse_args()
+
+    ref = load_predictions(args.ref)
+    pred = load_predictions(args.pred)
+    names = sorted(set(ref) & set(pred))
+    if not names:
+        raise ValueError('两路输出没有同名样本')
+    missing = (len(ref) - len(names)) + (len(pred) - len(names))
+    if missing:
+        print(f'警告: {missing} 个样本名称不匹配，已忽略')
+
+    rows = []
+    for name in tqdm(names, desc='compare', ncols=80):
+        rows.append({'name': name, **compare(ref[name], pred[name])})
+
+    summary = summarize(rows)
+    low = [r for r in rows if r['pearson'] < 0.9]
+    worst = sorted(rows, key=lambda r: r['pearson'])[:5]
+    report = {
+        'ref': str(args.ref), 'pred': str(args.pred),
+        'num_samples': len(rows),
+        'summary': summary,
+        'pearson_below_0.9': len(low),
+        'worst': [{'name': r['name'], 'pearson': r['pearson'],
+                   'mae': r['mae'], 'aligned_rmse': r['aligned_rmse']} for r in worst],
+        'per_image': rows,
+    }
+    print(f'\n样本数 {len(rows)}，pearson<0.9 的 {len(low)} 张')
+    print(f'{"指标":<14}{"mean":>12}{"p50":>12}{"p90":>12}{"min":>12}')
+    for k, v in summary.items():
+        print(f'{k:<14}{v["mean"]:>12.4f}{v["p50"]:>12.4f}{v["p90"]:>12.4f}{v["min"]:>12.4f}')
+    print('\n最差 5 张:')
+    for r in worst:
+        print(f'  {r["name"]:<32} pearson={r["pearson"]:.4f} mae={r["mae"]:.4f}')
+
+    if args.out:
+        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
+        with open(args.out, 'w') as fp:
+            json.dump(report, fp, indent=2)
+        print(f'\n结果已保存: {args.out}')
+
+
+if __name__ == '__main__':
+    main()

src/tool/compare_onnx_axmodel.py

@@ -0,0 +1,546 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Depth Anything V2：ONNX 与 AXMODEL 原始输出一致性对比。
+
+对同一批图片分别运行 ONNX 和 axmodel，在模型分辨率下比较两路深度输出
+（相对逆深度，数值越大越近），逐样本计算相似度指标，并汇总为 Markdown 文档。
+
+两个后端的输入预处理可以不同，但 resize 与颜色顺序必须一致：
+    默认 ONNX 做 /255 + ImageNet mean/std，axmodel 送 0-255 原始像素
+    （对应编译时把归一化写进 input_processors / calibration_mean/std 的方案）。
+如果 axmodel 重编译后仍需脚本侧归一化，使用 --axmodel-norm imagenet。
+
+指标：
+    cosine          两路输出的余弦相似度
+    pearson         皮尔逊相关系数
+    mae / rmse      绝对误差均值 / 均方根
+    max_abs/p99_abs 最大误差 / 99 分位误差
+    aligned_mae     最小二乘 scale-shift 对齐后的 MAE（区分全局尺度漂移与结构误差）
+    aligned_rmse    对齐后的 RMSE
+    rel_error       mae / mean(|onnx|)
+
+依赖：numpy、opencv-python、onnxruntime、axengine（板端 pyaxengine）。
+
+用法（在 hs/Depth-Anything-V2 目录下执行）：
+    # 离线比较已有结果（开发机，无需 axengine 或模型文件）
+    python3 src/tool/compare_onnx_axmodel.py \
+        --onnx-results results/onnx_full --axmodel-results results/board_full \
+        --output results/compare_full/onnx_vs_axmodel.md
+
+    # 单图
+    python3 src/tool/compare_onnx_axmodel.py \
+        --onnx depth_anything_v2_vits.onnx \
+        --axmodel depth_anything_v2_vits_ax650.axmodel \
+        --image /path/a.jpg --output results/compare/single.md
+
+    # 数据集（递归收集图片），默认 axmodel 送 0-255
+    python3 src/tool/compare_onnx_axmodel.py \
+        --onnx depth_anything_v2_vits.onnx \
+        --axmodel depth_anything_v2_vits_ax650.axmodel \
+        --dataset /path/images --limit 50 \
+        --output results/compare/onnx_vs_axmodel.md
+
+    # axmodel 仍需要脚本侧做 ImageNet 归一化时
+    python3 src/tool/compare_onnx_axmodel.py \
+        --onnx depth_anything_v2_vits.onnx --axmodel other.axmodel \
+        --dataset /path/images --axmodel-norm imagenet \
+        --output results/compare/onnx_vs_axmodel.md
+
+注意：
+    - axmodel 的输出名可能被编译器改写，脚本先按名字、再按 shape 回退绑定。
+    - 两个后端的输出 shape 必须一致；不一致时直接报错并打印实际接口。
+    - 结果默认输出到 results/compare/，不写预测 NPZ。
+"""
+
+import argparse
+import json
+import logging
+import time
+from datetime import datetime
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+MEAN = np.array([0.485, 0.456, 0.406], dtype=np.float32)
+STD = np.array([0.229, 0.224, 0.225], dtype=np.float32)
+EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.tif', '.tiff'}
+METRICS = ('cosine', 'pearson', 'mae', 'rmse', 'max_abs', 'p99_abs',
+           'aligned_mae', 'aligned_rmse', 'rel_error')
+
+
+def meta_type(meta):
+    return str(getattr(meta, 'type', getattr(meta, 'dtype', ''))).lower()
+
+
+def input_spec(shape, type_name, model_name):
+    shape = list(shape)
+    if len(shape) != 4 or not all(isinstance(v, int) and v > 0 for v in shape):
+        raise ValueError(f'{model_name} 输入必须是静态 4D NHWC/NCHW: {shape}')
+    if shape[0] != 1:
+        raise ValueError(f'{model_name} 仅支持 batch=1: {shape}')
+    if shape[1] == 3:
+        layout, size = 'NCHW', (shape[2], shape[3])
+    elif shape[3] == 3:
+        layout, size = 'NHWC', (shape[1], shape[2])
+    else:
+        raise ValueError(f'{model_name} 输入必须含 3 通道: {shape}')
+    if 'float' in type_name:
+        dtype = np.float32
+    elif 'uint8' in type_name or type_name.endswith('u8'):
+        dtype = np.uint8
+    elif 'int8' in type_name:
+        dtype = np.int8
+    else:
+        raise ValueError(f'{model_name} 不支持的输入类型: {type_name!r}')
+    return size, layout, dtype
+
+
+def onnx_interface(session):
+    inputs, outputs = session.get_inputs(), session.get_outputs()
+    logging.info('ONNX 输入: %s', [(m.name, m.shape, m.type) for m in inputs])
+    logging.info('ONNX 输出: %s', [(m.name, m.shape, m.type) for m in outputs])
+    if len(inputs) != 1:
+        raise ValueError(f'ONNX 应有 1 个输入: {[(m.name, m.shape) for m in inputs]}')
+    meta = inputs[0]
+    if 'float' not in str(meta.type):
+        raise ValueError(f'ONNX 输入要求 float32: {meta.name} {meta.type}')
+    size, layout, dtype = input_spec(meta.shape, str(meta.type), 'ONNX')
+    return meta.name, size, layout, dtype, outputs[0].name
+
+
+def axmodel_interface(session):
+    inputs, outputs = session.get_inputs(), session.get_outputs()
+    logging.info('AXMODEL 输入: %s', [(m.name, m.shape, meta_type(m)) for m in inputs])
+    logging.info('AXMODEL 输出: %s', [(m.name, m.shape, meta_type(m)) for m in outputs])
+    if len(inputs) != 1:
+        raise ValueError(f'axmodel 应有 1 个输入: {[(m.name, m.shape) for m in inputs]}')
+    meta = inputs[0]
+    size, layout, dtype = input_spec(meta.shape, meta_type(meta), 'AXMODEL')
+    return meta, size, layout, dtype, outputs
+
+
+def preprocess(image, size, layout, dtype, resize_mode, color_order, norm):
+    target_h, target_w = size
+    original_h, original_w = image.shape[:2]
+    if color_order == 'rgb':
+        image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+    if resize_mode == 'pad':
+        scale = min(target_h / original_h, target_w / original_w)
+        new_h = max(1, min(target_h, int(round(original_h * scale))))
+        new_w = max(1, min(target_w, int(round(original_w * scale))))
+        resized = cv2.resize(image, (new_w, new_h), interpolation=cv2.INTER_LINEAR)
+        canvas = np.zeros((target_h, target_w, 3), dtype=np.float32)
+        canvas[:new_h, :new_w] = resized
+        image_size = (new_h, new_w)
+    else:
+        canvas = cv2.resize(image, (target_w, target_h),
+                            interpolation=cv2.INTER_LINEAR).astype(np.float32)
+        image_size = (target_h, target_w)
+    canvas = canvas.astype(np.float32, copy=False)
+    if norm == 'imagenet':
+        if dtype != np.float32:
+            raise ValueError('整数输入不能使用 ImageNet 归一化')
+        canvas = (canvas / 255.0 - MEAN) / STD
+    if dtype != np.float32:
+        canvas = np.rint(np.clip(canvas, 0, 255)).astype(dtype)
+    tensor = canvas.transpose(2, 0, 1) if layout == 'NCHW' else canvas
+    return np.ascontiguousarray(tensor[None]), image_size
+
+
+def to_2d(array, model_name):
+    array = np.asarray(array)
+    if array.ndim == 4:
+        if array.shape[0] != 1:
+            raise ValueError(f'{model_name} 输出 batch 必须为 1: {array.shape}')
+        if array.shape[1] == 1:
+            array = array[0, 0]
+        elif array.shape[3] == 1:
+            array = array[0, :, :, 0]
+        else:
+            raise ValueError(f'{model_name} 输出无法压缩为 2D: {array.shape}')
+    elif array.ndim == 3:
+        if array.shape[0] == 1:
+            array = array[0]
+        elif array.shape[2] == 1:
+            array = array[:, :, 0]
+        else:
+            raise ValueError(f'{model_name} 输出无法压缩为 2D: {array.shape}')
+    if array.ndim != 2:
+        raise ValueError(f'{model_name} 输出必须是 2D 深度图: {array.shape}')
+    array = array.astype(np.float32, copy=False)
+    if not np.isfinite(array).all():
+        raise ValueError(f'{model_name} 输出包含 nan/inf')
+    return array
+
+
+def select_ax_output(outputs, metas, expected_shape):
+    if not isinstance(outputs, (list, tuple)):
+        outputs = [outputs]
+    if len(outputs) != len(metas):
+        raise ValueError(f'axmodel 输出数量不一致: {len(outputs)} vs {len(metas)}')
+    for index, meta in enumerate(metas):
+        if any(token in str(meta.name).lower() for token in ('depth', 'output')):
+            array = to_2d(outputs[index], 'AXMODEL')
+            if array.shape == expected_shape:
+                return array, str(meta.name)
+    candidates = []
+    for index, array in enumerate(outputs):
+        candidate = to_2d(array, 'AXMODEL')
+        if candidate.shape == expected_shape:
+            candidates.append((index, candidate))
+    if len(candidates) != 1:
+        raise ValueError('axmodel 输出无法按 name 或 shape 唯一匹配'
+                         f' {expected_shape}: {[(m.name, np.asarray(o).shape) for m, o in zip(metas, outputs)]}')
+    index, candidate = candidates[0]
+    return candidate, str(metas[index].name)
+
+
+def compare_arrays(reference, actual):
+    ref = reference.astype(np.float64).ravel()
+    act = actual.astype(np.float64).ravel()
+    diff = act - ref
+    ref_norm = np.linalg.norm(ref)
+    act_norm = np.linalg.norm(act)
+    cosine = float(np.dot(ref, act) / (ref_norm * act_norm + 1e-12))
+    if ref.std() > 1e-12 and act.std() > 1e-12:
+        pearson = float(np.corrcoef(ref, act)[0, 1])
+    else:
+        pearson = float('nan')
+    slope, offset = np.polyfit(ref, act, 1)
+    aligned = act - (slope * ref + offset)
+    abs_diff = np.abs(diff)
+    return {
+        'cosine': cosine,
+        'pearson': pearson,
+        'mae': float(abs_diff.mean()),
+        'rmse': float(np.sqrt(np.mean(diff ** 2))),
+        'max_abs': float(abs_diff.max()),
+        'p99_abs': float(np.percentile(abs_diff, 99)),
+        'aligned_mae': float(np.abs(aligned).mean()),
+        'aligned_rmse': float(np.sqrt(np.mean(aligned ** 2))),
+        'rel_error': float(abs_diff.mean() / (np.abs(ref).mean() + 1e-12)),
+    }
+
+
+def summarize(records):
+    summary = {}
+    for key in METRICS:
+        values = np.array([record[key] for record in records], dtype=np.float64)
+        values = values[np.isfinite(values)]
+        if values.size == 0:
+            summary[key] = None
+            continue
+        summary[key] = {'mean': float(values.mean()),
+                        'median': float(np.percentile(values, 50)),
+                        'p90': float(np.percentile(values, 90)),
+                        'p99': float(np.percentile(values, 99)),
+                        'min': float(values.min()),
+                        'max': float(values.max())}
+    return summary
+
+
+def format_value(value):
+    if value is None:
+        return '-'
+    if isinstance(value, float) and not np.isfinite(value):
+        return '-'
+    return f'{value:.6g}'
+
+
+def write_markdown(path, report):
+    lines = ['# Depth Anything V2：ONNX 与 AXMODEL 输出一致性', '']
+    lines.append(f'- 生成时间：{report["created"]}')
+    lines.append(f'- 样本数：{report["sample_count"]}')
+    lines.append(f'- 结果目录：`{report["output_dir"]}`')
+    if report['limit'] is not None:
+        lines.append(f'- 样本上限：{report["limit"]}')
+    lines.append('')
+    if report.get('mode') == 'results':
+        lines.extend([
+            '## 结果来源', '',
+            f'- ONNX：`{report["onnx_results"]}`',
+            f'- AXMODEL：`{report["axmodel_results"]}`',
+            '- 按相对路径匹配同名 `.depth.npy`，比较保存的深度图，不重新推理或 resize。',
+            '- 这些文件由推理脚本还原至原图尺寸，指标对应保存结果的像素空间。',
+            '- 离线比较不测量推理耗时；预处理配置以原推理记录为准。', '',
+        ])
+    else:
+        lines.append('## 模型与预处理')
+        lines.append('')
+        lines.append('| 项 | ONNX | AXMODEL |')
+        lines.append('| --- | --- | --- |')
+        lines.append(f'| 模型 | `{report["onnx"]["path"]}` | `{report["axmodel"]["path"]}` |')
+        lines.append(f'| 运行时 | {report["onnx"]["runtime"]} | {report["axmodel"]["runtime"]} |')
+        lines.append(f'| 输入 | {report["onnx"]["input"]} | {report["axmodel"]["input"]} |')
+        lines.append(f'| 输出 | {report["onnx"]["output"]} | {report["axmodel"]["output"]} |')
+        lines.append(f'| 归一化 | {report["onnx"]["norm"]} | {report["axmodel"]["norm"]} |')
+        lines.append(f'| resize | {report["resize_mode"]} | {report["resize_mode"]} |')
+        lines.append(f'| 颜色顺序 | {report["color_order"]} | {report["color_order"]} |')
+        lines.append(f'| warmup | {report["warmup"]} | {report["warmup"]} |')
+        lines.append('')
+    lines.append('## 汇总指标')
+    lines.append('')
+    lines.append('| 指标 | mean | median | p90 | p99 | min | max |')
+    lines.append('| --- | --- | --- | --- | --- | --- | --- |')
+    for key in METRICS:
+        stats = report['summary'][key]
+        if stats is None:
+            lines.append(f'| {key} | - | - | - | - | - | - |')
+        else:
+            lines.append(f'| {key} | {format_value(stats["mean"])} | '
+                         f'{format_value(stats["median"])} | {format_value(stats["p90"])} | '
+                         f'{format_value(stats["p99"])} | {format_value(stats["min"])} | '
+                         f'{format_value(stats["max"])} |')
+    lines.append('')
+    lines.append('## 逐样本结果')
+    lines.append('')
+    lines.append('| # | 图片 | cosine | pearson | mae | rmse | max_abs | p99_abs | '
+                 'aligned_mae | aligned_rmse | rel_error | ONNX ms | AXMODEL ms |')
+    lines.append('| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |')
+    for index, sample in enumerate(report['samples'], 1):
+        metrics = sample['metrics']
+        lines.append(
+            f'| {index} | `{sample["name"]}` | {format_value(metrics["cosine"])} | '
+            f'{format_value(metrics["pearson"])} | {format_value(metrics["mae"])} | '
+            f'{format_value(metrics["rmse"])} | {format_value(metrics["max_abs"])} | '
+            f'{format_value(metrics["p99_abs"])} | {format_value(metrics["aligned_mae"])} | '
+            f'{format_value(metrics["aligned_rmse"])} | {format_value(metrics["rel_error"])} | '
+            f'{format_value(sample["onnx_ms"])} | {format_value(sample["axmodel_ms"])} |')
+    lines.append('')
+    lines.append('## 指标说明')
+    lines.append('')
+    lines.append('- `cosine`：两路输出的余弦相似度，1 表示方向完全一致。')
+    lines.append('- `pearson`：线性相关系数，衡量结构一致性，对全局尺度不敏感。')
+    lines.append('- `mae` / `rmse`：未对齐的绝对误差，包含量化误差与整体尺度漂移。')
+    lines.append('- `max_abs` / `p99_abs`：最大误差和 99 分位误差，反映局部离群点。')
+    lines.append('- `aligned_mae` / `aligned_rmse`：先做最小二乘 scale-shift 对齐再计算，'
+                 '用于区分全局尺度漂移和真正的结构偏差。')
+    lines.append('- `rel_error`：`mae / mean(|ONNX|)`，便于跨图片比较。')
+    lines.append('')
+    lines.append('## 判定参考')
+    lines.append('')
+    lines.append(f'- 余弦相似度均值：{format_value(report["summary"]["cosine"]["mean"])}')
+    lines.append(f'- 对齐后 MAE 均值：{format_value(report["summary"]["aligned_mae"]["mean"])}')
+    lines.append(f'- 未���齐相对误差均值：'
+                 f'{format_value(report["summary"]["rel_error"]["mean"])}')
+    lines.append('')
+    lines.append('若 `cosine` 接近 1 但 `mae` 明显偏大、`aligned_mae` 很小，说明两路输出只存在'
+                 '整体尺度/偏移差异；若 `aligned_mae` 也明显偏大，则更可能是量化本身造成的'
+                 '结构失真，需要结合逐层精度分析继续定位。')
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text('\n'.join(lines) + '\n', encoding='utf-8')
+
+
+def collect_images(dataset):
+    paths = sorted(p for p in dataset.rglob('*')
+                   if p.is_file() and p.suffix.lower() in EXTENSIONS)
+    if not paths:
+        raise ValueError(f'目录中没有图片: {dataset}')
+    return paths
+
+
+def compare_result_dirs(args):
+    from tqdm import tqdm
+
+    files = []
+    for directory in (args.onnx_results, args.axmodel_results):
+        if not directory.is_dir():
+            raise ValueError(f'结果目录不存在: {directory}')
+        mapping = {p.relative_to(directory).as_posix(): p
+                   for p in directory.rglob('*.depth.npy') if p.is_file()}
+        if not mapping:
+            raise ValueError(f'结果目录中没有 *.depth.npy: {directory}')
+        files.append(mapping)
+    onnx_files, axmodel_files = files
+    if onnx_files.keys() != axmodel_files.keys():
+        onnx_only = sorted(onnx_files.keys() - axmodel_files.keys())
+        axmodel_only = sorted(axmodel_files.keys() - onnx_files.keys())
+        raise ValueError(f'结果文件未完全配对: ONNX 独有 {len(onnx_only)} 个 '
+                         f'{onnx_only[:5]}, AXMODEL 独有 {len(axmodel_only)} 个 '
+                         f'{axmodel_only[:5]}')
+    names = sorted(onnx_files)
+    if args.limit is not None:
+        names = names[:args.limit]
+    records = []
+    for name in tqdm(names, desc='比较深度输出', disable=len(names) == 1):
+        reference = to_2d(np.load(onnx_files[name], allow_pickle=False), f'ONNX {name}')
+        actual = to_2d(np.load(axmodel_files[name], allow_pickle=False), f'AXMODEL {name}')
+        if reference.size == 0 or reference.shape != actual.shape:
+            raise ValueError(f'{name} 深度图为空或 shape 不一致: '
+                             f'ONNX {reference.shape} vs AXMODEL {actual.shape}')
+        metrics = compare_arrays(reference, actual)
+        if args.debug:
+            logging.info('%s: %s', name, metrics)
+        records.append({'name': name[:-len('.depth.npy')], 'metrics': metrics,
+                        'onnx_ms': None, 'axmodel_ms': None})
+    report = {
+        'mode': 'results',
+        'created': datetime.now().astimezone().isoformat(timespec='seconds'),
+        'output_dir': str(args.output.resolve().parent),
+        'onnx_results': str(args.onnx_results.resolve()),
+        'axmodel_results': str(args.axmodel_results.resolve()),
+        'sample_count': len(records), 'limit': args.limit,
+        'summary': summarize([record['metrics'] for record in records]),
+        'samples': records,
+    }
+    write_markdown(args.output, report)
+    logging.info('样本数 %d，cosine mean=%.6f，aligned_mae mean=%.6g，报告: %s',
+                 len(records), report['summary']['cosine']['mean'],
+                 report['summary']['aligned_mae']['mean'], args.output)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='计算 ONNX 与 AXMODEL 深度输出的相似度并生成 Markdown 报告',
+        formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__)
+    parser.add_argument('--onnx', type=Path, help='FP32 ONNX 模型')
+    parser.add_argument('--axmodel', type=Path, help='编译后的 axmodel')
+    parser.add_argument('--onnx-results', type=Path, help='ONNX 结果目录（递归读取 *.depth.npy）')
+    parser.add_argument('--axmodel-results', type=Path, help='AXMODEL 结果目录（相对路径必须完全配对）')
+    source = parser.add_mutually_exclusive_group()
+    source.add_argument('--image', type=Path, help='单张图片')
+    source.add_argument('--dataset', type=Path, help='图片目录（递归）')
+    parser.add_argument('--output', type=Path,
+                        default=Path(__file__).resolve().parents[2] / 'results' /
+                        'compare' / 'onnx_vs_axmodel.md',
+                        help='Markdown 输出路径，默认 results/compare/onnx_vs_axmodel.md')
+    parser.add_argument('--resize-mode', choices=('stretch', 'pad'), default='stretch',
+                        help='两个后端共用的 resize 方式，默认 stretch')
+    parser.add_argument('--color-order', choices=('rgb', 'bgr'), default='rgb',
+                        help='两个后端共用的颜色顺序，默认 rgb')
+    parser.add_argument('--onnx-norm', choices=('imagenet', 'raw'), default='imagenet',
+                        help='ONNX 输入归一化，默认 imagenet')
+    parser.add_argument('--axmodel-norm', choices=('imagenet', 'raw'), default='raw',
+                        help='axmodel 输入归一化，默认 raw（编译时已吸收归一化）')
+    parser.add_argument('--warmup', type=int, default=3,
+                        help='数据集模式每个后端的 warmup 次数，默认 3')
+    parser.add_argument('--limit', type=int, help='数据集模式只处理前 N 张')
+    parser.add_argument('--debug', action='store_true', help='打印逐样本输入/输出统计')
+    args = parser.parse_args()
+    logging.basicConfig(level=logging.INFO, format='%(message)s')
+    if args.warmup < 0:
+        parser.error('--warmup 不能为负数')
+    if args.limit is not None and args.limit < 1:
+        parser.error('--limit 必须为正数')
+    if args.onnx_results is not None or args.axmodel_results is not None:
+        if args.onnx_results is None or args.axmodel_results is None:
+            parser.error('--onnx-results 和 --axmodel-results 必须同时提供')
+        if any(value is not None for value in (args.onnx, args.axmodel, args.image, args.dataset)):
+            parser.error('结果目录模式不能同时指定模型或图片输入')
+        compare_result_dirs(args)
+        return
+    if args.onnx is None or args.axmodel is None or (args.image is None and args.dataset is None):
+        parser.error('推理模式必须提供 --onnx、--axmodel 和 --image/--dataset；'
+                     '或使用 --onnx-results 和 --axmodel-results 进行离线比较')
+    if not args.onnx.is_file():
+        parser.error(f'--onnx 不存在: {args.onnx}')
+    if not args.axmodel.is_file():
+        parser.error(f'--axmodel 不存在: {args.axmodel}')
+
+    import onnxruntime as ort
+    import axengine
+    onnx_session = ort.InferenceSession(str(args.onnx))
+    axmodel_session = axengine.InferenceSession(str(args.axmodel))
+    onnx_input, onnx_size, onnx_layout, onnx_dtype, onnx_output = onnx_interface(onnx_session)
+    ax_meta, ax_size, ax_layout, ax_dtype, ax_outputs = axmodel_interface(axmodel_session)
+    if onnx_size != ax_size:
+        raise ValueError(f'两个后端输入尺寸不一致: ONNX {onnx_size} vs AXMODEL {ax_size}')
+
+    if args.image:
+        if not args.image.is_file():
+            parser.error(f'--image 不是文件: {args.image}')
+        images = [args.image]
+        root = args.image.parent
+    else:
+        if not args.dataset.is_dir():
+            parser.error(f'--dataset 不是目录: {args.dataset}')
+        images = collect_images(args.dataset)
+        if args.limit is not None:
+            images = images[:args.limit]
+        root = args.dataset
+
+    if args.axmodel_norm == 'imagenet' and ax_dtype != np.float32:
+        parser.error('axmodel 输入为整数类型，不能使用 --axmodel-norm imagenet')
+
+    # 数据集模式先 warmup，使用第一张图。
+    if len(images) > 1 and args.warmup:
+        first = cv2.imread(str(images[0]), cv2.IMREAD_COLOR)
+        if first is None:
+            raise ValueError(f'读取图片失败: {images[0]}')
+        onnx_tensor, _ = preprocess(first, onnx_size, onnx_layout, onnx_dtype,
+                                    args.resize_mode, args.color_order, args.onnx_norm)
+        ax_tensor, _ = preprocess(first, ax_size, ax_layout, ax_dtype,
+                                  args.resize_mode, args.color_order, args.axmodel_norm)
+        for _ in range(args.warmup):
+            onnx_session.run([onnx_output], {onnx_input: onnx_tensor})
+            axmodel_session.run(None, {ax_meta.name: ax_tensor})
+        logging.info('两个后端各 warmup %d 次', args.warmup)
+
+    records = []
+    for path in images:
+        name = str(path.relative_to(root)) if path != root else path.name
+        image = cv2.imread(str(path), cv2.IMREAD_COLOR)
+        if image is None:
+            raise ValueError(f'读取图片失败: {path}')
+        onnx_tensor, _ = preprocess(image, onnx_size, onnx_layout, onnx_dtype,
+                                    args.resize_mode, args.color_order, args.onnx_norm)
+        ax_tensor, _ = preprocess(image, ax_size, ax_layout, ax_dtype,
+                                  args.resize_mode, args.color_order, args.axmodel_norm)
+
+        start = time.perf_counter()
+        onnx_raw = onnx_session.run([onnx_output], {onnx_input: onnx_tensor})[0]
+        onnx_ms = (time.perf_counter() - start) * 1000
+        start = time.perf_counter()
+        ax_outputs_data = axmodel_session.run(None, {ax_meta.name: ax_tensor})
+        axmodel_ms = (time.perf_counter() - start) * 1000
+
+        reference = to_2d(onnx_raw, 'ONNX')
+        actual, ax_output_name = select_ax_output(ax_outputs_data, ax_outputs,
+                                                  reference.shape)
+        metrics = compare_arrays(reference, actual)
+        if not np.isfinite(metrics['cosine']):
+            raise ValueError(f'{name} 无法计算相似度，请检查输出是否常数')
+        if args.debug:
+            logging.info('%s: ONNX min=%.4f max=%.4f mean=%.4f | AXMODEL min=%.4f '
+                         'max=%.4f mean=%.4f | cosine=%.6f mae=%.6g',
+                         name, float(reference.min()), float(reference.max()),
+                         float(reference.mean()), float(actual.min()),
+                         float(actual.max()), float(actual.mean()),
+                         metrics['cosine'], metrics['mae'])
+        records.append({'name': name, 'metrics': metrics,
+                        'onnx_ms': onnx_ms, 'axmodel_ms': axmodel_ms})
+        if len(images) == 1:
+            logging.info('输出绑定: ONNX=%s AXMODEL=%s', onnx_output, ax_output_name)
+            logging.info('指标: %s', json.dumps(metrics, ensure_ascii=False))
+
+    report = {
+        'created': datetime.now().astimezone().isoformat(timespec='seconds'),
+        'output_dir': str(args.output.resolve().parent),
+        'sample_count': len(records),
+        'limit': args.limit if not args.image else None,
+        'warmup': args.warmup if len(images) > 1 else 0,
+        'resize_mode': args.resize_mode,
+        'color_order': args.color_order,
+        'onnx': {'path': str(args.onnx.resolve()),
+                 'runtime': 'onnxruntime ' + ort.__version__,
+                 'input': f'{onnx_input} {onnx_tensor.shape}',
+                 'output': onnx_output,
+                 'norm': args.onnx_norm},
+        'axmodel': {'path': str(args.axmodel.resolve()),
+                    'runtime': getattr(axengine, '__version__', 'unknown'),
+                    'input': f'{ax_meta.name} {tuple(ax_meta.shape)} {np.dtype(ax_dtype).name}',
+                    'output': ax_output_name,
+                    'norm': args.axmodel_norm},
+        'summary': summarize([record['metrics'] for record in records]),
+        'samples': records,
+    }
+    write_markdown(args.output, report)
+    logging.info('样本数 %d，cosine mean=%.6f，aligned_mae mean=%.6g，报告: %s',
+                 len(records), report['summary']['cosine']['mean'],
+                 report['summary']['aligned_mae']['mean'], args.output)
+
+
+if __name__ == '__main__':
+    main()

src/tool/depthart_export_axonnx.py

@@ -0,0 +1,555 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+把 DepthART ONNX 中的 com.depthart::SelectiveScan 改写为 pulsar2 可编译的纯 ONNX 子图。
+
+背景：
+    官方 relative_* ONNX 含自定义算子 SelectiveScan，pulsar2 前端直接报
+    "dont support SelectiveScan opr"。官方只提供 TensorRT 插件，没有 NPU 实现。
+    推理脚本里的 Loop 改写可以跑通 onnxruntime，但 AX 工具链不支持 Loop 控制流。
+
+做法：
+    选择性扫描是线性递推 h_t = exp(dt_t*A) * h_{t-1} + dt_t*B_t*u_t，可写成
+        h_t = exp(L_t) * h_{-1} + sum_{s<=t} exp(L_t - L_s) * dt_s*B_s*u_s
+    其中 L_t = cumsum_{r<=t}(dt_r*A)。把时间轴切成固定长度 T（默认 14），每个
+    分块内用 CumSum + 下三角 mask + MatMul 一次算出，块间只传一个状态。所有
+    指数项的指数都 <= 0，不会溢出。所有算子（CumSum/Exp/Where/MatMul 等）都在
+    AX 前端支持列表内，不含 Loop/Scan/自定义算子。
+
+校验：
+    - 本工具用 Identity 替换 scan 跑一遍，拿到每个 scan 的 D/G/N/L，再按实际
+      尺寸生成静态图；时间轴不是 T 整数倍时自动补零并在输出处裁掉。
+    - 改写后的整模型输出与已验证的 Loop 版本最大绝对误差约 6e-6（FP32）。
+    - 同时把 4D `Einsum` 换成按 k 的批 MatMul（`b k d l, k c d -> b k c l`
+      和 `b k r l, k d r -> b k d l`）：pulsar2 的量化执行器不支持 4D Einsum，
+      会报 Op Execution Error。
+
+用法（在 hs/DepthART 目录下执行）：
+    # 默认：448 模型，块大小 14，输出 onnx/relative_s_448_default_axonnx.onnx
+    ../../venv/bin/python src/tool/depthart_export_axonnx.py
+
+    # 指定模型/输出/块大小
+    ../../venv/bin/python src/tool/depthart_export_axonnx.py \\
+        --model onnx/relative_b_448_default.onnx \\
+        --output onnx/relative_b_448_default_axonnx.onnx --chunk-size 14
+
+    # 改写后用推理脚本验证数值
+    ../../venv/bin/python src/infer/depthart_infer_onnx.py \\
+        --model onnx/relative_s_448_default_axonnx.onnx --image /path/a.jpg
+
+注意：
+    - 块内两两指数矩阵形状为 [D*N, T, T]，T 越大显存/内存占用越大；
+      T=14 时 672 通道层约 1M 元素（4 MB），推荐保持默认。
+    - 输出是标准 ONNX，不再含自定义算子；原模型文件不会被修改。
+"""
+
+import argparse
+import logging
+from pathlib import Path
+
+import numpy as np
+import onnx
+import onnxruntime as ort
+from onnx import helper, numpy_helper, TensorProto
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_MODEL = PROJECT_ROOT / 'onnx' / 'relative_s_448_default.onnx'
+DOMAIN = 'com.depthart'
+OP = 'SelectiveScan'
+
+
+EINSUM_EQUATIONS = {
+    'b k d l, k c d -> b k c l',
+    'b k r l, k d r -> b k d l',
+}
+
+
+def collect_runtime_shapes(model):
+    """用 ORT 实际跑一遍，读取 scan 与 Einsum 的静态形状。
+
+    scan 会被替换成 Identity（输出形状等于 u，不影响下游形状）；Einsum 正常执行。
+    返回 (scan_shapes, einsum_shapes)：
+        scan_shapes  : 按图顺序的 [(D, G, N, L), ...]
+        einsum_shapes: {节点名: (x_shape, y_shape)}
+    """
+    nodes = []
+    scan_outputs, b_aliases = [], {}
+    einsum_x, einsum_y = {}, {}
+    for index, node in enumerate(model.graph.node):
+        if node.domain == DOMAIN and node.op_type == OP:
+            nodes.append(helper.make_node('Identity', [node.input[0]], [node.output[0]],
+                                          name=f'depthart_stub_scan_{index}'))
+            alias = f'depthart_stub_b_{index}'
+            nodes.append(helper.make_node('Identity', [node.input[3]], [alias],
+                                          name=f'depthart_stub_bnode_{index}'))
+            scan_outputs.append(node.output[0])
+            b_aliases[node.output[0]] = alias
+        else:
+            if node.op_type == 'Einsum':
+                x_alias = f'depthart_stub_einsum_x_{index}'
+                y_alias = f'depthart_stub_einsum_y_{index}'
+                nodes.append(helper.make_node('Identity', [node.input[0]], [x_alias],
+                                              name=f'{x_alias}_node'))
+                nodes.append(helper.make_node('Identity', [node.output[0]], [y_alias],
+                                              name=f'{y_alias}_node'))
+                einsum_x[node.name] = x_alias
+                einsum_y[node.name] = y_alias
+            nodes.append(node)
+
+    stub = onnx.ModelProto()
+    stub.CopyFrom(model)
+    del stub.graph.node[:]
+    stub.graph.node.extend(nodes)
+    for name in scan_outputs:
+        stub.graph.output.append(helper.make_tensor_value_info(name, TensorProto.FLOAT, None))
+        stub.graph.output.append(helper.make_tensor_value_info(b_aliases[name],
+                                                               TensorProto.FLOAT, None))
+    for x_alias, y_alias in zip(einsum_x.values(), einsum_y.values()):
+        stub.graph.output.append(helper.make_tensor_value_info(x_alias, TensorProto.FLOAT, None))
+        stub.graph.output.append(helper.make_tensor_value_info(y_alias, TensorProto.FLOAT, None))
+
+    meta = model.graph.input[0]
+    shape = [dim.dim_value for dim in meta.type.tensor_type.shape.dim]
+    if not all(shape):
+        raise ValueError(f'输入必须是静态形状: {meta.name} {shape}')
+    session = ort.InferenceSession(stub.SerializeToString())
+    values = dict(zip([out.name for out in session.get_outputs()],
+                      session.run(None, {meta.name: np.zeros(shape, dtype=np.float32)})))
+
+    scan_map = {}
+    for name in scan_outputs:
+        u_shape = values[name].shape
+        b_shape = values[b_aliases[name]].shape
+        if len(u_shape) != 3 or len(b_shape) != 4:
+            raise ValueError(f'scan 形状不符合预期: u={u_shape} B={b_shape}')
+        scan_map[name] = (int(u_shape[1]), int(b_shape[1]), int(b_shape[2]), int(u_shape[2]))
+    scan_shapes = [scan_map[node.output[0]] for node in model.graph.node
+                   if node.domain == DOMAIN and node.op_type == OP]
+    einsum_shapes = {name: (values[einsum_x[name]].shape, values[einsum_y[name]].shape)
+                     for name in einsum_x}
+    return scan_shapes, einsum_shapes
+
+
+class Rewriter:
+    def __init__(self, model, chunk_size, stub_scan=False, scan_method='pairwise'):
+        self.model = model
+        self.chunk_size = chunk_size
+        self.stub_scan = stub_scan
+        self.scan_method = scan_method
+        self.initializers = list(model.graph.initializer)
+        self.names = {tensor.name for tensor in self.initializers}
+        self.initializer_shapes = {tensor.name: tuple(tensor.dims)
+                                   for tensor in model.graph.initializer}
+        self.shared = {}
+
+    def build_einsum(self, prefix, node, x_shape, y_shape):
+        """b k d l, k c d -> b k c l  （以及 b k r l, k d r -> b k d l）。
+
+        两条式子都是按 k 的批 MatMul：W[k,out,in] @ x[b=1,k,in,l]。
+        替换掉 4D Einsum，避免量化执行器不支持。
+        """
+        out_name = node.output[0]
+        w_shape = self.initializer_shapes.get(node.input[1])
+        if w_shape is None:
+            raise ValueError(f'{node.name}: 第二个输入不是常量权重，暂不支持')
+        if len(w_shape) != 3 or len(x_shape) != 4:
+            raise ValueError(f'{node.name}: Einsum 形状不符合预期: {w_shape} {x_shape}')
+        if int(x_shape[0]) != 1:
+            raise ValueError(f'{node.name}: 仅支持 batch=1，实际 {x_shape}')
+        K, out_dim, in_dim = (int(v) for v in w_shape)
+        length = int(x_shape[3])
+        if int(x_shape[1]) != K:
+            raise ValueError(f'{node.name}: K 不一致: {x_shape} vs {w_shape}')
+        expected = (1, K, out_dim, length)
+        if tuple(int(v) for v in y_shape) != expected:
+            raise ValueError(f'{node.name}: 输出形状 {y_shape} != {expected}')
+        nodes = []
+        # 用 Squeeze/Unsqueeze 而不是 Reshape 还原 batch 维：onnxslim 会把
+        # MatMul 前后的 Reshape 当成冗余节点合并/改名，导致下游张量断链。
+        nodes.append(helper.make_node(
+            'Squeeze', [node.input[0], self.shared_const('axes0', np.array([0], np.int64))],
+            [f'{prefix}_x2']))
+        nodes.append(helper.make_node('MatMul', [node.input[1], f'{prefix}_x2'],
+                                      [f'{prefix}_y3']))
+        nodes.append(helper.make_node(
+            'Unsqueeze', [f'{prefix}_y3', self.shared_const('axes0', np.array([0], np.int64))],
+            [out_name]))
+        return nodes
+
+    def const(self, name, value):
+        if name not in self.names:
+            self.initializers.append(numpy_helper.from_array(np.asarray(value), name))
+            self.names.add(name)
+        return name
+
+    def shared_const(self, key, value):
+        if key not in self.shared:
+            self.shared[key] = self.const(f'depthart_{key}', value)
+        return self.shared[key]
+
+    def build_logspace(self, prefix, shapes, inputs):
+        """对数空间分块递推：每块 O(T) 而非 O(T^2)，不构造 [D*N,T,T] 两两矩阵。
+
+        h_t = exp(L_t) * ( h_prev + cumsum_s( exp(-L_s) * dt_s * B_s * u_s ) )
+        其中 L 为块内相对累计衰减（L_0=0，L_t<=0）。要求块内 exp(-L) 不超 U16 量程，
+        因此 T 要小（T=4 时最大约 e^9≈8e3）。
+        """
+        D, G, N, L = shapes
+        u, delta, a, b, c = inputs[:5]
+        d = inputs[5] if len(inputs) > 5 and inputs[5] else None
+        bias = inputs[6] if len(inputs) > 6 and inputs[6] else None
+        attrs = {item.name: item.i for item in self.node_attrs}
+        T = self.chunk_size
+        nodes = []
+
+        dt = delta
+        if bias is not None:
+            bias3 = self.const(f'{prefix}_bias3_shape', np.array([1, D, 1], np.int64))
+            nodes.append(helper.make_node('Reshape', [bias, bias3], [f'{prefix}_bias3']))
+            nodes.append(helper.make_node('Add', [delta, f'{prefix}_bias3'], [f'{prefix}_dtb']))
+            dt = f'{prefix}_dtb'
+        if int(attrs.get('delta_softplus', 0)):
+            nodes.append(helper.make_node('Softplus', [dt], [f'{prefix}_dt']))
+            dt = f'{prefix}_dt'
+
+        # 补零到 T 的整数倍，避免最后一块长度不足
+        pad = (-L) % T
+        Lp = L + pad
+        if pad:
+            nodes.append(helper.make_node(
+                'Concat', [dt, self.const(f'{prefix}_pad_dt', np.zeros((1, D, pad), np.float32))],
+                [f'{prefix}_dt_pad'], axis=2))
+            nodes.append(helper.make_node(
+                'Concat', [u, self.const(f'{prefix}_pad_u', np.zeros((1, D, pad), np.float32))],
+                [f'{prefix}_u_pad'], axis=2))
+            pad_bc = self.const(f'{prefix}_pad_bc', np.zeros((1, G, N, pad), np.float32))
+            nodes.append(helper.make_node('Concat', [b, pad_bc], [f'{prefix}_b_pad'], axis=3))
+            nodes.append(helper.make_node('Concat', [c, pad_bc], [f'{prefix}_c_pad'], axis=3))
+            dt, u, b, c = (f'{prefix}_dt_pad', f'{prefix}_u_pad',
+                           f'{prefix}_b_pad', f'{prefix}_c_pad')
+
+        # dtA = dt * A -> [1,D,N,Lp]
+        a4 = self.const(f'{prefix}_a4_shape', np.array([1, D, N, 1], np.int64))
+        nodes.append(helper.make_node('Reshape', [a, a4], [f'{prefix}_a4']))
+        dt3 = self.const(f'{prefix}_dt3_shape', np.array([1, D, 1, Lp], np.int64))
+        nodes.append(helper.make_node('Reshape', [dt, dt3], [f'{prefix}_dt4']))
+        nodes.append(helper.make_node('Mul', [f'{prefix}_dt4', f'{prefix}_a4'],
+                                      [f'{prefix}_dtA']))
+
+        b_full = self.expand_groups(b, D, G, N, Lp, f'{prefix}_b', nodes)
+        c_full = self.expand_groups(c, D, G, N, Lp, f'{prefix}_c', nodes)
+
+        if d is not None:
+            nodes.append(helper.make_node('Reshape', [d,
+                                                      self.const(f'{prefix}_d_shape',
+                                                                 np.array([1, D, 1], np.int64))],
+                                          [f'{prefix}_d3']))
+            d = f'{prefix}_d3'
+
+        axes_u2 = self.shared_const('axes_u2', np.array([2], np.int64))
+        axes_rs = self.shared_const('axes_rs2', np.array([2], np.int64))
+        axis_t = self.shared_const('axis2', np.array([2], np.int64))
+        axis_bc = self.shared_const('axis3', np.array([3], np.int64))
+        h_prev = self.const(f'{prefix}_h0', np.zeros((1, D, N, 1), np.float32))
+        outputs = []
+        for k in range(Lp // T):
+            start, end = k * T, (k + 1) * T
+            tag = f'{prefix}_c{k}'
+            starts = self.const(f'{tag}_starts', np.array([start], np.int64))
+            ends = self.const(f'{tag}_ends', np.array([end], np.int64))
+            for source, suffix, axis in ((f'{prefix}_dtA', 'dta', axis_bc),
+                                         (dt, 'dt', axis_t), (u, 'u', axis_t),
+                                         (b_full, 'b', axis_bc), (c_full, 'c', axis_bc)):
+                nodes.append(helper.make_node('Slice', [source, starts, ends, axis],
+                                              [f'{tag}_{suffix}']))
+
+            # L = cumsum(dtA)（块内，含首步）；h = exp(L) * (h_prev + cumsum(exp(-L)*b))
+            nodes.append(helper.make_node('CumSum', [f'{tag}_dta',
+                                                     self.shared_const('axis3s', np.array(3, np.int64))],
+                                          [f'{tag}_L']))
+            nodes.append(helper.make_node('Exp', [f'{tag}_L'], [f'{tag}_eL']))
+            nodes.append(helper.make_node('Neg', [f'{tag}_L'], [f'{tag}_negL']))
+            nodes.append(helper.make_node('Exp', [f'{tag}_negL'], [f'{tag}_eneg']))
+
+            # b = dt * u * B；G = cumsum(exp(-Lp) * b)
+            nodes.append(helper.make_node('Unsqueeze', [f'{tag}_dt', axes_u2], [f'{tag}_dt3']))
+            nodes.append(helper.make_node('Unsqueeze', [f'{tag}_u', axes_u2], [f'{tag}_u3']))
+            nodes.append(helper.make_node('Mul', [f'{tag}_dt3', f'{tag}_u3'], [f'{tag}_dtu']))
+            nodes.append(helper.make_node('Mul', [f'{tag}_dtu', f'{tag}_b'], [f'{tag}_bt']))
+            nodes.append(helper.make_node('Mul', [f'{tag}_eneg', f'{tag}_bt'], [f'{tag}_g']))
+            nodes.append(helper.make_node('CumSum', [f'{tag}_g',
+                                                     self.shared_const('axis3s', np.array(3, np.int64))],
+                                          [f'{tag}_G']))
+            nodes.append(helper.make_node('Add', [f'{tag}_G', h_prev], [f'{tag}_hp']))
+            nodes.append(helper.make_node('Mul', [f'{tag}_eL', f'{tag}_hp'], [f'{tag}_h']))
+
+            nodes.append(helper.make_node('Mul', [f'{tag}_h', f'{tag}_c'], [f'{tag}_hc']))
+            nodes.append(helper.make_node('ReduceSum', [f'{tag}_hc', axes_rs],
+                                          [f'{tag}_ysum'], keepdims=0))
+            if d is not None:
+                nodes.append(helper.make_node('Mul', [d, f'{tag}_u'], [f'{tag}_du']))
+                nodes.append(helper.make_node('Add', [f'{tag}_ysum', f'{tag}_du'],
+                                              [f'{tag}_y']))
+            else:
+                nodes.append(helper.make_node('Identity', [f'{tag}_ysum'], [f'{tag}_y']))
+            outputs.append(f'{tag}_y')
+
+            nodes.append(helper.make_node('Slice', [f'{tag}_h',
+                                                    self.const(f'{tag}_hl', np.array([T - 1], np.int64)),
+                                                    self.const(f'{tag}_he', np.array([T], np.int64)),
+                                                    axis_bc], [f'{tag}_hnext']))
+            h_prev = f'{tag}_hnext'
+
+        nodes.append(helper.make_node('Concat', outputs, [f'{prefix}_ycat'], axis=2))
+        if pad:
+            nodes.append(helper.make_node('Slice', [
+                f'{prefix}_ycat',
+                self.const(f'{prefix}_out_start', np.array([0], np.int64)),
+                self.const(f'{prefix}_out_end', np.array([L], np.int64)),
+                self.shared_const('axis2', np.array([2], np.int64))], [self.out_name]))
+        else:
+            nodes.append(helper.make_node('Identity', [f'{prefix}_ycat'], [self.out_name]))
+        return nodes
+
+    def build(self, prefix, shapes, inputs):
+        D, G, N, L = shapes
+        u, delta, a, b, c = inputs[:5]
+        d = inputs[5] if len(inputs) > 5 and inputs[5] else None
+        bias = inputs[6] if len(inputs) > 6 and inputs[6] else None
+        attrs = {item.name: item.i for item in self.node_attrs}
+        T = self.chunk_size
+        nodes = []
+
+        # dt = softplus(delta + bias)
+        dt = delta
+        if bias is not None:
+            bias3 = self.const(f'{prefix}_bias3_shape', np.array([1, D, 1], np.int64))
+            nodes.append(helper.make_node('Reshape', [bias, bias3], [f'{prefix}_bias3']))
+            nodes.append(helper.make_node('Add', [delta, f'{prefix}_bias3'], [f'{prefix}_dtb']))
+            dt = f'{prefix}_dtb'
+        if int(attrs.get('delta_softplus', 0)):
+            nodes.append(helper.make_node('Softplus', [dt], [f'{prefix}_dt']))
+            dt = f'{prefix}_dt'
+
+        # 时间轴补零到 T 的整数倍
+        pad = (-L) % T
+        Lp = L + pad
+        if pad:
+            nodes.append(helper.make_node(
+                'Concat', [dt, self.const(f'{prefix}_pad_dt', np.zeros((1, D, pad), np.float32))],
+                [f'{prefix}_dt_pad'], axis=2))
+            nodes.append(helper.make_node(
+                'Concat', [u, self.const(f'{prefix}_pad_u', np.zeros((1, D, pad), np.float32))],
+                [f'{prefix}_u_pad'], axis=2))
+            pad_bc = self.const(f'{prefix}_pad_bc', np.zeros((1, G, N, pad), np.float32))
+            nodes.append(helper.make_node('Concat', [b, pad_bc], [f'{prefix}_b_pad'], axis=3))
+            nodes.append(helper.make_node('Concat', [c, pad_bc], [f'{prefix}_c_pad'], axis=3))
+            dt, u, b, c = (f'{prefix}_dt_pad', f'{prefix}_u_pad',
+                           f'{prefix}_b_pad', f'{prefix}_c_pad')
+
+        # B/C 按组连续复制：[1,G,N,Lp] -> [1,D,N,Lp]
+        b_full = self.expand_groups(b, D, G, N, Lp, f'{prefix}_b', nodes)
+        c_full = self.expand_groups(c, D, G, N, Lp, f'{prefix}_c', nodes)
+
+        # A -> [1,D,N,1]，dt -> [1,D,N,T]，再摊平成 [D*N,T] 做 CumSum
+        a4 = self.const(f'{prefix}_a_shape', np.array([1, D, N, 1], np.int64))
+        nodes.append(helper.make_node('Reshape', [a, a4], [f'{prefix}_a4']))
+        if d is not None:
+            d3 = self.const(f'{prefix}_d_shape', np.array([1, D, 1], np.int64))
+            nodes.append(helper.make_node('Reshape', [d, d3], [f'{prefix}_d3']))
+            d = f'{prefix}_d3'
+
+        mask = np.tril(np.ones((T, T), dtype=bool)).reshape(1, T, T)
+        mask_name = self.shared_const(f'mask_{T}', mask)
+        neg_name = self.shared_const('mask_fill', np.array(-1e4, np.float32))
+        flat_axis = self.shared_const('axis1', np.array(1, np.int64))
+        axes_u2 = self.shared_const('axes_u2', np.array([2], np.int64))
+        axes_u3 = self.shared_const('axes_u3', np.array([3], np.int64))
+        axes_rs = self.shared_const('axes_rs2', np.array([2], np.int64))
+
+        h_prev = self.const(f'{prefix}_h0', np.zeros((1, D, N, 1), np.float32))
+        outputs = []
+        for k in range(Lp // T):
+            start, end = k * T, (k + 1) * T
+            tag = f'{prefix}_c{k}'
+            starts = self.const(f'{tag}_starts', np.array([start], np.int64))
+            ends = self.const(f'{tag}_ends', np.array([end], np.int64))
+            axis_t = self.shared_const('axis2', np.array([2], np.int64))
+            axis_bc = self.shared_const('axis3', np.array([3], np.int64))
+            for source, suffix, axis in ((dt, 'dt', axis_t), (u, 'u', axis_t),
+                                         (b_full, 'b', axis_bc), (c_full, 'c', axis_bc)):
+                nodes.append(helper.make_node('Slice', [source, starts, ends, axis],
+                                              [f'{tag}_{suffix}']))
+
+            # dtA = dt * A  -> [1,D,N,T] -> [D*N,T]，L = cumsum_t(dtA)
+            nodes.append(helper.make_node('Unsqueeze', [f'{tag}_dt', axes_u2], [f'{tag}_dt3']))
+            nodes.append(helper.make_node('Mul', [f'{tag}_dt3', f'{prefix}_a4'], [f'{tag}_dtA']))
+            nodes.append(helper.make_node('Reshape', [f'{tag}_dtA',
+                                                      self.const(f'{tag}_dtA2_shape',
+                                                                 np.array([D * N, T], np.int64))],
+                                          [f'{tag}_dtA2']))
+            nodes.append(helper.make_node('CumSum', [f'{tag}_dtA2', flat_axis], [f'{tag}_L2']))
+            nodes.append(helper.make_node('Reshape', [f'{tag}_L2',
+                                                      self.const(f'{tag}_L_shape',
+                                                                 np.array([1, D, N, T], np.int64))],
+                                          [f'{tag}_L']))
+
+            # 两两指数矩阵 E[t,s] = exp(L_t - L_s)（s>t 置为 -1e4 后 exp 为 0）
+            nodes.append(helper.make_node('Reshape', [f'{tag}_L2',
+                                                      self.const(f'{tag}_Lt_shape',
+                                                                 np.array([D * N, T, 1], np.int64))],
+                                          [f'{tag}_Lt']))
+            nodes.append(helper.make_node('Reshape', [f'{tag}_L2',
+                                                      self.const(f'{tag}_Ls_shape',
+                                                                 np.array([D * N, 1, T], np.int64))],
+                                          [f'{tag}_Ls']))
+            nodes.append(helper.make_node('Sub', [f'{tag}_Lt', f'{tag}_Ls'], [f'{tag}_diff']))
+            nodes.append(helper.make_node('Where', [mask_name, f'{tag}_diff', neg_name],
+                                          [f'{tag}_diffm']))
+            nodes.append(helper.make_node('Exp', [f'{tag}_diffm'], [f'{tag}_E']))
+
+            # b = dt * u * B，形状 [D*N,1,T]；contrib[t] = sum_{s<=t} E[t,s]*b[s]
+            nodes.append(helper.make_node('Unsqueeze', [f'{tag}_u', axes_u2], [f'{tag}_u3']))
+            nodes.append(helper.make_node('Mul', [f'{tag}_dt3', f'{tag}_u3'], [f'{tag}_dtu']))
+            nodes.append(helper.make_node('Mul', [f'{tag}_dtu', f'{tag}_b'], [f'{tag}_bt']))
+            nodes.append(helper.make_node('Reshape', [f'{tag}_bt',
+                                                      self.const(f'{tag}_bt2_shape',
+                                                                 np.array([D * N, 1, T], np.int64))],
+                                          [f'{tag}_bt2']))
+            nodes.append(helper.make_node('Mul', [f'{tag}_E', f'{tag}_bt2'], [f'{tag}_eb']))
+            nodes.append(helper.make_node('ReduceSum', [f'{tag}_eb',
+                                                       self.shared_const('axis2s', np.array([2], np.int64))],
+                                          [f'{tag}_contrib2'], keepdims=0))
+            nodes.append(helper.make_node('Reshape', [f'{tag}_contrib2',
+                                                      self.const(f'{tag}_contrib_shape',
+                                                                 np.array([1, D, N, T], np.int64))],
+                                          [f'{tag}_contrib']))
+
+            # 块间状态：h_t = exp(L_t) * h_prev + contrib
+            nodes.append(helper.make_node('Exp', [f'{tag}_L'], [f'{tag}_expL']))
+            nodes.append(helper.make_node('Mul', [f'{tag}_expL', h_prev], [f'{tag}_carry']))
+            nodes.append(helper.make_node('Add', [f'{tag}_carry', f'{tag}_contrib'],
+                                          [f'{tag}_h']))
+
+            # y = sum_n(h*C) + D*u
+            nodes.append(helper.make_node('Mul', [f'{tag}_h', f'{tag}_c'], [f'{tag}_hc']))
+            nodes.append(helper.make_node('ReduceSum', [f'{tag}_hc', axes_rs],
+                                          [f'{tag}_ysum'], keepdims=0))
+            if d is not None:
+                nodes.append(helper.make_node('Mul', [d, f'{tag}_u'], [f'{tag}_du']))
+                nodes.append(helper.make_node('Add', [f'{tag}_ysum', f'{tag}_du'],
+                                              [f'{tag}_y']))
+            else:
+                nodes.append(helper.make_node('Identity', [f'{tag}_ysum'], [f'{tag}_y']))
+            outputs.append(f'{tag}_y')
+
+            nodes.append(helper.make_node('Gather', [f'{tag}_h',
+                                                     self.const(f'{tag}_last', np.array(T - 1, np.int64))],
+                                          [f'{tag}_hlast'], axis=3))
+            nodes.append(helper.make_node('Unsqueeze', [f'{tag}_hlast', axes_u3],
+                                          [f'{tag}_hnext']))
+            h_prev = f'{tag}_hnext'
+
+        nodes.append(helper.make_node('Concat', outputs, [f'{prefix}_ycat'], axis=2))
+        if pad:
+            nodes.append(helper.make_node('Slice', [
+                f'{prefix}_ycat',
+                self.const(f'{prefix}_out_start', np.array([0], np.int64)),
+                self.const(f'{prefix}_out_end', np.array([L], np.int64)),
+                self.shared_const('axis2', np.array([2], np.int64))], [self.out_name]))
+        else:
+            nodes.append(helper.make_node('Identity', [f'{prefix}_ycat'], [self.out_name]))
+        return nodes
+
+    def expand_groups(self, x, D, G, N, L, prefix, nodes):
+        gs = D // G
+        r1_shape = self.const(f'{prefix}_r1_shape', np.array([1, G, 1, N, L], np.int64))
+        nodes.append(helper.make_node('Reshape', [x, r1_shape], [f'{prefix}_r1']))
+        target = self.const(f'{prefix}_tgt', np.array([1, G, gs, N, L], np.int64))
+        nodes.append(helper.make_node('Expand', [f'{prefix}_r1', target], [f'{prefix}_e']))
+        r2_shape = self.const(f'{prefix}_r2_shape', np.array([1, D, N, L], np.int64))
+        nodes.append(helper.make_node('Reshape', [f'{prefix}_e', r2_shape], [f'{prefix}_bc4']))
+        return f'{prefix}_bc4'
+
+    def rewrite(self):
+        shapes, einsum_shapes = collect_runtime_shapes(self.model)
+        if not shapes:
+            raise ValueError('模型中没有 SelectiveScan 节点，无需改写')
+        new_nodes, index, einsum_index = [], 0, 0
+        for node in self.model.graph.node:
+            if node.domain == DOMAIN and node.op_type == OP:
+                if self.stub_scan:
+                    # 仅用于测 NPU 耗时的对照模型：扫描直接透传 u，精度无意义。
+                    stub_node = helper.make_node('Identity', [node.input[0]], [node.output[0]],
+                                                 name=f'depthart_stub_scan_{index}')
+                    new_nodes.append(stub_node)
+                    index += 1
+                    continue
+                self.node_attrs = node.attribute
+                self.out_name = node.output[0]
+                builder = self.build_logspace if self.scan_method == 'log' else self.build
+                nodes = builder(f'depthart_pscan_{index}', shapes[index], node.input)
+                new_nodes.extend(nodes)
+                index += 1
+            elif node.op_type == 'Einsum':
+                equation = None
+                for attr in node.attribute:
+                    if attr.name == 'equation':
+                        equation = attr.s.decode()
+                if equation not in EINSUM_EQUATIONS:
+                    raise ValueError(f'{node.name}: 不支持的 Einsum 方程 {equation!r}')
+                x_shape, y_shape = einsum_shapes[node.name]
+                nodes = self.build_einsum(f'depthart_einsum_{einsum_index}',
+                                          node, x_shape, y_shape)
+                new_nodes.extend(nodes)
+                einsum_index += 1
+            else:
+                new_nodes.append(node)
+        out = onnx.ModelProto()
+        out.CopyFrom(self.model)
+        del out.graph.node[:]
+        for position, node in enumerate(new_nodes):
+            if not node.name:
+                node.name = f'depthart_gen_{position}'
+        out.graph.node.extend(new_nodes)
+        out.graph.initializer.extend(self.initializers[len(self.model.graph.initializer):])
+        return out
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='把 DepthART SelectiveScan 改写为 pulsar2 可编译的纯 ONNX 子图')
+    parser.add_argument('--model', type=Path, default=DEFAULT_MODEL,
+                        help=f'输入 ONNX，默认 {DEFAULT_MODEL.relative_to(PROJECT_ROOT)}')
+    parser.add_argument('--output', type=Path,
+                        default=PROJECT_ROOT / 'onnx' / 'relative_s_448_default_axonnx.onnx',
+                        help='输出 ONNX（不会覆盖输入模型）')
+    parser.add_argument('--chunk-size', type=int, default=14,
+                        help='分块长度 T，默认 14；越大显存占用越高')
+    parser.add_argument('--stub-scan', action='store_true',
+                        help='把 SelectiveScan 替换为 Identity，生成仅用于测 NPU 耗时的对照模型（精度无意义）')
+    parser.add_argument('--scan-method', choices=('pairwise', 'log'), default='pairwise',
+                        help='pairwise=两两指数矩阵(默认)；log=对数空间递推，无 T^2 矩阵，T 需小')
+    args = parser.parse_args()
+    logging.basicConfig(level=logging.INFO, format='%(message)s')
+    if args.chunk_size < 1:
+        parser.error('--chunk-size 必须为正数')
+    if not args.model.is_file():
+        parser.error(f'--model 不存在: {args.model}')
+    if args.output.resolve() == args.model.resolve():
+        parser.error('--output 不能与 --model 相同')
+
+    model = onnx.load(str(args.model))
+    if not any(node.domain == DOMAIN and node.op_type == OP for node in model.graph.node):
+        raise ValueError(f'{args.model} 中没有 {DOMAIN}::{OP} 节点')
+    rewriter = Rewriter(model, args.chunk_size, args.stub_scan, args.scan_method)
+    rewritten = rewriter.rewrite()
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    onnx.save(rewritten, str(args.output))
+    logging.info('已写出标准 ONNX: %s（节点数 %d）', args.output, len(rewritten.graph.node))
+    logging.info('下一步：把 pulsar2 配置的 input 指向该文件；'
+                 '可先用 src/infer/depthart_infer_onnx.py 验证数值。')
+
+
+if __name__ == '__main__':
+    main()

src/tool/evaluate_nyu654_depth.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+NYU Depth V2 Eigen test split (654 张) 相对深度精度评估。
+
+输入：
+    --mat     nyu_depth_v2_labeled.mat（GT 直接从这里读，不落盘）
+    --split   export_nyu654_test.py 生成的 split.json
+    --pred    一个或多个 <名称>=<NPZ 目录>，NPZ 由 infer 脚本 --dump-npz 生成
+
+评估协议：
+    1. 有效像素：rawDepths > 0 且 depths 在 (0, max_depth]；
+    2. 预测上采样到 GT 分辨率（bilinear）；
+    3. 相对深度对齐：
+       - disparity（默认，MiDaS 协议）：拟合 a*pred + b ≈ 1/gt，再取倒数得米制深度；
+       - depth：拟合 a*pred + b ≈ gt；
+       最小二乘在有效像素上求解；
+    4. 逐图计算 AbsRel / SqRel / RMSE / RMSE_log / δ<1.25 / 1.25² / 1.25³，
+       对 654 张取平均；
+    5. 第一个 --pred 作为基准，其余输出相对掉点 (%)。
+
+注意：未做 Eigen crop，绝对数值不能直接与论文表格对比；同一批图上不同后端的
+相对掉点不受影响。
+
+用法：
+    ../../venv/bin/python src/tool/evaluate_nyu654_depth.py \
+        --mat ../../datasets/nyu_depth_v2_labeled.mat \
+        --split datasets/nyu654_test/split.json \
+        --pred fp32=results/nyu654_fp32/npz axonnx=results/nyu654_axonnx/npz \
+        --out results/nyu654_eval
+"""
+
+import argparse
+import json
+from pathlib import Path
+
+import cv2
+import h5py
+import numpy as np
+from tqdm import tqdm
+
+METRICS = ('AbsRel', 'SqRel', 'RMSE', 'RMSE_log', 'd1', 'd2', 'd3')
+SIGMA = (1.25, 1.25 ** 2, 1.25 ** 3)
+
+
+def solve_scale_shift(pred, target, mask):
+    """在 mask 上最小二乘求解 a, b 使 a*pred + b ≈ target。"""
+    p = pred[mask]
+    t = target[mask]
+    A = np.stack([p, np.ones_like(p)], axis=1)
+    (a, b), *_ = np.linalg.lstsq(A, t, rcond=None)
+    return float(a), float(b)
+
+
+def compute_metrics(pred_depth, gt_depth, mask, align, max_depth):
+    clipped = 0.0
+    if align == 'disparity':
+        gt_target = 1.0 / gt_depth
+        a, b = solve_scale_shift(pred_depth, gt_target, mask)
+        if a <= 0:
+            raise ValueError(f'disparity 对齐斜率为负 (a={a:.4f})，'
+                             f'预测不是"越大越近"的视差量')
+        aligned = a * pred_depth + b
+        # 极少数图（低纹理/异常预测）会拟出负视差，裁剪到最大深度的下限
+        neg = aligned[mask] <= 0
+        clipped = float(neg.mean())
+        aligned = np.maximum(aligned, 1.0 / max_depth)
+        pred = 1.0 / aligned
+    else:
+        a, b = solve_scale_shift(pred_depth, gt_depth, mask)
+        pred = a * pred_depth + b
+
+    pred = pred[mask]
+    gt = gt_depth[mask]
+    if np.any(pred <= 0):
+        raise ValueError('对齐后预测深度出现非正值')
+
+    diff = pred - gt
+    out = {
+        'AbsRel': float(np.mean(np.abs(diff) / gt)),
+        'SqRel': float(np.mean(diff ** 2 / gt)),
+        'RMSE': float(np.sqrt(np.mean(diff ** 2))),
+        'RMSE_log': float(np.sqrt(np.mean((np.log(pred) - np.log(gt)) ** 2))),
+    }
+    ratio = np.maximum(pred / gt, gt / pred)
+    for name, s in zip(('d1', 'd2', 'd3'), SIGMA):
+        out[name] = float(np.mean(ratio < s))
+    return out, a, b, clipped
+
+
+def load_predictions(path):
+    """读取预测：汇总 NPZ（names/depths）、分块汇总目录，或旧的逐图 NPZ 目录。"""
+    path = Path(path)
+    if path.is_file():
+        files = [path]
+    elif path.is_dir():
+        files = sorted(path.glob('*.npz'))
+        if not files:
+            raise ValueError(f'目录中没有 NPZ: {path}')
+    else:
+        raise FileNotFoundError(f'预测路径不存在: {path}')
+
+    preds = {}
+    for fp in files:
+        with np.load(fp, allow_pickle=False) as data:
+            if 'depths' in data and 'names' in data:
+                for name, depth in zip(data['names'], data['depths']):
+                    preds[str(name)] = depth
+            elif 'depth' in data:
+                preds[fp.name[:-len('.npz')]] = data['depth']
+            else:
+                raise ValueError(f'无法识别的 NPZ 格式: {fp}')
+    return preds
+
+
+def main():
+    parser = argparse.ArgumentParser(description='NYU 654 相对深度评测')
+    parser.add_argument('--mat', required=True)
+    parser.add_argument('--split', required=True, help='split.json')
+    parser.add_argument('--pred', nargs='+', required=True, help='名称=NPZ目录，第一个为基准')
+    parser.add_argument('--out', required=True, help='结果目录')
+    parser.add_argument('--align', choices=['disparity', 'depth'], default='disparity')
+    parser.add_argument('--max-depth', type=float, default=10.0)
+    args = parser.parse_args()
+
+    pred_sets = []
+    for item in args.pred:
+        name, _, path = item.partition('=')
+        if not path:
+            raise ValueError(f'--pred 需要 名称=路径 格式: {item}')
+        pred_sets.append((name, load_predictions(path)))
+
+    split = json.load(open(args.split))
+    out_dir = Path(args.out)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    per_image = {name: [] for name, _ in pred_sets}
+    failed = {name: [] for name, _ in pred_sets}
+    with h5py.File(args.mat, 'r') as f:
+        for record in tqdm(split, desc=f'eval({args.align})', ncols=80):
+            i = record['mat_index']
+            gt = np.asarray(f['depths'][i], dtype=np.float32)
+            raw = np.asarray(f['rawDepths'][i], dtype=np.float32)
+            mask = (raw > 0) & (gt > 0) & (gt <= args.max_depth)
+
+            for name, preds in pred_sets:
+                if record['file'] not in preds:
+                    raise KeyError(f'{name} 缺少预测: {record["file"]}')
+                pred = np.asarray(preds[record['file']], dtype=np.float32)
+                if pred.ndim == 3:
+                    pred = pred[0]
+                pred = cv2.resize(pred, (gt.shape[1], gt.shape[0]), interpolation=cv2.INTER_LINEAR)
+                try:
+                    m, a, b, clipped = compute_metrics(pred, gt, mask, args.align, args.max_depth)
+                except ValueError as error:
+                    failed[name].append({'file': record['file'], 'reason': str(error)})
+                    continue
+                m.update({'file': record['file'], 'scale': a, 'shift': b,
+                          'clipped_frac': clipped, 'valid_pixels': int(mask.sum())})
+                per_image[name].append(m)
+
+    results = {}
+    for name, _ in pred_sets:
+        rows = per_image[name]
+        results[name] = {k: float(np.mean([r[k] for r in rows])) for k in METRICS}
+        results[name]['p90_absrel'] = float(np.percentile([r['AbsRel'] for r in rows], 90))
+        results[name]['clipped_images'] = int(sum(r['clipped_frac'] > 0 for r in rows))
+        results[name]['clipped_pixel_frac'] = float(np.mean([r['clipped_frac'] for r in rows]))
+        results[name]['evaluated_images'] = len(rows)
+        results[name]['failed_images'] = len(failed[name])
+
+    base = pred_sets[0][0]
+    drops = {}
+    for name, _ in pred_sets[1:]:
+        drops[name] = {}
+        for k in METRICS:
+            b, v = results[base][k], results[name][k]
+            drops[name][k] = float((v - b) / b * 100)
+        b, v = results[base]['p90_absrel'], results[name]['p90_absrel']
+        drops[name]['p90_absrel'] = float((v - b) / b * 100)
+
+    summary = {
+        'dataset': 'nyu_depth_v2_labeled / eigen test split',
+        'num_images': len(split),
+        'align': args.align,
+        'max_depth': args.max_depth,
+        'eigen_crop': False,
+        'results': results,
+        'baseline': base,
+        'drop_percent': drops,
+        'failed': failed,
+        'per_image': {name: per_image[name] for name, _ in pred_sets},
+    }
+    with open(out_dir / 'metrics.json', 'w') as fp:
+        json.dump(summary, fp, indent=2)
+
+    print(f'\n{"指标":<10}' + ''.join(f'{n:>14}' for n, _ in pred_sets))
+    for k in METRICS + ('p90_absrel',):
+        print(f'{k:<10}' + ''.join(f'{results[n][k]:>14.4f}' for n, _ in pred_sets))
+    for name, d in drops.items():
+        print(f'\n{name} 相对 {base} 掉点 (%): ' +
+              ', '.join(f'{k}={v:+.2f}' for k, v in d.items()))
+    for name, _ in pred_sets:
+        if failed[name]:
+            print(f'\n{name}: {len(failed[name])} 张对齐失败（方向反了或输出异常），未计入均值')
+    print(f'\n结果已保存: {out_dir / "metrics.json"}')
+
+
+if __name__ == '__main__':
+    main()

src/tool/export_nyu654_test.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+从 nyu_depth_v2_labeled.mat 导出官方 Eigen test split 的 654 张 RGB 图片。
+
+划分来源：BTS 仓库 utils/splits.mat 的 testNdxs（1-based，共 654 个），
+与 train_test_inputs/nyudepthv2_test_files_with_gt.txt 的 654 行逐场景帧数一致，
+已核对无重叠、并集覆盖 1..1449。
+
+只导出 RGB，GT 不落盘：评测脚本按 split.json 里的 mat_index 直接从 mat 读取，
+避免重复存储。
+
+用法：
+    # 导出 654 张到 datasets/nyu654_test/
+    ../../venv/bin/python src/tool/export_nyu654_test.py \
+        --mat ../../datasets/nyu_depth_v2_labeled.mat \
+        --splits datasets/nyu654_test/splits.mat \
+        --out-dir datasets/nyu654_test
+
+输出：
+    <out-dir>/images/{序号:04d}_{scene}.png
+    <out-dir>/split.json    [{mat_index, scene, file}, ...]
+"""
+
+import argparse
+import json
+from pathlib import Path
+
+import cv2
+import h5py
+import numpy as np
+import scipy.io as sio
+from tqdm import tqdm
+
+
+def decode_cell(f, ref):
+    return ''.join(chr(c) for c in np.asarray(f[ref]).ravel())
+
+
+def main():
+    parser = argparse.ArgumentParser(description='导出 NYU Depth V2 Eigen test split 654 张')
+    parser.add_argument('--mat', required=True, help='nyu_depth_v2_labeled.mat')
+    parser.add_argument('--splits', required=True, help='含 testNdxs 的 splits.mat')
+    parser.add_argument('--out-dir', required=True, help='输出目录')
+    args = parser.parse_args()
+
+    out_dir = Path(args.out_dir)
+    image_dir = out_dir / 'images'
+    image_dir.mkdir(parents=True, exist_ok=True)
+
+    ndxs = sio.loadmat(args.splits)['testNdxs'].ravel().astype(int)
+    if len(ndxs) != 654:
+        raise ValueError(f'testNdxs 应为 654 个，实际 {len(ndxs)}')
+
+    records = []
+    with h5py.File(args.mat, 'r') as f:
+        for seq, mat_index in enumerate(tqdm(ndxs, desc='export', ncols=80)):
+            i = mat_index - 1  # matlab 1-based
+            scene = decode_cell(f, f['scenes'][0, i])
+            rgb = np.asarray(f['images'][i]).transpose(1, 2, 0)  # CHW -> HWC
+            name = f'{seq:04d}_{scene}.png'
+            if not cv2.imwrite(str(image_dir / name), cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)):
+                raise RuntimeError(f'写入失败: {image_dir / name}')
+            records.append({'mat_index': int(i), 'scene': scene, 'file': name})
+
+    with open(out_dir / 'split.json', 'w') as fp:
+        json.dump(records, fp, indent=2)
+    print(f'已导出 {len(records)} 张到 {image_dir}，划分文件 {out_dir / "split.json"}')
+
+
+if __name__ == '__main__':
+    main()

src/tool/export_nyu_train795.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+从 nyu_depth_v2_labeled.mat 导出 795 张训练集（trainNdxs）图片。
+
+划分来源与 export_nyu654_test.py 相同：BTS utils/splits.mat。
+trainNdxs 与 testNdxs（654）无重叠、并集覆盖 1..1449，可以与测试集严格隔离，
+用于量化校准或训练。
+
+只导出 RGB；GT 仍从 mat 按 split.json 的 mat_index 读取。
+
+用法：
+    ../../venv/bin/python src/tool/export_nyu_train795.py \
+        --mat ../../datasets/nyu_depth_v2_labeled.mat \
+        --splits datasets/nyu654_test/splits.mat \
+        --out-dir datasets/nyu_train795
+"""
+
+import argparse
+import json
+from pathlib import Path
+
+import cv2
+import h5py
+import numpy as np
+import scipy.io as sio
+from tqdm import tqdm
+
+
+def decode_cell(f, ref):
+    return ''.join(chr(c) for c in np.asarray(f[ref]).ravel())
+
+
+def main():
+    parser = argparse.ArgumentParser(description='导出 NYU Depth V2 训练集 795 张')
+    parser.add_argument('--mat', required=True, help='nyu_depth_v2_labeled.mat')
+    parser.add_argument('--splits', required=True, help='含 trainNdxs 的 splits.mat')
+    parser.add_argument('--out-dir', required=True, help='输出目录')
+    args = parser.parse_args()
+
+    image_dir = Path(args.out_dir) / 'images'
+    image_dir.mkdir(parents=True, exist_ok=True)
+
+    ndxs = sio.loadmat(args.splits)['trainNdxs'].ravel().astype(int)
+    if len(ndxs) != 795:
+        raise ValueError(f'trainNdxs 应为 795 个，实际 {len(ndxs)}')
+
+    records = []
+    with h5py.File(args.mat, 'r') as f:
+        for seq, mat_index in enumerate(tqdm(ndxs, desc='export', ncols=80)):
+            i = mat_index - 1
+            scene = decode_cell(f, f['scenes'][0, i])
+            rgb = np.asarray(f['images'][i]).transpose(1, 2, 0)
+            name = f'{seq:04d}_{scene}.png'
+            if not cv2.imwrite(str(image_dir / name), cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)):
+                raise RuntimeError(f'写入失败: {image_dir / name}')
+            records.append({'mat_index': int(i), 'scene': scene, 'file': name})
+
+    with open(Path(args.out_dir) / 'split.json', 'w') as fp:
+        json.dump(records, fp, indent=2)
+    print(f'已导出 {len(records)} 张到 {image_dir}')
+
+
+if __name__ == '__main__':
+    main()

src/tool/inspect_nyu_depth_v2.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+NYU Depth V2 (labeled) 数据集查看与导出工具。
+
+nyu_depth_v2_labeled.mat 是 MATLAB v7.3 (HDF5) 格式，scipy.io.loadmat 无法读取，
+这里统一用 h5py 按需读取，避免一次性载入 2.8GB。
+
+数据内容（N = 1449，图像为竖版 640x480，H=640, W=480，RGB 与深度已对齐）：
+    images             [N, 3, 640, 480] uint8    RGB
+    depths             [N, 640, 480]    float32  已填补深度，单位米
+    rawDepths          [N, 640, 480]    float32  原始深度，0 表示缺失
+    labels             [N, 640, 480]    uint16   语义标签，0=未标注，1..894 对应 names
+    instances          [N, 640, 480]    uint8    实例标签，0=无实例
+    names              [1, 894]         cell     类别名（1-based 下标即 label id）
+    namesToIds         containers.Map           MATLAB Map，h5py 无法直接解析
+    scenes             [1, N]           cell     场景名，如 kitchen_0004
+    sceneTypes         [1, N]           cell     场景类型，如 kitchen
+    rawRgbFilenames    [1, N]           cell     原始 RGB 文件名
+    rawDepthFilenames  [1, N]           cell     原始深度文件名
+    accelData          [4, N]           float32  加速度计数据
+
+用法（在 hs/DepthART 目录下执行）：
+    # 打印结构、场景/类别统计和深度数值范围（默认抽样 step=50）
+    ../../venv/bin/python src/tool/inspect_nyu_depth_v2.py --mat ../../datasets/nyu_depth_v2_labeled.mat
+
+    # 全量扫描统计（较慢）
+    ... --mat ../../datasets/nyu_depth_v2_labeled.mat --full-stats
+
+    # 列出全部 894 个类别名
+    ... --mat ... --list-classes
+
+    # 单样本导出：rgb.png / depth.npy / depth_vis.png / raw_depth.npy
+    ... --mat ... --index 0 --out-dir results/nyu_demo --with-labels
+
+    # 批量导出，例如某场景全部帧
+    ... --mat ... --export-dir results/nyu_export --scene kitchen_0004 --with-labels
+
+    # 批量导出前 50 张
+    ... --mat ... --export-dir results/nyu_export --count 50
+"""
+
+import argparse
+import collections
+from pathlib import Path
+
+import cv2
+import h5py
+import numpy as np
+from tqdm import tqdm
+
+# 深度可视化统一范围（米），超出部分截断
+DEPTH_VIS_RANGE = (0.5, 10.0)
+
+
+def decode_cell(f, ref):
+    """把 MATLAB cell 中的 char 数组解码为 str。"""
+    return ''.join(chr(c) for c in np.asarray(f[ref]).ravel())
+
+
+def read_cell_list(dset):
+    return [decode_cell(dset.file, dset[0, i]) for i in range(dset.shape[1])]
+
+
+def print_info(f, stride, full_stats):
+    print('== 变量 ==')
+    for k in f.keys():
+        if k.startswith('#'):
+            continue
+        o = f[k]
+        line = f'{k:20s} shape={str(o.shape):24s} dtype={o.dtype}'
+        if o.compression:
+            line += f'  compression={o.compression}'
+        print(line)
+
+    n = f['depths'].shape[0]
+    h, w = f['depths'].shape[1:]
+    names = read_cell_list(f['names'])
+    scenes = read_cell_list(f['scenes'])
+    scene_types = read_cell_list(f['sceneTypes'])
+
+    print('\n== 规模 ==')
+    print(f'样本数          {n}')
+    print(f'分辨率          W={w}, H={h}（data layout 为 [N, C, H, W]）')
+    print(f'场景数          {len(set(scenes))}')
+    print(f'场景类型数      {len(set(scene_types))}')
+    print(f'语义类别数      {len(names)}（label id 1..{len(names)}，0 为未标注）')
+    print('场景类型分布    ' + ', '.join(f'{k}:{v}' for k, v in
+                                       collections.Counter(scene_types).most_common()))
+
+    idx = range(0, n) if full_stats else range(0, n, stride)
+    idx = list(idx)
+    print(f'\n== 数值统计（{"全量" if full_stats else f"抽样 {len(idx)} 张, step={stride}"}） ==')
+    d_min, d_max = np.inf, -np.inf
+    raw_missing = 0
+    raw_total = 0
+    cls_count = collections.Counter()
+    inst_max = 0
+    for i in tqdm(idx, desc='scan', ncols=80):
+        d = f['depths'][i]
+        r = f['rawDepths'][i]
+        d_min = min(d_min, float(d.min()))
+        d_max = max(d_max, float(d.max()))
+        raw_missing += int((r == 0).sum())
+        raw_total += r.size
+        for c in np.unique(f['labels'][i]):
+            if c > 0:
+                cls_count[int(c)] += 1
+        inst_max = max(inst_max, int(f['instances'][i].max()))
+
+    print(f'depths 范围     [{d_min:.4f}, {d_max:.4f}] m')
+    print(f'rawDepths 缺失  {raw_missing / raw_total * 100:.2f}% (值为 0)')
+    print(f'出现类别数      {len(cls_count)} / {len(names)}')
+    print(f'instances 最大  {inst_max}')
+    print('\n最常见类别      ' + ', '.join(
+        f'{names[c - 1]}({cnt})' for c, cnt in cls_count.most_common(15)))
+
+
+def depth_to_vis(depth, raw=False):
+    lo, hi = DEPTH_VIS_RANGE
+    norm = np.clip((depth - lo) / (hi - lo), 0.0, 1.0)
+    vis = cv2.applyColorMap((norm * 255).astype(np.uint8), cv2.COLORMAP_TURBO)
+    if raw:
+        vis[depth <= 0] = 0
+    return vis
+
+
+def export_sample(f, index, out_dir, with_labels):
+    entry = out_dir / f'{index:05d}_{decode_cell(f, f["scenes"][0, index])}'
+    entry.mkdir(parents=True, exist_ok=True)
+
+    rgb = np.asarray(f['images'][index]).transpose(1, 2, 0)  # CHW -> HWC, RGB
+    depth = np.asarray(f['depths'][index], dtype=np.float32)
+    raw = np.asarray(f['rawDepths'][index], dtype=np.float32)
+
+    cv2.imwrite(str(entry / 'rgb.png'), cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR))
+    cv2.imwrite(str(entry / 'depth_vis.png'), depth_to_vis(depth))
+    cv2.imwrite(str(entry / 'raw_depth_vis.png'), depth_to_vis(raw, raw=True))
+    np.save(entry / 'depth.npy', depth)
+    np.save(entry / 'raw_depth.npy', raw)
+
+    if with_labels:
+        labels = np.asarray(f['labels'][index])
+        np.save(entry / 'labels.npy', labels)
+        # 语义标签着色：按 label id 的哈希色，0 保持黑色
+        rng = np.random.default_rng(0)
+        lut = rng.integers(40, 255, size=(65536, 3), dtype=np.uint8)
+        lut[0] = 0
+        cv2.imwrite(str(entry / 'labels_vis.png'), lut[labels])
+
+    return entry
+
+
+def main():
+    parser = argparse.ArgumentParser(description='查看/导出 NYU Depth V2 labeled 数据集')
+    parser.add_argument('--mat', required=True, help='nyu_depth_v2_labeled.mat 路径')
+    parser.add_argument('--list-classes', action='store_true', help='打印全部类别名及 id')
+    parser.add_argument('--index', type=int, help='导出单个样本的下标')
+    parser.add_argument('--out-dir', help='--index 模式的输出目录')
+    parser.add_argument('--export-dir', help='批量导出目录')
+    parser.add_argument('--count', type=int, help='批量导出数量，默认全部')
+    parser.add_argument('--step', type=int, default=1, help='批量导出间隔，默认 1')
+    parser.add_argument('--scene', help='只导出指定场景，如 kitchen_0004')
+    parser.add_argument('--with-labels', action='store_true', help='同时导出语义标签')
+    parser.add_argument('--full-stats', action='store_true', help='统计时扫描全部样本')
+    parser.add_argument('--stats-stride', type=int, default=50, help='抽样统计间隔，默认 50')
+    args = parser.parse_args()
+
+    with h5py.File(args.mat, 'r') as f:
+        if args.list_classes:
+            names = read_cell_list(f['names'])
+            for i, name in enumerate(names, 1):
+                print(f'{i:4d}  {name}')
+            return
+
+        if args.index is not None:
+            out_dir = Path(args.out_dir or '.')
+            entry = export_sample(f, args.index, out_dir, args.with_labels)
+            print(f'已导出 {entry}')
+            return
+
+        if args.export_dir:
+            n = f['depths'].shape[0]
+            indices = list(range(0, n, args.step))
+            if args.scene:
+                scenes = read_cell_list(f['scenes'])
+                indices = [i for i in indices if scenes[i] == args.scene]
+                print(f'场景 {args.scene} 命中 {len(indices)} 张')
+            if args.count:
+                indices = indices[:args.count]
+            out_dir = Path(args.export_dir)
+            for i in tqdm(indices, desc='export', ncols=80):
+                export_sample(f, i, out_dir, args.with_labels)
+            print(f'已导出 {len(indices)} 张到 {out_dir}')
+            return
+
+        print_info(f, args.stats_stride, args.full_stats)
+
+
+if __name__ == '__main__':
+    main()

src/tool/make_nyu_calibration.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+从 NYU 训练集 795 张中按场景均匀抽取量化校准图片。
+
+抽样规则：
+    - 按场景类型（scene 去掉 _0001 后缀，如 kitchen、bedroom）分组；
+    - 每个场景至少 1 张，其余名额按场景图片数比例分配（最大余数法）；
+    - 场景内按等距索引选取，结果确定可复现。
+
+输出：
+    <out-dir>/images/*.png        校准图片
+    <out-dir>/selection.json      每张图的来源 mat_index / scene / 源文件
+    <out-dir>/<name>.tar          给 pulsar2 的校准包，内部为 <name>/xxx.png
+
+用法：
+    ../../venv/bin/python src/tool/make_nyu_calibration.py \
+        --source-dir datasets/nyu_train795 --count 48 \
+        --out-dir datasets/nyu_calibration_48
+"""
+
+import argparse
+import json
+import shutil
+import subprocess
+from collections import defaultdict
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+
+def scene_type(scene):
+    return scene.rsplit('_', 1)[0]
+
+
+def allocate(groups, count):
+    """最大余数法分配名额，每个场景至少 1 张。"""
+    total = sum(len(v) for v in groups.values())
+    if count < len(groups):
+        raise ValueError(f'抽取数量 {count} 少于场景数 {len(groups)}，无法保证每场景 1 张')
+    quota = {k: 1 for k in groups}
+    left = count - len(groups)
+    exact = {k: left * len(v) / total for k, v in groups.items()}
+    for k, v in exact.items():
+        quota[k] += int(np.floor(v))
+    remain = count - sum(quota.values())
+    order = sorted(exact, key=lambda k: exact[k] - np.floor(exact[k]), reverse=True)
+    for k in order[:remain]:
+        quota[k] += 1
+    return quota
+
+
+def main():
+    parser = argparse.ArgumentParser(description='按场景均匀抽取 NYU 校准集')
+    parser.add_argument('--source-dir', required=True, help='export_nyu_train795.py 的输出目录')
+    parser.add_argument('--count', type=int, default=48, help='抽取张数，默认 48')
+    parser.add_argument('--out-dir', required=True, help='校准集输出目录')
+    parser.add_argument('--name', help='tar 包内目录名，默认取 out-dir 名')
+    parser.add_argument('--ext', choices=('png', 'jpg'), default='png',
+                        help='校准图片格式，默认 png；pulsar2 读取异常时可改 jpg')
+    args = parser.parse_args()
+
+    source = Path(args.source_dir)
+    split = json.load(open(source / 'split.json'))
+    groups = defaultdict(list)
+    for record in split:
+        groups[scene_type(record['scene'])].append(record)
+
+    quota = allocate(groups, args.count)
+    selected = []
+    for scene, records in sorted(groups.items()):
+        records = sorted(records, key=lambda r: r['file'])
+        idx = np.linspace(0, len(records) - 1, quota[scene]).round().astype(int)
+        selected.extend(records[i] for i in sorted(set(idx.tolist())))
+
+    if len(selected) != args.count:
+        raise RuntimeError(f'实际选出 {len(selected)} 张，与目标 {args.count} 不符')
+
+    out_dir = Path(args.out_dir)
+    image_dir = out_dir / 'images'
+    image_dir.mkdir(parents=True, exist_ok=True)
+    for record in selected:
+        src = source / 'images' / record['file']
+        if args.ext == 'png':
+            dst = image_dir / record['file']
+            shutil.copy2(src, dst)
+        else:
+            dst = image_dir / (Path(record['file']).stem + '.jpg')
+            image = cv2.imread(str(src), cv2.IMREAD_COLOR)
+            if image is None:
+                raise RuntimeError(f'读取失败: {src}')
+            cv2.imwrite(str(dst), image, [cv2.IMWRITE_JPEG_QUALITY, 95])
+
+    with open(out_dir / 'selection.json', 'w') as fp:
+        json.dump(selected, fp, indent=2)
+
+    name = args.name or out_dir.name
+    tar_path = out_dir / f'{name}.tar'
+    subprocess.run(
+        ['tar', '-cf', str(tar_path), '--transform', f's,^,{name}/,', '-C', str(image_dir)]
+        + sorted(p.name for p in image_dir.iterdir()),
+        check=True)
+
+    print(f'已抽取 {len(selected)} 张，覆盖 {len(groups)} 个场景类型')
+    for scene in sorted(groups):
+        print(f'  {scene:<16} {quota[scene]:>3} 张 / 共 {len(groups[scene])}')
+    print(f'校准包: {tar_path}')
+
+
+if __name__ == '__main__':
+    main()