Data Objects

Learn about usage of Data Object in Toncut, using examples and clearly readable tables.

Profile

Profile refers to an optimization profile.

It describes the configuration for algorithms to be used and optimization limits, such as maximum time, maximum number of combination, etc.

An optimization profile allows users to specify the parameters and constraints for an optimization process, ensuring that the algorithms used are tailored to their specific needs and requirements.

The user can define up to 20 profiles, allowing them to test different optimization strategies to achieve the best results.

Attributes

name
string mandatory
The name of the optimization profile.
active
bool mandatory
Set it to true, to activate the profile. It will be used only if it is active.
algorithms
object mandatory
Configuration of algorithms to be used by the profile.
Show Child Attributes
grouping
booldef: true
When activated, this algorithm groups pieces into larger rectangles, which not only speeds up the optimization process but also typically yields better results.

deduction
booldef: true
When activated, this algorithm tries to predict what will be the waste during the optimization process.

If the predicted waste is greater than the best solution found so far, the algorithm stops exploring the current branch and switches to another one.

lastStockItem
booldef: true
Optimization can take longer when there aren’t enough pieces to fill the entire area.

When activated, this algorithm speeds up the optimization process by quickly optimizing the last cuttings.

firstHit
booldef: true
When activated, this algorithm immediately stops optimization of a single cutting as soon as it finds the first solution that fills the entire area.

It's important to note that while this algorithm may generate the best results for a single cutting, it may not always produce the best results for the entire optimization process.
fast
booldef: false
When activated, this algorithm activates a shallow optimization process that is very fast but may produce weaker results.

balance
booldef: true
When activated, this algorithm addresses the issue of greedy optimization.

Small pieces are easier to optimize, so they may all be used in the first cuttings, leaving only large pieces that are difficult to layout optimally.

This can result in perfectly optimized first cuttings but huge waste on the last. To avoid this, the balancing algorithm distributes small, medium, and large pieces throughout all the cuttings.

adaptive
object
The adaptive algorithm is a type of global algorithm. It operates by repeating the optimization process multiple times.

In each subsequent iteration, problematic elements are shifted to earlier cuttings to improve the results.

Show Child Attributes
enabled
booldef: true
Enables or disables the adaptive object.

level
int(2-40)def: 5
The level property describes maximum number of iterations that can be done for each solution.

ai
object
AI is a type of global optimization algorithm that leverages artificial intelligence to discover superior solutions that cannot be achieved by traditional algorithms.

Show Child Attributes
enabled
booldef: false
Enables or disables the ai object.

level
int(0-4)def: 0
The level of the AI algorithm refers to several of its parameters. A higher level means a longer optimization process but also results in a better solution.

Typically, levels 1 or 2 produce satisfactory results.
Each algorithm is ignored if ai algorithm is enabled.
limits
object
Here we can define the conditions for early termination of global and/or single optimization.
A configuration profile is validated when it is loaded; an invalid value is a load error, not a silent default. Counts and time limits must not be negative, and a limit that is enabled must be greater than zero. A time limit must be a finite number of time units within the supported range. Percentages (goodEnoughWaste, minWaste, threshold) must be between 0 and 100, and algorithms.ai.level between 0 and 4. A sub-section that is present but is not a JSON object is rejected as well.
Show Child Attributes
single
object
Allows to specify the limits of the optimization of a single StockItem.

Show Child Attributes
maxCombinations
object
Allows to specify the maximum number of combinations.

Show Child Attributes
enabled
bool def: false
Enables or disables the limit.

limit
int
Optimization will be completed if the number of checked combinations exceeds the given value.

maxTime
object
Allows to specify the maximum optimization time.

Show Child Attributes
enabled
bool def: false
Enables or disables the limit.

limit
time
The optimization will be terminated if it lasts longer than the specified time.

This limit is applied separately to every StockItem, so setting it as large as the whole job's time budget can let optimization of a single StockItem consume that entire budget.

When the limit is reached, the engine stops and keeps the best result found so far instead of reporting an error; the job still finishes normally. The result may not include all requested pieces, and no field lists which pieces remain unplaced. To check whether a result is complete, compare each piece's requested quantity against how often it was actually placed in the returned Cutting objects (a piece's quantity multiplied by how many times its pieceId occurs in pieces).

This limit always bounds a single StockItem attempt; it is never a job- or variant-level limit. However, while stockOrder.order.direction is allPermutations and a material is being primed with complete stock orders (see below), if profile.maxTime or variant.maxTime is also enabled, the engine may give an individual attempt less time than this limit so the priming orders still fit inside whichever of those is tighter.

The stock order currently running keeps the full single.maxTime window, unshortened, for every attempt it still needs for as long as it is estimated to finish on its own within the remaining time and no stock order of this priming has yet run to its own natural end (its demand placed, its stock exhausted, or its accept limit reached). Once that stops holding - the current order would not finish in time, or an earlier stock order already ran to its end - the remaining time is shared across the attempts the current and later priming orders still need, giving a larger stock item a larger share of that time than a smaller one.

The shortened window is never below 2 seconds, is timed from the attempt's own start, and never exceeds this limit. Outside that priming phase, and whenever neither profile.maxTime nor variant.maxTime is enabled, this limit is applied unchanged.
goodEnoughWaste
object
Allows to specify (in percent) the amount of waste (usable and non-usable) that is acceptable.

Show Child Attributes
enabled
bool def: false
Enables or disables the limit.

limit
percent
Optimization of a single StockItem will be completed when the waste size is lower than the given value, as a percentage of the stock's material (its area without holes).

variant
object
Allows to specify the limits of a single optimization variant.

Show Child Attributes
maxCombinations
object
Allows to specify the maximum number of combinations.

Show Child Attributes
enabled
bool def: false
Enables or disables the limit.

limit
int
Optimization will be completed if the number of checked combinations exceeds the given value.

maxTime
object
Allows to specify the maximum optimization time.

Show Child Attributes
enabled
bool def: false
Enables or disables the limit.

limit
time
The optimization will be terminated if it lasts longer than the specified time.

When the limit is reached, the engine stops and keeps the best result found so far for this variant instead of reporting an error; the job still finishes normally. The result may not include all requested pieces, and no field lists which pieces remain unplaced. Compare each piece's requested quantity against how often it was actually placed in the returned Cutting objects to check whether the result is complete.
profile
object
Allows you to specify the limits for all variants optimized as part of this profile.

Show Child Attributes
maxCombinations
object
Allows to specify the maximum number of combinations.

Show Child Attributes
enabled
bool def: false
Enables or disables the limit.

limit
int
Optimization will be completed if the number of checked combinations exceeds the given value.

maxTime
object
Allows to specify the maximum optimization time.

Show Child Attributes
enabled
bool def: false
Enables or disables the limit.

limit
time
The optimization will be terminated if it lasts longer than the specified time.

When the limit is reached, the engine stops and keeps the best result found so far across the profile's variants instead of reporting an error; the job still finishes normally. The result may not include all requested pieces, and no field lists which pieces remain unplaced. Compare each piece's requested quantity against how often it was actually placed in the returned Cutting objects to check whether the result is complete.
stockOrder
object
Here we can specify the stock sequence strategy. This is of great importance and can significantly affect the quality of the results.
These settings apply to all algorithms except ai.
Regardless of the configured sort order, a stock item that is the only remaining stock able to hold a piece the job still needs is tried early. A layout that places such a piece is accepted even when it is otherwise sparse.
Stock holes hold no material, so stock usage, sparseness, and the large-stock decisions of the stock search are measured on the stock's material area, not on its gross size.
Show Child Attributes
order
object
Here we define the main strategy for the order of stock selection.

Show Child Attributes
direction
Directionenum
Stock's sorting
Allowed values
fromLarge

The stock will be sorted by size, from larger to smaller.
fromSmall

The stock will be sorted by size, from smaller to larger.
random

The stock will be in random order.
allPermutations

The optimizer searches alternative stock-item orders and keeps the best result. Unsupported combinations fall back to fromLarge.
For a material below the high-volume threshold (500 pieces) whose stock search can accept more than one result, the search is primed with a few complete stock orders before the adaptive search begins, in one of two sequences: dominant-width then large-first, or small-first then dominant-width then large-first. These priming orders, and the adaptive search that follows them, share the initial ~10% of the material's reported optimization progress.
Dominant-width can lead only when an exact-width ("zero-slack") stock exists for the piece width that carries the most area (the narrow side, for a piece that can rotate) and that exact-width stock covers at least 25% of that width's total piece area; a few small remnants at the exact width no longer qualify on their own. Even then, small-first leads instead whenever single.maxTime is enabled and either profile.maxTime or variant.maxTime gives a known time budget that small-first's own priming order is estimated to finish within, using the full single.maxTime window for every attempt it still needs: small-first reliably reaches the demand that dominant-width could otherwise spend the whole time budget approaching through the exact-width stock alone. With no such known time budget, or with single.maxTime disabled, there is no budget to check small-first against, and dominant-width leads whenever the exact-width/25% condition above holds, as before.
def: fromLarge
Here we can define if and how the stock will be sorted.
switchToSmall
object
It is a modifier of the fromLarge direction. If waste exceeds the given threshold, the order of the remaining stock will be automatically changed according to fromSmall direction.

Show Child Attributes
enabled
bool def: false
Enables or disables the switchToSmall modifier of the fromLarge direction.

minWaste
percent
The waste threshold expressed in percentage. If the waste, as a percentage of the stock's material (its area without holes), is larger than the specified value, the switchToSmall modifier will be executed.

randomOrders
object
It is a modifier of the fromSmall direction. It generates specified number of random orders for small stock items.

Show Child Attributes
enabled
bool def: false
Enables or disables the randomOrders modifier of the fromSmall direction.

count
int
Number of random orders for the small stock items.

randomDrawCount
int def: 10
It is modifier of the random direction. Defines number of random orders that should be checked.

adaptiveOrder
object
An additional dynamic stock reorder strategy can be enabled here.

This strategy only works in a “forward” manner and does not alter the order of already optimized cuttings.

If the waste of a single cutting exceeds a given threshold, the program will reject it and move the StockItem to the end of the queue. Optimization will then continue with the next StockItem.

Show Child Attributes
enabled
booldef: true
Enables or disables the adaptive reorder strategy.

minWaste
percentdef: 15%
The waste size threshold expressed in percentage. If the waste, as a percentage of the stock's material (its area without holes), is larger than specified value, the order of the remaining stock items will be changed.

maxTries
intdef: 3
Maximum number of reorders per cycle.

maxCycles
intdef: 1
Maximum number of cycles. The cycle ends when we are optimizing again a StockItem that was already rejected by this strategy.
advanced
object
Here we can change some advanced settings.
Before you change anything here, make sure you understand what you are doing, as these settings may significantly change the quality of results and also time of the optimization process.
Show Child Attributes
dynamicMethodSwitch
object
This is a simple, yet very effective strategy that shortens optimization time significantly.

If the program cannot find a better solution for the specified time, it will switch optimization process to something that we call “a fast route”.

The “fast route” will be automatically disabled when the time comes.

Show Child Attributes
enabled
bool def: true
Enables or disables the dynamicMethodSwitch.

threshold
time
The amount of time during which the program is unable to find a better solution. When this threshold is reached the optimization will switch to the “fast route”.

fastMethodForLastStockItems
object
Optimization of last stock items usually takes more time because of less optimization tools available.

To make this process faster one can enable fast method.

When this option is enabled, the fast method will be activated automatically when total size of available elements is smaller than provided percentage of the StockItem's size.

Show Child Attributes
enabled
booldef: true
Enables or disables the fastMethodForLastStockItems.

threshold
percentdef: 80%
If total size of all available pieces is smaller than the value provided here, then fast method will be activated.

searchDirection
searchDirectionenum
Direction of StockItem's placement
Allowed values
byLength

Horizontally, by length.
byWidth

Vertically, by width (doesn’t make sense for 1D materials).
auto

The direction will be selected automatically.
def: auto
Specifies the direction in which items are placed on the StockItem.
searchPrecision
object
Controls how many piece alternatives the search considers. Higher values can improve results but require more search work; they do not guarantee a better result within a fixed time limit.

Be careful, as setting too high numbers here can make the optimization process much longer.
Show Child Attributes
firstLevel
int def: maximum/all pieces
How many pieces should be checked in the first step.

nextLevels
int def: 1
How many pieces should be checked in the next steps.

Note that value of 2 here is already very high!

Profile object

{
  "profiles": {
    "name": "fromSmall",
    "active": true,
    "algorithms": {
      "grouping": true,
      "deduction": true,
      "lastStockItem": true,
      "firstHit": true,
      "fast": false,
      "balance": false,
      "adaptive": {
          "enabled": true,
          "level": 5
      },
      "ai": {
          "enabled": false,
          "level": 0
      }
    },
    "limits": {
      "single": {
        "maxCombinations": {
          "enabled": false,
          "limit": 1000
        },
        "maxTime": {
          "enabled": true,
          "limit": "5s"
        },
        "goodEnoughWaste": {
          "enabled": true,
          "limit": "5%"
        }
      },
      "variant": {
        "maxCombinations": {
          "enabled": false,
          "limit": 100000
        },
        "maxTime": {
          "enabled": false,
          "limit": "30s"
        }
      },
      "profile": {
        "maxCombinations": {
          "enabled": false,
          "limit": 10000000
        },
        "maxTime": {
          "enabled": true,
          "limit": "10m"
        }
      }
    },
    "stockOrder": {
      "order": {
          "direction": "fromSmall",
          "switchToSmall": {
            "enabled": false,
            "minWaste": "0.20%"
          },
          "randomOrders": {
            "enabled": false,
            "count": 5
          },
          "randomDrawCount": 10
      },
      "adaptiveOrder": {
          "enabled": true,
          "minWaste": "0.15%",
          "maxTries": 3,
          "maxCycles": 1
      }
    },
    "advanced": {
      "dynamicMethodSwitch": {
          "enabled": true,
          "threshold": "1s"
      },
      "fastMethodForLastStockItems": {
          "enabled": true,
          "threshold": "0.80%"
      },
      "searchDirection": "auto",
      "searchPrecision": {
          "firstLevel": 2147483647,
          "nextLevels": 1
      }
    }
  }
}

Device

Device object represents a cutting device.

It specifies the features and limitations of the device.

Attributes

id
int mandatory
Unique device id.
title
string mandatory
Device title.
driver
string
Identifier of the device driver associated with this device.
defaultRotation
angle def: 0°
Default (initial) rotation of the device's work area, as used by TonCut Desktop. Like the piece rotation, it honours defaultUnits.angle (the format default angle unit is radians), and a string such as "90deg" forces the unit. Allowed values are 0°, 90°, 180° and 270°; any other value is rejected with the error Device default rotation must be 0, 90, 180 or 270 degrees. It does not affect optimization or the results.
defaultMirror
bool def: false
Default (initial) mirroring of the device's work area, as used by TonCut Desktop. true mirrors the work area horizontally (left-right); a mirror is always left-right. Combined with defaultRotation it expresses every orientation (a top-bottom flip is a left-right mirror plus 180°). A non-boolean value is rejected with the error defaultMirror: expected a boolean. It does not affect optimization or the results.
materialKind
MaterialKindenum
Material kind device's made for
Allowed values
1d

1D materials like profiles, pipes, rods, beams, etc.
2d

2D materials like glass, panels, fabric, aluminum, cardboard, etc.
mandatory
Specifies the material kind this device is made for.
slants
object 1D only
Specifies support for miter cuts in 1D materials.
Show Child Attributes
supported
booldef: false
Set it to true if the device supports miter cuts.

leftMeasurement
LeftMeasurementenum
Measurement of the left slant
Allowed values
fromMiddleToLeft
fromMiddleToRight
fromLeft
fromRight
def: fromMiddleToRight
How the left slant's angle is measured.
rightMeasurement
RightMeasurementenum
Measurement of the right slant
Allowed values
fromMiddleToLeft
fromMiddleToRight
fromLeft
fromRight
def: fromMiddleToLeft
How the right slant's angle is measured.
canCutAnyShapes
bool 2D onlydef: false
Set it to true if the device allows cutting of non-rectangular shapes (e.g. circles, polygons, etc.).
Available only with Ultimate license!

It forces special true-nesting algorithm that may be slower than the standard one.
canCrossCuts
bool 2D onlydef: false
Set it to true if the device allows the cuts to cross each other.

Ignored if canCutAnyShapes is enabled.
fullCutsOnly
bool 2D onlydef: true
Set it to true if only full cuts (from edge to edge) are allowed.

Ignored if canCutAnyShapes is enabled.
stripCutting
StripCuttingenum
Strip cutting direction
Allowed values
none

No strip cutting.
byLength

Horizontal strips.
byWidth

Vertical strips.
2D onlydef: none
Set it to byLength or byWidth if the device cuts in strips (e.g. for panel saw).
It makes sense only if fullCutsOnly option is set to true.
It may be used together with maxCutDepth option.
Ignored if canCutAnyShapes is enabled.
For backward compatibility, when stripCutting is absent a boolean stripCuts is accepted: true means byLength and false means none. New integrations should use stripCutting.
maxStripeWidth
lengthdef: 1200mm
Used only when strip cutting is enabled (see stripCutting above); specifies the maximum stripe width.
minCutDistance
lengthdef: 0
The minimum kerf-excluded material gap between span-overlapping parallel interior cuts (line spacing minus kerf). It applies between parallel cuts only. It does not apply between a cut and the stock boundary or a hole edge. Use 0 to disable this limit.
Setting this value makes sense when cutting glass – you don't want to have two parallel cuts too close to each other, because then breaking off can be significantly more difficult.
Please note that this is not a kerf that can be set in the material group settings.
minCutDistance is distinct from minCutSize: it constrains the kerf-excluded material gap between span-overlapping parallel cuts, while minCutSize constrains cut-out dimensions. The legacy minCutWidth name does not configure this setting.
minCutSize
lengthdef: 0
The minimum permitted dimension of a rectangular cut-out. The limit applies to both its length and width, including pieces, trims, waste, and reusable waste. For one-dimensional cutting, only length is checked. A dimension equal to the limit is allowed. Use 0 to disable this limit. Pieces below the limit are loaded normally. Methods that enforce an individual-piece minimum exclude them during selection before optimization, leaving them unplaced. The comparison uses effective cutting dimensions, including additions and edging adjustments. A method that supports smaller constituent pieces through series or sets keeps those pieces eligible. This exception applies only to individual pieces; edging, waste, reusable waste, and remnants retain their minimum-size requirements.
The former name minCutWidth is accepted for backward compatibility. New integrations should use minCutSize. If both names are present, minCutSize takes precedence.
minEdgeDistance
object
Defines the minimum distance from each stock edge to a parallel cut. This is a cut-position limit, not a reserved stock band. The limit applies at the edge of a stock hole as at a sheet edge, with the margin of the sheet side that the hole edge stands in for (a hole edge with material below it acts as a top edge, one with material to its right as a left edge). Values can be overridden per side by the Material and StockItem settings.
Show Child Attributes
left
lengthdef: 0
Minimum distance from the left edge to a parallel cut.

right
lengthdef: 0
Minimum distance from the right edge to a parallel cut.

top
length 2D onlydef: 0
Minimum distance from the top edge to a parallel cut.

bottom
length 2D onlydef: 0
Minimum distance from the bottom edge to a parallel cut.
edgingCuts
EdgingCutsenum
Specifies the edging method
Allowed values
optimal

An optimal edging method ensures precise and accurate cutting of edges, resulting in clean, smooth, and well-defined boundaries while minimizing any unintended removal or distortion of the desired elements.
horizontalFirst

A "HorizontalFirst" edging method involves cutting off the horizontal edges first, followed by the vertical edges.
verticalFirst

A "VerticalFirst" edging method refers to a technique where the vertical edges are cut off before the horizontal edges.
2D onlydef: optimal
Edging method.
originEdgingCuts
OriginEdgingCutsenum
Edging method for the top and left edges.
Allowed values
default

Nothing changes and edges will be cut off as described in edgingCuts property description.
twoFullCuts

Top and left edges will be cut off as full cuts (from edge to edge)
2D onlydef: default
Edging method for the top and left edges.
firstCutDirection
CutDirectionenum
Specifies the direction of the first cut
Allowed values
horizontal

First cut will be horizontal, along the length of the StockItem.
vertical

First cut will be vertical, along the width of the StockItem.
any

Algorithm will decide.
2D onlydef: any
Specifies whether the first cut will be done horizontally or vertically. Note that it is overwritten if strip cutting is turned on.
It's important to note that setting the correct firstCutDirection can be crucial when used in conjunction with the maxCutDepth option.
Ignored if canCutAnyShapes is enabled.
maxCutDepth
object 2D only
Specifies maximum cut depth level the device is supporting.
The picture below shows what is the cut depth level:
Ignored if canCutAnyShapes is enabled.
It makes sense only if fullCutsOnly is set to true.
Show Child Attributes
enabled
bool def: false
Enables or disables maximum cut depth limit.

limit
int
The cut depth limit.

includeEdging
bool def: false
Set it to true if cutting off edges should be included when calculating cut depth.
maxCutLengthByLength
object
Maximum horizontal cut length.
It can also be used when cutting in strips - then it allows to limit the width of the strip.
This option is especially useful when the device is a guillotine.
Ignored if canCutAnyShapes is enabled.
Show Child Attributes
enabled
booldef: false
Enables or disables maximum horizontal cut length.

limit
length
Maximum cut length.
maxCutLengthByWidth
object 2D only
Maximum vertical cut length.
It can also be used when cutting in strips - then it allows to limit the width of the strip.
This option is especially useful when the device is a guillotine.
Ignored if canCutAnyShapes is enabled.
Show Child Attributes
enabled
booldef: false
Enables or disables maximum vertical cut length.

limit
length
Maximum cut length.
costs
object
Defines cost parameters for cost-based optimization. See cmdAddJob's bestSolutionCriterion input parameter for more details.
Available only with Enterprise license!
Accurate cost values are essential for generating meaningful optimization results. Cost parameters may be defined on multiple levels - Device, Material, Piece, and StockItem. If these values are incomplete, inconsistent, or significantly inaccurate, the optimization engine will inevitably reflect these issues in its output. To ensure reliable and realistic results, verify that all relevant cost fields are correctly provided and aligned with actual production and operational conditions.
Show Child Attributes
cutCostPerMeter
pricedef: 0
Cost per meter for cutting operations.

When also defined on Material, both values are summed. Material’s value does not override the Device’s.
reuseCost
pricedef: 0
This property defines the cost of handling reusable waste. For example, it represents the cost to move the reusable waste back to the warehouse.

When also defined on Material, both values are summed. Material’s value does not override the Device’s.
utilizationCostPerKg
pricedef: 0
Specifies the cost per kilogram for waste disposal, covering expenses for collection, transport, and processing of waste material.

When also defined on Material, both values are summed. Material’s value does not override the Device’s.
segmentShiftCost
pricedef: 0
This property represents the additional cost incurred when a material segment must be shifted to avoid damage during a perpendicular cut. For example, in stone cutting the blade may need to extend beyond the target piece to complete a cut, requiring adjacent pieces to be repositioned by a distance determined by the blade’s diameter and the material’s thickness.

When also defined on Material, both values are summed. Material’s value does not override the Device’s.
segmentRotationCost
pricedef: 0
This property specifies the additional cost incurred when rotating a material segment for a perpendicular cut. For example, if the cutting machine’s blade moves in only one direction, the segment must be rotated by 90° to perform the cut.

When also defined on Material, both values are summed. Material’s value does not override the Device’s.
algorithmData
object
Optional opaque algorithm-specific data for this device. Its contents are implementation-defined and are not part of the public API contract.
Supply algorithmData only through an integration-specific contract.
Available only with Enterprise license! Without it the property is ignored.
customData
any
Custom data that will be directly passed to customData.device property in Cutting.
It can be any JSON compatible data, for example: { "myId": "932422" }, "932422", or 932422.
Available only with Enterprise license!

{
  "devices": [
    {
      "title": "Device 1D",
      "materialKind": "1d",
      "slants": {
          "supported": true,
          "leftMeasurement": "fromMiddleToRight",
          "rightMeasurement": "fromMiddleToLeft"
      },
      "minCutDistance": 0,
      "minCutSize": 0,
      "edgingCuts": "optimal",
      "maxCutLengthByLength": {
          "enabled": false,
          "limit": 10000
      },
      "id": 1
    }
  ]
}

StandardStockItem

The StandardStockItem object is used to define standard dimensions and default characteristics of stock items.

For each material you can define list of standard stock items.

Attributes

id
int mandatory
Unique id of a StandardStockItem.
title
string
Title of a StandardStockItem.
length
length mandatory
Length of a StandardStockItem.
width
length mandatory 2D only
Width of a StandardStockItem.
structure
Structuresset
The structure of the StandardStockItem
Allowed values
none

The material has no structure.
byLength

The structure is horizontal (along length).
byWidth

The structure is vertical (along width).
2D onlydef: []
The structure of the StandardStockItem.
edging
object
Edging configuration.
Show Child Attributes
left
lengthdef: 0
The size of the edge to be cut off on the left side of the StockItem.

right
lengthdef: 0
The size of the edge to be cut off on the right side of the StockItem.

top
length 2D onlydef: 0
The size of the edge to be cut off on the top of the StockItem.

bottom
length 2D onlydef: 0
The size of the edge to be cut off on the bottom of the StockItem.

Material

The Material object defines material group.

Each piece or StockItem must belong to a material group.

Thanks to this, the program knows which pieces are to be placed on which stock items.

Attributes

id
int mandatory
Unique id of a material group.
deviceId
int mandatory
Id of a cutting device used to cut this material group.
algorithm
string
Allows selection of custom algorithms.

Available only with Enterprise license!
title
string mandatory
Title of the material group.
kind
MaterialKindenum
Type of the material
Allowed values
1d

1D materials like profiles, pipes, rods, beams, etc.
2d

2D materials like glass, panels, fabric, aluminum, cardboard, etc.
mandatory
Specifies the type of the material.
width
length mandatory 1D only
Specifies the width of the material.
thickness
length mandatory
Specifies the thickness of the material.
canHaveStructure
bool 2D onlydef: false
Specifies whether the material group can have a structure.
colorable
booldef: false
Specifies whether the pieces can have different colors. It doesn't influence the optimization process.
canRotate
bool def: false
Specifies whether the pieces of this material group can be rotated by 1D and true-shape algorithms.

Other algorithms ignore this property and determine allowed orientations only from the material, stock, and piece structure settings.
True-shape algorithms respect the structure settings as well. On a StockItem with a structure, the structure alone decides the orientation of a piece. This property therefore permits free rotation only on stock without a structure, in steps of the rotationStep of the piece.
canMirror
bool def: false
Specifies whether the pieces of this material group can be reversed (back to front) by 1D and true-shape algorithms.

Other algorithms ignore this property and determine allowed orientations only from the material, stock, and piece structure settings.
qualityLevel
QualityLevelenum
Shape path simplification quality level
Allowed values
precission

Highest quality, but slowest.
compromise

Good quality and speed.
speed

Lowest quality, but fastest.
2D only
Specifies the quality level used for shape path simplification.

It influences the speed of the optimization process and the quality of the results.
Applies only to true-shape nesting algorithm.
surplus
lengthdef: 0
This setting defines the default surplus for pieces, meaning the amount by which each cut element will be enlarged on all sides.

For instance, if a piece is 300x200 and the surplus is set to 2, the optimizer will use a size of 304x204.

In the case of 1D materials, this applies, of course, only to the length.
surplusEditable
booldef: true
This setting determines whether the surplus can be adjusted in the piece configuration.

If set to false, any surplus specified by the piece will be disregarded and the one defined in material group will be used.
margin
lengthdef: 0
This setting determines the default margin for pieces, which is the amount by which each cut element will be reduced on all sides.

For instance, if a piece is 300x200 and the margin is set to 2, the optimizer will use 296x196.

In the case of 1D materials, this applies, of course, only to the length.
marginEditable
booldef: true
This setting determines whether the margin can be adjusted in the piece configuration.

If set to false, any margin specified by the piece will be disregarded and the one defined in material group will be used.
defaultEdging
lengthdef: 0
Specifies default edging for new stock items.
cuttingDimensions
Dimensionsenum
Piece size used for cutting
Allowed values
net

The size specified by length & width of the piece will be used.

Note that surplus and margin may be applied if they are specified.
gross

The size of the piece will be increased by the thickness of the veneers used.
mandatory2D only
Specifies what should be the piece size that will be used for cutting.
canBeVeneered
bool 2D onlydef: false
Specifies whether pieces of the material group can be veneered.
kerf
length mandatory
Specifies the size of the kerf, i.e. the width of the waste line left by the cutting device.
minEdgeDistance
object
Overrides the cutting device's minimum edge-to-cut distance for the supplied sides. An omitted side inherits the device value; an explicit 0 disables the inherited limit for that side. A StockItem may override this setting again.
Show Child Attributes
left
lengthdef: inherited
Minimum distance from the left stock edge to a parallel cut.

right
lengthdef: inherited
Minimum distance from the right stock edge to a parallel cut.

top
length 2D onlydef: inherited
Minimum distance from the top stock edge to a parallel cut.

bottom
length 2D onlydef: inherited
Minimum distance from the bottom stock edge to a parallel cut.
allowEdgeCuts
booldef: false
Specifies whether it is possible to do something that we call the “edge cutting”.

If you have 2mm to cut off and the kerf is 3mm, then you kind of have to "take off" those 2mm with just the saw blade - that's edge cutting.
It cannot be enabled when the used cutting device's minCutSize or minCutDistance is greater than zero. A positive value supplied through the legacy minCutWidth name has the same conflict because that name is an alias of minCutSize.
It requires a positive kerf; otherwise the material is rejected with material.allowEdgeCuts requires positive kerf.
An algorithm that does not support it rejects a material with allowEdgeCuts enabled, and any stock item of that material.
With allowEdgeCuts enabled, the kerf may overflow into a stock hole just as it may overflow beyond the stock edge, because a hole is no material. Without it, the kerf must stay in material, also next to a hole.
cutShift
object 2D only
Controls automatic shifting of adjacent material segments to prevent blade-overtravel damage when a perpendicular cut must extend beyond the target piece (e.g. stone cutting).
The optimizer may reserve ordinary waste between piece-bearing regions to provide clearance for blade overtravel. This can avoid an additional segment shift while preserving all configured cutting and machine limits.
Segment shifting is available only in algorithms with documented support. Select a compatible algorithm when this feature is required.
Show Child Attributes
cutExcess
length def: 0
Over-travel distance of the cutting tool measured from the nominal cut line to the blade exit point. Set to any value needed to fully separate the part. Use 0 to disable shifting.
A 0 value always resolves the total shift limit to 0, regardless of totalShiftsLimit, so no shifts are made.
Cut excess is available only with algorithms that support cut overrun; an algorithm that does not support it rejects a material with cutExcess greater than 0.
totalShiftsLimit
int def: 0
Maximum number of individual shift operations permitted for the whole stock item. Use -1 when no global limit is required.
In algorithms that support segment shifting, a negative value means unlimited: no cap is placed on the shift count, although shifts still count toward cost. A 0 or omitted value permits no shifts at all, so a positive cutExcess with no totalShiftsLimit set produces only layouts without shifts.
horizontalShiftsLimit
int def: 0
Maximum allowed shifts along the width (up or down). Set to -1 for unlimited horizontal shifts. 0 or omitted permits no horizontal shifts, following the same convention as totalShiftsLimit. Unless a machine envelope is active, a shift also needs a nonzero limit for its axis, so totalShiftsLimit: -1 with both per-axis limits omitted still yields no shifts.
verticalShiftsLimit
int def: 0
Maximum allowed shifts along the length (left or right). Set to -1 for unlimited vertical shifts. 0 or omitted permits no vertical shifts, following the same convention as totalShiftsLimit. Unless a machine envelope is active, a shift also needs a nonzero limit for its axis, so totalShiftsLimit: -1 with both per-axis limits omitted still yields no shifts.
Some algorithms additionally bound material and cuts within a configured machine envelope. While that envelope is active, only totalShiftsLimit is enforced; the per-axis limits above are not applied separately.
reuseWaste
object
It defines the criterion for qualifying waste as usable.
Usable waste is one that goes to the warehouse for later use.
A minimum length must not exceed the corresponding maximum when that maximum is set (not 0). Otherwise the material is rejected with reuseWaste: minimum shorter length exceeds maximum. or reuseWaste: minimum longer length exceeds maximum.
Enabling reuse does not require every qualifying region to be retained. With optimal edging, an edge strip may remain ordinary waste when retaining it would prevent a valid cutting layout. Other suitable remnants can still be reusable. Cut-overrun safety and machine constraints continue to apply.
Show Child Attributes
enabled
booldef: true
Enables or disables generation of reusable waste. If disabled, the entire unused material is treated as waste.

minLongerLength
lengthdef: 200
The minimum size of the longer dimension that qualifies the waste as usable.

minShorterLength
length 2D onlydef: 200
The minimum size of the shorter dimension that qualifies the waste as usable.

maxLongerLength
lengthdef: 0
The maximum size of the longer dimension that qualifies the waste as usable. Use 0 for no upper limit.

maxShorterLength
length 2D onlydef: 0
The maximum size of the shorter dimension that qualifies the waste as usable. Use 0 for no upper limit.

prefLongerLength
lengthdef: 600
The preferred size of the longer dimension that qualifies the waste as usable.

prefShorterLength
length 2D onlydef: 600
The preferred size of the shorter dimension that qualifies the waste as usable.

expectedUsage
percent
Expected usable share of a reusable waste area (for example, 65 or "65%" means about 65% of the area will be used in the future). Helps decide whether it is more cost-effective to generate reusable waste or use the area immediately; this value is used in cost optimization.

edging
object
Specified default edging for the waste that was qualified as usable.

Show Child Attributes
enabled
booldef: false
Enables or disables setting the edging to the StockItem created from the usable waste.

default
lengthdef: 0
The default edging size. Note that edging will be applied to all edges of the new StockItem.
stackCutting
object
It defines the stack cutting rules.
Stack cutting is available only with algorithms that support it. A material with stack cutting enabled is rejected by an algorithm that does not support it.
Show Child Attributes
enabled
booldef: false
Enables or disables stack cutting.

defStackSize
int def: 1
The default stack size. Note that stack cutting applies only to stock items with standard dimensions.

An unsigned integer. A negative value is rejected with stackCutting.defStackSize: expected an integer within the Cardinal range. When stack cutting is enabled, zero is rejected with stackCutting: sizes must be positive and minimum must not exceed default.
weightOfSqM
weight 2D onlydef: 0
Weight of a square meter of the material.

Weight values are used directly in cost calculations, including utilizationCostPerKg. If the provided weight is inaccurate or left at default, disposal and waste-related cost optimization results will also be inaccurate.
weightOfMeter
weight 1D onlydef: 0
Weight of a meter of the material.

Weight values are used directly in cost calculations, including utilizationCostPerKg. If the provided weight is inaccurate or left at default, disposal and waste-related cost optimization results will also be inaccurate.
costs
object
Defines cost parameters for cost-based optimization. See cmdAddJob's bestSolutionCriterion input parameter for more details.
Available only with Enterprise license!
Accurate cost values are essential for generating meaningful optimization results. Cost parameters may be defined on multiple levels - Device, Material, Piece, and StockItem. If these values are incomplete, inconsistent, or significantly inaccurate, the optimization engine will inevitably reflect these issues in its output. To ensure reliable and realistic results, verify that all relevant cost fields are correctly provided and aligned with actual production and operational conditions.
Show Child Attributes
pricePerSqM
price 2D onlydef: 0
The price of a square meter of the material.

pricePerMeter
price 1D onlydef: 0
The price of a meter of the material.

priceToCostMultiplier
float
Used in cost optimization together with reuseWaste.expectedUsage to estimate the assumed revenue from reusable waste. It affects the decision whether it is more cost-effective to generate reusable waste or to use the material immediately.

cutCostPerMeter
pricedef: 0
Cost per meter for cutting operations.

This cost is added to the Device’s cutCostPerMeter. It does not override the Device’s value.
reuseCost
pricedef: 0
This property defines the cost of handling reusable waste. For example, it represents the cost to move the reusable waste back to the warehouse.

This cost is added to the Device’s reuseCost. It does not override the Device’s value.
utilizationCostPerKg
pricedef: 0
Specifies the cost per kilogram for waste disposal, covering expenses for collection, transport, and processing of waste material.

This cost is added to the Device’s utilizationCostPerKg. It does not override the Device’s value.
segmentShiftCost
pricedef: 0
This property represents the additional cost incurred when a material segment must be shifted to avoid damage during a perpendicular cut. For example, in stone cutting the blade may need to extend beyond the target piece to complete a cut, requiring adjacent pieces to be repositioned by a distance determined by the blade’s diameter and the material’s thickness.

This cost is added to the Device’s segmentShiftCost. It does not override the Device’s value.
segmentRotationCost
pricedef: 0
This property specifies the additional cost incurred when rotating a material segment for a perpendicular cut. For example, if the cutting machine’s blade moves in only one direction, the segment must be rotated by 90° to perform the cut.

This cost is added to the Device’s segmentRotationCost. It does not override the Device’s value.
standardStockItems
list(StandardStockItem)
The list of standardStockItems for the material group.
algorithmData
object
Optional opaque algorithm-specific data for this material. Its contents are implementation-defined and are not part of the public API contract.
Supply algorithmData only through an integration-specific contract.
Available only with Enterprise license! Without it the property is ignored.
customData
any
Custom data that will be directly passed to customData.material property in Cutting.
It can be any JSON compatible data, for example: { "myId": "932422" }, "932422", or 932422.
Available only with Enterprise license!

{
  "materials": [
    {
      "deviceId": 1,
      "title": "Material 1D",
      "kind": "1d",
      "width": 100,
      "thickness": 100,
      "canRotate": true,
      "canMirror": true,
      "surplus": 0,
      "surplusEditable": true,
      "margin": 0,
      "marginEditable": true,
      "defaultEdging": 0,
      "kerf": 0,
      "allowEdgeCuts": true,
      "reuseWaste": {
          "minLongerLength": 200,
          "maxLongerLength": 0,
          "edging": {
            "enabled": false,
            "default": 0
          }
      },
      "canBeVeneered": true,
      "id": 3
    }
  ]
}

Veneer

The Veneer object specifies characteristics of a veneer.

Attributes

id
int mandatory
Unique id of the veneer.
title
string mandatory
Title of the veneer.
width
length mandatory
Width of the veneer.
thickness
length mandatory
Thickness of the veneer.
surplus
length def: 0
The surplus is automatically added when the demand for the amount of veneer is calculated. Please note that the surplus is added twice.
maxMaterialThickness
length mandatory
The maximum thickness of the material for which this veneer can be used.

2D input

{
"veneers": [
    {
      "title": "Oak",
      "width": 22,
      "thickness": 1.5,
      "maxMaterialThickness": 18,
      "id": 1
    }
  ]
}

Piece

The Piece object describes piece.

Attributes

id
int mandatory
Unique piece id.
materialId
int mandatory
The ID of the material group from which this piece will be cut.
identifier
string
The user defined identifier of the piece. It must be Code128 barcode compatible.
color
string
Color of the piece.
description
string
Description of the piece.
length
length mandatory
The net length of the piece.

Keep in mind that for 1D shapes, it is always the total length, including slants:
width
length mandatory 2D only
The net width of the piece.
shapeType
ShapeTypeenum
Shape of the piece
Allowed values
none

No shape, the same as rectangle.
rectangle

Just rectangle, so no additional shape definition is necessary.
linear

1D shape with slants. The shape property contains slant values.
any

Any shape. You can define any shape using the shape property - convex or concave, or even with holes.
slantRect

Rectangle with one slanted corner.
L

L-shaped piece.
rightTriangle

Right triangle.
slopeRect

Rectangle with one sloped edge.
trapezoid

Trapezoid shape.
octagon

Octagonal shape.
ellipse

Elliptical shape.
circle

Circular shape.
ring

Ring shape (circular with a hole).
def: none
Type of the shape of the piece.
shape
object
Depending on shapeType it may contain different format. See Shapes for more information.
rotationStep
angledef: 30°
Specifies the rotation step. For instance, if it is set to 90, the piece can be rotated only by 0, 90, 180, or 270 degrees.
rotation
angledef: 0°
Specifies the initial rotation of the piece. It is useful when you want to have some pieces rotated by default.
mirror
booldef: false
Specifies whether the piece is mirrored (back to front).
quantity
int mandatory
Specifies quantity of pieces.
structure
Structuresset
Structure of the piece
Allowed values
none

The material has no structure.
byLength

The structure is horizontal (along length).
byWidth

The structure is vertical (along width).
2D onlydef: [none,byLength,byWidth]
Specifies acceptable structures of the piece.
Usually you want to specify only one value here, e.g. byLength.

But, sometimes you don’t care what structure a piece will have – then you can set it to “none,byLength,byWidth”.
Structures are matched between the piece and the StockItem it is placed on.

A stock item without a structure accepts only pieces whose set contains none, and such pieces may be placed in any orientation. In true-shape algorithms, free rotation on such stock additionally requires canRotate of the Material.

A stock item with a structure accepts only pieces whose set contains byLength or byWidth. A piece that accepts both may be placed in either orientation. A piece that accepts only one of them is placed in the single orientation that aligns it with the structure of the stock item, and it is never turned across that structure in order to fit.
priority
int def: 1
Priority of the piece. It can be any positive integer number. TonCut will use higher-priority pieces even if they cause larger waste.
The priority can also be expressed as a string, where:
- normal corresponds to priority 1.
- high corresponds to priority 10.
- critical corresponds to priority 100.
- auto means the priority is derived by the engine.
In cost-based optimization, priority guides piece placement and may contribute implementation-defined utility to the score used to compare solutions. This utility is not cash revenue. Under every other bestSolutionCriterion, priority also affects that ranking: pieces are grouped by priority tier (normal, high, critical), and how completely each tier's demand is placed contributes to a solution's rank, so completing more high- or critical-priority pieces produces a better-ranked solution even at the cost of more waste.
group
int def: 0
Identifier of the destination rack (or pallet) for the piece. The optimizer is free to mix and interleave cuts from different groups in any sequence; only the order rule (see below) must be respected within each individual group. Group 0 is fully unrestricted: pieces assigned to it may be cut at any moment, in any order, and can break the internal ordering rules that apply to the other groups.
The value must be within the WORD range (0...65535).
Order groups are available only with algorithms that sequence them. A piece whose material uses an algorithm without that support is rejected if its group or order is not 0. Set both to 0 (or omit them), or assign the material to an algorithm that sequences order groups.
order
int def: 0
In-group cutting priority. The value must be within the WORD range (0...65535). For every non-zero group, pieces with a lower order value must leave the cutting line before pieces with a higher value in the same group. If several pieces share the same order, their relative sequence is unconstrained as long as they all precede higher numbers and follow lower numbers in that group. This property is ignored for pieces in group 0.
The value must be within the WORD range (0...65535).
Cross-group deadlock risk: Certain combinations of order values across different groups can create circular dependencies (e.g. group 1 needs order=2 cut before group 2’s order=1, while group 2 simultaneously requires the reverse), preventing some pieces from ever being scheduled. Validate order sequences to ensure that no such deadlocks exist.
costs
object
Defines cost parameters for cost-based optimization. See cmdAddJob's bestSolutionCriterion input parameter for more details.
Available only with Enterprise license!
Accurate cost values are essential for generating meaningful optimization results. Cost parameters may be defined on multiple levels - Device, Material, Piece, and StockItem. If these values are incomplete, inconsistent, or significantly inaccurate, the optimization engine will inevitably reflect these issues in its output. To ensure reliable and realistic results, verify that all relevant cost fields are correctly provided and aligned with actual production and operational conditions.
Show Child Attributes
sellingPrice
pricedef: 0
The selling price of the piece.

storageCost
pricedef: 0
The cost of storing the piece in the warehouse.
surplus
lengthdef: 0
Specifies the surplus, meaning the amount by which the piece size will be enlarged on all sides.

For instance, if a piece is 300x200 and the surplus is set to 2, the optimizer will use a size of 304x204.

In the case of 1D materials, this applies, of course, only to the length.
margin
lengthdef: 0
Specifies the margin, which is the amount by which the piece size will be reduced on all sides.

For instance, if a piece is 300x200 and the margin is set to 2, the optimizer will use 296x196.

In the case of 1D materials, this applies, of course, only to the length.
veneers
object 2D only
Specifies which veneers should be used.
This parameter is only used if the shapeType is specified as none or rectangle and the material group allows veneering (i.e. its canBeVeneered property is set to true).
If shapeType is set to rectangle, the veneers specified here will override the veneers in shape definition!
Show Child Attributes
leftVeneerId
int
ID of the veneer to be used on the left edge.

rightVeneerId
int
ID of the veneer to be used on the right edge.

topVeneerId
int
ID of the veneer to be used on the top edge.

bottomVeneerId
int
ID of the veneer to be used on the bottom edge.
weight
float
Optional relative importance of the piece when the optimizer weighs the area it places. It is a dimensionless factor, not a mass. It must be a finite number that is not negative; a negative value is rejected. An explicit 0 behaves as if the property were omitted. When omitted, the engine derives it from the piece's area.
weight is not the same as priority. How it influences the result is implementation-defined.
weightModifier
floatdef: 1
Multiplier applied to the piece's weight. It must be a finite number that is not negative; a negative value is rejected. 0 means that the piece does not contribute to the weighted area.
previewColor
stringdef: none
Color used when this piece is drawn in a preview. One of:
- "#rrggbb" - a hexadecimal RGB color, for example "#ff8800"; exactly six hexadecimal digits after #, letters in either case.
- "none" - no preview color is assigned (the default).
- "random" - a stable color derived from the piece id is used.
The keywords none and random are matched case-insensitively. The value does not influence optimization in any way.
The value must be a JSON string. A JSON number is rejected, like any other string that is not a valid color, with previewColor: expected color in #rrggbb form, "none", or "random".; a boolean, object, array or null is rejected with previewColor: expected a color string.
algorithmData
object
Optional opaque algorithm-specific data for this piece. Its contents are implementation-defined and are not part of the public API contract.
Supply algorithmData only through an integration-specific contract.
Available only with Enterprise license! Without it the property is ignored.
customData
any
Custom data that will be directly passed to customData property in ResultPiece.
It can be any JSON compatible data, for example: { "myId": "932422" }, "932422", or 932422.
Available only with Enterprise license!

{
  "pieces": [
    {
      "materialId": 3,
      "identifier": "",
      "length": 500,
      "shapeType": "linear",
      "quantity": 15,
      "priority": "normal",
      "description": "",
      "surplus": 0,
      "margin": 0,
      "shape": {
          "leftAngle": 45,
          "rightAngle": 25
      },
      "id": 1
    },
    {
      "materialId": 3,
      "identifier": "",
      "length": 532,
      "shapeType": "linear",
      "quantity": 12,
      "priority": "normal",
      "description": "",
      "surplus": 0,
      "margin": 0,
      "shape": {
          "leftAngle": 35,
          "rightAngle": -25
      },
      "id": 2
    }
  ]
}

StockItem

The StockItem object describes a StockItem.

Attributes

id
int mandatory
Unique StockItem id.
materialId
int mandatory
The ID of the material group the StockItem is made from.
identifier
string
The user defined identifier of the StockItem.
It must be Code128 barcode compatible.
description
string
Description of the StockItem.
priority
int def: 10
Priority of the StockItem, an integer from 0 to 100. Higher values mean the StockItem is consumed earlier.
The priority can also be expressed as a string, where:
- low corresponds to priority 0.
- normal corresponds to priority 10 (the default).
Unlike piece priority, high and critical are not valid StockItem priority labels; use a numeric value above 10 instead.
A numeric value outside [0, 100] is rejected with stock N: priority must be within [0, 100]. (N is the StockItem id); a string that is not one of the named labels (for example "high") is rejected with priority: unknown enum value "high".; a value that is neither a number nor a string is rejected with stock.priority must be an integer or named priority.
Priority is soft: it never forces a stock order by itself. Stock is ordered by the selected stock-order strategy's own criteria, and priority breaks only an exact tie between stock items that are otherwise equal under that strategy. Independently of ordering, the solution score also receives a bonus or penalty relative to normal priority, bounded so it can only decide between otherwise-close layouts - in price-less input, where there is no financial score to adjust, it therefore only breaks ties. Leaving every StockItem's priority at the default 10 does not change optimization results.
If every StockItem in an input shares the same non-default priority (for example, every StockItem is low, which is common in real inputs), the score adjustment still applies to every sheet: no StockItem is preferred over another, but the adjustment itself shifts every sheet's score by the same bounded amount, so the finished result can still differ from an older engine version or from an equivalent input that instead leaves every StockItem at the default priority. To reproduce the previous, unadjusted behaviour, leave priority at its default (10, normal) for every StockItem.
This replaces the previous low/normal StockItem priority, and two behaviours changed as a result. low-priority stock is no longer strictly tried after all normal-priority stock - it is used whenever doing so otherwise produces a better-scoring layout. And a low-priority sheet with a negative score (material cost without piece income) is no longer preferred over normal-priority stock; older engine versions could prefer it in that case.
length
length mandatory
Length of the StockItem.
width
length mandatory 2D only
Width of the StockItem.
quantity
int mandatory
If stack cutting is enabled for the Material, it specifies the quantity of stacks. Otherwise, it indicates the quantity of stock items.

The meaning of the quantity property varies depending on whether stack cutting is enabled or disabled.
stackSize
int
The stack size. Note that stack cutting applies only to stock items with standard dimensions.

Applies only to material groups with enabled stack cutting. See the stackCutting property of the Material data object.
structure
Structureenum
Structure of the StockItem
Allowed values
none

The material has no structure.
byLength

The structure is horizontal (along the length).
byWidth

The structure is vertical (along the width).
2D onlydef: none
Specifies the structure of the StockItem.
edging
object
Edging configuration.
Show Child Attributes
left
lengthdef: 0
The size of the edge to be cut off on the left side of the StockItem.

right
lengthdef: 0
The size of the edge to be cut off on the right side of the StockItem.

top
length 2D onlydef: 0
The size of the edge to be cut off on the top of the StockItem.

bottom
length 2D onlydef: 0
The size of the edge to be cut off on the bottom of the StockItem.
minEdgeDistance
object
Overrides the material or device minimum edge-to-cut distance for the supplied sides. An omitted side inherits the material or device value; an explicit 0 disables the inherited limit for that side.
minEdgeDistance controls where a cut may be placed, while edging reserves an unusable material band. Do not set both to a positive value on the same side.
Show Child Attributes
left
lengthdef: inherited
Minimum distance from the left edge to a parallel cut.

right
lengthdef: inherited
Minimum distance from the right edge to a parallel cut.

top
length 2D onlydef: inherited
Minimum distance from the top edge to a parallel cut.

bottom
length 2D onlydef: inherited
Minimum distance from the bottom edge to a parallel cut.
cutShift
object 2D only
Controls automatic shifting of adjacent material segments to prevent blade-overtravel damage when a perpendicular cut must extend beyond the target piece (e.g. stone cutting).
Segment shifting is available only in algorithms with documented support. Select a compatible algorithm when this feature is required.
Show Child Attributes
horizontalShiftsLimit
int def: -1
Maximum allowed shifts along the width (up or down). Set to -1 for default material's limit of horizontal shifts.
verticalShiftsLimit
int def: -1
Maximum allowed shifts along the length (left or right). Set to -1 for default material's limit of vertical shifts.
A negative value (including the default -1) or an omitted field inherits the Material's effective limit for that axis; the material's own 0-or-absent-means-no-shift and negative-means-unlimited convention then applies. A value of 0 allows no shifts on that axis, even if the material allows them. While a configured machine envelope is active for the selected algorithm, only the material's totalShiftsLimit is enforced and these per-axis limits do not apply separately.
defects
list(Defect)
Defines the list of defects: damaged parts of the stock, such as a scratch. A defect is still material. It counts toward the stock's material area, it can be cut through, and it can end up in waste or in reusable waste. The optimizer only avoids placing a piece on it.
Defect support depends on the selected cutting method. For automatic rectangular cutting, method selection takes each stock item's defects into account. An explicitly selected method must support the supplied defects. An automatic cutting method that does not support defects rejects stock with a non-empty defects list at load instead of ignoring it.
holes
list(Hole)
Defines rectangular voids where the stock contains no material. The stock already comes with them; the engine never creates holes. Unlike defects, a hole is not material: there is nothing to cut, it is not waste, and it is neither usable nor available area. The stock's material area excludes its holes.
Holes are supported by a limited set of cutting methods (for example, to describe stepped or stair-shaped stock), so an explicitly selected method must support them.
Nothing is cut in a hole. Cuts end at a hole edge, the cut length and cutting cost count only the parts of a cut that pass through material, and a hole edge is not a cut. The kerf may overflow into a hole only when the material's allowEdgeCuts is enabled.
costs
object
Defines cost parameters for cost-based optimization. See cmdAddJob's bestSolutionCriterion input parameter for more details.
Available only with Enterprise license!
Accurate cost values are essential for generating meaningful optimization results. Cost parameters may be defined on multiple levels - Device, Material, Piece, and StockItem. If these values are incomplete, inconsistent, or significantly inaccurate, the optimization engine will inevitably reflect these issues in its output. To ensure reliable and realistic results, verify that all relevant cost fields are correctly provided and aligned with actual production and operational conditions.
Show Child Attributes
extractionCost
pricedef: 0
Cost of extracting the stock item from the warehouse.

pricePerSqM
price
This StockItem's own price per square metre, overriding the Material's costs.pricePerSqM for this stock item only. When the field is absent, the Material's costs.pricePerSqM applies instead (0 if the Material declares none either). An explicit 0 is a valid price of its own, distinct from leaving the field absent.
The value must be finite and >= 0; an explicit 0 is accepted. A negative number is rejected with stock N: costs.pricePerSqM must be a finite nonnegative price. (N is the StockItem id); a value that is not a number, null, or not finite (e.g. NaN/Infinity) is rejected as an input error as well.
Read under the same license edition as the other costs fields on this object.
Two StockItems that are otherwise identical but differ in their own pricePerSqM are no longer considered the same stock.
algorithmData
object
Optional opaque algorithm-specific data for this stock item. Its contents are implementation-defined and are not part of the public API contract.
Supply algorithmData only through an integration-specific contract.
Available only with Enterprise license! Without it the property is ignored.
customData
any
Custom data that will be directly passed to customData.stock property in Cutting.
It can be any JSON compatible data, for example: { "myId": "932422" }, "932422", or 932422.
Available only with Enterprise license!

{
  "stock": [
    {
      "materialId": 3,
      "identifier": "",
      "description": "",
      "priority": "normal",
      "length": 6000,
      "quantity": 10,
      "edging": {
          "left": 0,
          "right": 0
      },
      "id": 2
    }
  ]
}

Defect

This object describes location of stock item's defect, a damaged part of the material. A defect is still material, unlike a Hole.

Attributes

Defect and hole rectangles of a StockItem are checked when it is loaded: x and y must not be negative, length and width must be greater than zero, and the rectangle must lie inside the stock item.

x
length
X-coordinate of the defect’s upper-left corner, measured from the stock origin (0 mm, 0 mm) along the primary length (X) axis.
y
length
Y-coordinate of the defect’s upper-left corner, measured from the stock origin along the width (Y) axis.
length
length mandatory
Horizontal extent of the defect parallel to the X axis. It must be positive.
width
length mandatory
Vertical extent of the defect parallel to the Y axis. It must be positive.

{
  "stock": [
    {
      "id": 2,
      "materialId": 1,
      "quantity": 1,
      "edging": {
        "left": 15,
        "right": 15,
        "top": 15,
        "bottom": 15
      },
      "defects": [
        {
          "x": 250,
          "y": 480,
          "length": 100,
          "width": 150
        },
        {
          "x": 1350,
          "y": 100,
          "length": 150,
          "width": 100
        }
      ]
    }
  ]
}

Hole

A Hole object describes a rectangular area where material is absent. It is used for holes in a StockItem and for holes in a Waste item. A hole is not a defect: it is no material at all, so it is not waste and not usable area. The stock comes with its holes; the engine never creates them. Nothing is cut in a hole: cuts end at a hole edge, cut length and cost count only material, and a hole edge is not a cut. minEdgeDistance applies at a hole edge as at a sheet edge, using the margin of the side the hole edge stands in for: a hole edge with material below it acts as a top edge, one with material to its right as a left edge. With allowEdgeCuts enabled the kerf may overflow into a hole as it may beyond the stock edge; without it the kerf stays in material.

Attributes

x
length
X-coordinate of the hole's upper-left corner, relative to the containing stock or waste item.
y
length
Y-coordinate of the hole's upper-left corner, relative to the containing stock or waste item.
length
length mandatory
Horizontal extent of the hole parallel to the X axis. It must be positive.
width
length mandatory
Vertical extent of the hole parallel to the Y axis. It must be positive.

Hole object

{
  "x": 0,
  "y": 0,
  "length": 1500,
  "width": 160
}

ResultPiece

This object describes location and transformation of a piece that was placed on a cutting.

Normally you don't have to know how the shapes are transformed, as we are providing the shape property, which is already transformed. But, just in case it is needed for whatever reason, here is how the transformation works.

Here is how 2D piece is positioned depending on its rotation:

Linear pieces are positioned in a different way.

The order of transormation is:

Rotation - rotation is done around the origin point [0, 0] of the shape.
Mirror - a flip around the Y axis. - the Y coordinates are simply multiplied by -1.
Translation - the shape is moved to its target position, so its [0, 0] is placed on [x, y] position.

Attributes

pieceId
int
ID of the piece.
x
length
X position of the piece.
y
length
Y position of the piece.
rotation
angle
Specifies the rotation angle of the piece.
Note that in previous versions of the JSON format (older than 3), we had rotated boolean property instead. The way the pieces are transformed is different for 1D and 2D materials.
For 1D materials, it is easy. The piece may be rotated by 0° or 180°. If it is rotated, the rotation property will be 180°, otherwise it will be 0°. It works like before.
But, for 2D materials, it is different now. The rotation is always done around the origin point of the piece.
See also the transformation order above.
mirrored
bool
Specifies if the piece was reversed (back to front). It is present for 1D pieces only, always, with the value true or false; a 2D piece does not carry it.
See also the transformation order above.
shape
string
The shape of the piece after rotation and mirror transformations were applied. See Shapes for more information.
The shape is in SVG path format.
bbox
object
The bounding box of the piece including all modificators: net/gross dimensions, surplus and margin.
Show Child Attributes
length
length
Cutting length of the piece.

width
length
Cutting width of the piece.
customData
any
Custom data passed directly from customData property in Piece.
Available only with Enterprise license!

{
  "pieces": [
    {
      "pieceId": 6667,
      "x": 1300,
      "y": 0,
      "rotation": "1.570796rad",
      "shape": "M0,0 L-0.00131134164985269,30000 L-80000,70000 L-130000,69999.9921875 L-130000,-0.00568248052150011 Z ",
      "bbox": {
        "length": 700,
        "width": 1300
      }
    },
    {
      "pieceId": 6670,
      "x": 2800,
      "y": 900,
      "rotation": "1.570796rad",
      "shape": "M-0.00262268329970539,-60000 L-0.00393402483314276,-90000 L-150000,-89999.9921875 L-150000,0.00655670836567879 L-100000,0.0043711387552321 L-100000,-59999.99609375 Z ",
      "bbox": {
        "length": 900,
        "width": 1500
      }
    },
    {
      "pieceId": 6666,
      "x": 2310,
      "y": 1800,
      "rotation": "0.000000rad",
      "shape": "M0,-100000 L60000,0 L90000,0 L90000,-150000 L0,-150000 Z ",
      "bbox": {
        "length": 900,
        "width": 1500
      }
    },
    {
      "pieceId": 665,
      "x": -4.42,
      "y": 1417.75,
      "rotation": "4.188790rad",
      "shape": "M72320.5859375,-58362.36328125 C63717.1640625,-64595.515625 54200.72265625,-73008.265625 42865.37890625,-71523.7734375 C31492.857421875,-69766.4921875 37802.3359375,-58001.359375 37480.4765625,-50425.95703125 C38450.70703125,-41511.05078125 34132.85546875,-31447.298828125 24676.423828125,-29281.689453125 C11102.244140625,-26010.267578125 -296.594482421875,-11591.1982421875 4614.576171875,2547.31372070313 C8271.796875,15577.7431640625 26787.5546875,17550.5 35676.83203125,9118.0263671875 C42448.734375,3642.40747070313 43353.92578125,-5358.4677734375 47301.01171875,-12560.7255859375 C52277.515625,-21167.947265625 65848.2109375,-21490.744140625 71991.9609375,-13645.4453125 C78732.515625,-6508.025390625 76769.890625,3872.63452148438 78216.8671875,12672.03125 C79421.109375,25375.65625 81635.1171875,40010.51171875 92448.109375,48497.22265625 C103825.0703125,55355.390625 118195.828125,46930.125 123328.3046875,36329.72265625 C128114.015625,28401.912109375 127719.8828125,15187.5263671875 118086.796875,10779.84375 C109521.046875,6886.07080078125 99087.84375,11533.6533203125 91097.484375,6066.517578125 C85168.9140625,-692.234680175781 89955.2109375,-12109.86328125 98019.25,-14667.6982421875 C111201.8125,-19536.3046875 129202.59375,-14629.009765625 134765.4375,-683.946472167969 C140619.4375,13652.93359375 130403.625,29531.4453125 137785.875,43627.9609375 C142208.09375,51624.71875 153718.796875,50439.359375 159879.953125,45444.82421875 C166528.421875,40148.09375 170356.359375,32232.294921875 175212.390625,25421.6953125 C181935.078125,15316.5537109375 185048.109375,2281.75854492188 180305.34375,-9436.4384765625 C173518.734375,-29034.017578125 149651.890625,-41900.5078125 129873.7890625,-34403.33203125 C117298.859375,-30476.994140625 104641.4140625,-21479.12109375 90828.1328125,-25998.80859375 C81448.5078125,-29111.390625 80203,-41287.67578125 84438.71875,-48771.359375 C91572.8671875,-62191.078125 110681.859375,-64337.9609375 116352.578125,-78976.3828125 C119918.59375,-86067.2890625 113968.6640625,-94399.546875 106439.6640625,-95336.203125 C96650.765625,-97803.5625 86575.84375,-90378.5390625 85334.5,-80733.1875 C83879.5546875,-73600.7109375 86524.0390625,-64013.8359375 79622.2734375,-59202 C77376.0859375,-57919.0625 74790.234375,-57302.75 72320.59375,-58362.36328125 Z ",
      "bbox": {
        "length": 1408.99,
        "width": 1666.61
      }
    }
  ]
}

Waste

The Waste object describes a waste item.

Attributes

x
length
X position of the waste.
y
length
Y position of the waste.
length
length
Length of the waste.
width
length
Width of the waste.
holes
list(Hole)
Optional rectangular voids within the waste item's bounding rectangle. These are holes carried over from the stock; they hold no material, so they are not waste. Hole coordinates are relative to the waste item's x and y position. The waste area excludes these holes. Present only when usable is true.
defects
list(Defect)
Optional defects associated with this waste item. A defect is damaged material that remained inside the waste item, so it is part of its area. Present only when usable is true.
identifier
string
Automatically generated identifier string.
usable
bool
Specifies whether the waste is usable.
shapeType
ShapeTypeenum
Shape of the waste
Allowed values
none

No shape, the same as rectangle.
rectangle

Just rectangle, so no additional shape definition is necessary.
linear

1D shape with slants. The shape CustomProperty contains slant values.
Optional type of the shape of the waste.
shape
object
Optional shape details whose format depends on shapeType.

For the moment only LinearShape is supported.

{
  "rest": [
    {
      "x": 0,
      "y": 0,
      "length": 0,
      "width": 100,
      "shapeType": "linear",
      "shape": {
          "leftAngle": "0.00rad",
          "rightAngle": "0.00rad"
      },
      "identifier": "",
      "usable": false
    },
    {
      "x": 5952.8,
      "y": 0,
      "length": 74,
      "width": 100,
      "shapeType": "linear",
      "shape": {
          "leftAngle": "0.26rad",
          "rightAngle": "0.00rad"
      },
      "identifier": "",
      "usable": false
    }
  ]
}

Cut

Cut object describes a cut to be made.

Cuts may be straight line segments or cubic Bézier curves.

Attributes

type
CutTypeenum
Type of the cut
Allowed values
line

A straight cut segment between two points.
curve

A cubic bezier curve cut between two points with two control points.
Type of the cut.
startX
length
Start X position of the cut.
startY
length
Start Y position of the cut.
endX
length
End X position of the cut.
endY
length
End Y position of the cut.
startXp
length
First control point's X position for cubic bezier curve.
startYp
length
First control point's Y position for cubic bezier curve.
endXp
length
Second control point's X position for cubic bezier curve.
endYp
length
Second control point's Y position for cubic bezier curve.
needShift
bool
Marks this cut as the governing boundary for one segment motion. At the start of this event, after earlier governing motions, the cut line is evaluated against the blade-reach limits before this event's own motion. The affected material is then displaced at this boundary before overrun safety and the post-event material state are evaluated. May be set to true only when the Material option cutShift.cutExcess is greater than 0.
Segment shifting is available only in algorithms with documented support. Select a compatible algorithm when this feature is required.
shiftDistance
length
Complete movement commanded at this cut's governing boundary, including any case-2 contributions folded into this event. The value is 0 when needShift is false.
Segment shifting is available only in algorithms with documented support. Select a compatible algorithm when this feature is required.

{
  "cuts": [
    {
      "type": "line",
      "startX": 820,
      "startY": 0,
      "endX": 793.2,
      "endY": 100,
      "needShift": false,
      "shiftDistance": 0
    },
    {
      "type": "line",
      "startX": 1613.2,
      "startY": 0,
      "endX": 1613.2,
      "endY": 100,
      "needShift": false,
      "shiftDistance": 0
    },
    {
      "type": "line",
      "startX": 2433.2,
      "startY": 0,
      "endX": 2406.4,
      "endY": 100,
      "needShift": false,
      "shiftDistance": 0
    },
    {
      "type": "line",
      "startX": 3226.4,
      "startY": 0,
      "endX": 3226.4,
      "endY": 100,
      "needShift": false,
      "shiftDistance": 0
    }
  ]
}

Cutting

The Cutting object describes single cutting.

Attributes

stockItemId
int mandatory
ID of the StockItem for which this cut is made.
quantity
int mandatory
If stack cutting is enabled for the material, it indicates the number of stacks the cutting should be performed for. Otherwise, it indicates the number of times the cutting should be performed.
The meaning of the quantity property varies depending on whether stack cutting is enabled or disabled.
stackSize
int
Optional. If stack cutting is enabled for the material, it indicates the size of a single stack.
statistics
object mandatory
Statistics of the entire cutting.
Show Child Attributes
2d
object
Contains cutting's statistics if the material type is 2D.

This block is written only for 2D materials. A 1D cutting has only the 1d block, which has no edging or kerf waste fields.
Show Child Attributes
field
field
The material area of all used stock items: the stock area without its holes, which hold no material.
If a cutting is invalid against the holes (a rectangular piece over a hole, or used plus usable area larger than the material), the engine logs an error and reports that cutting's statistics with gross figures: the full stock area, with the unused and waste areas counted over the whole stock. The invalid layout is penalised in the ranking.
usedField
field
The total surface area of all used pieces.

wasteField
field
The total waste area of the stock's material, so stock holes are not counted. Kerf, edging, and technological waste remain included.
field = usedField + wasteField + unusedField.
unusedField
field
The total surface area of usable waste. Only material is counted; a hole inside a usable waste item is not.
technologicalWasteField
field
The waste area attributed to technological allowances.

edgingWasteField
field
The waste area attributed to stock edging.

Excludes edging that lies over a stock hole inside a plain waste item (there is no material there), so this value is at most wasteField. Exception: a shaped 1D trim waste keeps its exact edging even where it overlaps a hole, so it can overstate this field only by the area inside that hole.
A value an algorithm supplies for this field directly is reported as given.
kerfWasteField
field
The waste area removed by cutting kerfs.

Excludes kerf that runs through a stock hole (there is no material there), so this value is at most wasteField. Exception: a slanted 1D cut keeps its full kerf even where it crosses a hole, so it can overstate this field only by the area inside that hole.
A value an algorithm supplies for this field directly is reported as given.
cutCount
int
The number of cuts.

cutsLength
length
The total length of all the cuts.

1d
object
Contains cutting's statistics if the material type is 1D.

Show Child Attributes
length
length
The material length of all used stock items: the bar length without its holes.

usedLength
length
The total length of all used pieces.

wasteLength
length
The total waste length.

Counts material only, so stock holes are excluded as in the 2D wasteField; without stock holes this has no effect.
unusedLength
length
The total length of usable waste.

cutCount
int
The number of cuts.

cutsLength
length
The total length of all the cuts.
pieces
list(ResultPiece) mandatory
A list of all pieces placed on the cutting, including their positions and transformations.
rest
list(Waste) mandatory
A list of all Waste items, including their positions and sizes.
cuts
list(Cut) mandatory
A list of Cut objects.
cost
price
Total estimated production cost for this cutting, calculated from the Device, Material and StockItem costs parameters (machine time, tool wear, material price, etc.).
Available only with Enterprise license!
income
price
Total selling income for the pieces placed in this cutting, before subtracting cost.
Available only with Enterprise license!
gain
price
Total profit for this cutting, defined as income minus cost. When cost-based optimisation is enabled, solutions are ranked by the highest positive gain.
Available only with Enterprise license!
score
price
Final optimization score for this cutting, written like cost, income and gain. The score is intended for comparing results; its calculation is implementation-defined.
Available only with Enterprise license!
customData
object
Opaque application-defined data propagated from the input. The engine does not interpret its contents. The whole object is omitted when all three entries below are empty.
Available only with Enterprise license!
Show Child Attributes
device
any
The input customData of the Device the cutting used.

material
any
The input customData of the Material the cutting used.

stock
any
The input customData of the StockItem the cutting used.

{
  "cuttings": [
    {
      "stockItemId": 2,
      "quantity": 3,
      "cost": 0,
      "income": 0,
      "gain": 0,
      "score": 0,
      "statistics": {
        "1d": {
          "length": 6000,
          "usedLength": 5939.4,
          "wasteLength": 60.6,
          "unusedLength": 0,
          "cutCount": 8,
          "cutsLength": 817.64466576987
        }
      },
      // ...
    }
  ]
}

Data Objects

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Directionenum

fromLarge

fromSmall

random

allPermutations

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

searchDirectionenum

byLength

byWidth

auto

Show Child Attributes

Profile object

MaterialKindenum

1d

2d

Show Child Attributes

LeftMeasurementenum

fromMiddleToLeft

fromMiddleToRight

fromLeft

fromRight

RightMeasurementenum

fromMiddleToLeft

fromMiddleToRight

fromLeft

fromRight

StripCuttingenum

none

byLength

byWidth

Show Child Attributes

EdgingCutsenum

optimal

horizontalFirst

verticalFirst

OriginEdgingCutsenum

default

twoFullCuts

CutDirectionenum

horizontal

vertical

any

Show Child Attributes

Show Child Attributes

Show Child Attributes

Show Child Attributes

Structuresset

none

byLength

byWidth

Show Child Attributes

MaterialKindenum

1d

2d

QualityLevelenum

precission

compromise

speed

`Direction`enum

`fromLarge`

`fromSmall`

`random`

`allPermutations`

`searchDirection`enum

`byLength`

`byWidth`

`auto`

`MaterialKind`enum

`1d`

`2d`

`LeftMeasurement`enum

`fromMiddleToLeft`

`fromMiddleToRight`

`fromLeft`

`fromRight`

`RightMeasurement`enum

`fromMiddleToLeft`

`fromMiddleToRight`

`fromLeft`

`fromRight`

`StripCutting`enum

`none`

`byLength`

`byWidth`

`EdgingCuts`enum

`optimal`

`horizontalFirst`

`verticalFirst`

`OriginEdgingCuts`enum

`default`

`twoFullCuts`

`CutDirection`enum

`horizontal`

`vertical`

`any`

`Structures`set

`none`

`byLength`

`byWidth`

`MaterialKind`enum

`1d`

`2d`

`QualityLevel`enum

`precission`

`compromise`

`speed`

`Dimensions`enum

`net`

`gross`

`ShapeType`enum

`none`

`rectangle`

`linear`

`any`

`slantRect`

`L`

`rightTriangle`

`slopeRect`

`trapezoid`

`octagon`

`ellipse`

`circle`

`ring`

`Structures`set

`none`

`byLength`

`byWidth`

`Structure`enum

`none`

`byLength`

`byWidth`

`ShapeType`enum

`none`

`rectangle`

`linear`

`CutType`enum

`line`

`curve`