Sheet cutting

Two calls, both taking a sheet cut list, field for field as the web's sheet form saves it.

Call	Does	Counts as
POST /v1/sheet/validate	Checks the cut list without solving	Free call
POST /v1/sheet/solves	Solves it and answers with the plan	Solve

The request

{
  "unit": "mm",
  "kerf": "4",
  "mode": "guillotine",
  "stages": "3",
  "minimum_leftover": "200",
  "target": "waste",
  "strict": false,
  "band_types": [{ "name": "PVC 2 mm", "thickness": "2" }],
  "part_sizes": "finished",
  "band_waste": "10",
  "sheets": [
    { "width": "2440", "height": "1220", "qty": "", "grain": "width", "trim_left": "10", "trim_right": "10", "trim_top": "10", "trim_bottom": "10", "defects": [] }
  ],
  "parts": [
    { "width": "600", "height": "400", "quantity": "10", "label": "Door", "grain": true, "band": "PVC 2 mm", "band_long": 2, "band_short": 2 },
    { "width": "350", "height": "350", "quantity": "6", "label": "Shelf" }
  ]
}

Field	Meaning
unit	mm, cm, m or in.
kerf	The blade's kerf, lost at every cut.
mode	guillotine for a panel saw (edge-to-edge cuts in stages) or free for a CNC router (parts placed anywhere).
stages	For a panel saw, 2 or 3 stages of cuts; anything else reads as 3.
minimum_leftover	The smallest leftover worth keeping.
target	sheets (fewest sheets), waste, leftover (the most reusable leftover) or cost.
strict	true fails the request when a part cannot be placed.
band_types[]	The edge bands parts may take: each a name and a thickness.
part_sizes	finished (the default) when part sizes include the edge band, or cut when they are the sizes cut from the sheet.
band_waste	The percent of band to order on top of what the edges measure; blank for none.
sheets[]	Each sheet size: width, height, qty (blank for as many as needed), grain (width, the default, height or none), optional price, material_key, the four trim_* edges, and defects[] to cut around.
parts[]	Each part: width, height, quantity, label, grain (true: its grain matters and runs along its width), grain_along (width or height: which way it runs), optional priority and material_key, and band, band_long and band_short for edge banding.

Options that belong to the Bench plan: target: "cost", material_key and priority. On Free they are refused with 403 naming the plan.

The plan

The answer is a SheetReport: sheets[], each with its grain, its parts placed (x, y, width, height as cut, whether it was turned, finished_width and finished_height, grain, band, band_long and band_short), the saw cuts by stage for a panel saw, and its leftovers; metrics for the job; unplaced[]; unpriced_sheet_rows[]; cost; banding[], the band each band type takes; and an explanation. The exact shapes are in the API reference under SheetRequest and SheetReport.

Grain

A sheet's grain runs along its width or its height, or it has none, as MDF or melamine. A sheet sent without grain has it along its width.

A part whose grain matters lines up with the grain of the sheet it comes from. On a sheet grained along its width, a part grained along its width stays as typed, and a part grained along its height is turned a quarter. On a sheet grained along its height it is the other way round. On a sheet with no grain, any part may turn. Parts without grain turn whenever that fits more.

grain: true alone means the grain runs along the part's width, so on a sheet with its grain along its width the part never turns.

Edge banding

Name each band once in band_types, with its thickness. A part takes one of them in band, on band_long and band_short of its edges, each 0, 1 or 2. Its long edges run along its longer side.

With part_sizes: "finished", the sizes typed are the finished part, band included. The band's thickness comes off for each banded edge to give the size cut: a 600 × 400 door banded all round with 2 mm band is cut 596 × 396. With part_sizes: "cut", the sizes are cut as typed and the band is added on after.

banding[] in the plan gives each band type's edges, their length along the finished edges, and length_with_waste, the length to order with band_waste on top. The CSV and Excel files on the web list the same, with each part's finished size and banded edges.

Labels

A solved plan on the web prints labels for every part and every reusable leftover, on every plan. A part label carries its name, finished size (and cut size when banding changes it), material, its sheet and where on it, its banded edges, a grain arrow when its grain matters, and a QR code. A leftover label carries its size, material, its sheet and a QR code. The QR code holds short plain text that says what the piece is, so it reads without NestSolver. Exports lists the label sizes.

PTX for the panel saw

On the Bench plan and up, a panel saw plan on the web downloads as a PTX file (.ptx), the pattern exchange file that panel saw software reads. It is written to the Pattern Exchange File specification V1.12 in Magi-Cut's Interface Guide: comma-separated ASCII records, each line ending in CR LF.

• Sizes are in millimetres, or decimal inches when the plan is in inches.
• Each run of identical sheets is one pattern, with the number of sheets to cut. Its cuts list each rip, then the cross cuts of that strip, then any recut, in the order the saw makes them. Each cut gives the size of the piece it cuts off; the saw adds its kerf.
• A board is read a quarter turn round from the drawing on screen: its length is the sheet's height, and rips run up the sheet from its left edge. Check that this matches how sheets go onto your saw.
• Trims come off as trim cuts. Saws count a trim with the kerf in it, so set each trim at least as wide as the blade.
• Each board carries its grain and each part its grain, finished size and edge bands. Reusable leftovers are offcuts, so the saw can label them.
• Thickness and book height are left blank for the saw's own settings.

Router plans have no PTX file. Cut one test board from the file and measure it before you run the job.

Panel saw or router

Pick guillotine when the parts come off a panel saw or a table saw: every cut runs edge to edge, so the plan lists the cuts in the order to make them, by stage. Pick free for a router or a laser, where parts can sit anywhere on the sheet and nest more tightly. Irregular parts are a different job: true-shape nesting.