Data Groups

TonCut Engine uses 3 data groups:

Configuration – contains configuration, i.e. optimization profiles.
Input – contains input data, i.e. pieces, stock, veneers, material groups and devices.
Output – contains output data, i.e. piece locations, piece transformations and cuts.

Each of the data groups is described in JSON format.

Common

All the data groups must contain two properties that are used to decode the data.

Input and configuration validation

TonCut Engine validates known input and configuration properties when loading JSON, before optimization starts. A property that is present must have the documented JSON type and an accepted value. Invalid types, enum values, set members, units, or values outside the supported range cause a load error; they are not treated as omitted properties or silently replaced by defaults. Optional properties that are omitted keep their documented default or inherited behavior.

Related settings and geometry are checked together during loading. For example, a negative device minCutSize is invalid, and enabling material allowEdgeCuts while the associated device has a positive minCutSize or minCutDistance is invalid. Positive trim edging must meet minCutSize. Loading also checks that inherited minEdgeDistance settings and edging are compatible with the usable stock geometry. Correct the reported input or configuration and load it again before starting optimization.

Identifiers and references are checked at load time too. The id of every device, material, StockItem and piece must be greater than zero and unique within its own list. A material must reference an existing device through deviceId, and a StockItem or piece must reference an existing material through materialId. A missing, unknown or duplicate identifier is a load error: the object is never skipped silently, because that would also drop everything that depends on it.

Numbers must be finite: NaN and infinite values are rejected, and so is a negative length. Time limits must be non-negative and fit the supported range. Configuration profiles are validated as well, see Profile.

Pieces below minCutSize are accepted when loading JSON. Before optimization, methods that enforce an individual-piece minimum exclude pieces whose effective cutting length or width is below the device limit. For one-dimensional cutting, only length is checked. Excluded pieces remain in the input as unplaced demand. A dimension equal to the limit is allowed. Effective dimensions include the configured additions and edging adjustments. A method that supports smaller constituent pieces through series or sets keeps those pieces eligible for optimization. This exception concerns individual pieces only; minimum-size rules for edging, waste, reusable waste, and remnants still apply.

For cutting with splices, loading checks the effective splice length for every piece and stock-item pairing whose structures permit them to be used together. An invalid pairing rejects the load and identifies the stock item and piece, even if another stock item or orientation could work. This check applies whether stock items or pieces are loaded first.

version

The version property specifies the version of the format the data group is encoded in.

The version may be different for different data groups, as we are increasing it always when the format changes. All three data groups (configuration, input and output) are currently at version 4.

defaultUnits

The defaultUnits property specifies the default units for various measurements in the data group.

It contains several sub-properties:


`time`	default unit for time measurements.
`percent`	default unit for percentage measurements.
`length`	default unit for length measurements.
`field`	default unit for field measurements.
`angle`	default unit for angle measurements.
`weight`	default unit for weight measurements.

{
  "version": 4,
  "defaultUnits": {
    "time": "{s|m|h|d}",
    "percent": "{%}",
    "length": "{um|mm|cm|in}",
    "field": "{sqmm|sqcm|sqm|sqin|sqft}",
    "angle": "{rad|deg}",
    "weight": "{mg|g|kg|t|oz|lb|sht|st|toz}"
  },
  // ...
}

Configuration

Config data group contains just a list of profiles to be used.

Attributes

version
int mandatory
Version number of the data group.

Set it to 4, which is also the version the engine writes. Versions 3 and 4 share the same property layout and are loaded identically. Version 2, which has flat limits (maxCombinations, maxTimeSingle, maxTime and goodEnoughWaste directly in limits), is still read. A missing version is read as version 1. Newer configuration properties are additive, and loading rejects invalid values, see Common.
defaultUnits
object
Default units specification as described in defaultUnits section.
profiles
list(Profile)
List of profile objects.
If no profiles are provided, the program will use the default ones.

Configuration data group

{
  "version": 4,
  "defaultUnits": {
    "time": "s",
    "percent": "%",
    "length": "mm",
    "field": "sqmm",
    "angle": "rad"
  },
  "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": 5000000
          },
          "maxTime": {
            "enabled": false,
            "limit": "5s"
          },
          "goodEnoughWaste": {
            "enabled": false,
            "limit": "0.00%"
          }
        },
        "variant": {
          "maxCombinations": {
            "enabled": false,
            "limit": 100000
          },
          "maxTime": {
            "enabled": false,
            "limit": "30s"
          }
        },
        "profile": {
          "maxCombinations": {
            "enabled": false,
            "limit": 10000000
          },
          "maxTime": {
            "enabled": true,
            "limit": "10m"
          }
        }
      },
      // ...
    }
  ]
}

Input

Input data group contains input data.

Attributes

version
int mandatory
Version number of the data group.

Set it to 4. The engine currently does not validate or branch on it.
defaultUnits
object
Default units specification as described in defaultUnits section.
devices
list(Device) mandatory
List of device objects.
materials
list(Material) mandatory
List of material objects.
veneers
list(Veneer)
List of veneer objects.
pieces
list(Piece) mandatory
List of piece objects.
stock
list(StockItem) mandatory
List of StockItem objects.

Input data group

{
  "version": 4,
  "defaultUnits": {
    "time": "s",
    "percent": "%",
    "length": "mm",
    "field": "sqmm",
    "angle": "deg"
  },
  "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
    }
  ],
  "pieces": [
    {
      "materialId": 3,
      "identifier": "",
      "length": 500,
      "shapeType": "linear",
      "quantity": 15,
      "priority": "normal",
      "description": "",
      "surplus": 0,
      "margin": 0,
      "shape": {
        "leftAngle": 45,
        "rightAngle": 25
      },
      "id": 1
    }
  ],
  "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
    }
  ],
  "stock": [
    {
      "materialId": 3,
      "identifier": "",
      "description": "",
      "priority": "normal",
      "length": 6000,
      "quantity": 10,
      "edging": {
        "left": 0,
        "right": 0
      },
      "id": 2
    }
  ],
  "veneers": []
}

Output

Output data group contains optimization results.

Attributes

version
int
Version number of the data group.

Latest version is 4. Version 1 had no support for quantity in Cutting object. Version 3 replaced the piece's rotated boolean with the rotation angle, added pieceId, shape and bbox to piece entries, type (line or curve) with curve end points to cuts, and stackSize to cuttings. Version 4 added applicationVersion, optimizationDate and optimizationTimeMs; cutting income and score, with gain = income - cost; 2D statistics technologicalWasteField, edgingWasteField and kerfWasteField; cut shiftDistance; holes and reusable-waste defects on waste and rest entries; and cutting-level customData (device, material, stock) and piece customData. Several of the fields listed for version 4 were already emitted by later engines that still reported version 3, so clients should detect fields by their presence rather than branch on version.
applicationVersion
string
Product version of the TonCut Engine executable that produced the result, in the major.minor.release.build form, for example "2.1.314.3286". Always present.
optimizationDate
date
The moment the optimization finished, as an ISO 8601 date-time in UTC with a trailing Z, for example "2026-10-06T14:42:38.452Z". It is set also when the optimization ended by a stop or a limit. null when no optimization ran for the job.
optimizationTimeMs
int
Wall-clock duration of the optimization, always in milliseconds and not affected by defaultUnits.time, from the optimization start until the best result was selected. Loading the input and writing the output are not included. null when no optimization ran for the job.
defaultUnits
object
Default units specification as described in defaultUnits section.
statistics
object
Global statistics of the entire optimization.
Show Child Attributes
2d
object
Contains cutting's statistics if the material type is 2D.

For a 1D job, this block's field, usedField, wasteField, unusedField, technologicalWasteField, cutCount, and cutsLength stay 0. edgingWasteField and kerfWasteField are the exception: a 1D piece or waste with a slant (see LinearShape) can give them a nonzero value, as described below.
Show Child Attributes
field
field
The material area of all used stock items: the stock area without its holes, which hold no material.
The engine's statistics do not check a shaped (non-rectangular) or freely rotated piece against stock holes. Such a layout is flagged only if used plus usable area exceeds the 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.
For a 1D job, this includes the part of a slanted cut's trim that falls inside the stock's edging strips.
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.
For a 1D job, this is the kerf area removed along a slanted cut: the material's kerf width times the slanted cut's length. Because the cut runs at an angle, that length is the material width divided by cos(angle), not the width itself.
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.
cuttings
list(Cutting)
List of cutting objects.

Output data group

{
  "version": 4,
  "applicationVersion": "2.1.314.3286",
  "optimizationDate": "2026-10-06T14:42:38.452Z",
  "optimizationTimeMs": 1520,
  "defaultUnits": {
      "length": "mm",
      "field": "sqmm",
      "angle": "rad"
  },
  "statistics": {
      "2d": {
        "field": 0,
        "usedField": 0,
        "wasteField": 0,
        "unusedField": 0,
        "technologicalWasteField": 0,
        "edgingWasteField": 0,
        "kerfWasteField": 0,
        "cutCount": 0,
        "cutsLength": 0
      },
      "1d": {
        "length": 48000,
        "usedLength": 42582,
        "wasteLength": 5418,
        "unusedLength": 0,
        "cutCount": 114,
        "cutsLength": 12316.7744553597
      }
  },
  "cuttings": [
      {
        "stockItemId": 2,
        "quantity": 1,
        "cost": 0,
        "income": 0,
        "gain": 0,
        "score": 0,
        "customData": {},
        "statistics": {
            "1d": {
              "length": 6000,
              "usedLength": 5939.4,
              "wasteLength": 60.6,
              "unusedLength": 0,
              "cutCount": 8,
              "cutsLength": 817.64466576987
            }
        },
        "pieces": [
            {
              "pieceId": 3,
              "x": 0,
              "y": 0,
              "rotation": "0.000000rad",
              "mirrored": false
            },
            {
              "pieceId": 3,
              "x": 820,
              "y": 0,
              "rotation": "3.141593rad",
              "mirrored": false
            },
            {
              "pieceId": 3,
              "x": 1613.2,
              "y": 0,
              "rotation": "0.000000rad",
              "mirrored": false
            }
        ],
        "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
            }
        ],
        // ...
      }
  ]
}

Data Groups

Common

Input and configuration validation

version

defaultUnits

Configuration

Configuration data group

Input

Input data group

Output

Show Child Attributes

Show Child Attributes

Show Child Attributes

Output data group