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.
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.

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.

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.

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.
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.
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.
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: disabled
Enables or disables the switchToSmall modifier of the fromLarge direction.

minWaste
percent
The waste threshold expressed in percentage. If the waste 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: disabled
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 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: enabled
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
Specifies the accuracy of the search.
The higher the values here, the better results will be found.

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,
      "forking": {
          "enabled": false,
          "level": 1
      },
      "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.
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.
minCutWidth
lengthdef: 0
The minimum distance between two cuts.

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.
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: disabled
Enables or disables maximum cut depth limit.

limit
int
The cut depth limit.

includeEdging
bool def: disabled
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!
Show Child Attributes
cutCostPerMeter
pricedef: 0
Cost per meter for cutting operations.

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.

utilizationCostPerKg
pricedef: 0
Specifies the cost per kilogram for waste disposal, covering expenses for collection, transport, and processing of waste material.

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.

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.
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"
      },
      "minCutWidth": 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.
canMirror
bool def: false
Specifies whether the pieces of this material group can be reversed (back to front).
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.
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 is ignored if minCutWidth property of used cutting device is greater than zero.
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).
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.
totalShiftsLimit
int def: 0
Maximum number of individual shift operations permitted for the whole stock item. Use 0 when no global limit is required.
horizontalShiftsLimit
int def: 0
Maximum allowed shifts along the width (up or down). Set to 0 for unlimited horizontal shifts.
verticalShiftsLimit
int def: 0
Maximum allowed shifts along the length (left or right). Set to 0 for unlimited vertical shifts.
reuseWaste
object
It defines the criterion for qualifying waste as usable.
Usable waste is one that goes to the warehouse for later use.
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.

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.

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.
Show Child Attributes
enabled
booldef: false
Enables or disables stack cutting.

defStackSize
int
The default stack size. Note that stack cutting applies only to stock items with standard dimensions.
weightOfSqM
weight 2D onlydef: 0
Weight of a square meter of the material.
weightOfMeter
weight 1D onlydef: 0
Weight of a meter of the material.
costs
object
Defines cost parameters for cost-based optimization. See cmdAddJob's bestSolutionCriterion input parameter for more details.
Available only with Enterprise license!
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.

cutCostPerMeter
pricedef: 0
Cost per meter for cutting operations.

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.

utilizationCostPerKg
pricedef: 0
Specifies the cost per kilogram for waste disposal, covering expenses for collection, transport, and processing of waste material.

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.

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.
standardStockItems
list(StandardStockItem)
The list of standardStockItems for the material group.
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,
          "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”.
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.
Note that when using cost-based optimization, the priority is used as a hint only. It helps the optimizer to start the optimization process, but it is ignored when calculating the quality of the solution.
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.
order
int def: 0
In-group cutting priority. 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.
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!
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.
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
StockPriorityenum
Priority of the StockItem
Allowed values
normal

The StockItem is handled normally.
low

The stock is handled with lower priority – the program will try to avoid it.
def: normal
Priority of the StockItem.
Note that when using cost-based optimization, the priority is used as a hint only. It helps the optimizer to start the optimization process, but it is ignored when calculating the quality of the solution.
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.
defects
list(Defect)
Defines list of defects.

Only the true-shape nesting algorithm currently handles defects. Contact us if you need a defect-aware algorithm.
costs
object
Defines cost parameters for cost-based optimization. See cmdAddJob's bestSolutionCriterion input parameter for more details.
Available only with Enterprise license!
Show Child Attributes
extractionCost
pricedef: 0
Cost of extracting the stock item from the warehouse.
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.

Attributes

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
Horizontal extent of the defect parallel to the X axis.
width
length
Vertical extent of the defect parallel to the Y axis.

{
  "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
        }
      ]
    }
  ]
}

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).
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.
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.
Type of the shape of the waste.
shape
object
Depending on shapeType it may contain different format.

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.

At the moment, we only support straight cuts in the form of segments.

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
Signals that the material segments produced by this cut must be shifted apart immediately after the tool passes. May be set to true only when the Material option cutExcess > 0.
None of the standard algorithms currently handle segment shifting. Contact us if you need such an algorithm.

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

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
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.

Show Child Attributes
field
field
The total surface area of all used stock items.

usedField
field
The total surface area of all used pieces.

wasteField
field
The total waste area.

unusedField
field
The total surface area of usable waste.

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 total length of all used stock items.

usedLength
length
The total length of all used pieces.

wasteLength
length
The total waste length.

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 the entire nesting job, calculated from the Device, Material and StockItem costs parameters (machine time, tool wear, material price, etc.).
Available only with Enterprise license!
gain
price
Total profit for the nesting job, defined as income (selling price) minus cost. When cost-based optimisation is enabled, solutions are ranked by the highest positive gain.
Available only with Enterprise license!
customData
object
Custom data passed directly from customData properties in Device, Material and StockItem.
Available only with Enterprise license!
Show Child Attributes
device
any
Custom data passed directly from customData property in Device.
material
any
Custom data passed directly from customData property in Material.
stock
any
Custom data passed directly from customData property in StockItem.

{
  "cuttings": [
    {
      "stockItemId": 2,
      "quantity": 3,
      "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

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

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

Dimensionsenum

net

`Direction`enum

`fromLarge`

`fromSmall`

`random`

`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`

`StockPriority`enum

`normal`

`low`

`Structure`enum

`none`

`byLength`

`byWidth`

`ShapeType`enum

`none`

`rectangle`

`linear`

`CutType`enum