diff --git a/README.md b/README.md index 8c39da6..9ad776a 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ A Windows desktop application for CNC nesting — imports DXF drawings, arranges ## Features - **Import / export** — DXF & DWG parts (ACadSharp), Excel BOMs, bend-line detection, built-in parametric shapes; export DXF or post-processed G-code. -- **Nesting** — pluggable whole-job engines (Default, Strip, Vertical/Horizontal Remnant, StockLadder, plus DLL plugins), NFP-based interlocking pair evaluation, gravity compaction, rotation sweeps, multi-plate/multi-material jobs. +- **Nesting** — automatic multi-plate/multi-material jobs, interlocking pair evaluation, and built-in or plug-in engines. [Choose an engine](docs/nesting-engines.md). - **Plate operations** — manual sheet cut-offs, [plate- or nest-wide automatic scrap cutoffs with a minimum tail-to-keep setting](docs/automatic-scrap-cutoffs.md), oversized-part splitting (straight, weld-gap tabs, spike-groove), interactive editing, and spacing-aware pushes that can slide along or away from touching parts. - **Visual overlap check** — highlight shared material on the active plate, rechecked automatically after edits, including containment and cutouts, with area shading, pair centroids, and hover details through View > Overlap Check. [Usage and limitations](docs/geometry/visual-overlap-check.md). - **CNC output** — configurable lead-ins/outs and tabs, contour editing, user-defined G-code variables (`$name` → `#200+` machine variables), plugin post-processors (Cincinnati CL-707/800/900/940/CLX included). [Pre-post verification](docs/post-verification.md) checks overlaps, missing lead-ins, and rapid crossings, with explicit risk acknowledgment required to bypass warnings. @@ -34,9 +34,7 @@ dotnet test OpenNest.FrontEnd.Tests/OpenNest.FrontEnd.Tests.csproj # console/MCP dotnet run --project OpenNest/OpenNest.csproj # desktop app (Windows) ``` -`OpenNest.WinForms.Tests` (desktop-assembly tests) runs on Windows only; CI runs it and `OpenNest.FrontEnd.Tests` on a GitHub-hosted Windows runner for every master push and pull request. Format changed files with `dotnet format OpenNest.sln --include `. - -Shared coding-agent guidance lives in [AGENTS.md](AGENTS.md). [CLAUDE.md](CLAUDE.md) imports it for Claude Code compatibility; make shared instruction changes in AGENTS.md, not in duplicate agent-specific copies. +`OpenNest.WinForms.Tests` (desktop-assembly tests) runs on Windows only; CI runs it and `OpenNest.FrontEnd.Tests` on a GitHub-hosted Windows runner for every master push and pull request. ### Quick start @@ -56,18 +54,21 @@ dotnet run --project OpenNest.Console -- part1.dxf part2.dxf --size 60x120 --aut dotnet run --project OpenNest.Console -- project.zip # re-fill a nest file ``` -Key options: `--size WxL`, `--autonest` (validated single-sheet whole-job nesting), `--allow-invalid` (explicit warning override), `--engine ` (jobs engine or fill strategy), `--quantity`, `--spacing`, `--template `, `--output `, `--check-overlaps`, `--post `, `--no-save`. Run without arguments for the full list. +| Option | What it does | +|--------|--------------| +| `--size WxL` | Set the plate size; required for DXF-only input. | +| `--autonest` | Run validated whole-job nesting on one sheet. | +| `--engine ` | Choose a whole-job engine with `--autonest`, or a fill strategy without it. | +| `--quantity ` | Limit parts placed (0 means unlimited). | +| `--spacing ` | Override part spacing. | +| `--template ` | Read plate defaults from a nest file. | +| `--output ` | Set the output nest path. | +| `--check-overlaps` | Check the result for overlaps. | +| `--post ` | Run a post-processor after nesting. | +| `--no-save` | Skip saving the nest. | +| `--allow-invalid` | Explicitly keep a representable invalid `--autonest` result; otherwise it is rejected. | -## Benchmarking Engines - -`OpenNest.Benchmark` runs every registered `INestingEngine` against `.nest` files (or a JSON manifest of DXFs + quantities) and scores by salvage-credited sheet area, with a penalty per unplaced part. - -```bash -dotnet run --project OpenNest.Benchmark -- ./benchmark-jobs \ - --sheet-sizes 48x96,60x120,72x120 --engines Irregular,Rectangles --csv results.csv -``` - -Layouts are validated (bounds, spacing, quantity, rotation, stock match); invalid runs place nothing and pay the penalty. `--parallel` (default 3) speeds up scoring but inflates `Time(ms)` — use `--parallel 1` when comparing speed. Pass `--sheet-sizes` for an unbiased run; otherwise only each file's original sizes are offered. `--progress` logs each solve's start, the engine's `NestJobProgress` (plate evaluations throttled to one line per 2 s, every plate commit) and its finish. Custom engines drop in as DLLs implementing `INestingEngine` (public parameterless constructor) in an `Engines/` folder next to the benchmark. Built-in engines and how to change them: [nesting engines](docs/nesting-engines.md). +Run `dotnet run --project OpenNest.Console -- --help` for the complete options and their defaults. ## Project Structure @@ -87,19 +88,7 @@ Layouts are validated (bounds, spacing, quantity, rotation, stock match); invali ## Nesting Engines -Engines implement `INestingEngine.Solve(NestJob)`. Desktop Auto Nest, console autonest, MCP autonest and the API use one independent validation pipeline for every engine, including plug-ins. Invalid layouts require an explicit decision; malformed output cannot be kept. See [automatic nesting and validation](docs/automatic-nesting.md) for caller behavior and API validation status. - -| Engine | Description | -|--------|-------------| -| **Default** | Any job: runs Irregular and Rectangles and keeps the cheapest valid layout | -| **Rectangles** | Plain and near-rectangular plates: maximal-rectangles box packing | -| **Irregular** | Irregular profiles: no-fit-polygon frontier packing | -| **Fill** | Multi-phase: linear fill → pairs → rect best-fit → extents (named Default in earlier releases) | -| **Strip** | Iterative shrink-fill for mixed-drawing layouts | -| **Vertical / Horizontal Remnant** | Optimizes a clean remnant drop on one edge | -| **StockLadder** | Whole-job, stock-constrained baseline with salvage-credit ranking | - -Which engine suits which jobs, renamed engine names, and the rules for changing an engine: [nesting engines](docs/nesting-engines.md). +Default compares the built-in Irregular and Rectangles engines and keeps the best valid whole-job layout. Other engines and plug-ins suit particular jobs; see [which engine to use](docs/nesting-engines.md). Desktop Auto Nest, console autonest, MCP autonest, and the API share an independent validation pipeline, including for plug-ins. [Automatic nesting and validation](docs/automatic-nesting.md) explains how callers handle invalid results. ## File Format diff --git a/docs/nesting-engines.md b/docs/nesting-engines.md index 701d264..4d96c79 100644 --- a/docs/nesting-engines.md +++ b/docs/nesting-engines.md @@ -138,6 +138,8 @@ falls back to the default engine with the usual status-bar warning. ## Changing an engine +Use the [engine benchmarking guide](performance/engine-benchmarking.md) for the command, candidate-sheet controls, and comparison procedure. + - A change lands only when it beats the engine's current result on `OpenNest.Benchmark` for the jobs that engine targets, with every layout valid. Report cost, validity, unplaced parts and time. - Placement must be deterministic: no clocks, unseeded randomness or environment variables. Budget diff --git a/docs/performance/engine-benchmarking.md b/docs/performance/engine-benchmarking.md new file mode 100644 index 0000000..a0bcee7 --- /dev/null +++ b/docs/performance/engine-benchmarking.md @@ -0,0 +1,12 @@ +# Benchmarking whole-job engines + +`OpenNest.Benchmark` runs each registered `INestingEngine` against `.nest` files or JSON manifests of DXFs and quantities. It ranks complete jobs first, then salvage-credited sheet cost with a penalty for each unplaced part. Invalid runs (bounds, spacing, quantity, rotation, or stock mismatch) place nothing and pay the penalty. + +```bash +dotnet run --project OpenNest.Benchmark -- ./benchmark-jobs \ + --sheet-sizes 48x96,60x120,72x120 --engines Irregular,Rectangles --csv results.csv +``` + +Supply `--sheet-sizes` for an independent candidate pool; otherwise a saved nest offers only its original sheet sizes, which can bias comparisons. The default `--parallel 3` runs solves concurrently and confounds per-engine timing; use `--parallel 1` for timing comparisons. `--progress` logs each solve's start, engine progress, and finish. Retain input hashes, exact commands, validity, fulfillment, costs, and raw results outside source control when comparing revisions; see [fill performance verification](fill-verification.md). + +Custom engines are DLLs implementing `INestingEngine` with a public parameterless constructor, loaded from `Engines/` beside the benchmark executable. See [nesting engines](../nesting-engines.md) for built-ins and engine-change rules. Run `dotnet run --project OpenNest.Benchmark -- --help` for all options.