Skip to main content

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​

Task accepted

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)

FieldTypeRequiredDescription
stepFileIdsarray of stringyesIDs 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.
fileUnitmm | cm | m | innoA unit of length: 'mm' (millimetres), 'cm' (centimetres), 'm' (metres) or 'in' (inches).
optionsobjectyesThe 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.sheetsarray of objectyesThe stock to nest onto: kinds of rectangular sheets, or one strip.
options.partsarray of objectnoThe 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.spacingnumbernoThe 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.marginnumbernoThe 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.timeBudgetSecondsnumbernoHow long the search may run; the best layout found by then is returned. Defaults to 10 seconds, at most 120.
options.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.
options.evaluationBudgetintegernoStop after this many placements are tried, which makes a run repeatable for one seed; the time budget still applies. 0 means no limit.
options.seedintegernoThe seed of the search's random choices. Defaults to 1.
options.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 are written in, and their mesh quality.
outputs.formatsarray of objectyesOutput formats to generate; each gives a separate downloadable result. 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 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​

StatusDescription
202Task accepted
400Validation error
403Insufficient scope
500Server 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.