OpenNest-Engines/OpenNest.Engine.Opus55/README.md

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

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

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.