0308a862b8
Opus55 ignored NestJobPart.Priority, so the shared contract test (lower number wins scarce stock) failed; lower-number priority now precedes its placement score. SheetEconomics is replaced by the host's NestJobCost so it optimizes exactly what the benchmark scores, and its footprint margin comes from NestTolerances.SafeClearanceMargin plus four Clipper grid units - the same 0.003 total as before, which keeps its contact points. Synthetic benchmark (5 jobs, salvage 0.5): all valid, cost unchanged at 5452.79, time 611 -> 456 ms. Co-Authored-By: Codex <noreply@openai.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
108 lines
6.7 KiB
Markdown
108 lines
6.7 KiB
Markdown
# OpenNest.Engine.Opus55
|
||
|
||
An independent whole-job `INestingEngine`: **frontier-advance NFP packing with look-ahead
|
||
stock selection**. It does not call, wrap, or select over any built-in engine
|
||
(`StockLadderNestingEngine`, `FixedStrategyNestingEngine` strategies, `PlateNesterFactory`,
|
||
`NestingEngineRegistry`), nor the removed `OpenNest.Engine/Nfp` bottom-left-fill/annealing code.
|
||
Every placement decision (which part, which rotation, where, on which sheet) comes from the logic below.
|
||
|
||
## Algorithm
|
||
|
||
**1. Geometry (`PartCatalog`, `NoFitCache`)**
|
||
- Each part's outer perimeter is polygonized with a known chord tolerance (0.002 by default,
|
||
coarsened for arc-heavy parts until the outline is ≤ ~64 vertices, capped at 0.1% of part size).
|
||
- Candidate rotations come from the part's `RotationPolicy`: for `Automatic`, the four right
|
||
angles plus the two orientations that axis-align the minimum-area bounding rectangle
|
||
(`RotatingCalipers`); for sweeps, the host policy grid truncated by the engine's orientation limit. Point-symmetric duplicates are dropped.
|
||
- Each orientation gets a **footprint**: outline inflated (miter joins, so it contains the exact
|
||
round offset) by `spacing / 2 + NestTolerances.SafeClearanceMargin(chordTolerance) / 2`
|
||
plus four Clipper grid units per footprint. The extra grid allowance preserves this
|
||
engine's established contact points through repeated NFP Boolean operations; removing it
|
||
increased mixed-job cost from 1586.94 to 1589.81 in the migration check.
|
||
- **No-fit polygons** between footprints come from Clipper2 Minkowski sums: an O(n+m)
|
||
edge merge for convex pairs, and for concave pairs the boundary sweep ∪ (A + p₀) ∪ (−B + a₀).
|
||
The last two terms cover "B inside A" and "B swallows A". NFPs are cached per orientation pair.
|
||
|
||
**2. Sheet filling (`FrontierPacker`)**
|
||
- For every (part type, orientation) still in play, the packer keeps the exact **free region** of
|
||
legal reference points: the inner-fit rectangle minus the NFPs of everything placed. Each
|
||
placement subtracts one translated NFP from each region (in parallel, which stays deterministic).
|
||
Regions only shrink, and an empty region is retired for the rest of the sheet.
|
||
- At every step the lowest-number priority with a feasible placement wins; peer types × orientations compete (there is no fixed placement sequence):
|
||
1. **Gap fill:** if any part fits without pushing the packing front forward, place the
|
||
*largest* such part at its lowest point.
|
||
2. **Advance:** otherwise place the part with the least front advance per `area^β`, i.e. the
|
||
most material coverage for the sheet length it consumes.
|
||
- The front sweeps along X or Y, which leaves one full-width offcut strip for salvage credit.
|
||
|
||
**3. Whole job (`Opus55NestingEngine`, `NestJobCost`)**
|
||
- Sheet by sheet, every available stock size is trial-filled. The trial with the lowest
|
||
*estimated whole-job cost* (its net area, plus the remaining demand priced at the best
|
||
efficiency any trial achieved) is committed. This lets a sheet that finishes the job beat a
|
||
denser partial one.
|
||
- Net area = sheet area − `SalvageRate` × the largest qualifying full-width/full-length edge
|
||
offcut. This is the objective the benchmark scores.
|
||
- Six strategy variants (front axis X/Y × β ∈ {1, 0.5, 1.5}) each run whole-job, and the cheapest
|
||
plan wins (fewest unplaced, then cost, then sheets). A **tail re-plan** then re-decodes the
|
||
parts on the last 1–3 sheets with each stock forced first, and keeps any strictly cheaper result.
|
||
- **Deterministic:** no clock or randomness affects decisions. Effort is capped by a
|
||
count-based work budget (free-region subtractions), not wall time.
|
||
|
||
## Layout
|
||
|
||
| File | Role |
|
||
|---|---|
|
||
| `Opus55NestingEngine.cs` | `Solve()`: demand filtering, variants, stock look-ahead, tail re-plan, result assembly |
|
||
| `FrontierPacker.cs` | One-sheet fill: free regions and the gap-fill/advance choice rule |
|
||
| `NoFitCache.cs` | Spacing footprints and cached NFPs (Clipper2 Minkowski) |
|
||
| `PartCatalog.cs` | Snapshot → perimeter polygon per allowed orientation |
|
||
| `tests/` | xUnit suite. Layouts are judged by `Engine.Testing.LayoutAssert` and `NestLayoutCheck` |
|
||
|
||
## Build / test
|
||
|
||
```bash
|
||
dotnet build OpenNest.Engine.Opus55/OpenNest.Engine.Opus55.csproj -c Release
|
||
dotnet test OpenNest.Engine.Opus55/tests/OpenNest.Engine.Opus55.Tests.csproj
|
||
```
|
||
|
||
This project is intentionally **outside** `OpenNest.sln`. It's discovered at runtime as a plugin.
|
||
|
||
## Benchmark
|
||
|
||
```bash
|
||
dotnet build OpenNest.Benchmark/OpenNest.Benchmark.csproj -c Release
|
||
mkdir -p ../OpenNest/OpenNest.Benchmark/bin/Release/net8.0/Engines
|
||
cp OpenNest.Engine.Opus55/bin/Release/net8.0/OpenNest.Engine.Opus55.dll ../OpenNest/OpenNest.Benchmark/bin/Release/net8.0/Engines/
|
||
dotnet ../OpenNest/OpenNest.Benchmark/bin/Release/net8.0/OpenNest.Benchmark.dll <path-to-.nest-or-manifest-or-folder>
|
||
```
|
||
|
||
Or build and deploy in one step with `./Build-Engines.ps1 -Engines Opus55`.
|
||
|
||
The engine reports as `Opus55NestingEngine`.
|
||
|
||
## Known limitations
|
||
|
||
- **No part-in-part:** holes are treated as solid, so small parts never nest inside cutouts.
|
||
- **Clearance padding:** gaps are ~0.003 (plus up to the chord tolerance) wider than the
|
||
required spacing, to stay valid under `NestValidator`'s 0.001 arc flattening. The margin was
|
||
0.022 while it assumed a 0.01 validator tolerance. The constants are absolute and assume job
|
||
units near inch/mm scale.
|
||
- **Rotation coverage:** `Automatic` parts try at most 8 orientations (fewer when a job has many
|
||
distinct parts: `48 / partCount`, minimum 2). Free-angle rotations aren't explored beyond the MBR alignment.
|
||
- **Greedy core:** there is no order/permutation search. The variants and tail re-plan are the only
|
||
search, and density on small mixed jobs trails what an interlocking-pair filler can reach.
|
||
- **Priority is enforced during placement** (lower number first). Progress reports
|
||
`EvaluatingCandidate` per trial and `PlateCommitted` at the end, with no finer-grained progress.
|
||
- Parts whose geometry has no readable closed perimeter, or that fit no offered stock at any
|
||
allowed rotation, are reported unplaced (`NoPlacementFound`) instead of failing the job.
|
||
|
||
## Shared services migration
|
||
|
||
`JobPartGeometry.TryRead` supplies the perimeter. `ForShape(policy, perimeter, limit)`
|
||
retains the engine's orientation cap and `DistinctOutlines` drops perimeter symmetry.
|
||
Stock `WorkArea`/`Fits`, host salvage scoring and `NestJobResultBuilder` replace copied
|
||
plumbing. The frontier, NFP cache, variant work budget and tail improvement remain local.
|
||
The shared contract suite exposed and now guards lower-number priority precedence.
|
||
Every old engine-specific test remains. All five salvage benchmark costs and validity
|
||
match baseline; see [PR 5 results](../MIGRATION-PR5.md).
|