将 ScanNet 场景、SMPL-X 人体运动、表面接触几何与 Qwen 连接成一条可审计的推理链：不仅回答人体与场景如何交互，还展示答案所依据的身体部位、目标物体、距离和接触比例。
- 🎯 可验证 Human-in-Scene 推理：输入三维场景、人体运动前缀、候选轨迹和语言问题，输出接触部位、目标物体与物理解释。
- 🦴 六身体区域表面证据：分别建模左臂、右臂、左腿、右腿、骨盆和躯干/头部，不把人体压缩成单一包围盒。
- 📐 精确表面几何：基于点到三角面的距离、最小/末帧距离及接触帧比例，构造可复查的时序接触证据。
- 🧠 Relation-aware Grounder：分离 Uni3D 语义、解剖编码和物理关系特征，通过查询条件选择器定位问题相关身体部位。
- 🔁 反事实训练与审计：使用答案会随人体部位/物体变化而改变的配对样本，检查模型是否真正响应接触方向变化。
- 🤖 Qwen 结构化解码：Qwen3.5-2B 通过 LoRA 与受约束的 64-mask 解码，生成结构化 JSON 和中英文证据解释。
- 🛡️ Evidence Authority：显式区分几何规则、Grounder 预测和最终采用的证据，减少语言模型“说得像但证据不一致”的情况。
- 🖥️ 交互式 3D 控制台：在 Gradio 中同步查看 ScanNet 场景、SMPL-X 动作、目标物体、当前帧距离和序列级接触判定。
给定：
- 一个带物体实例与表面的 ScanNet 三维场景；
- 一段场景对齐的 SMPL-X 人体运动；
- 人体轨迹或交互候选；
- 关于人体—物体关系的自然语言问题；
PhysHIS 预测人体运动是否可行、与哪个物体发生交互、哪个身体部位提供关键证据，并解释物理失败或接触关系。
典型结构化输出：
{
"mask_id": 8,
"contact_parts": ["right_leg"],
"target_object": "couch"
}项目刻意把“几何证据提取”“身体部位定位”和“语言表达”拆开，便于分别测量错误来自 Grounder 还是 Qwen。
核心链路：
ScanNet 场景 + SMPL-X 动作 + 语言问题
│
▼
表面级距离与时序接触统计
│
├──► 确定性 6-part 几何接触掩码
│
▼
Uni3D 语义 + 解剖编码 + 关系编码
│
▼
Relation-aware Grounder + 反事实约束
│
▼
Evidence Authority 策略
│
▼
Qwen3.5-2B 结构化 JSON + 双语解释
│
▼
Gradio 3D 证据控制台
| 模块 | 输入 | 输出 | 作用 |
|---|---|---|---|
| Surface Geometry | ScanNet 网格、SMPL-X 顶点 | 点到三角面距离 | 形成可复查的物理测量 |
| Temporal Evidence | 逐帧距离 | 最小/末帧距离、接触比例 | 区分当前帧与整个序列 |
| Relation-aware Grounder | Uni3D、解剖、关系、问题 | 6-part 接触概率 | 学习问题相关的身体部位 |
| Counterfactual Objective | 成对交互样本 | 排序与一致性损失 | 检验预测是否随证据方向改变 |
| Evidence Authority | 几何/模型掩码 | 最终证据掩码 | 明确答案依据及冲突处理策略 |
| Structured Qwen | 问题、掩码、数值证据 | JSON 与自然语言解释 | 忠实表达而非替代几何判定 |
控制台以统一时间轴呈现 24 帧动作，并把两类容易混淆的证据明确分开：
- 当前帧证据：所显示帧的精确表面距离，距离不大于 5 cm 时标为
CONTACT。 - 序列级证据：整个采样序列的最小距离及接触比例；冻结规则要求最小距离不大于 5 cm 且接触帧比例不低于 10%。
因此，某个中间帧可以显示为 CLEAR，而完整序列仍被判断为发生接触。这不是矛盾，而是时间尺度不同。
当前界面已将数据集中的 persistent contact 明确解释为 sequence-level thresholded contact / 序列级阈值接触。它不会把“至少 10% 采样帧进入 5 cm 阈值”误写成全程连续接触。
平台包括：
- ScanNet 点云和目标物体实例；
- 六色 SMPL-X 身体网格及动作帧滑块；
- 当前帧/序列级证据轨；
- 六身体区域逐帧接触时间轴；
- 首次/末次接触帧、最长连续采样帧与接触区间数；
- 六身体部位距离、比例和接触状态表；
- Geometry、Grounder 与 Selected Authority 三种掩码；
- Qwen 结构化结果和双语解释；
- 一键下载当前样本的 JSON 证据审计记录；
- 带版本号与 HUMANISE motion ID 的渲染缓存校验，自动淘汰来源不一致的旧缓存；
- 反事实样本切换与证据一致性提示。
以下结果来自 3 折场景不重叠的开发集交叉验证。每个样本都由没有见过该 ScanNet 场景的模型预测，但它不是外部/OOD 最终测试。
| 指标 | Generic M16 | Relation-aware M26 | 提升 |
|---|---|---|---|
| Exact contact mask | 43.70% | 98.58% | +54.88 pp |
| Micro-F1 | 85.16% | 99.75% | +14.59 pp |
| Left-arm F1 | 77.11% | 99.77% | +22.66 pp |
| Right-arm F1 | 75.03% | 99.58% | +24.55 pp |
| Mean arm F1 | 76.06% | 99.67% | +23.61 pp |
| Changed-direction accuracy | 43.44% | 99.09% | +55.65 pp |
| Strict both-exact-and-flipped | 15.09% | 97.73% | +82.64 pp |
| 实验规模 | 数值 |
|---|---|
| QA 样本 | 2,254 |
| ScanNet 场景 | 35 |
| 反事实 pairs | 1,014 |
| 交叉验证 | 3 folds，scene-disjoint |
| M16 baseline 参数量 | 11.33M |
| M26 参数量 | 1.29M |
| M26 CV 峰值 GPU 显存 | 156.84 MiB |
| 冻结开发门槛 | 4 / 4 通过 |
| 受保护最终集读取 | 0 |
156.84 MiB 仅指这个小型 Grounder 的交叉验证峰值，不代表完整 Qwen、SMPL-X 或 Demo 管线的显存需求。
原始机器可读记录：summary.json、protocol.json、pooled_metrics.csv。
M25 在冻结策略后只打开一次 476-QA、6 场景最终集。它反映 M25 Grounder 的真实泛化差距，不能与 M26 的开发交叉验证混为同一测试。
| 策略 | JSON/mask fidelity | Task exact | Task micro-F1 | Changed direction |
|---|---|---|---|---|
| Grounder-authoritative | 100% | 38.87% | 81.33% | 29.53% |
这里的 100% 是语言输出对选定证据掩码的忠实度；38.87% 才是 M25 Grounder 在受保护最终集上的 exact 指标。该结果直接推动了 M26 的关系感知架构。
PhysHIS 通过 26 个可审计里程碑逐步构建，而不是一次性堆叠模型：
| 阶段 | 里程碑 | 主要进展 |
|---|---|---|
| 几何基础 | M0–M5 | 碰撞检查、HIS-Bench 数据审计、场景不重叠划分、Physics-lite、2K Contact QA |
| 人体表面 | M6–M15 | HUMANISE/SMPL-X 对齐、六部位 mesh token、ScanNet surface、查询条件选择器、50 场景扩展 |
| 因果定位 | M16–M22 | 自动反事实数据、Stage-A/B Grounder、错误归因、校准解码、pair direction |
| 忠实生成 | M23–M25 | 结构化 Qwen、证据化解释、Explicit Evidence Authority、受保护最终评估 |
| 完整系统 | M26 | Relation-aware Grounder、三折 scene CV、双时间尺度 3D 证据 Demo |
每个阶段的协议、结果和限制均保留在 reports/ 中。
- Python 3.10+
- PyTorch 2.6+
- NVIDIA GPU（训练与 Qwen 推理推荐）
- Linux/CUDA 环境（完整数据管线推荐）
git clone https://github.com/BoPythonAI/PhysHIS.git
cd PhysHIS
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e '.[dev]'PYTHONPATH=. pytest -q
python scripts/smoke_geometry.py本仓库不重新分发 ScanNet、HUMANISE、SMPL-X、HIS-Bench/HIS-GPT 数据、Qwen 权重或 Uni3D 特征。请从各自官方渠道申请并下载，然后按脚本参数放置或传入路径。
推荐的本地布局：
data/
└── raw/
├── his_bench/
├── his_gpt/
├── humanise/
├── scannet/
├── smplx/
└── models/
└── Qwen3.5-2B/
Demo 需要已生成的 M21/M25 协议、预测缓存、HUMANISE/ScanNet/SMPL-X 资源。完整参数说明见 demo/README.md。
pip install -e '.[demo]'
python demo/app.py --server-name 0.0.0.0 --port 7860浏览器访问 http://127.0.0.1:7860。远程服务器建议通过 SSH 隧道访问，不要直接暴露研究服务。
在完成 M16 自动 grounding 数据和 Qwen query embedding 准备后运行：
bash scripts/run_m26_relation_grounder.sh协议构建、训练和汇总脚本分别位于：
scripts/build_m26_grounder_protocol.py
scripts/train_m26_grounder_cv.py
scripts/run_m26_relation_grounder.sh
PhysHIS/
├── configs/ # 各阶段实验配置
├── .github/workflows/ # GitHub Actions 自动测试
├── demo/
│ ├── app.py # 双语 3D 物理证据控制台
│ └── README.md # Demo 数据契约与启动方式
├── docs/assets/ # 架构图、结果图与真实平台截图
├── reports/ # M1–M26 研究记录及完整中文项目报告
├── results/ # 可公开协议、汇总 JSON 与 CSV
├── scripts/ # 数据、训练、评估、审计和可视化脚本
├── src/physhis/
│ ├── data/ # HIS-Bench/HUMANISE/ScanNet 数据适配
│ ├── modeling/ # Surface token、Grounder、SMPL-X 等
│ ├── constrained_decoder.py # 64-mask 受约束解码
│ ├── evidence_authority.py # 证据权限与冲突策略
│ ├── geometry.py # 可验证几何层
│ ├── grounded_explanation.py # 证据化自然语言解释
│ └── structured_qwen.py # Qwen 结构化生成
├── tests/ # 125 项单元/协议测试
├── pyproject.toml
└── README.md
这是项目最重要的阅读说明：
- M26 的目标接触掩码由显式表面距离、接触比例和时序关系通过确定性规则生成，而这些关系也作为输入提供给模型。
- 因此接近满分的开发集结果验证的是：特征提取正确、身体部位身份保留、冻结规则可跨开发场景传递、反事实方向被忠实处理。
- 它不能单独证明模型理解开放世界中的力、支撑、摩擦、稳定性，也不能证明对另一套接触标注政策的泛化。
- M26 没有读取 M21 的 476-QA 受保护最终集，也没有读取旧版 668-QA locked test。
- 对 Relation-aware Grounder 的最终结论仍需要独立标注、场景不重叠的外部/OOD 测试集。
当前准确表述是：PhysHIS 已构建可验证的表面规则 Grounder、忠实的 Qwen 证据解码器和端到端 3D 证据 Demo；开放世界物理泛化仍未被证明。
最新服务器验证：
125 passed
同时完成：
- Python 模块与脚本编译检查；
- M26 协议哈希与受保护场景零重叠审计；
- 3 折训练、checkpoint 重载和重新评估；
- Gradio 根页面与配置 API HTTP 200；
- 真实样本加载、帧更新、3D 图、证据轨和六部位表联动测试。
- GitHub Actions 在 push 与 Pull Request 时自动运行完整测试。
| 资源 | 用途 | 获取方式 |
|---|---|---|
| ScanNet | 三维场景、物体实例与表面 | 官方许可/下载协议 |
| HUMANISE | 场景对齐人体动作 | 官方项目许可 |
| SMPL-X | 参数化人体网格 | 官方注册与许可证 |
| HIS-Bench / HIS-GPT | Human-in-Scene QA 与训练数据 | 上游发布条款 |
| Uni3D | 目标物体语义特征 | 上游模型条款 |
| Qwen3.5-2B | 结构化回答与双语解释 | 上游模型许可证 |
请分别遵守所有上游数据与模型的许可证。本仓库目前未声明项目级开源许可证；在获得明确许可前，请勿假定代码可用于商业再分发。
欢迎通过 Issue 提交复现问题、协议审计、独立标注数据或外部/OOD 评估建议。若本项目用于研究，请引用本仓库并注明所使用的里程碑、协议哈希和数据授权版本。
PhysHIS — from plausible answers to inspectable physical evidence.