main
ci / macos-latest / apple-clang (push) Waiting to run
ci / windows-latest / mingw (push) Waiting to run
ci / windows-latest / msvc (push) Waiting to run
ci / ubuntu-latest / clang (push) Failing after 43s
ci / ubuntu-latest / gcc (push) Failing after 40s
ci / coverage / gcc (push) Failing after 34s
g70: FreeCAD drop-in configure 绿收口——MSVC 移植第三轮 9 警告全清(首次 MSVC 全绿) +
1f14a47 reconfirm 潜伏缺陷修复 + apply.ps1 接线工具 + 31/34 号记录
VDCS — ViewDesign Constraint Solver
2D + 3D 通用几何约束求解引擎,以独立 C++ 核心库/SDK 形式交付,ViewDesign 系列产品。对标 D-Cubed DCM / Siemens LGS,重鲁棒性、性能与扩展性。
命名说明:与 ViewDesign 系列产品(ViewDesignEngine →
vde)同规,全库统一 vdcs 标识——头文件路径#include <vdcs/...>、命名空间vdcs::、C ABIvdcs_*(92 符号冻结契约)、CMake target /find_package(vdcs)/ 链接名vdcs::vdcs。v2.1.0 完成一次性切换(旧gcs*标识不再保留别名),下游接入请对齐本版口径。
构建
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build
依赖(CMake 自动获取,亦可由 vcpkg 提供):Eigen3、nlohmann/json、GoogleTest。
当前能力(v2.1.0+:planeGCS 词表全覆盖 + 3D 词表 17 词收官,替换就绪)
- 2D 实体:Point2D / Line2D(法向式 φ,d)/ Circle2D / Arc2D / Segment2D / Ellipse2D / ArcOfEllipse2D / Hyperbola2D / ArcOfHyperbola2D / Parabola2D / ArcOfParabola2D / BSpline2D / ScalarParam2D / ExternalCurve2D(宿主样条等自由曲线只读委托)
- 3D 实体:Point3D / Line3D(方向球坐标 + 正交基锚点,消滑移冗余)/ Plane3D / Sphere3D / Cylinder3D / RigidBody(SO(3) 切空间参数化 + 增量重基准)
- 约束:2D 33 类(重合、距离、DistanceX/Y、半径/直径/长度、水平/竖直、平行、垂直、共线、相切(含端点形式与线-椭圆/外部曲线)、同心、等半径/等长/等距、中点、对称、线-线角、三点角(象限)、弧角/弧长、椭圆半径/直径/主轴角、Block、SnellsLaw、椭圆/双曲线/抛物线 InternalAlignment、BSpline 求值族、P2P 角度族等)+ 3D 17 词(重合/距离/点-面距/点-线距/点-球面距/异面线距、方向极角/方位角、平行/垂直/中点/线∥面/角度/同心、圆柱/球半径、刚体固连/扭转/姿态锁定)
- 拖拽交互:DragController 三段式(Begin/Move/End)+ 分解式子树优先级——欠约束自由度吸收拖拽目标,子树外几何不动(C ABI 同步暴露);拖拽基准 129 场景全量对拍、60fps 帧预算双侧零违规
- 求解:三引擎——稠密 Newton(小模型)/ 稀疏 Levenberg-Marquardt(
Model::Solve按规模路由)/ 分解求解(DR-planning:DM 图分解 → 块 DAG 拓扑序逐块小规模 LM → 装配),helix_truss_170 场景对整体式 LM 达 32× 加速(76.8ms → 2.36ms) - 图分解:DOF 加权 Dulmage-Mendelsohn(Hopcroft-Karp 最大匹配 + 三部划分 + Tarjan SCC)→ well/过约束/欠约束块 + 自底向上求解序
- 诊断:DM 块级结构定位——冲突(
kConflictingConstraint,未收敛的过约束块)与一致冗余(kRedundantConstraint,可收敛)区分、欠约束逐实体定位、数值秩亏(隐藏冗余)与结构层 UID 去重、structural_redundancy结构冗余量;Grübler 计数 + 雅可比秩检测 + 停滞区分(kStalledvskNotConverged);结构化SolveResult可 JSON 序列化 - 序列化:原生二进制
.vdcs与 JSON 双格式(98 约束 kind);加载端值域/引用/类型完整性校验 - C ABI:
include/vdcs/c_api/vdcs_c_api.h纯 C 边界(句柄式、错误码返回、异常不跨 ABI;153 符号冻结,追加式演进) - 鲁棒性:矛盾/退化/病态尺度/大旋转扰动结构化拒绝或收敛;模糊七轴——字节腐蚀 100000 迭代(驱动路径轮转七路径)+ C ABI 调用序列编排 300000 ops(双 seed)+ 随机语义场景 10000 场景(四硬不变量)+ 结构感知 JSON 腐蚀 + 表达式腐蚀 + 增量编辑序列对拍 + 兼容层调用编排 300000 ops,零崩溃零异常逃逸;扰动鲁棒性五路径配对口径(分解路径 100% 收敛)
- planeGCS 兼容:
examples/freecad_compat/drop-in shim(GCS::System/Geo/Constraints 头面,内部转发 vdcs,设计见 34-FreeCAD集成层设计);真实语料回归 136 场景三目录(2D 上游 105 + 3D 引擎自有 24 + 引擎自有扩展 7,planeGCS 官方求解回归语义等价转换 + 引擎自有词自证)双回放器 100%(tests/corpus/)
快速上手
#include <vdcs/vdcs.h>
vdcs::Model model;
auto p1 = model.AddPoint2D("P1", 0.0, 0.0).Value();
auto p2 = model.AddPoint2D("P2", 10.0, 0.0).Value();
model.AddFixed2D("F1", p1);
model.AddDistance2D("D1", p1, p2, 12.5);
auto report = model.Solve(vdcs::SolveOptions{});
诊断与 DOF 分析:
auto dof = vdcs::DofAnalyzer::Analyze(model);
auto result = vdcs::SolveDiagnostics::Build(report.Value(), dof);
// result.status / result.mobility / result.diagnostics
3D 建模与分解求解:
vdcs::Model model;
auto a = model.AddPoint3D("A", 0, 0, 0).Value();
auto b = model.AddPoint3D("B", 5, 0, 0).Value();
model.AddFixed3D("FA", a);
model.AddDistance3D("DAB", a, b, 5.0);
auto decomp = vdcs::Decomposer::Decompose(model); // DM 结构分解
auto report = model.Solve(vdcs::SolveOptions{}); // 或 DecomposedSolver 逐块
auto result = vdcs::SolveDiagnostics::Build( // 结构诊断(块级定位)
report.Value(), vdcs::DofAnalyzer::Analyze(model), decomp);
示例
| 示例 | 语言 | 演示 |
|---|---|---|
examples/minimal_sketch |
C++ | 两点距离最小草图(Phase 0 PoC) |
examples/sketch_tutorial |
C++ | 相切圆对:混合实体、欠约束诊断、尺寸驱动重解、JSON 往返 |
examples/c_api_demo |
C | C ABI 全链路:建模 → 求解 → 尺寸驱动 → 诊断逐条访问 |
examples/host_adapter |
C++ | 宿主适配层参考实现:七桥面(几何/约束/参数表/求解诊断/拖拽/读回/持久化)七场景自校验 |
examples/freecad_compat |
C++ | planeGCS drop-in 兼容层:GCS::System API + Geo/Constraints 头直接替换,内部转发 vdcs(mini_host 十三场景 835 断言自校验) |
文档
设计文档与执行计划见 docs/;开发进度见 docs/design/31-开发进度跟踪.md。
参与贡献
见 CONTRIBUTING.md——构建/测试/工作流/代码风格,good-first-issue 七类候选入门任务。
支持策略
版本通道、支持窗口与兼容性承诺见 docs/design/32-长期支持策略.md:LTS 系列 GA 起 24 个月标准支持 + 12 个月延长支持;C ABI 在 LTS 系列内冻结(ctest 门禁保证)。
许可证
Apache-2.0,见 LICENSE。
Languages
C++
94.9%
C
2.3%
Python
1.4%
CMake
1.3%
PowerShell
0.1%