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 |
|---|
namestring mandatoryThe name of the optimization profile.
activebool mandatorySet it to
true, to activate the profile. It will be used only if it is active.algorithmsobject mandatoryConfiguration of algorithms to be used by the profile.
Show Child Attributes
Each algorithm is ignored if
aialgorithm is enabled.limitsobjectHere we can define the conditions for early termination of global and/or single optimization.
Show Child Attributes
stockOrderobjectHere 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
advancedobjectHere 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
Profile object
Device
Device object represents a cutting device.
It specifies the features and limitations of the device.
| Attributes |
|---|
idint mandatoryUnique device id.
titlestring mandatoryDevice title.
materialKindmandatoryMaterialKindenum Material kind device's made for
Allowed values
1d1D materials like profiles, pipes, rods, beams, etc.
2d2D materials like glass, panels, fabric, aluminum, cardboard, etc.
Specifies the material kind this device is made for.
slantsobject 1D onlySpecifies support for miter cuts in 1D materials.
Show Child Attributes
canCutAnyShapesbool 2D onlydef: falseSet it to
trueif 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.canCrossCutsbool 2D onlydef: falseSet it to
trueif the device allows the cuts to cross each other.Ignored ifcanCutAnyShapesis enabled.fullCutsOnlybool 2D onlydef: trueSet it to
trueif only full cuts (from edge to edge) are allowed.Ignored ifcanCutAnyShapesis enabled.stripCutting2D onlydef: noneStripCuttingenum Strip cutting direction
Allowed values
noneNo strip cutting.
byLengthHorizontal strips.
byWidthVertical strips.
Set it to
byLengthorbyWidthif the device cuts in strips (e.g. for panel saw).It makes sense only if
fullCutsOnlyoption is set totrue.
It may be used together withmaxCutDepthoption.Ignored ifcanCutAnyShapesis enabled.minCutWidthlengthdef: 0The 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.
edgingCuts2D onlydef: optimalEdgingCutsenum Specifies the edging method
Allowed values
optimalAn 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.
horizontalFirstA "HorizontalFirst" edging method involves cutting off the horizontal edges first, followed by the vertical edges.
verticalFirstA "VerticalFirst" edging method refers to a technique where the vertical edges are cut off before the horizontal edges.
Edging method.
originEdgingCuts2D onlydef: defaultOriginEdgingCutsenum Edging method for the top and left edges.
Allowed values
defaultNothing changes and edges will be cut off as described in
edgingCutsproperty description.twoFullCutsTop and left edges will be cut off as full cuts (from edge to edge)
Edging method for the top and left edges.
firstCutDirectionSpecifies 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
firstCutDirectioncan be crucial when used in conjunction with themaxCutDepthoption.Ignored ifcanCutAnyShapesis enabled.maxCutDepthobject 2D onlySpecifies maximum cut depth level the device is supporting.
The picture below shows what is the cut depth level:Ignored ifcanCutAnyShapesis enabled.It makes sense only if
fullCutsOnlyis set totrue.Show Child Attributes
maxCutLengthByLengthobjectMaximum 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 ifcanCutAnyShapesis enabled.Show Child Attributes
maxCutLengthByWidthobject 2D onlyMaximum 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 ifcanCutAnyShapesis enabled.Show Child Attributes
costsobjectDefines cost parameters for cost-based optimization. See cmdAddJob's
bestSolutionCriterioninput parameter for more details.Available only with Enterprise license!Show Child Attributes
customDataanyCustom data that will be directly passed to
customData.deviceproperty in Cutting.It can be any JSON compatible data, for example:
{ "myId": "932422" },"932422", or932422.Available only with Enterprise license!
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 |
|---|
idint mandatoryUnique id of a StandardStockItem.
titlestringTitle of a StandardStockItem.
lengthlength mandatoryLength of a StandardStockItem.
widthlength mandatory 2D onlyWidth of a StandardStockItem.
structure2D onlydef: []Structuresset The structure of the StandardStockItem
Allowed values
noneThe material has no structure.
byLengthThe structure is horizontal (along length).
byWidthThe structure is vertical (along width).
The structure of the StandardStockItem.
edgingobjectEdging configuration.
Show Child Attributes
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 |
|---|
idint mandatoryUnique id of a material group.
deviceIdint mandatoryId of a cutting device used to cut this material group.
algorithmstringAllows selection of custom algorithms.
Available only with Enterprise license!titlestring mandatoryTitle of the material group.
kindmandatoryMaterialKindenum Type of the material
Allowed values
1d1D materials like profiles, pipes, rods, beams, etc.
2d2D materials like glass, panels, fabric, aluminum, cardboard, etc.
Specifies the type of the material.
widthlength mandatory 1D onlySpecifies the width of the material.
thicknesslength mandatorySpecifies the thickness of the material.
canHaveStructurebool 2D onlydef: falseSpecifies whether the material group can have a structure.
colorablebooldef: falseSpecifies whether the pieces can have different colors. It doesn't influence the optimization process.
canRotatebool def: falseSpecifies whether the pieces of this material group can be rotated.
canMirrorbool def: falseSpecifies whether the pieces of this material group can be reversed (back to front).
qualityLevel2D onlyQualityLevelenum Shape path simplification quality level
Allowed values
precissionHighest quality, but slowest.
compromiseGood quality and speed.
speedLowest quality, but fastest.
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.surpluslengthdef: 0This 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.
surplusEditablebooldef: trueThis setting determines whether the surplus can be adjusted in the piece configuration.
If set tofalse, any surplus specified by the piece will be disregarded and the one defined in material group will be used.marginlengthdef: 0This 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.
marginEditablebooldef: trueThis 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.defaultEdginglengthdef: 0Specifies default edging for new stock items.
cuttingDimensionsmandatory2D onlyDimensionsenum Piece size used for cutting
Allowed values
netThe size specified by length & width of the piece will be used.
Note that surplus and margin may be applied if they are specified.grossThe size of the piece will be increased by the thickness of the veneers used.
Specifies what should be the piece size that will be used for cutting.
canBeVeneeredbool 2D onlydef: falseSpecifies whether pieces of the material group can be veneered.
kerflength mandatorySpecifies the size of the kerf, i.e. the width of the waste line left by the cutting device.

allowEdgeCutsbooldef: falseSpecifies 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
minCutWidthproperty of used cutting device is greater than zero.cutShiftobject 2D onlyControls 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
reuseWasteobjectIt defines the criterion for qualifying waste as usable.
Usable waste is one that goes to the warehouse for later use.Show Child Attributes
stackCuttingobjectIt defines the stack cutting rules.
Show Child Attributes
weightOfSqMweight 2D onlydef: 0Weight of a square meter of the material.
weightOfMeterweight 1D onlydef: 0Weight of a meter of the material.
costsobjectDefines cost parameters for cost-based optimization. See cmdAddJob's
bestSolutionCriterioninput parameter for more details.Available only with Enterprise license!Show Child Attributes
standardStockItemslist(StandardStockItem)The list of standardStockItems for the material group.
customDataanyCustom data that will be directly passed to
customData.materialproperty in Cutting.It can be any JSON compatible data, for example:
{ "myId": "932422" },"932422", or932422.Available only with Enterprise license!
Veneer
The Veneer object specifies characteristics of a veneer.
| Attributes |
|---|
idint mandatoryUnique id of the veneer.
titlestring mandatoryTitle of the veneer.
widthlength mandatoryWidth of the veneer.
thicknesslength mandatoryThickness of the veneer.
surpluslength def: 0The surplus is automatically added when the demand for the amount of veneer is calculated. Please note that the surplus is added twice.
maxMaterialThicknesslength mandatoryThe maximum thickness of the material for which this veneer can be used.
2D input
Piece
The Piece object describes piece.
| Attributes |
|---|
idint mandatoryUnique piece id.
materialIdint mandatoryThe ID of the material group from which this piece will be cut.
identifierstringThe user defined identifier of the piece. It must be Code128 barcode compatible.
colorstringColor of the piece.
descriptionstringDescription of the piece.
lengthlength mandatoryThe net length of the piece.
Keep in mind that for 1D shapes, it is always the total length, including slants:widthlength mandatory 2D onlyThe net width of the piece.
shapeTypedef: noneShapeTypeenum Shape of the piece
Allowed values
noneNo shape, the same as rectangle.
rectangleJust rectangle, so no additional shape definition is necessary.
linear1D shape with slants. The shape property contains slant values.
anyAny shape. You can define any shape using the shape property - convex or concave, or even with holes.
slantRectRectangle with one slanted corner.
LL-shaped piece.
rightTriangleRight triangle.
slopeRectRectangle with one sloped edge.
trapezoidTrapezoid shape.
octagonOctagonal shape.
ellipseElliptical shape.
circleCircular shape.
ringRing shape (circular with a hole).
Type of the shape of the piece.
shapeobjectDepending on
shapeTypeit may contain different format. See Shapes for more information.rotationStepangledef: 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.
rotationangledef: 0°Specifies the initial rotation of the piece. It is useful when you want to have some pieces rotated by default.
mirrorbooldef: falseSpecifies whether the piece is mirrored (back to front).
quantityint mandatorySpecifies quantity of pieces.
structure2D onlydef: [none,byLength,byWidth]Structuresset Structure of the piece
Allowed values
noneThe material has no structure.
byLengthThe structure is horizontal (along length).
byWidthThe structure is vertical (along width).
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”.priorityint def: 1Priority 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:
normalcorresponds to priority1.highcorresponds to priority10.criticalcorresponds to priority100.
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.
groupint def: 0Identifier 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
orderrule (see below) must be respected within each individual group. Group0is 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.orderint def: 0In-group cutting priority. For every non-zero
group, pieces with a lowerordervalue must leave the cutting line before pieces with a higher value in the same group. If several pieces share the sameorder, 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 group0.Cross-group deadlock risk: Certain combinations of
ordervalues across different groups can create circular dependencies (e.g. group 1 needsorder=2cut before group 2’sorder=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.costsobjectDefines cost parameters for cost-based optimization. See cmdAddJob's
bestSolutionCriterioninput parameter for more details.Available only with Enterprise license!Show Child Attributes
surpluslengthdef: 0Specifies 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.
marginlengthdef: 0Specifies 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.
veneersobject 2D onlySpecifies which veneers should be used.
This parameter is only used if the
shapeTypeis specified asnoneorrectangleand the material group allows veneering (i.e. itscanBeVeneeredproperty is set totrue).If
shapeTypeis set torectangle, the veneers specified here will override the veneers in shape definition!Show Child Attributes
customDataanyCustom data that will be directly passed to
customDataproperty in ResultPiece.It can be any JSON compatible data, for example:
{ "myId": "932422" },"932422", or932422.Available only with Enterprise license!
StockItem
The StockItem object describes a StockItem.
| Attributes |
|---|
idint mandatoryUnique StockItem id.
materialIdint mandatoryThe ID of the material group the StockItem is made from.
identifierstringThe user defined identifier of the StockItem.
It must be Code128 barcode compatible.descriptionstringDescription of the StockItem.
prioritydef: normalStockPriorityenum Priority of the StockItem
Allowed values
normalThe StockItem is handled normally.
lowThe stock is handled with lower priority – the program will try to avoid it.
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.
lengthlength mandatoryLength of the StockItem.
widthlength mandatory 2D onlyWidth of the StockItem.
quantityint mandatoryIf 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
quantityproperty varies depending on whether stack cutting is enabled or disabled.stackSizeintThe 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
stackCuttingproperty of the Material data object.structure2D onlydef: noneStructureenum Structure of the StockItem
Allowed values
noneThe material has no structure.
byLengthThe structure is horizontal (along the length).
byWidthThe structure is vertical (along the width).
Specifies the structure of the StockItem.
edgingobjectEdging configuration.
Show Child Attributes
defectslist(Defect)Defines list of defects.
Only the true-shape nesting algorithm currently handles defects. Contact us if you need a defect-aware algorithm.costsobjectDefines cost parameters for cost-based optimization. See cmdAddJob's
bestSolutionCriterioninput parameter for more details.Available only with Enterprise license!Show Child Attributes
customDataanyCustom data that will be directly passed to
customData.stockproperty in Cutting.It can be any JSON compatible data, for example:
{ "myId": "932422" },"932422", or932422.Available only with Enterprise license!
Defect
This object describes location of stock item's defect.
| Attributes |
|---|
xlengthX-coordinate of the defect’s upper-left corner, measured from the stock origin (0 mm, 0 mm) along the primary length (X) axis.
ylengthY-coordinate of the defect’s upper-left corner, measured from the stock origin along the width (Y) axis.
lengthlengthHorizontal extent of the defect parallel to the X axis.
widthlengthVertical extent of the defect parallel to the Y axis.
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
Yaxis. - theYcoordinates 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 |
|---|
pieceIdintID of the piece.
xlengthX position of the piece.
ylengthY position of the piece.
rotationangleSpecifies the rotation angle of the piece.
Note that in previous versions of the JSON format (older than
3), we hadrotatedboolean 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
rotationproperty will be180°, otherwise it will be0°. 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.
mirroredboolSpecifies if the piece was reversed (back to front).
See also the transformation order above.
shapestringThe shape of the piece after rotation and mirror transformations were applied. See Shapes for more information.
The shape is in SVG path format.
bboxobjectThe bounding box of the piece including all modificators: net/gross dimensions, surplus and margin.
Show Child Attributes
customDataanyCustom data passed directly from
customDataproperty in Piece.Available only with Enterprise license!
Waste
The Waste object describes a waste item.
| Attributes |
|---|
xlengthX position of the waste.
ylengthY position of the waste.
lengthlengthLength of the waste.
widthlengthWidth of the waste.
identifierstringAutomatically generated identifier string.
usableboolSpecifies whether the waste is usable.
shapeTypeShapeTypeenum Shape of the waste
Allowed values
noneNo shape, the same as rectangle.
rectangleJust rectangle, so no additional shape definition is necessary.
linear1D shape with slants. The shape CustomProperty contains slant values.
Type of the shape of the waste.
shapeobjectDepending on
shapeTypeit may contain different format.For the moment only LinearShape is supported.
Cut
Cut object describes a cut to be made.
At the moment, we only support straight cuts in the form of segments.
| Attributes |
|---|
typeCutTypeenum Type of the cut
Allowed values
lineA straight cut segment between two points.
curveA cubic bezier curve cut between two points with two control points.
Type of the cut.
startXlengthStart X position of the cut.
startYlengthStart Y position of the cut.
endXlengthEnd X position of the cut.
endYlengthEnd Y position of the cut.
startXplengthFirst control point's X position for cubic bezier curve.
startYplengthFirst control point's Y position for cubic bezier curve.
endXplengthSecond control point's X position for cubic bezier curve.
endYplengthSecond control point's Y position for cubic bezier curve.
needShiftboolSignals that the material segments produced by this cut must be shifted apart immediately after the tool passes. May be set to
trueonly when the Material optioncutExcess > 0.None of the standard algorithms currently handle segment shifting. Contact us if you need such an algorithm.
Cutting
The Cutting object describes single cutting.
| Attributes |
|---|
stockItemIdint mandatoryID of the StockItem for which this cut is made.
quantityint mandatoryIf 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
quantityproperty varies depending on whether stack cutting is enabled or disabled.stackSizeintIf stack cutting is enabled for the material, it indicates the size of a single stack.
statisticsobject mandatoryStatistics of the entire cutting.
Show Child Attributes
pieceslist(ResultPiece) mandatoryA list of all pieces placed on the cutting, including their positions and transformations.
restlist(Waste) mandatoryA list of all Waste items, including their positions and sizes.
cutslist(Cut) mandatoryA list of Cut objects.
costpriceTotal estimated production cost for the entire nesting job, calculated from the Device, Material and StockItem
costsparameters (machine time, tool wear, material price, etc.).Available only with Enterprise license!gainpriceTotal profit for the nesting job, defined as income (selling price) minus
cost. When cost-based optimisation is enabled, solutions are ranked by the highest positivegain.Available only with Enterprise license!customDataobjectCustom data passed directly from
customDataproperties in Device, Material and StockItem.Available only with Enterprise license!Show Child Attributes