Nesting - place flat parts on sheets or a strip
POST/api/v1/cad/pro/nesting/nest
Proprietary true-shape 2D nesting: places the flat parts of uploaded STEP files onto rectangular sheets or one strip, turning and flipping them as each part's options allow, with a spacing that holds on the true curved edges and parts placed inside other parts' holes. Every part a file places is a part, with each of its solids on its own, so an unfold's output gives one part per flat pattern; 'stepFileIds' gives the full rule. Requires the 'cad' API key scope. Returns 202 with a task ID; every used sheet is one compound of its placed parts, laid in a row on the XZ plane, combined into one output per format, and the NestingReport (placements with their transforms, each part as read, what was left and why, totals) is delivered as the metadata result.
Request
Responses
- 202
- 400
- 403
- 500
Task accepted
Validation error
Insufficient scope
Server error
Reference
POST /api/v1/cad/pro/nesting/nest
Proprietary true-shape 2D nesting: places the flat parts of uploaded STEP files onto rectangular sheets or one strip, turning and flipping them as each part's options allow, with a spacing that holds on the true curved edges and parts placed inside other parts' holes. Every part a file places is a part, with each of its solids on its own, so an unfold's output gives one part per flat pattern; 'stepFileIds' gives the full rule. Requires the 'cad' API key scope. Returns 202 with a task ID; every used sheet is one compound of its placed parts, laid in a row on the XZ plane, combined into one output per format, and the NestingReport (placements with their transforms, each part as read, what was left and why, totals) is delivered as the metadata result.
Request body
Content type: application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
stepFileIds | array of string | yes | IDs of previously uploaded STEP files (.step, .stp or gzip-compressed .stpz), at most 50 and 200 MB together. Parts are read file after file, as each file's product structure gives them: every placement of a part (a product) is a part, and a file with no assembly is its one part. Within a part, every solid is a part of its own, in the order they sit, and whatever else it holds stays one part after them (an unfolded flat pattern with its bend lines, a drawing's outline with its holes); a part with no edge is skipped, and a request whose files give no part at all is refused. Parts are read into the Y-up working space the report uses. options.parts[i] pairs with the i-th part over all files, at most 5000, and the report names each part's file. |
fileUnit | mm | cm | m | in | no | A unit of length: 'mm' (millimetres), 'cm' (centimetres), 'm' (metres) or 'in' (inches). |
options | object | yes | The stock, the per-part options and the settings of a nesting run. Every length is in the parts' units: millimetres on the nesting routes, which read their STEP files in millimetres, and the unit a pipeline models its shapes in for an occtPro.nesting step. |
options.sheets | array of object | yes | The stock to nest onto: kinds of rectangular sheets, or one strip. |
options.parts | array of object | no | The options of each part, in the order of the parts; the list may not be longer than the parts there are. A null entry, and every part past the end of the list, takes the defaults. All copies together stay within 100000, every part counting its quantity, or 1 when it has no entry or its entry gives none: the entries given are checked when the request arrives, and the total over every part once the parts are read. The request body may grow by 256 bytes for each of the 5000 parts nesting takes, so the options of every part fit, each with its quantity, a few fixed angles, a flip, a priority and an x direction. |
options.spacing | number | no | The least distance kept between any two parts, in the parts' units (millimetres for parts read from STEP files), measured on their true shapes. Defaults to 0, where parts that tile exactly may touch. |
options.margin | number | no | The band along each sheet's edges that no part enters, in the parts' units (millimetres for parts read from STEP files). Defaults to 0. |
options.timeBudgetSeconds | number | no | How long the search may run; the best layout found by then is returned. Defaults to 10 seconds, at most 120. |
options.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. |
options.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. |
options.seed | integer | no | The seed of the search's random choices. Defaults to 1. |
options.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 are written in, and their mesh quality. |
outputs.formats | array of object | yes | Output formats to generate; each gives a separate downloadable result. 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 a decomposed-mesh output from Y-up, as the server models, to Z-up. It applies to decomposed-mesh only: a STEP output is always written Z-up, so a STEP sent in comes back as it went in, 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/nesting/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.