Skip to main content

Sheet metal - unfold all solids and nest the flats on sheets

POST 

/api/v1/cad/pro/unfold/solid-and-nest

Proprietary sheet-metal unfold and true-shape nesting in one call: flattens every solid in an uploaded STEP file and nests the flat patterns on sheets straight away, without writing them to a file and reading them back. Left out, the sheets are sized for the flats and the spacing and margin are scaled to them; 'fileUnit' reads a file whose header names the wrong unit. Every length is in millimetres. Requires the 'cad' API key scope. Returns 202 with a task ID; the nested sheets come in the requested formats as on POST /api/v1/cad/pro/nesting/nest, 'flat-meshes' gives each solid's flat triangulated where it was unfolded, the NestingReport (each part naming its solid) is the metadata result, and the per-solid unfold report array is delivered in the task metadata.

Request​

Responses​

Task accepted

Reference​

POST /api/v1/cad/pro/unfold/solid-and-nest

Proprietary sheet-metal unfold and true-shape nesting in one call: flattens every solid in an uploaded STEP file and nests the flat patterns on sheets straight away, without writing them to a file and reading them back. Left out, the sheets are sized for the flats and the spacing and margin are scaled to them; 'fileUnit' reads a file whose header names the wrong unit. Every length is in millimetres. Requires the 'cad' API key scope. Returns 202 with a task ID; the nested sheets come in the requested formats as on POST /api/v1/cad/pro/nesting/nest, 'flat-meshes' gives each solid's flat triangulated where it was unfolded, the NestingReport (each part naming its solid) is the metadata result, and the per-solid unfold report array is delivered in the task metadata.

Request body​

Content type: application/json (required)

FieldTypeRequiredDescription
stepFileIdstringyesID of the previously uploaded STEP file (returned by the file upload endpoint). Both plain STEP (.step/.stp) and gzip-compressed STEP (.stpz) uploads are accepted - compression is detected automatically.
fileUnitmm | cm | m | innoA unit of length: 'mm' (millimetres), 'cm' (centimetres), 'm' (metres) or 'in' (inches).
kFactornumbernoSheet-metal K-factor (neutral-axis position), typically ~0.5.Default: 0.5.
thicknessOverridenumbernoSheet thickness override in millimetres; 0 auto-detects thickness from face pairs.Default: 0.
nestingobjectnoHow the flat patterns of an unfold are nested: the stock, the copies, how each flat may turn, and the search settings. Every length is in millimetres.
nesting.sheetsarray of objectnoThe stock to nest onto: kinds of rectangular sheets, or one strip. Left out, one kind of sheet is sized for the flat patterns: at least twice as long as it is wide, holding the largest flat with its margins, large enough that all the flats fill about half of it, its sides rounded up. When every flat fits on standard 3000 x 1500 stock and that sheet would be larger, the standard stock is used instead.
nesting.quantityintegernoHow many copies of every flat pattern to place: the number of models to make. Defaults to 1. All copies together, this number times the number of flat patterns, stay within 100000.
nesting.rotationsobject | object | objectnoHow a part may turn on the sheet: a fixed list of angles, steps that divide a full turn, or any angle. Without it a part turns in steps of 90 degrees.
nesting.allowFlipbooleannoWhether every flat pattern may be turned over (a half turn about an axis in its plane, never a mirror). Defaults to false.
nesting.spacingnumbernoThe least distance kept between any two flat patterns, in millimetres, measured on their true shapes. Defaults to a gap sized to the flats: a fiftieth of the square root of their area, rounded to 1, 2 or 5 of its decade.
nesting.marginnumbernoThe band along each sheet's edges that no flat pattern enters, in millimetres. Defaults to the gap sized to the flats, the same one the spacing takes when it is left out; a spacing that is given does not change it.
nesting.timeBudgetSecondsnumbernoHow long the nesting may search; the best layout found by then is returned. Defaults to 5 seconds, at most 120.
nesting.tolerancenumbernoHow far the straight chords that stand in for curved edges may stray from them, in the parts' units (millimetres for parts read from STEP files); the spacing still holds on the true curves. Defaults to 0.1.
nesting.evaluationBudgetintegernoStop after this many placements are tried, which makes a run repeatable for one seed; the time budget still applies. 0 means no limit.
nesting.seedintegernoThe seed of the search's random choices. Defaults to 1.
nesting.sheetGapnumbernoThe gap between sheets as they are laid out in a row in the output, in the parts' units (millimetres for parts read from STEP files). Defaults to a tenth of the widest sheet.
outputsobjectnoWhich formats the nested sheets and the flat patterns are written in, and their mesh quality.
outputs.formatsarray of stringyesOutput formats to generate; each gives a separate downloadable result. The nested sheets come in the formats of NestingOutputFormat, and 'flat-meshes' gives each solid's flat pattern triangulated where it was unfolded, tagged with its solidIndex, for showing beside the model; a flat that could not be meshed has no mesh there but is nested all the same, and its unfold report entry says why in 'meshError'. Give 'step' or 'stpz', not both.
outputs.meshPrecisionnumbernoMesh tessellation precision (lower = finer). Range: [0.0001, 10]
outputs.gltfMeshPrecisionnumbernoMesh tessellation precision (lower = finer). Range: [0.0001, 10]
outputs.adjustYtoZbooleannoTurns the decomposed-mesh and flat-meshes outputs from Y-up, as the server models, to Z-up. It applies to those two only: a STEP output is always written Z-up, and a glTF output is always Y-up, as glTF asks.

Responses​

StatusDescription
202Task accepted
400Validation error
403Insufficient scope
500Server error

Example request​

curl -X POST "https://api.bitbybit.dev/api/v1/cad/pro/unfold/solid-and-nest" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ ... }'

Authentication: send your key in the x-api-key header. The full machine-readable specification is at openapi.json.