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
- 202
- 400
- 403
- 500
Task accepted
Validation error
Insufficient scope
Server error
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)
| Field | Type | Required | Description |
|---|---|---|---|
stepFileId | string | yes | ID 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. |
fileUnit | mm | cm | m | in | no | A unit of length: 'mm' (millimetres), 'cm' (centimetres), 'm' (metres) or 'in' (inches). |
kFactor | number | no | Sheet-metal K-factor (neutral-axis position), typically ~0.5.Default: 0.5. |
thicknessOverride | number | no | Sheet thickness override in millimetres; 0 auto-detects thickness from face pairs.Default: 0. |
nesting | object | no | How 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.sheets | array of object | no | The 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.quantity | integer | no | How 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.rotations | object | object | object | no | How 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.allowFlip | boolean | no | Whether every flat pattern may be turned over (a half turn about an axis in its plane, never a mirror). Defaults to false. |
nesting.spacing | number | no | The 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.margin | number | no | The 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.timeBudgetSeconds | number | no | How long the nesting may search; the best layout found by then is returned. Defaults to 5 seconds, at most 120. |
nesting.tolerance | number | no | How 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.evaluationBudget | integer | no | Stop after this many placements are tried, which makes a run repeatable for one seed; the time budget still applies. 0 means no limit. |
nesting.seed | integer | no | The seed of the search's random choices. Defaults to 1. |
nesting.sheetGap | number | no | The 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. |
outputs | object | no | Which formats the nested sheets and the flat patterns are written in, and their mesh quality. |
outputs.formats | array of string | yes | Output 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.meshPrecision | number | no | Mesh tessellation precision (lower = finer). Range: [0.0001, 10] |
outputs.gltfMeshPrecision | number | no | Mesh tessellation precision (lower = finer). Range: [0.0001, 10] |
outputs.adjustYtoZ | boolean | no | Turns 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
| Status | Description |
|---|---|
202 | Task accepted |
400 | Validation error |
403 | Insufficient scope |
500 | Server 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.