erichare/verity

Verity 比较直接来自 [X3P](https://www.iso.org/standard/62395.html) 文件 (ISO 25178-72) 的 3D 表面形貌扫描 —— 包括弹头阳膛表面、弹壳底火台印痕、线条状和凹陷状工具痕迹，以及（未来计划支持的）鞋印和断裂表面。它将领域通用的表面比对与**透明、经过校准的似然比决策层**及区域级归因相结合。该机器从不报告“匹配”；它报告的是一个*可审计的证据权重*，并在指定的数据集上进行表征。 ## 设计初衷 如今的法庭科学枪械/工具痕迹比对，要么是主观的检验员判断，要么是专有的黑盒关联 (IBIS)，而开放的工具只是一堆*特定领域*的 R 包，缺乏统一、可部署的平台。法院对未经证实的模式匹配证词越来越持怀疑态度 (*Abruquah v. Maryland*, 2023; FRE 702 的 2023 年修正案)，并且**目前还没有任何学科具有充分表征的错误率** (Cuellar et al., 2024)。Verity 的押注是：**一种通用、经过校准、可解释的方法** —— 首先在基准真相最可靠的地方（枪械）得到证明，然后跨领域转移。 **设计原则** - **由统计学决定，而非黑盒。** 一种表示产生一个*分数*；一个透明且经验上限的校准将该分数转换为可报告的似然比。无论分数是如何计算的，该报告都是可解释的 —— 这就是抵御黑盒的防火墙。 - **结构化的可复现性。** 确定性、版本锁定、内容哈希。 - **开放且语言无关。** 基于 X3P 标准；MIT/Apache-2.0。 ## 你会得到什么 不是一个裁定 —— 而是一份经过校准的 **`ComparisonReport`**：一个带有其文字等价物和**可信区间**的似然比（对参考进行聚类 bootstrap，因此 LR 带有自身的校准不确定性），在*指定的*参考人群上表征的成本 (**Cllr**)，关于数据能支持多强声明的**经验上限**（受 ELUB 启发），以及驱动该分数的**区域级归因**。 ``` { "likelihood_ratio": 146.0, "log10_lr": 2.16, "verbal": "moderately strong support for same source", "lr_bound_log10": 2.16, // a percentile credible interval on log10 LR — the reference is bootstrapped (clustered // by source/barrel) and refit, so the number carries its own calibration uncertainty "log10_lr_ci_lo": 1.74, "log10_lr_ci_hi": 2.16, "lr_ci_method": "bootstrap-clustered", // reference diagnostics are the *in-sample* fit of the named reference; the honest // validation figure is the source-disjoint Cllr ≈ 0.19 pooled (≈ 0.11 on Hamby-252 // alone) — every number, with its protocol, lives in docs/headline-numbers.md "reference": { "name": "pooled bullet-land", "n_km": 146, "n_knm": 1755, "auc": 0.984, "cllr": 0.193, "cllr_min": 0.168 }, "attribution": [ /* the matched regions — the explanation */ ], "scope_note": "Not a claim about the error rate of examination, which remains unknown." } ``` ## 方法 —— 一致匹配区域 (CMR) CMR 将 Song 的**一致匹配单元**（标准的弹壳方法）从 2D 单元和固定的平移+旋转推广到**任意变换组**下的**任意维度区域** —— 因此一个算法可以对线条状、凹陷状和（研究中的）断裂痕迹进行评分。将痕迹划分为多个区域，将每个区域与另一个痕迹进行配准，并计算在同一个共同几何结构上达成一致的区域数量。一致的区域*即是*归因图。 | 形态 | 区域 | 变换组 | 归约为 | |------------|---------------------|---------------------------|-------------------| | 线条状 | 1D 轮廓窗口 | 1D 平移 | ≈ Chumbley / CMS | | 凹陷状 | 2D 网格单元 | 2D 平移+旋转 | ≈ CMC | | 断裂状 | 3D 网格面片 | 3D 刚体姿态 | (研究中) | 完整说明：[`docs/congruent-matching-regions.md`](docs/congruent-matching-regions.md)。 ## 验证（实事求是） - **来源分离、第一性原理（无学习表示）。** 在枪管分离协议下（没有任何枪管同时出现在训练集和测试集中；按研究报告，从不跨品牌混合），生产级 `diag_contrast` 评分器在留出的枪管上取得了 **AUC ≈ 1.00 且测试 Cllr ≈ 0.11（在 Hamby-252 上）**（这是最强的单项研究；四项研究混合后的来源分离 Cllr ≈ 0.19，且冻结的 `bullets-v1` 基准测试复现为 ≈ 0.21），并且在四项 NBTRD 子弹研究（Hamby-252/173, PGPD Beretta, Phoenix Ruger）中，**测试 Cllr ≈ 0.11–0.35，AUC ≈ 0.97–1.00** —— 这完全基于测量学，提供了一种信息丰富且经过校准的证据权重。（`Cllr < 1` = 提供有效信息；`Cllr − Cllr_min` 的差距是来源分离拆分所暴露的校准损失，从而正面回应了 Cuellar et al. 的批评。）该评分器是通过显式的枪管分离消融（`verity-margin`）被选中，而非第一阶段的 `diag_mean` 或多变量融合 —— 坦白说，该消融重用了与本次验证相同的四项研究，因此在未接触过的数据上进行一次性确认是下一个里程碑（见白皮书的局限性）；`verity-validation-report` 会重新生成完整的表征 —— Tippett、DET、校准以及来源分离总结 —— 作为法庭就绪的 PDF。经过训练的 `bulletxtrctr` 随机森林专家模型在运行相同协议后，在 Hamby-252 上达到了 **Cllr ≈ 0.06** —— 专家模型在其主场上依然领先；Verity 在子弹方面的贡献在于经过校准、有边界、可部署的 LR 层，而不是一个更好的匹配器。 - **学习表示（Phase-2b）。** 在 210 个 Hamby 扫描上进行了枪管分离训练，它**并没有超越互相关基准** —— 它过拟合了（留出集 AUC 崩溃至 ≈ 0.67）。合成测试证实，如果给足信号，流水线*确实能*学习：这是一个**数据限制，而非缺陷**。下一步：扩大数据集并重新测试。 这里没有任何内容是对法庭科学检验错误率的声明，该错误率目前仍然未知。 ## 仓库结构 一个多语言 monorepo：一个 Rust 编解码核心，轻量级的语言绑定，以及构建在其上的 Python 科学计算与服务栈。 | 包 | 语言 | 作用 | |---|---|---| | [`crates/verity-x3p`](crates/verity-x3p) | Rust | 原生 X3P (ISO 25178-72) 读取器/写入器 —— 该格式的唯一事实来源。 | | [`bindings/python`](bindings/python) | PyO3 + NumPy | 核心的 Python 绑定（位级一致的 I/O）。 | | [`bindings/r/verityx3p`](bindings/r/verityx3p) | extendr | 核心的 R 绑定（兼容 `x3ptools` 的布局）。 | | [`services/engine`](services/engine) | Python | 测量学预处理、配准、CMR、校准的 LR 决策层。 | | [`services/api`](services/api) | FastAPI | 提供 `ComparisonReport` 服务的比对 HTTP API。 | | [`services/catalog`](services/catalog) | Python | 标准化目录 + 内容寻址存储 + 数据摄取 (NBTRD/Figshare)。 | | [`services/web`](services/web) | Next.js | [verity.codes](https://verity.codes) 和交互式比对 UI。 | ## 快速入门 ### X3P 编解码器 —— Rust / Python / R ``` use verity_x3p::{read_x3p, write_x3p, WriteOptions}; let surface = read_x3p("scan.x3p")?; // verifies the stored MD5 write_x3p(&surface, "copy.x3p", &WriteOptions::default())?; ``` ``` import verity_x3p s = verity_x3p.read_x3p("scan.x3p") # s.data, s.mask are (ny, nx) NumPy arrays verity_x3p.write_x3p(s, "copy.x3p", z_type="D") ``` ``` library(verityx3p) s <- read_x3p("scan.x3p") # s$surface is an nx-by-ny matrix write_x3p(s, "copy.x3p") ``` 从任何绑定写入的文件在其他绑定中都能**位级一致**地读回。 ### 通过 HTTP 比较两个痕迹 ``` curl -s -X POST https://api.verity.codes/compare \ -F domain=striated \ -F mark_a=@bulletA_land1.x3p -F mark_a=@bulletA_land2.x3p \ -F mark_b=@bulletB_land1.x3p -F mark_b=@bulletB_land2.x3p ``` 请查看完整的 **[文档](https://verity.codes/docs)** 和交互式 **[API 参考](https://api.verity.codes/scalar)**。 ### 开发 ``` cargo test -p verity-x3p # the Rust core cd services/engine && uv venv --python 3.12 && uv pip install -e ".[dev]" && uv run pytest cd services/api && uv run --extra dev verity-api # API on :8000 cd services/web && pnpm install && pnpm dev # web on :3000 ``` 部署（Vercel + 用于 API 的容器托管）已在 [`DEPLOY.md`](DEPLOY.md) 中记录。 ## 状态与路线图 - ✅ **`verity-x3p`** 原生编解码器 + Python/R 绑定（位级一致的往返）。 - ✅ **引擎**：ISO 16610 预处理、配准、校准的 LR 决策层、CMR；来源分离的 Hamby 验证。 - ✅ **平台**：比对 API + Web 应用，已在 verity.codes 上线。 - 🔜 扩充子弹/弹壳/工具痕迹数据集（NBTRD 收集）并重新测试学习表示；在 Fadul 上实现 CMR-2D → CMC 的一致性；TypeScript/Swift/Java 编解码绑定。 ## 许可证 根据您的选择，在 [**MIT**](LICENSE-MIT) 或 [**Apache-2.0**](LICENSE-APACHE) 双重许可下授权。捆绑的参考数据带有其各自的上游归属 —— 请参阅 [`services/api/verity_api/references/NOTICE.md`](services/api/verity_api/references/NOTICE.md)。

标签：Python, R, Rust, 三维形貌分析, 似然比, 可视化界面, 司法科学, 无后门, 网络流量审计, 逆向工具