feat(common-line): place parts on common lines automatically at a chosen level

Slice 3 of common-line cutting. On costly plate (N26-295: 3/16 RA310S at about
$2,500 a sheet) pairing parts one kerf apart fits the part the spacing cannot:
the last plate's 38 parts fit on one 48x120 with Auto Nest only with pairs.

- Drawing Properties gains "Allow common line" (Drawing.AllowCommonLine, off by
  default because customer edge-quality needs vary). The nest's CommonLineUsage
  (Off / When it adds parts / Whenever available) is set in Auto Nest and seeded
  from Tools > Nest Defaults; both persist (nest.json, defaults.json).
- NestPipeline runs the ordinary solve, then, with a level on, trials where
  eligible parts are offered as kerf-gap pair compounds. Placed pairs expand into
  parts plus explicit NestJobCommonLine groups, are validated again, and
  CommonLineRanking keeps a trial only by the level: count first, then sheets;
  "when it adds parts" keeps the plain layout on a tie, "whenever" also takes a
  shorter cut or less material, never at the cost of a part. Engines, FillScore
  and their comparers are unchanged; Off asks the engine exactly what it did.
- NestLayoutCheck exempts members only through a sheet's explicit group list and
  only when the job allows common lines; materializing and committing create
  Plate.CommonLines.
- Server nesting writes common-line jobs as version 3 and replays the recorded
  trial answers, so the desktop binds the same groups.
- Fill Area honors the level through a PlateFillService overload.
- The benchmark gains --common-lines <level> --kerf <k>.

Benchmark (synthetic nests + N26-295, --parallel 1): with no flag and with
--common-lines off every engine matches the base commit; with a level on no
layout becomes invalid and three runs save a sheet at equal nested area.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
ajandClaude Opus 5.5 committed 2026-11-05 19:38:00 -05:00
1 parent f9b2713420
commit b026bd19d2
61 files changed
+2155 -118

No files matched your search

+1
View File
@@ -6,6 +6,7 @@
2. Resolve the selected name through `NestingEngineRegistry` (built-ins and plug-ins use the same path).
3. Bundle parts that fit other parts' enclosed cutouts into their frames ([filling cutouts](nesting-engines.md#filling-cutouts)); a refused or less complete bundled trial is replaced by the ordinary solve.
4. Run the engine without mutating caller drawings or plates.
When the job's common-line level is on, solve once more with eligible parts offered as kerf-gap pairs and keep that layout only by the level's ranking ([automatic common-line placement](common-line-cutting.md#automatic-placement)).
5. Check returned placements with the independent `NestLayoutCheck` used by the benchmark (for bundles, again after expanding them to physical frames and inserts).
6. Consolidate exact ordered nonempty layouts only when the entire result is valid, then bind each layout to the caller's drawing references; the caller decides whether to commit it.
+52 -6
View File
@@ -97,13 +97,62 @@ head on the second. Changing the setting after planning makes the plan stale.
- Moving one member moves only that part and breaks the group. Rejoin, or remove the group.
- Join, Remove and Cut Common Lines Twice are undoable like any other edit.
## Automatic placement
Auto Nest, the server's nesting worker and Fill Area can place parts on common lines themselves.
- **Who may pair.** Only drawings with **Allow common line** set in Drawing Properties
(`Drawing.AllowCommonLine`, off by default: a shared edge is cut from the centerline, which some
customers' edge-quality requirements do not accept). A drawing pairs only with copies of itself.
- **The level** is the nest's `Nest.CommonLineUsage`, chosen in the Auto Nest dialog (saved with
the nest) and seeded for new nests from the nest defaults (`defaults.json`, Tools > Nest
Defaults):
- **Off** (the default): engines and fills run exactly as without common lines; the pipeline
asks the engine nothing more.
- **When it adds parts:** a common-line layout is kept only when it places more parts than the
best layout without common lines, or (whole jobs) the same parts on fewer sheets. A tie keeps
the layout without common lines.
- **Whenever available:** part count still ranks first and sheets second, so common lines never
cost a part or a sheet. With both equal, the common-line layout is kept when it is better on
one of material (a lower salvage-credited cost, then a larger compactness offcut: a shorter
used length or a larger remnant) and cut length (perimeters less each shared span once), and
no worse on the other.
- **The kerf** is the plate's cutting kerf for the nest's material and thickness (the machine's,
see [machine cutting defaults](machine-cutting-defaults.md)). With no kerf, or a kerf not
smaller than the part spacing, nothing pairs.
- **How.** `CommonLinePair` builds a compound of two copies sharing the part's longest straight
edge (the second turned half a turn, so that edge faces its own copy one kerf apart; shorter
edges are tried when the turned copy would come closer than the kerf elsewhere). The compound's
outline is both perimeters (arcs circumscribed) and the kerf between them, without holes. The
pair needs a part that may turn half a turn: automatic rotation, or a rotation limit that allows
the 180° equivalent.
- **Whole jobs** (`NestPipeline`, every engine, built-in or plug-in): after the ordinary solve,
`CommonLinePipelinePrepass` offers each eligible part as pairs plus its odd copy (all copies
paired, then about half, so rows that fit an odd count are tried too) and solves again. Placed
pairs expand into their two parts and one `NestJobCommonLine` group each on the result sheet
(`NestJobPlateResult.CommonLines`: placement positions and kerf). The expanded layout is checked
by `NestLayoutCheck` again, and `CommonLineRanking` chooses at the job's level
(`NestJobOptions.CommonLineUsage`, `CommonLineKerf`, `NestJobPart.AllowCommonLine`). Committing
adds the groups to `Plate.CommonLines`. Engines themselves are unchanged, and `FillScore` and
every engine comparer still rank their own layouts.
- **Fill Area** (`PlateFillService.FillItem` with a level and kerf) also fills the area with
pairs and keeps that fill when it places more parts, or, at "Whenever available", as many and
the strategy's own ranking does not prefer the plain fill. Other interactive fills, the console
and MCP fills do not pair.
- **Benchmark:** `--common-lines off|when-it-adds-parts|whenever --kerf <k>` runs each job through
the pipeline with every part allowed to pair; `off` is the baseline to compare the levels with
(see [engine benchmarking](performance/engine-benchmarking.md)).
## Checks
- **Part spacing** (the pre-post review and the desktop's live label): any two members of one
group are held to the group's kerf instead of the plate's part spacing. Everything else,
including spacing to non-members and the plate edge, is unchanged. The engines' layout
certification (`NestLayoutCheck`) knows nothing of groups. Engines never make them, and a plate
with groups is not an engine result.
including spacing to non-members and the plate edge, is unchanged.
- **Engine results** (`NestLayoutCheck`, the benchmark's and the pipeline's validation): the
exemption comes only from a result sheet's explicit group list, never from proximity. A group
must be allowed by the job (a level on, the job's kerf, members whose parts allow common lines,
each placement in one group at most), smaller than the part spacing, and intact
(`CommonLineGeometry.Check`).
- **Common lines** (pre-post, a warning that needs consent like any other):
- a member that no longer shares a span one kerf from another member, or a group split in two;
- a group whose kerf differs from the plate's cutting parameters' kerf (when the plate has
@@ -133,6 +182,3 @@ back to cutting the line twice. Set the plate to cut its lines twice and plan ag
See [nest file format](nest-file-format.md#common-lines).
## Planned next
Automatic common-line placement in fills, after the machine trial above.
+11 -1
View File
@@ -119,6 +119,15 @@ nonfinite or nonpositive kerf. Spans are not saved; they are derived from the pl
Versions before it ignore the array, so they load the parts one kerf apart and report the
pairs as part-spacing findings: never a silently different cut.
The nest's optional `commonLineUsage` (`Nest.CommonLineUsage`) is `"whenItAddsParts"` or
`"whenever"`: when Auto Nest and Fill Area may place parts on common lines themselves (see
[automatic placement](common-line-cutting.md#automatic-placement)). It is omitted when off, the
default; an unknown value reads as off. A drawing's optional `allowCommonLine: true`
(`Drawing.AllowCommonLine`) lets its parts take part; it is omitted when false. Older readers
ignore both, so they nest without common lines. Drawing packages leave `allowCommonLine` out of
their canonical content, like the other nesting settings, so it never changes a package hash
(and a library drawing added to a nest starts with it off).
A plate's optional `cutCommonLinesTwice` (`Plate.CutCommonLinesTwice`) is `true` when its
common lines are cut twice; it is omitted when false, the default, in which Plan Cutting cuts
each shared span once. A program planned that way saves its shared cuts as motions tagged
@@ -342,7 +351,8 @@ the server's library record owns are written as their defaults, so editing them
changes the hash:
- nest and drawing `name` (blank), drawing `customer`, material `name` and `grade` (blank);
- `color`, `customColor`, `priority`, `nestPriority`, `cutFirst` and `constraints` (omitted);
- `color`, `customColor`, `priority`, `nestPriority`, `cutFirst`, `allowCommonLine` and
`constraints` (omitted);
- `quantity.required` (zero) and `library` (omitted).
Adding a library drawing to a nest ignores whatever a package holds for these fields
+12
View File
@@ -540,6 +540,18 @@ mixed sheet sizes. Every whole-job engine chooses among the offered stock sizes.
Gpt6Astra and Qwen38FlashNext are no longer shipped and have no alias. A saved selection of either
falls back to the default engine with the usual status-bar warning.
## Common lines
Engines do not know about common lines. When the job's `NestJobOptions.CommonLineUsage` is on,
`NestPipeline` solves once more with each part that allows it offered as kerf-gap pairs (a
compound part), expands the placed pairs into parts plus explicit `NestJobCommonLine` groups and
keeps the trial only by the level's ranking; see
[automatic placement](common-line-cutting.md#automatic-placement). Off asks the engine exactly what
it asked before. An engine or plug-in may return groups itself on `NestJobPlateResult.CommonLines`;
`NestLayoutCheck` holds members to the kerf only through that list and only when the job allows
common lines. Benchmark a level with `--common-lines <level> --kerf <k>` against
`--common-lines off`, reporting placed parts and absolute nested area.
## Changing an engine
Use the [engine benchmarking guide](performance/engine-benchmarking.md) for the command, candidate-sheet controls, and comparison procedure.
+2
View File
@@ -9,4 +9,6 @@ dotnet run --project OpenNest.Benchmark -- ./benchmark-jobs \
Supply `--sheet-sizes` for an independent candidate pool; otherwise a saved nest offers only its original sheet sizes, which can bias comparisons. A saved nest's first plate also supplies spacing, quadrant and clamps: its machine clamp rail is resolved for every candidate size, as desktop Auto Nest does, and its baseline layout is checked against the clamps it was made with. Manifests have no clamps. A manifest part rotates freely (automatic rotation: any angle) unless `"allowRotation": false` locks it at 0°, or `"rotations"` lists its only angles in degrees: `[0]`, `[0, 180]` or `[0, 90, 180, 270]`. A manifest's `"offcutCut": "horizontal"` (or `"vertical"`) sets `NestJobOptions.OffcutCut`, so only full-width (or full-length) edge strips count as offcut; use it to match a benchmark that scores used sheet height (or length). A saved nest records its salvage rate, but salvage credit applies only with a positive `--min-salvage-dimension`. Without it, every complete one-sheet layout costs the same, as in desktop Auto Nest on a single plate size. 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. `--time-limit <seconds>` stops each solve at that wall-clock limit and scores the best valid plan the engine had reported (see [time limits](../nesting-engines.md#time-limits)); a solve with none counts as timed out. Without a limit the harness abandons a solve after five minutes; with one it waits for the limit plus a minute, so the engine's limit always fires first. Retain input hashes, exact commands, validity, fulfillment, costs, and raw results outside source control when comparing revisions; see [fill performance verification](fill-verification.md).
`--common-lines off|when-it-adds-parts|whenever --kerf <k>` solves each job through `NestPipeline` (as desktop Auto Nest does) with every part allowed to share a [common line](../common-line-cutting.md#automatic-placement) at that level; compare a level with `--common-lines off`, not with a run without the option, which calls the engine directly. Report placed parts and absolute nested area, not only utilization.
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.
+9 -4
View File
@@ -104,7 +104,9 @@ package and result on the server.
geometry fingerprint (a SHA-256 of the exact motions the freshness check compares, which a
later Open checks the nest's drawings against; workers ignore it), every stock
entry as `NestStockJson` (size, quantity, spacing, quadrant, cost, clamp zones in plate
coordinates, clamp rail, irregular outline), and the job options. A server job never sets
coordinates, clamp rail, irregular outline), and the job options, including the common-line
level and kerf. A job that uses common lines is written as version 3, so a worker without them
refuses it instead of solving it differently from the desktop's replay. A server job never sets
`SearchUntilCancelled` and never runs under a `DeadlineNestingEngine`: it has no time
limit, so a throttled worker finds the same nest a fast one does, later.
- `drawings.nest`: a throwaway nest of exactly the items' drawings, written by `NestWriter`.
@@ -115,7 +117,10 @@ package and result on the server.
**The result** is a `NestSolveTranscript`: every engine solve the pipeline made on the worker,
in order, as what was asked (part and stock ids with quantities) and the raw `NestJobResult`
returned. Poses keep their IEEE values, nonfinite ones included. No bound plates or
validation travel back.
validation travel back. A [common-line](common-line-cutting.md#automatic-placement) trial is one
more recorded solve whose answer places pair proxies; the desktop's replay expands them into the
same parts and groups the worker made, so the groups travel as those recorded answers (a sheet's
own `commonLines`, written only when an engine returns groups itself, travel too).
**Live progress** travels separately while the job runs, both as versioned JSON the server
never opens: `RemoteNestProgress` (the stage of the solve in progress: `NestJobStage`, stock,
@@ -124,14 +129,14 @@ raw placements of `NestJobStage.PlanImproved`). The desktop rebuilds the request
its own drawings (the same part ids the worker solved) and draws the plan on detached
drawings, exactly as a local run's `PlanSheets`; a bundled cutout trial's frame proxies are
bundled once on the desktop the first time a plan names one. Like a local plan it is
unvalidated and never kept.
unvalidated and never kept. A common-line trial's pair proxies are rebuilt the same way.
## Replay on the desktop
`RemoteNestSubmission.Complete` first checks that each item's drawing still has the geometry
it had when the job was sent; a changed drawing refuses the result. It then runs
`NestPipeline.Run` with a `ReplayNestingEngine` that answers each solve with the next recorded
result, after checking it is asked the same question. Cutout bundling, the ordinary-solve
result, after checking it is asked the same question. Cutout bundling, common-line trials, the ordinary-solve
comparison and clamp-removal recovery therefore happen here exactly as on the worker, and the
result is validated by `NestLayoutCheck` and bound to the caller's own drawings like a local
run. A recorded sheet that matches one of the request's stock entries uses that entry itself.
+1 -1
View File
@@ -9,7 +9,7 @@ building nests and posts the same way:
| `machine` | machine id | A Tools > Machine Configuration entry: materials, grades, thicknesses, leads, kerf, lead-in rounding, tabs, pierce, cut-offs, motion limits, plate sizes, support grid, clamps | `%APPDATA%\OpenNest\Machines\<id>.json` |
| `post` | post type name, e.g. `OpenNest.Posts.CincinnatiCIFiber.CIFiberPostProcessor` | A post's settings, as its JSON file holds them | `%APPDATA%\OpenNest\Posts\<post>.json`, else the shipped `<post>.json` beside the post DLL in `Posts\` until the first save (an update replaces the install folder, so edits are never saved there) |
| `clamps` | `default` | Legacy clamp settings, read only to copy them onto a machine once (machines now hold their clamps) | `%APPDATA%\OpenNest\clamps.json` |
| `nest-defaults` | `default` | Tools > Nest Defaults: units, sheet size, quadrant, spacing, default machine | `%APPDATA%\OpenNest\defaults.json` |
| `nest-defaults` | `default` | Tools > Nest Defaults: units, sheet size, quadrant, spacing, default machine, common-line usage | `%APPDATA%\OpenNest\defaults.json` |
File mode, the console, MCP and API front ends use only this PC's copies.