项目结构
买了源码之后,从哪看起。
这一章是给买了源码的用户的。打开仓库的前 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 testcore/ 是单独的解决方案,要跑契约的测试:dotnet test core/PreciSim.Core.sln。
不依赖我们这边的任何路径或私有源。 每次交付前都会在一个全新目录里做一遍 「还原 → 编译 → 跑测试」,所以你 clone 下来应该能直接编过。编不过是我们的 bug,开 issue。
跟上更新
git pull origin main
git log --oneline v0.1.0..每个版本打 tag、发 Release。新版本的包随 git pull 一起更新到 packages/。
破坏性变更只在大版本发生,并在更新日志里单独标注。
下一篇:怎么加一个页面。