Project structure
You bought the source. Here is where to start reading.
This chapter is for source customers. The first five minutes with a repository decide your opinion of it, so "where to start" comes first rather than leaving you to dig.
The source is sold as two repositories, each of which builds on its own: the HMI source
(precisim-hmi-source) and the algorithms source (precisim-algorithms-source, the algorithm
layer: vision, calibration, numerics, statistics, alignment, path planning). The trees below are what you see after cloning;
each repository is projected from the same whitelist.
HMI source
precisim-hmi-source/
├── PreciSim.sln HMI solution
├── Directory.Build.props Repository-wide build settings (TreatWarningsAsErrors and so on)
├── NuGet.config Points at packages/; no private feed
├── README.md Getting it running
├── LICENSE-COMMERCIAL.md Source licence
├── src/
│ ├── 02.PreciSim.Devices Real device implementations (Real/, placeholders today; write them for your hardware)
│ ├── 03.PreciSim.Framework Framework layer: Null implementations of the algorithm contracts (Fallbacks/), failed-frame dump (Imaging/)
│ ├── 06.PreciSim.Workflow Station abstraction + DAG engine (Stations/); production: drill-file parsing, recipes, production stations (Process/)
│ └── 07.PreciSim.App WPF HMI (MVVM): Views/ + ViewModels/; the composition root is Composition/;
│ the production workflow is in Workflows/, the offline manual in Help/
├── tests/
│ └── PreciSim.Workflow.Tests Regression tests for workflow, stations, drill-file parsing and the production flow
├── samples/
│ └── demo-panel-60x50.drl Sample drill file (60 × 50 mm, 177 holes, 4 tools); format notes in the README next to it
├── build/
│ ├── publish.ps1 Publish script (runs the tests, then dotnet publish)
│ └── PreciSim.iss Installer script (Inno Setup)
├── core/ Contract source (its own solution)
│ ├── PreciSim.Core.sln
│ ├── src/PreciSim.Core Coordinate conventions C1–C10 (Geometry/), units, result types, Frame
│ ├── src/PreciSim.Devices.Abstractions Device interfaces
│ ├── src/PreciSim.Algorithms.Abstractions Algorithm interfaces (Vision/, Calibration/, Alignment/, PathPlanning/)
│ └── tests/PreciSim.Core.Tests Tests for the coordinate conventions
└── packages/ NuGet packages shipped with the repository (see below)
There is no 01, 04 or 05: the contracts live in core/, and vision, calibration, alignment and
path planning belong to the algorithm layer, which comes in as packages.
Algorithms source
precisim-algorithms-source/
├── PreciSim.Algorithms.sln Algorithm-layer solution
├── Directory.Build.props Repository-wide build settings (TreatWarningsAsErrors and so on)
├── NuGet.config Points at packages/; no private feed
├── README.md Getting it running
├── LICENSE-COMMERCIAL.md Source licence
├── src/
│ ├── Vision.Managed Vision operators
│ ├── Calibration The seven calibration chains: Procedures/ (sampling and flow) + Solvers/ (point sets in, parameters out)
│ ├── Numerics Numerics
│ ├── Statistics Statistics (residuals)
│ ├── Alignment Alignment: fiducial point sets → rotation / scale / offset
│ └── PathPlanning Path planning: partitioning by galvo field, serpentine order
├── tools/
│ └── Cli Command line tool: run chains against ground truth, config check, capture, panorama export, render benchmark
├── tests/
│ ├── PreciSim.Algorithms.Tests Solver unit tests on point sets (Solvers/)
│ └── PreciSim.Calibration.Tests Regression of the calibration chains against ground truth
├── core/ Contract source (identical to core/ in the HMI repository)
│ ├── PreciSim.Core.sln
│ ├── src/PreciSim.Core
│ ├── src/PreciSim.Devices.Abstractions
│ ├── src/PreciSim.Algorithms.Abstractions
│ └── tests/PreciSim.Core.Tests
└── packages/ NuGet packages shipped with the repository (see below)
Packages shipped with the repository
The two repositories, and each repository and the engine, are connected only through NuGet
packages. They live in the repository's packages/ folder and the root NuGet.config already
points at it: no private feed, no sign-in.
| Package | HMI repo | Algorithms repo |
|---|---|---|
PreciSim.Core / Devices.Abstractions / Algorithms.Abstractions (contracts) |
✓ (source also in core/) |
✓ (source also in core/) |
PreciSim.Vision.Managed / Calibration / Numerics / Statistics / Alignment / PathPlanning (algorithms) |
✓ binary | not shipped: the source is in src/ |
PreciSim.Engine / Engine.Drivers (virtual device engine and virtual drivers) |
✓ binary | ✓ binary |
The engine ships as a binary only. Its physics is documented in full under
physics — the formulas are public, the implementation is
not. Machine description files land in machines/ in the output folder together with the engine
package.
If you buy only the HMI source, the algorithms come as binary packages; what each source package lets you do is in the source licence.
Three files to read on day one
| File | Repository | Why |
|---|---|---|
core/src/PreciSim.Core/Geometry/Jacobian2x2.cs |
both | The foundation of pixel-to-millimetre conversion; teaches the C1–C10 conventions and why sign direction belongs in the comments |
src/Calibration/Procedures/PixelSizeProcedure.cs |
algorithms | A complete calibration chain; the other six share its structure. Its solver is src/Calibration/Solvers/PixelSizeSolver.cs |
src/07.PreciSim.App/ViewModels/Calibration/ChainWizardViewModel.cs |
HMI | How a wizard drives a chain: parameters, acquisition, result, apply — including progress, cancel and re-run |
With both repositories, those three are enough to add an eighth chain yourself.
Dependency direction
HMI repo: App ──→ Workflow ──→ algorithm contracts (Algorithms.Abstractions)
│ └──→ Framework ─┘
└────→ Devices ───→ device contracts + Core
(App is the composition root: only it references the algorithm and engine packages)
Algorithms repo: Calibration ──→ Numerics / Statistics ──→ Core
Calibration ──→ algorithm contracts
Vision.Managed ─→ algorithm contracts
(only tools/Cli and the test projects reference the engine; the algorithms themselves do not know it)
Dependencies only point downward. HMI business code knows only the contracts in core/;
concrete algorithm and engine types appear only in 07.PreciSim.App/Composition/. Every algorithm
contract has a Null implementation in 03.PreciSim.Framework/Fallbacks/, so the HMI starts without
the algorithm packages. That is the thing to check when lifting a layer into your own product.
The boundary between repositories is hard: the HMI repository contains no algorithm or engine source at all, so a cross-layer reference does not compile. The direction inside a repository is kept by the project structure and by review; it is not an architecture test yet.
It builds on a clean clone
git clone <the repository URL you received>
cd <repository folder>
dotnet restore
dotnet build -c Release # must be warning-free: TreatWarningsAsErrors is on
dotnet testcore/ is a separate solution; to run the contract tests: dotnet test core/PreciSim.Core.sln.
No dependency on our paths or private feeds. Before every delivery the repository is restored, built and tested in a fresh folder, so a fresh clone should compile as is. If it does not, that is our bug — open an issue.
Keeping up with updates
git pull origin main
git log --oneline v0.1.0..Every release is tagged and has release notes. New package versions arrive in packages/ with the
git pull. Breaking changes only happen on major versions and are called out separately in the
changelog.
Next: adding a page.