Skip to content
Stella ConnectDocs
Parts

Nest one or more planar parts onto sheet stock

POST{baseUrl}/v2.0/2d/parts/nesting/planar

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.

Authx-api-key

application/json
Field
Type
Required
Description
parts[]object[]Yes

Parts to nest. Each entry references a previously imported and classified planar part by PartId together with its requested quantity.

parts[].partIduuidNo

PartId of a previously imported and classified planar part.

parts[].partNamestringNo

Free-form display name echoed back on the corresponding Parts[].Name in the response.

parts[].grainbooleanNo

Grain-alignment constraint. When true, the nester may only rotate the part by 0° or 180° (grain axis preserved). When false, 90° rotations are also allowed.

parts[].quantityintegerNo

Number of copies of this part to nest. Must be greater than zero.

parts[].measurementUnitstringNo

Length unit the part's cached dimensions are expressed in. Common values: "inch", "millimeter", "meter".

sheetobjectYes

Sheet stock definition — material properties, thickness, and one or more candidate sheet sizes the nester may draw from.

sheet.namestringNo

Free-form display name echoed back on the corresponding Sheets[].Name in the response.

sheet.densitynumberNo

Material density used to derive sheet and part weights.

sheet.densityUnitstringNo

Unit for Density (e.g. "pound_per_cubic_inch", "kilogram_per_cubic_meter").

sheet.thicknessnumberNo

Sheet thickness (gauge) in ThicknessUnit.

sheet.thicknessUnitstringNo

Length unit for Thickness.

sheet.sizes[]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.sizes[].lengthnumberNo

Sheet length (long side) in LengthUnit.

sheet.sizes[].lengthUnitstringNo

Length unit for Length. Common values: "inch", "millimeter", "meter".

sheet.sizes[].widthnumberNo

Sheet width (short side) in WidthUnit.

sheet.sizes[].widthUnitstringNo

Length unit for Width. Common values: "inch", "millimeter", "meter".

sheet.sizes[].quantityinteger | nullNo

Maximum number of sheets of this size available. null or 0 is treated as unlimited.

sheet.sizes[].variantIdstringNo

Caller-defined identifier that ties this size to an external stock record. Not interpreted by the nester; echo only.

sheet.sizes[].remnantobjectNo

Per-size remnant policy. When present, overrides Remnant for this sheet size.

sheet.sizes[].remnant.keepRemnantbooleanNo

When true, the nester is allowed to leave a useful leftover on the final sheet (fractional sheet). When false, sheets are nested full.

sheet.sizes[].remnant.minimumWidthnumber | nullNo

Minimum leftover width to be considered a keepable remnant. Both MinimumWidth and MinimumLength must clear their thresholds for a remnant to be kept.

sheet.sizes[].remnant.widthUnitstringNo

Length unit for MinimumWidth.

sheet.sizes[].remnant.minimumLengthnumber | nullNo

Minimum leftover length to be considered a keepable remnant. Both MinimumLength and MinimumWidth must clear their thresholds for a remnant to be kept.

sheet.sizes[].remnant.lengthUnitstringNo

Length unit for MinimumLength.

optionsobjectNo

Nesting behavior options — part-to-part / part-to-edge clearances and a global remnant policy that applies to every generated layout.

options.clearanceobjectNo

Clearance (empty gap) requirements between parts and between parts and the sheet edge.

options.clearance.partnumberNo

Minimum empty gap between neighboring parts. Expressed in PartUnit.

options.clearance.partUnitstringNo

Length unit for Part.

options.clearance.edgenumberNo

Minimum empty gap between any part and the outer edge of the sheet. Expressed in EdgeUnit.

options.clearance.edgeUnitstringNo

Length unit for Edge.

options.remnantobjectNo

Default remnant policy. Applies to any sheet size that does not carry its own Remnant.

options.remnant.keepRemnantbooleanNo

When true, the nester is allowed to leave a useful leftover on the final sheet (fractional sheet). When false, sheets are nested full.

options.remnant.minimumWidthnumber | nullNo

Minimum leftover width to be considered a keepable remnant. Both MinimumWidth and MinimumLength must clear their thresholds for a remnant to be kept.

options.remnant.widthUnitstringNo

Length unit for MinimumWidth.

options.remnant.minimumLengthnumber | nullNo

Minimum leftover length to be considered a keepable remnant. Both MinimumLength and MinimumWidth must clear their thresholds for a remnant to be kept.

options.remnant.lengthUnitstringNo

Length unit for MinimumLength.

outputLengthUnitstringYes

Unit for length values in the response (e.g. Length, Width, Thickness). Common values: "inch", "millimeter", "meter". Defaults to "inch".

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
dataobject | nullNo

Response payload for the planar-parts nesting endpoint. Returned inside a ConnectEnvelope<PlanarNestingOutputResponse>.

data.nestingIduuidNo

Server-generated identifier for this nesting result. Pass this value to the render-planar-nest endpoint to produce an image of the layout.

data.parts[]object[]No

Per-part summary — one entry per distinct PartId submitted in the request. Carries the part's derived unit weights (bounding-box vs true shape) but not any layout information.

data.parts[].partIduuidNo

Echo of the PartId submitted in the request.

data.parts[].namestringNo

Echo of the PartName supplied in the request.

data.parts[].unitRectangularWeightnumberNo

Bounding-box weight of one copy of the part — RectangularArea × Thickness × Density. Ignores holes and cutouts; useful as an upper bound on material consumption.

data.parts[].unitTrueWeightnumberNo

True-shape weight of one copy of the part — SurfaceArea × Thickness × Density. Holes and cutouts are subtracted, so this is the actual mass of the finished blank.

data.parts[].densitynumberNo

Echo of the sheet material density used to derive weights.

data.parts[].densityUnitstringNo

Unit for Density (e.g. "pound_per_cubic_inch").

data.sheets[]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.sheets[].sheetIduuidNo

Server-generated identifier for this sheet instance within the nest.

data.sheets[].namestringNo

Echo of the sheet Name supplied in the request.

data.sheets[].productIdstringNo

Reserved for future use. Currently always null.

data.sheets[].thicknessnumberNo

Sheet thickness, in the request's ThicknessUnit.

data.sheets[].lengthnumberNo

Length (long side) of the chosen sheet size, in LengthUnit.

data.sheets[].widthnumberNo

Width (short side) of the chosen sheet size, in LengthUnit.

data.sheets[].lengthUsednumberNo

Length (long side) of the material actually consumed on this sheet, in LengthUnit. When KeepRemnant is false this equals Length; when a remnant was cropped off, it is the extent of the retained cut region.

data.sheets[].widthUsednumberNo

Width (short side) of the material actually consumed on this sheet, in LengthUnit. Counterpart to LengthUsed.

data.sheets[].lengthUnitstringNo

Length unit for Length, Width, LengthUsed, WidthUsed, and Thickness. Reflects the request's OutputLengthUnit.

data.sheets[].weightnumberNo

Weight of a single full sheet at this size — Length × Width × Thickness × Density. Rounded to three decimals.

data.sheets[].weightUnitstringNo

Unit for Weight and TotalWeight (always "pound").

data.sheets[].totalWeightnumberNo

Combined weight of all sheets of this size actually consumed — Weight × TotalSheets. Reflects fractional sheet usage when KeepRemnant is true. Rounded to three decimals.

data.sheets[].numberOfSheetsRequiredintegerNo

Physical count of full sheets of this size required to complete the nest. Always rounded up from TotalSheets.

data.sheets[].totalSheetsnumberNo

Fractional sheet count actually consumed. When KeepRemnant is true, the final sheet may be a fraction (≤ 1) representing the portion that was cut before the remnant policy stopped further nesting. Otherwise equals NumberOfSheetsRequired.

data.sheets[].keepRemnantbooleanNo

Whether the nester actually kept a remnant on this sheet size. This is the effective decision — the nester may report false even when the request asked to keep a remnant, if the leftover was smaller than the configured minimums.

data.sheets[].remnantCropTypestringNo

Shape of the retained remnant. One of "VerticalCrop", "HorizontalCrop", "LShapeCrop", or "NoCrop".

data.sheets[].nestedParts[]object[]No

Per-part usage on this sheet — one entry per distinct PartId placed on it, with the count of copies and derived weights.

data.sheets[].nestedParts[].partIduuidNo

Echo of the PartId that was placed on this sheet.

data.sheets[].nestedParts[].unitNestedWeightnumberNo

Weight of one nested copy accounting for grain and orientation as actually placed on this sheet.

data.sheets[].nestedParts[].unitTrueWeightnumberNo

True-shape weight of one copy of the part — SurfaceArea × Thickness × Density. Matches UnitTrueWeight.

data.sheets[].nestedParts[].totalNumberOfUnitsNestedintegerNo

Number of copies of this PartId placed on this sheet.

errors[]object[] | nullNo

One or more errors describing why the request failed. Absent (null) on success.

errors[].descriptionstring | nullNo

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[].errorIdstring | nullNo

Machine-readable, stable error identifier. Consumers should branch on this value rather than on Description. See ConnectErrorIds for the catalog.

pagingobject | nullNo

Paging metadata for list endpoints. Absent on single-item responses.

paging.limitintegerNo
paging.startintegerNo
paging.totalintegerNo

Example 200 response
{
  "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
  }
}