+122
View File
@@ -0,0 +1,122 @@
# VDCS-019:装配配合需要 3D 刚体位姿分量与实体级 mate 约束(P0,主需求)
> **编号说明(2026-10-28)**:本需求最初以 `VDCS-018` 提交(分支 `feedback/VDCS-018`),
> 但 VDCS 主分支已将 `VDCS-018` 用于「CAE 参数化设计研究 / 批量驱动 + 事务回滚」,
> 因此按主分支现状重新编号为 **VDCS-019** 并重提,内容不变。
## 背景
宿主要实现 SolidWorks 式装配配合:用户选两个 **实体**(面/边/轴/顶点)建重合/同心/距离/角度等配合,拖动零件时配合实时满足,并支持编辑/抑制/过定义提示。
VDCS 已具备完整的通用约束求解框架(Newton / LM / dogleg、DOF 与秩分析、冗余诊断、decomposer、drag_controller、2D/3D 分量),但缺少:
1. **3D 刚体位姿分量**(每零件 6 DOF,四元数位姿);
2. **实体级 mate 约束**(B-Rep 面/边/轴/点参数,不是草图实体)。
VDE 侧只负责 B-Rep 拓扑/几何与装配树位姿(另见 VDE-1238 实体几何参数与稳定引用),不承担配合求解。
## 期望行为
### 1. 刚体位姿分量(新分量类型 RigidBody)
```
参数 = { tx, ty, tz, qw, qx, qy, qz } // 平移 + 单位四元数
DOF = 6;fixed 时 0
```
- 增量更新用 `delta = [dt(3), dtheta(3)]`,四元数按增量旋转后归一化,避免欧拉角奇点;
- 每个零件一个分量,可被多个 mate 跨分量引用;
- 序列化:位姿可保存/回读。
### 2. mate 实体(MateEntity,不依赖 B-Rep 类型)
```
entity kind = MateEntity
参数 = { component_uid,
kind ∈ {Plane, Cylinder, Sphere, Cone, Line, Point},
point(3), dir(3), radius, half_angle, reversed }
```
- point/dir/radius 为**零件局部**几何参数,求解时按分量位姿变换到世界;
- 宿主从 B-Rep 求值后传入(VDE-1238 提供面/边参数与内孔反向),VDCS 不直接依赖 B-Rep。
### 3. mate 约束类型与残差(`r=0` 满足;`aligned=false` 时 b 的法向取反)
| 类型 | 残差 |
|---|---|
| Coincident(Plane,Plane) | `nA·(pB-pA)`(1)+ `nA×nB'`(2) |
| Distance(Plane,Plane) | `nA·(pB-pA) - value`(1) |
| Angle(Plane,Plane) | 由 `nA·nB' = cos(value)` 导出的 1 维(避免 acos 不稳) |
| Concentric(Cylinder,Cylinder) | `(pB-pA) - ((pB-pA)·aA)aA`(2)+ `aA×aB`(2) |
| Parallel(Plane/Line) | `nA×nB'`(2) |
| Perpendicular(Plane/Line) | `nA·nB`(1) |
| Insert(孔-轴) | 同心(4)+ 面-面重合(3) |
| Lock | 位姿 6 维:两零件参考系重合 |
| Tangent / Sphere·Cone·Point 组合 | 二期(结构先留) |
- 可选限位:Distance/Angle 的 min/max(二期);
- 雅可比:优先解析(平面/圆柱易求);一期可用数值差分(开关控制),但需满足性能要求(见 §5)。
### 4. 求解接口(C++ / C API 建议)
```cpp
// C++ 侧
vdcs_uid vdcs_add_rigid_body(vdcs_model* m, const char* name, const double pose[7]);
vdcs_uid vdcs_add_mate_entity(vdcs_model* m, vdcs_uid component,
int kind, const double point[3], const double dir[3],
double radius, double half_angle, int reversed);
vdcs_uid vdcs_add_mate(vdcs_model* m, vdcs_uid ent_a, vdcs_uid ent_b,
int mate_type, int aligned, double value);
vdcs_result vdcs_update_mate(vdcs_model* m, vdcs_uid mate,
int aligned, double value, int suppressed);
vdcs_result vdcs_remove_mate(vdcs_model* m, vdcs_uid mate);
vdcs_result vdcs_solve(vdcs_model* m); // 复用现有求解入口
vdcs_result vdcs_drag(vdcs_model* m, vdcs_uid component, const double delta[6]); // 拖拽增量
vdcs_result vdcs_mate_residuals(vdcs_model* m, double* residuals, int capacity, int* count);
vdcs_result vdcs_conflicts(vdcs_model* m, vdcs_uid* mates, int capacity, int* count);
vdcs_result vdcs_get_pose(vdcs_model* m, vdcs_uid component, double pose[7]);
```
要求:
- 收敛后位姿可回读(宿主写回装配树);
- 未收敛返回冲突 mate uid 列表(宿主 UI 标红/可抑制);
- 过定义/冗余沿用现有诊断(约束行进入 SVD/秩分析),并给出冗余 mate 建议;
- 线程安全、无全局状态:宿主在拖拽 mousemove 中频繁调用 `vdcs_drag`。
### 5. 性能要求
| 场景 | 要求 |
|---|---|
| 2 零件 / 3 mate,完整 solve | < 10ms(数值雅可比)/ < 1ms(解析) |
| 拖拽增量(放开被拖分量+约束链,1~3 次迭代) | < 5ms/次(数值)/ < 1ms(解析) |
| 20 零件 / 40 mate 完整 solve | < 100ms(解析雅可比;数值雅可比可放宽) |
### 6. 序列化
- mate(实体 uid + 参数 + 类型 + aligned + value + suppressed)与刚体分量位姿可保存/回读;
- 版本号 + 向后兼容。
## 复现/验证场景(验收)
1. 两方块 `Plane`-`Plane` `Coincident`(aligned / anti):收敛、残差 <1e-8、朝向正确;
2. 轴-孔 `Cylinder`-`Cylinder` `Concentric`:横向残差 <1e-8、轴向自由(DOF=2);
3. 面-面 `Distance(10mm)` → 收敛且距离=10;改 20 收敛到 20;
4. 面-面 `Angle(45°)` → 收敛;改 30° 收敛;
5. `vdcs_drag` 拖一个刚体,另一保持贴合(残差 <1e-6),单次 <10ms;
6. 矛盾场景(同一面 Distance 10 + Coincident)→ 未收敛 + `vdcs_conflicts` 返回冲突 mate;
7. 过定义(一对零件 7 个独立约束)→ 冗余诊断给出多余 mate 建议;
8. 序列化往返后求解结果一致;
9. 固定件(fixed)不参与位姿更新;全固定时 solve 直接返回。
## 排查建议
- 角度残差(无量纲)与长度残差(mm)需归一化,避免条件数差;
- 四元数参数块建议“旋转增量 + 归一化投影”参数化(参考现有 3D 分量实现);
- 复用 `decomposed_solver` 按约束图分解,显著缩小大装配求解规模;
- 与 VDE-1238 对齐 `reversed`(内孔)语义,避免内外圆柱同心方向相反。
## 关联
- **VDE-1238(P0,配套)**:B-Rep 实体几何参数查询(平面/圆柱/球/锥/直线 + 内孔反向)与稳定实体引用序列化 —— 宿主用它生成 `MateEntity` 参数
- **VDE-1237(deferred)**:背景资料(VDE 侧不做配合求解)
- 宿主设计:`docs/dev/assembly-mates-design.md`;差距分析:`docs/dev/assembly-mates-gap-analysis.md`
- 宿主 UI/架构:`src/vd_shell/mate_panel.*`、`assembly_tree.*`、`src/vd_assembly/*`