跳到正文
PreciSim
source-guide

项目结构

买了源码之后,从哪看起。

这一章是给买了源码的用户的。打开仓库的前 5 分钟决定你的评价, 所以我们把「从哪看起」写在最前面,而不是让你自己翻。

源码分两个仓库卖,各自能单独编译:上位机源码(precisim-hmi-source)和 算法源码(precisim-algorithms-source,即算法层:视觉、标定、数值、统计、对位、路径规划)。 下面的目录树就是你 clone 下来看到的样子,每个仓库都由同一份白名单投影出来。

上位机源码

precisim-hmi-source/
├── PreciSim.sln                 上位机解决方案
├── Directory.Build.props        全仓编译设置(TreatWarningsAsErrors 等)
├── NuGet.config                 指向 packages/,不需要私有源
├── README.md                    先跑起来的步骤
├── LICENSE-COMMERCIAL.md        源码商业许可
├── src/
│   ├── 02.PreciSim.Devices      真机设备实现(Real/,目前是占位,按你的硬件写)
│   ├── 03.PreciSim.Framework    框架层:算法契约的 Null 实现(Fallbacks/)、失败帧落盘(Imaging/)
│   ├── 06.PreciSim.Workflow     Station 抽象 + DAG 引擎(Stations/);生产:钻孔图档解析、配方、生产工站(Process/)
│   └── 07.PreciSim.App          WPF 上位机(MVVM):Views/ + ViewModels/,组合根在 Composition/;
│                                生产流程定义在 Workflows/,离线使用说明在 Help/
├── tests/
│   └── PreciSim.Workflow.Tests  工作流、工站、图档解析与生产流程的回归
├── samples/
│   └── demo-panel-60x50.drl     示例钻孔图档(60 × 50 mm,177 孔、4 把刀),格式说明见同目录 README
├── build/
│   ├── publish.ps1              发布脚本(先跑测试,再 dotnet publish)
│   └── PreciSim.iss             安装包脚本(Inno Setup)
├── core/                        契约源码(单独一个解决方案)
│   ├── PreciSim.Core.sln
│   ├── src/PreciSim.Core                     坐标约定 C1–C10(Geometry/)、单位、结果类型、Frame
│   ├── src/PreciSim.Devices.Abstractions     设备接口
│   ├── src/PreciSim.Algorithms.Abstractions  算法接口(Vision/、Calibration/、Alignment/、PathPlanning/)
│   └── tests/PreciSim.Core.Tests             坐标约定的测试
└── packages/                    随仓附带的 NuGet 包(见下)

编号里没有 01、04、05:契约在 core/,视觉、标定、对位、路径规划在算法层,以包的形式进来。

算法源码

precisim-algorithms-source/
├── PreciSim.Algorithms.sln      算法层解决方案
├── Directory.Build.props        全仓编译设置(TreatWarningsAsErrors 等)
├── NuGet.config                 指向 packages/,不需要私有源
├── README.md                    先跑起来的步骤
├── LICENSE-COMMERCIAL.md        源码商业许可
├── src/
│   ├── Vision.Managed           视觉算子
│   ├── Calibration              七条标定链:Procedures/(采样与流程)+ Solvers/(只收点集、只出参数)
│   ├── Numerics                 数值
│   ├── Statistics               统计(残差)
│   ├── Alignment                对位:基准点点集 → 旋转 / 涨缩 / 平移
│   └── PathPlanning             路径规划:按振镜场分块、蛇形排序
├── tools/
│   └── Cli                      命令行工具:跑标定链并对照真值、配置自检、取图、全景导出、渲染基准
├── tests/
│   ├── PreciSim.Algorithms.Tests    求解器点集级单测(Solvers/)
│   └── PreciSim.Calibration.Tests   标定链对照真值的回归
├── core/                        契约源码(与上位机仓里的 core/ 相同)
│   ├── PreciSim.Core.sln
│   ├── src/PreciSim.Core
│   ├── src/PreciSim.Devices.Abstractions
│   ├── src/PreciSim.Algorithms.Abstractions
│   └── tests/PreciSim.Core.Tests
└── packages/                    随仓附带的 NuGet 包(见下)

随仓附带的包

两个仓库之间、仓库和引擎之间只靠 NuGet 包相连,包放在仓库的 packages/ 目录里, 根目录的 NuGet.config 已经指向它,不需要配私有源,也不需要登录。

包 上位机仓 算法仓
PreciSim.Core / Devices.Abstractions / Algorithms.Abstractions(契约) ✓(源码也在 core/) ✓(源码也在 core/)
PreciSim.Vision.Managed / Calibration / Numerics / Statistics / Alignment / PathPlanning(算法) ✓ 二进制 不附带:源码就在本仓 src/
PreciSim.Engine / Engine.Drivers(虚拟设备引擎与虚拟驱动) ✓ 二进制 ✓ 二进制

引擎只有二进制:它的物理模型在文档的物理部分里完整公开—— 公式公开,实现闭源。机台描述文件随引擎包落到输出目录的 machines/ 下。

只买上位机源码的话,算法以二进制包提供;两种源码各自的许可范围见源码商业许可。

第一天该看的三个文件

文件 在哪个仓 为什么
core/src/PreciSim.Core/Geometry/Jacobian2x2.cs 两个都有 像素↔毫米换算的地基。看完就懂了 C1–C10 这套坐标约定,以及符号方向为什么要写进注释
src/Calibration/Procedures/PixelSizeProcedure.cs 算法 一条标定链的完整样板,其余六条结构相同;对应的求解器在 src/Calibration/Solvers/PixelSizeSolver.cs
src/07.PreciSim.App/ViewModels/Calibration/ChainWizardViewModel.cs 上位机 向导怎么和标定链对接:参数 → 采集 → 结果 → 应用,含进度、中止、重跑

两个仓都买了,看完这三个就能自己加第八条标定链。

依赖方向

上位机仓:  App ──→ Workflow ──→ 算法契约(Algorithms.Abstractions)
             │ └──→ Framework ─┘
             └────→ Devices ───→ 设备契约 + Core
             (App 是组合根:只有它引用算法实现包和引擎包)

算法仓:    Calibration ──→ Numerics / Statistics ──→ Core
             Calibration ──→ 算法契约
             Vision.Managed ─→ 算法契约
             (tools/Cli 与测试工程才引用引擎包,算法本身不认识引擎)

只允许从上往下依赖。 上位机的业务代码只认 core/ 里的契约,算法和引擎的具体实现只在 07.PreciSim.App/Composition/ 里出现。每个算法契约在 03.PreciSim.Framework/Fallbacks/ 有 Null 实现, 所以不装算法包也能开机。把某一层搬进自己的产品时,要检查的就是这条。

仓库之间的边界是硬的:上位机仓里根本没有算法和引擎的源码,想跨层引用也编不过。 仓库内部的依赖方向目前靠工程结构和代码检视保证,没有做成架构测试。

能独立编译

git clone <你收到的仓库地址>
cd <仓库目录>
dotnet restore
dotnet build -c Release     # 必须零警告:TreatWarningsAsErrors 开着
dotnet test

core/ 是单独的解决方案,要跑契约的测试:dotnet test core/PreciSim.Core.sln。

不依赖我们这边的任何路径或私有源。 每次交付前都会在一个全新目录里做一遍 「还原 → 编译 → 跑测试」,所以你 clone 下来应该能直接编过。编不过是我们的 bug,开 issue。

跟上更新

git pull origin main
git log --oneline v0.1.0..

每个版本打 tag、发 Release。新版本的包随 git pull 一起更新到 packages/。 破坏性变更只在大版本发生,并在更新日志里单独标注。

下一篇:怎么加一个页面。

最后更新: 2026/9/23
这页有帮助吗?