True-shape nesting

Arbitrary polygons packed onto fixed sheets.

True-shape nesting

POST /v1/optimize/nest

{
  "parts": [
    {
      "name": "bracket",
      "polygon": [[0, 0], [300, 0], [300, 100], [100, 100], [100, 300], [0, 300]],
      "qty": 4,
      "allowedRotations": [0, 90, 180, 270]
    },
    {
      "name": "gusset",
      "polygon": [[0, 0], [280, 0], [0, 280]],
      "qty": 4,
      "allowedRotations": [0, 90, 180, 270]
    }
  ],
  "stock": [
    {
      "w": 2440,
      "h": 1220,
      "price": 12.5,
      "exclusions": [{ "polygon": [[0, 0], [300, 0], [0, 300]], "quality": 0 }]
    }
  ]
}

The three modes above pack rectangles. POST /v1/optimize/nest packs ARBITRARY POLYGONS: a part is an outline (polygon, with optional interior holes), not a width×height, so parts interlock into each other’s concave pockets and the notch-air a bounding box wastes is reclaimed — on a representative job, 6 sheets where the same parts by bounding box need 9.

It is a different class of algorithm (a geometric collision engine, not the guillotine packer), for laser, plasma and waterjet cutting. Two things the rectangular API cannot express come with it: per-sheet exclusion zones (stock[].exclusions — a defect, a clamp footprint, a pre-printed area; a quality-0 zone is a no-go region for any part) and true-shape holes. material partition and the meta passthrough work as everywhere else.

Spacing is set twice: options.minSeparation between parts, and options.edgeClearance at the sheet edge (it defaults to minSeparation). With several stock sizes for one material, both engines compare them and keep the best plan — by sheet area, or by price with minimizeCost — and may mix sizes (a half-empty last sheet moves to a smaller size), so the result does not depend on the order you list them in.

The default engine, lbf, answers instantly; engine "max" runs the same job asynchronously and searches for a layout with fewer sheets (see Async jobs). The example below is one real captured call — eight parts on a single sheet with a damaged corner excluded.

Every format, engine, limit and code sample for developers: CutOptim nesting API

Nest — response

{
  "engine": "lbf",
  "engineVersion": "1.0.0+nest-d4046d5-3780cda5",
  "contractVersion": "1",
  "deterministic": true,
  "sheets": [
    {
      "w": 2440,
      "h": 1220,
      "stock": 0,
      "price": 12.5,
      "density": 0.1217,
      "cutLength": 8623.919,
      "pierces": 8,
      "usedWidth": 580.204,
      "usedHeight": 1102.332,
      "usedArea": 639577.44,
      "parts": [
        { "name": "bracket", "sheet": 0, "x": 300.003, "y": 400.226, "rotation": -180 },
        { "name": "bracket", "sheet": 0, "x": 300.133, "y": 700.617, "rotation": -180 },
        { "name": "bracket", "sheet": 0, "x": 300.061, "y": 1000.969, "rotation": -180 },
        { "name": "bracket", "sheet": 0, "x": 400.095, "y": 1102.332, "rotation": -180 },
        { "name": "gusset", "sheet": 0, "x": 530.102, "y": 50.205, "rotation": 90 },
        { "name": "gusset", "sheet": 0, "x": 300.058, "y": 380.171, "rotation": -90 },
        { "name": "gusset", "sheet": 0, "x": 580.15, "y": 380.193, "rotation": 90 },
        { "name": "gusset", "sheet": 0, "x": 300.204, "y": 660.982, "rotation": -90 }
      ],
      "exclusions": [{ "polygon": [[0, 0], [300, 0], [0, 300]], "quality": 0 }]
    }
  ],
  "metrics": {
    "sheetCount": 1,
    "density": 0.1217,
    "placed": 8,
    "total": 8,
    "totalPrice": 12.5,
    "cutLength": 8623.919,
    "pierces": 8
  },
  "stockUsage": [
    {
      "stock": 0,
      "w": 2440,
      "h": 1220,
      "sheetCount": 1,
      "totalPrice": 12.5,
      "density": 0.1217,
      "usedArea": 639577.44
    }
  ],
  "unplaced": [],
  "warnings": [],
  "timing": { "solveMs": 26.34 }
}

Each entry in sheets is one used sheet; a placed part carries the rigid transform (rotation in degrees, then x/y translation), NOT a re-emitted polygon — rotate your input outline by rotation about its origin and add (x, y) to reconstruct the placement exactly. rotation may be negative; the reconstruction is exact regardless of sign.

⚠️ density is the placed POLYGON area over used sheet area — the honest fill, with concave pockets counted as empty — and is NOT comparable to a rectangular packer’s yieldPct (which counts each bounding box as solid, so it reads higher for a worse result); the cross-comparable metric across the two is sheetCount on the same parts.

The layout is deterministic: set options.seed to reproduce it. exclusions is echoed on each sheet for rendering. Every sheet carries stock — the index of the stock row it was cut from — and stockUsage totals the sheets, price and density per stock row, so a quote can be priced per sheet size. Every sheet also carries cutLength and pierces (metrics totals them): the summed perimeter of its placed parts’ outlines and holes, and one pierce per closed contour — geometric, with no common-line cutting or lead-ins.

Every sheet also carries usedWidth and usedHeight — the farthest point its placed parts reach from the sheet origin, the used bounding box for partial-sheet charging — and usedArea (stockUsage totals it per row).

Both engines compact the least-filled sheet toward that corner by default, with rotation subsets of what each part allows (options.compact: false turns it off; options.compactFor picks the measure to minimise — "box" (default) the used area, "horizontal" the used height for a full-width strip charge, "vertical" the used width for a full-height strip; sheet count and price never change).

Ask for include:["svg","dxf"] and the response also carries a self-contained SVG drawing and an R12 DXF of the achieved nest, inline.