Nest one or more planar parts onto sheet stock
Nests one or more classified planar (sheet-metal) parts onto candidate
sheet stock and returns per-sheet layout usage plus per-part weights.
Get a PartId by uploading a file
here — every imported file yields one or more
parts. The returned NestingId can be passed to
RenderPlanarNest2D to produce an image
of the layout.
The weight unit is always pounds.
Parts must be flat. To nest a 3D sheet-metal file (STEP), import it through
ImportFiles3D with Unfold=true and use that part id;
the 2D importer does not flatten 3D geometry.
Errors: part_not_found (404) when a PartId was never imported,
part_not_nestable (422) when a part is not flat or has no outline that can be
placed on a sheet, nesting_failed (500) for any other upstream failure.
x-api-keyapplication/jsonField | Type | Required | Description |
|---|---|---|---|
| parts[] | object[] | Yes | Parts to nest. Each entry references a previously imported and classified
planar part by |
| parts[]. | uuid | No |
|
| parts[]. | string | No | Free-form display name echoed back on the corresponding
|
| parts[]. | boolean | No | Grain-alignment constraint. When |
| parts[]. | integer | No | Number of copies of this part to nest. Must be greater than zero. |
| parts[]. | string | No | Length unit the part's cached dimensions are expressed in. Common
values: |
| sheet | object | Yes | Sheet stock definition — material properties, thickness, and one or more candidate sheet sizes the nester may draw from. |
| sheet. | string | No | Free-form display name echoed back on the corresponding
|
| sheet. | number | No | Material density used to derive sheet and part weights. |
| sheet. | string | No | Unit for Density (e.g. |
| sheet. | number | No | Sheet thickness (gauge) in ThicknessUnit. |
| sheet. | string | No | Length unit for Thickness. |
| sheet. | object[] | No | Candidate sheet sizes. Provide one or more; the nester picks the best fit for each layout. Each size may carry its own per-size remnant policy that overrides Remnant. |
| sheet. | number | No | Sheet length (long side) in LengthUnit. |
| sheet. | string | No | Length unit for Length. Common values: |
| sheet. | number | No | Sheet width (short side) in WidthUnit. |
| sheet. | string | No | Length unit for Width. Common values: |
| sheet. | integer | null | No | Maximum number of sheets of this size available. |
| sheet. | string | No | Caller-defined identifier that ties this size to an external stock record. Not interpreted by the nester; echo only. |
| sheet. | object | No | Per-size remnant policy. When present, overrides Remnant for this sheet size. |
| sheet. | boolean | No | When |
| sheet. | number | null | No | Minimum leftover width to be considered a keepable remnant. Both MinimumWidth and MinimumLength must clear their thresholds for a remnant to be kept. |
| sheet. | string | No | Length unit for MinimumWidth. |
| sheet. | number | null | No | Minimum leftover length to be considered a keepable remnant. Both MinimumLength and MinimumWidth must clear their thresholds for a remnant to be kept. |
| sheet. | string | No | Length unit for MinimumLength. |
| options | object | No | Nesting behavior options — part-to-part / part-to-edge clearances and a global remnant policy that applies to every generated layout. |
| options. | object | No | Clearance (empty gap) requirements between parts and between parts and the sheet edge. |
| options. | number | No | Minimum empty gap between neighboring parts. Expressed in PartUnit. |
| options. | string | No | Length unit for Part. |
| options. | number | No | Minimum empty gap between any part and the outer edge of the sheet. Expressed in EdgeUnit. |
| options. | string | No | Length unit for Edge. |
| options. | object | No | Default remnant policy. Applies to any sheet size that does not carry its own Remnant. |
| options. | boolean | No | When |
| options. | number | null | No | Minimum leftover width to be considered a keepable remnant. Both MinimumWidth and MinimumLength must clear their thresholds for a remnant to be kept. |
| options. | string | No | Length unit for MinimumWidth. |
| options. | number | null | No | Minimum leftover length to be considered a keepable remnant. Both MinimumLength and MinimumWidth must clear their thresholds for a remnant to be kept. |
| options. | string | No | Length unit for MinimumLength. |
| outputLengthUnit | string | Yes | Unit for length values in the response (e.g. |
Status | When |
|---|---|
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | A PartId does not match any imported part. |
| 422 | A part is not flat, or has no outline that can be placed on a sheet. |
| 500 | An unexpected error occurred on the server. |
Field | Type | Required | Description |
|---|---|---|---|
| data | object | null | No | Response payload for the planar-parts nesting endpoint. Returned inside a
|
| data. | uuid | No | Server-generated identifier for this nesting result. Pass this value to the render-planar-nest endpoint to produce an image of the layout. |
| data. | object[] | No | Per-part summary — one entry per distinct |
| data. | uuid | No | Echo of the |
| data. | string | No | Echo of the |
| data. | number | No | Bounding-box weight of one copy of the part —
|
| data. | number | No | True-shape weight of one copy of the part —
|
| data. | number | No | Echo of the sheet material density used to derive weights. |
| data. | string | No | Unit for Density (e.g. |
| data. | object[] | No | Per-sheet layout — one entry per physical (or fractional) sheet the nester used. Each entry lists the parts placed on that sheet and the derived sheet-level weights. |
| data. | uuid | No | Server-generated identifier for this sheet instance within the nest. |
| data. | string | No | Echo of the sheet |
| data. | string | No | Reserved for future use. Currently always |
| data. | number | No | Sheet thickness, in the request's |
| data. | number | No | Length (long side) of the chosen sheet size, in LengthUnit. |
| data. | number | No | Width (short side) of the chosen sheet size, in LengthUnit. |
| data. | number | No | Length (long side) of the material actually consumed on this sheet, in
LengthUnit. When KeepRemnant is
|
| data. | number | No | Width (short side) of the material actually consumed on this sheet, in LengthUnit. Counterpart to LengthUsed. |
| data. | string | No | Length unit for Length, Width,
LengthUsed, WidthUsed, and
Thickness. Reflects the request's |
| data. | number | No | Weight of a single full sheet at this size —
|
| data. | string | No | Unit for Weight and TotalWeight (always
|
| data. | number | No | Combined weight of all sheets of this size actually consumed —
|
| data. | integer | No | Physical count of full sheets of this size required to complete the nest. Always rounded up from TotalSheets. |
| data. | number | No | Fractional sheet count actually consumed. When KeepRemnant
is |
| data. | boolean | No | Whether the nester actually kept a remnant on this sheet size. This is
the effective decision — the nester may report |
| data. | string | No | Shape of the retained remnant. One of |
| data. | object[] | No | Per-part usage on this sheet — one entry per distinct |
| data. | uuid | No | Echo of the |
| data. | number | No | Weight of one nested copy accounting for grain and orientation as actually placed on this sheet. |
| data. | number | No | True-shape weight of one copy of the part —
|
| data. | integer | No | Number of copies of this PartId placed on this sheet. |
| errors[] | object[] | null | No | One or more errors describing why the request failed. Absent ( |
| errors[]. | string | null | No | Human-readable explanation of the error. Intended for display to end users or logs. Wording is not stable and should not be branched on. |
| errors[]. | string | null | No | Machine-readable, stable error identifier. Consumers should branch on this value
rather than on Description. See |
| paging | object | null | No | Paging metadata for list endpoints. Absent on single-item responses. |
| paging. | integer | No | |
| paging. | integer | No | |
| paging. | integer | No |
{
"data": {
"nestingId": "11e99bc8-e511-474a-b049-938734f567db",
"parts": [
{
"partId": "08fcc2e5-7760-493b-b8f1-1ad26fcb0a9e",
"name": "string",
"unitRectangularWeight": 0.1,
"unitTrueWeight": 0.1,
"density": 0.1,
"densityUnit": "string"
}
],
"sheets": [
{
"sheetId": "1c65aa74-73fc-4fac-b8af-41acabfc39cc",
"name": "string",
"productId": "string",
"thickness": 0.1,
"length": 0.1,
"width": 0.1,
"lengthUsed": 0.1,
"widthUsed": 0.1,
"lengthUnit": "string",
"weight": 0.1,
"weightUnit": "string",
"totalWeight": 0.1,
"numberOfSheetsRequired": 0,
"totalSheets": 0.1,
"keepRemnant": true,
"remnantCropType": "string",
"nestedParts": [
{
"partId": "08fcc2e5-7760-493b-b8f1-1ad26fcb0a9e",
"unitNestedWeight": 0.1,
"unitTrueWeight": 0.1,
"totalNumberOfUnitsNested": 0
}
]
}
]
},
"errors": [
{
"description": "string",
"errorId": "string"
}
],
"paging": {
"limit": 0,
"start": 0,
"total": 0
}
}