Reference API

Základní URL https://api.cutoptim.com · verze kontraktu v1

Klíč si vytvořte na své nástěnce a pak jej posílejte jako Authorization: Bearer <key>.

Specifikace OpenAPI: /engine/openapi.json

Endpointy

Jednotky

API je vůči jednotkám neutrální. Zvolte si jednu jednotku — milimetry, palce, cokoli — používejte ji pro každé číslo, které posíláte, a každé číslo, které dostanete zpátky, bude ve stejné jednotce. Na serveru se nic nepřepočítává a žádný název pole žádnou jednotku nepředepisuje.

Platí to pro rozměry dílů i materiálu, kerf, tolerance, trim a minOffcut na vstupu a pro každou souřadnici, pozici, zbývající délku, zbytek i délku řezu na výstupu. Míchání jednotek v jednom požadavku vytvoří plán, který projde validací a přitom je fyzicky špatný — a server to nemá jak poznat.

Souřadný systém

Počátek je levý horní roh desky: x roste doprava po šířce desky, y roste dolů po výšce desky. x a y dílu jsou jeho levý horní roh a w a h jsou rozměry tak, jak je díl umístěný — už prohozené, když je rotated true — takže obdélník x, y, w, h je přímo obrys na desce, bez dalšího přepočítávání. Obdélníky zbytků používají stejný systém.

Ořez posouvá umístění: trim.left posune každý díl doprava a trim.top každý díl dolů, protože díly se rozmisťují do využitelné plochy a ta se pak přesouvá zpátky na celou desku. trim.right a trim.bottom využitelnou plochu zmenšují, ale počátek neposouvají. w a h desky jsou vždy plné rozměry materiálu, včetně ořezu — a právě proto se ořez v yieldPct počítá jako odpad.

2D — požadavek

POST /v1/optimize/2d
Authorization: Bearer co_live_…
Content-Type: application/json

{
  "parts": [{ "name": "Door", "w": 600, "h": 400, "qty": 4, "rotatable": true }],
  "stock": [{ "w": 2440, "h": 1220, "qty": 10, "price": 42 }],
  "options": {
    "kerf": 3,
    "trim": { "left": 10, "top": 10 },
    "minimizeCost": true,
    "effort": "balanced"
  },
  "engine": "heuristic",
  "include": ["cutPlan", "offcuts"]
}

Pole dílu

Pole materiálu

w a h jsou povinné. qty má výchozí hodnotu 1 a pevným limitem je jen ve spojení s respectStock. price je cena za desku a vstupuje do totalPrice a do režimu nákladů. priority (boolean) spotřebuje tento materiál nejdřív; material (libovolný řetězec) ho omezí na díly stejného materiálu.

Volby

include dělá dvě věci. ZÚŽENÍ — "cutPlan" a "offcuts" jsou zapnuté ve výchozím stavu; přítomné pole ponechá jen ta zužovací klíčová slova, která vyjmenuje (prázdné pole obě vypustí). PŘIDÁVANÝ EXPORT — "svg", "csv" a "dxf" každý přidá do odpovědi příslušný export jako ŘETĚZEC: svg samostatný 2D výkres rozvržení (jen 2D — požadavek 1d/wood místo něj vrátí upozornění), dxf výkres R12/AC1009 na vrstvách STOCK/PARTS/LABELS, csv seznam řezů. Exportní klíčová slova zúžení neovlivňují, takže include:["svg"] přidá svg a — protože neuvádí žádné zužovací klíčové slovo — vypustí cutPlan/offcuts; použijte ["cutPlan","offcuts","svg"], chcete-li zachovat vše a přidat svg.

Volba effort vyvažuje čas výpočtu proti využití. Tady je ten kompromis, změřený na jedné náročné zakázce — každé číslo pochází ze skutečného packeru.

A tak jako tak je to rychlé: i největší výrobní zakázky — 2000 dílů a více — se na výchozím enginu vyřeší v řádu sekund, pohodlně v časovém rozpočtu API.

2D — odpověď

{
  "engine": "heuristic",
  "engineVersion": "1.0.0+10e0c941",
  "contractVersion": "1",
  "deterministic": true,
  "sheets": [
    {
      "w": 2440,
      "h": 1220,
      "price": 42,
      "parts": [
        { "name": "Door", "x": 10, "y": 10, "w": 600, "h": 400, "rotated": false },
        { "name": "Door", "x": 613, "y": 10, "w": 600, "h": 400, "rotated": false },
        { "name": "Door", "x": 1216, "y": 10, "w": 600, "h": 400, "rotated": false },
        { "name": "Door", "x": 1819, "y": 10, "w": 600, "h": 400, "rotated": false }
      ],
      "offcuts": [
        { "x": 2422, "y": 10, "w": 18, "h": 400 },
        { "x": 10, "y": 413, "w": 2430, "h": 807 }
      ]
    }
  ],
  "metrics": {
    "sheetCount": 1,
    "yieldPct": 32.25,
    "placed": 4,
    "total": 4,
    "cutLines": 5,
    "sawPasses": 5,
    "cutLength": 4030,
    "totalPrice": 42
  },
  "unplaced": [],
  "warnings": [],
  "guillotineValid": true,
  "timing": { "solveMs": 3.13 },
  "cutPlan": [
    { "sheet": 0, "step": 1, "axis": "h", "pos": 410, "length": 2430, "stage": 1 },
    { "sheet": 0, "step": 2, "axis": "v", "pos": 610, "length": 400, "stage": 2 },
    { "sheet": 0, "step": 3, "axis": "v", "pos": 1213, "length": 400, "stage": 2 },
    { "sheet": 0, "step": 4, "axis": "v", "pos": 1816, "length": 400, "stage": 2 },
    { "sheet": 0, "step": 5, "axis": "v", "pos": 2419, "length": 400, "stage": 2 }
  ]
}

• cutLines vs sawPasses — cutLines sdružuje řezy ležící na stejné souřadnici (jedno nastavení dorazu); sawPasses počítá každý průjezd. Dvě poctivé míry téhož plánu, ne tvrzení, že se shodují s číslem některého konkurenta.
• guillotineValid / cutPlan — Když rozvržení nelze rozřezat průchozími řezy od hrany k hraně, je guillotineValid false a cutPlan null. To je skutečná informace — na formátovací pile se vyrobit nedá — ne chyba.
• unplaced + warnings — Nesplnitelná zakázka vrací 200, díly jsou vypsané v unplaced a poznámka je ve warnings. Plán, se kterým se dá pracovat, je lepší než stavový kód.
• edgeBanding — Když některý díl nese edgeBanding, odpověď přidá blok edgeBanding: běžné metry, které spotřebuje každý odkaz na typ, na díl i jako součet za celou zakázku. Je to přesná geometrie bez přídavku na odpad — vlastní přídavek si přidá dílna — a předpokládá vstup v milimetrech (÷1000 na metry). U zakázky bez olepení klíč zcela chybí.
• materials / unmatchedMaterials — Když některý díl nebo materiál nese material, odpověď přidá materials (souhrn po jednotlivých materiálech — material, sheetCount/rodCount, yieldPct, placed, total, totalPrice) a unmatchedMaterials (poptávka, jejíž materiál nemá odpovídající zásobu). U dřeva se materiál nese u každé sekce průřezu. Oba klíče u zakázky bez materiálu chybí a ta zůstává bajtově identická.

Pole odpovědi

Názvy polí a jejich typy jsou součástí kontraktu, takže tabulky níže zůstávají ve všech jazycích v angličtině — přeložený název pole by dokumentoval API, které neexistuje.

2D · edgeBanding

Když některý díl nese edgeBanding, odpověď přidá blok edgeBanding: běžné metry, které spotřebuje každý odkaz na typ, na díl i jako součet za celou zakázku. Je to přesná geometrie bez přídavku na odpad — vlastní přídavek si přidá dílna — a předpokládá vstup v milimetrech (÷1000 na metry). U zakázky bez olepení klíč zcela chybí.

POST /v1/optimize/2d

{
  "parts": [
    {
      "name": "Door",
      "w": 600,
      "h": 400,
      "qty": 2,
      "edgeBanding": {
        "top": "ABS oak 22",
        "bottom": "ABS oak 22",
        "left": "ABS white 22",
        "right": "ABS white 22"
      }
    },
    { "name": "Shelf", "w": 800, "h": 300, "edgeBanding": { "top": "ABS oak 22" } }
  ],
  "stock": [{ "w": 2440, "h": 1220, "qty": 10, "price": 42 }],
  "options": { "kerf": 3 }
}

{
  "edgeBanding": {
    "totalMeters": 4.8,
    "byType": [
      { "reference": "ABS oak 22", "meters": 3.2 },
      { "reference": "ABS white 22", "meters": 1.6 }
    ],
    "byPart": [
      {
        "name": "Door",
        "meters": 4,
        "byType": [
          { "reference": "ABS oak 22", "meters": 2.4 },
          { "reference": "ABS white 22", "meters": 1.6 }
        ]
      },
      {
        "name": "Shelf",
        "meters": 0.8,
        "byType": [{ "reference": "ABS oak 22", "meters": 0.8 }]
      }
    ]
  }
}

material

Když některý díl nebo materiál nese material, odpověď přidá materials (souhrn po jednotlivých materiálech — material, sheetCount/rodCount, yieldPct, placed, total, totalPrice) a unmatchedMaterials (poptávka, jejíž materiál nemá odpovídající zásobu). U dřeva se materiál nese u každé sekce průřezu. Oba klíče u zakázky bez materiálu chybí a ta zůstává bajtově identická.

POST /v1/optimize/2d

{
  "parts": [
    { "name": "Door", "w": 600, "h": 400, "qty": 4, "material": "MDF 18" },
    { "name": "Shelf", "w": 800, "h": 300, "qty": 6, "material": "Oak 18" },
    { "name": "Back panel", "w": 1000, "h": 500, "qty": 2, "material": "Ply 6" }
  ],
  "stock": [
    { "w": 2440, "h": 1220, "qty": 10, "price": 42, "material": "MDF 18" },
    { "w": 2440, "h": 1220, "qty": 10, "price": 68, "material": "Oak 18", "priority": true }
  ],
  "options": { "kerf": 3 },
  "engine": "heuristic"
}

{
  "materials": [
    {
      "material": "MDF 18",
      "sheetCount": 1,
      "yieldPct": 32.25,
      "placed": 4,
      "total": 4,
      "totalPrice": 42
    },
    {
      "material": "Oak 18",
      "sheetCount": 1,
      "yieldPct": 48.37,
      "placed": 6,
      "total": 6,
      "totalPrice": 68
    }
  ],
  "unmatchedMaterials": [
    {
      "material": "Ply 6",
      "parts": [{ "name": "Back panel", "w": 1000, "h": 500, "qty": 2 }]
    }
  ]
}

cutPlan — co jeden krok fyzicky znamená

Jeden krok je jeden pohyb kotouče a seznam je v tom pořadí, ve kterém se skutečně dá řezat: nadřazený řez stojí před řezy uvnitř kusu, který jím vznikl, protože pásek nemůžete zkrátit napříč, dokud ho neodříznete. axis "h" znamená, že kotouč jede podél x a odděluje horní část od dolní; axis "v" znamená, že jede podél y a odděluje levou část od pravé. pos je NIŽŠÍ hrana kotouče z hlediska souřadnic — hodnota y pro "h", hodnota x pro "v" — nikoli jeho osa: šířka řezu (kerf) zabírá úsek od pos do pos + kerf, takže kotouč ubírá materiál ve směru, ve kterém souřadnice roste — u "h" tedy dolů a u "v" doprava. Materiál na nižší straně řezné linie — u "h" nad ní, u "v" vlevo od ní — je ten kus, který daný řez uvolní. length je vzdálenost, kterou kotouč na tom jednom řezu ujede: rozsah oblasti, kterou přejíždí, ne šířka celé desky.

stage je jeden průjezd stroje. Začíná na 1 a zvyšuje se jen tehdy, když se axis oproti nadřazenému řezu překlopí — takže rozříznutí desky na šest pásků je jedna fáze a jejich příčné zkrácení je fáze další. Přesně takto rozumí „třífázovému řezání“ formátovací pila; není to hloubka stromu řezů a je to právě to, co omezuje maxCutStages. sheet je index do sheets počítaný od nuly a step začíná na každé desce znovu od 1, místo aby běžel přes celou zakázku.

cutPlan je null — ne chybějící, ne prázdný — vždy, když je guillotineValid false: rozvržení, které nelze rozřezat průchozími řezy od hrany k hraně, nemá žádnou sekvenci řezů, kterou by šlo vrátit. Z odpovědi zmizí úplně jen v případě, že jste jej vynechali z include.

1D — lineární

POST /v1/optimize/1d

{
  "parts": [{ "name": "Rail", "length": 1200, "qty": 6 }],
  "stock": [{ "length": 3000, "qty": 5, "price": 12.5 }],
  "options": { "kerf": 3, "trim": { "start": 10, "end": 0 } }
}

Díly mají length (plus qty, name, priority); materiál má length, qty a price. Díly i zásoba navíc přijímají volitelnou značku material (zásoba i priority) — material omezí díl na zásobu stejného materiálu a odpověď pak přidá materials a unmatchedMaterials jako u 2D. Volby jsou kerf, tolerance, trim.start / trim.end, minimizeCost, respectStock a minOffcut. Odpověď vrací rods místo sheets, každou s vlastními díly, zbývající délkou a zbytky.

1D — odpověď

{
  "engine": "heuristic",
  "engineVersion": "1.0.0+10e0c941",
  "contractVersion": "1",
  "deterministic": true,
  "rods": [
    {
      "length": 3000,
      "price": 12.5,
      "remaining": 584,
      "parts": [
        { "name": "Rail", "pos": 10, "length": 1200 },
        { "name": "Rail", "pos": 1213, "length": 1200 }
      ],
      "offcuts": [584]
    },
    {
      "length": 3000,
      "price": 12.5,
      "remaining": 584,
      "parts": [
        { "name": "Rail", "pos": 10, "length": 1200 },
        { "name": "Rail", "pos": 1213, "length": 1200 }
      ],
      "offcuts": [584]
    },
    {
      "length": 3000,
      "price": 12.5,
      "remaining": 584,
      "parts": [
        { "name": "Rail", "pos": 10, "length": 1200 },
        { "name": "Rail", "pos": 1213, "length": 1200 }
      ],
      "offcuts": [584]
    }
  ],
  "metrics": {
    "rodCount": 3,
    "yieldPct": 80,
    "placed": 6,
    "total": 6,
    "cuts": 6,
    "totalPrice": 37.5,
    "toleranceAcceptedCount": 0
  },
  "unplaced": [],
  "warnings": [],
  "timing": { "solveMs": 2.19 },
  "cutPlan": [
    { "sheet": 0, "step": 1, "axis": "v", "pos": 1210, "length": 0, "stage": 1 },
    { "sheet": 0, "step": 2, "axis": "v", "pos": 2413, "length": 0, "stage": 1 },
    { "sheet": 1, "step": 1, "axis": "v", "pos": 1210, "length": 0, "stage": 1 },
    { "sheet": 1, "step": 2, "axis": "v", "pos": 2413, "length": 0, "stage": 1 },
    { "sheet": 2, "step": 1, "axis": "v", "pos": 1210, "length": 0, "stage": 1 },
    { "sheet": 2, "step": 2, "axis": "v", "pos": 2413, "length": 0, "stage": 1 }
  ]
}

rods nahrazuje sheets a guillotineValid tady není, protože lineární řez je vždy vyrobitelný. pos každého dílu je odstup jeho bližšího konce od toho konce tyče, který ořezává trim.start, takže první díl začíná přesně na trim.start a každé další pos přidává jednu šířku řezu (kerf). remaining je VYUŽITELNÝ zbytek: šířka řezu, kterým se odděluje od posledního kusu, je už odečtena, takže je to znovupoužitelná délka, ne holá mezera. Uvádí se u každé tyče, i když je menší než minOffcut — minOffcut filtruje pouze pole offcuts, které obsahuje nejvýše jeden záznam. V plánu řezání je sheet index tyče, axis je vždy "v", stage je vždy 1 a length je vždy 0: příčné zkrácení tyče nemá žádnou dráhu, kterou by šlo hlásit, a proto také 1D metrics obsahují cuts, ale žádné cutLength.

Dřevo — průřez

POST /v1/optimize/wood

{
  "parts": [
    { "name": "Rafter", "sw": 50, "sh": 100, "length": 2400, "qty": 2 },
    { "name": "Noggin", "sw": 50, "sh": 100, "length": 600, "qty": 4 },
    { "name": "Beam", "sw": 50, "sh": 150, "length": 3000, "qty": 2 }
  ],
  "stock": [
    { "name": "C24 50x100", "sw": 50, "sh": 100, "length": 4000, "qty": 5, "price": 12.5 },
    { "name": "C24 50x150", "sw": 50, "sh": 150, "length": 4000, "qty": 3, "price": 18 }
  ],
  "options": { "kerf": 3 }
}

Dřevo má identitu, kterou holá tyč nemá: díl 50×150 z materiálu 50×100 nevyřežete, ať zbývá jakákoli délka. Díly i materiál proto nesou sw a sh, dvě strany průřezu, v libovolném pořadí — 50×100 a 100×50 je tentýž otočený hranol a patří do jednoho průřezu. Zakázka se rozdělí podle průřezu, každý průřez se přiřadí vlastnímu materiálu a řeší se samostatně, a jedno volání vrátí celek. Díly i zásoba navíc přijímají volitelnou značku material (zásoba i priority): s ní se dub 50×100 a borovice 50×100 stanou dvěma samostatnými sekcemi a každá sekce nese svůj materiál. Volby jsou stejné jako u 1D.

Dřevo — odpověď

{
  "engine": "heuristic",
  "engineVersion": "1.0.0+7c1f3a62",
  "contractVersion": "1",
  "deterministic": true,
  "sections": [
    {
      "section": "50x100",
      "sw": 50,
      "sh": 100,
      "stockName": "C24 50x100",
      "rods": [
        {
          "length": 4000,
          "price": 12.5,
          "remaining": 391,
          "parts": [
            { "name": "Rafter", "pos": 0, "length": 2400 },
            { "name": "Noggin", "pos": 2403, "length": 600 },
            { "name": "Noggin", "pos": 3006, "length": 600 }
          ],
          "offcuts": [391]
        },
        {
          "length": 4000,
          "price": 12.5,
          "remaining": 391,
          "parts": [
            { "name": "Rafter", "pos": 0, "length": 2400 },
            { "name": "Noggin", "pos": 2403, "length": 600 },
            { "name": "Noggin", "pos": 3006, "length": 600 }
          ],
          "offcuts": [391]
        }
      ],
      "metrics": {
        "rodCount": 2,
        "yieldPct": 90,
        "placed": 6,
        "total": 6,
        "cuts": 6,
        "totalPrice": 25
      },
      "unplaced": []
    },
    {
      "section": "50x150",
      "sw": 50,
      "sh": 150,
      "stockName": "C24 50x150",
      "rods": [
        {
          "length": 4000,
          "price": 18,
          "remaining": 997,
          "parts": [{ "name": "Beam", "pos": 0, "length": 3000 }],
          "offcuts": [997]
        },
        {
          "length": 4000,
          "price": 18,
          "remaining": 997,
          "parts": [{ "name": "Beam", "pos": 0, "length": 3000 }],
          "offcuts": [997]
        }
      ],
      "metrics": {
        "rodCount": 2,
        "yieldPct": 75,
        "placed": 2,
        "total": 2,
        "cuts": 2,
        "totalPrice": 36
      },
      "unplaced": []
    }
  ],
  "unmatched": [],
  "metrics": {
    "sectionCount": 2,
    "rodCount": 4,
    "yieldPct": 82.5,
    "placed": 8,
    "total": 8,
    "cuts": 8,
    "totalPrice": 61,
    "toleranceAcceptedCount": 0
  },
  "unplaced": [],
  "warnings": [],
  "timing": { "solveMs": 2.96 },
  "cutPlan": [
    {
      "section": "50x100",
      "sheet": 0,
      "step": 1,
      "axis": "v",
      "pos": 2400,
      "length": 0,
      "stage": 1
    },
    {
      "section": "50x100",
      "sheet": 0,
      "step": 2,
      "axis": "v",
      "pos": 3003,
      "length": 0,
      "stage": 1
    },
    {
      "section": "50x100",
      "sheet": 0,
      "step": 3,
      "axis": "v",
      "pos": 3606,
      "length": 0,
      "stage": 1
    },
    {
      "section": "50x100",
      "sheet": 1,
      "step": 1,
      "axis": "v",
      "pos": 2400,
      "length": 0,
      "stage": 1
    },
    {
      "section": "50x100",
      "sheet": 1,
      "step": 2,
      "axis": "v",
      "pos": 3003,
      "length": 0,
      "stage": 1
    },
    {
      "section": "50x100",
      "sheet": 1,
      "step": 3,
      "axis": "v",
      "pos": 3606,
      "length": 0,
      "stage": 1
    },
    {
      "section": "50x150",
      "sheet": 0,
      "step": 1,
      "axis": "v",
      "pos": 3000,
      "length": 0,
      "stage": 1
    },
    {
      "section": "50x150",
      "sheet": 1,
      "step": 1,
      "axis": "v",
      "pos": 3000,
      "length": 0,
      "stage": 1
    }
  ]
}

sections nahrazuje rods na nejvyšší úrovni: každá položka je jeden průřez s vlastními rods (tvarem shodnými s 1D) a vlastními metrics, takže hodnoty za materiál máte bez dopočítávání. unmatched nemá v 1D obdobu — je to poptávka, pro jejíž průřez jste nezadali žádný materiál. To je jiný problém než unplaced (díly, které materiál měly a nevešly se) a řeší se jinak, proto se ty dva nikdy nemíchají. metrics.total počítá každý požadovaný kus, včetně těch v unmatched. V plánu řezů každý krok navíc uvádí svou section a sheet je index tyče UVNITŘ daného průřezu, ne čítač přes celou zakázku.

Nesting podle skutečného tvaru

POST /v1/optimize/nest

{
  "parts": [
    {
      "name": "bracket",
      "polygon": [[0, 0], [300, 0], [300, 100], [100, 100], [100, 300], [0, 300]],
      "qty": 4,
      "allowedRotations": [0, 90, 180, 270]
    },
    {
      "name": "gusset",
      "polygon": [[0, 0], [280, 0], [0, 280]],
      "qty": 4,
      "allowedRotations": [0, 90, 180, 270]
    }
  ],
  "stock": [
    {
      "w": 2440,
      "h": 1220,
      "price": 12.5,
      "exclusions": [{ "polygon": [[0, 0], [300, 0], [0, 300]], "quality": 0 }]
    }
  ]
}

Tři výše uvedené režimy rozmisťují obdélníky. POST /v1/optimize/nest rozmisťuje LIBOVOLNÉ POLYGONY: díl je obrys (polygon, s volitelnými vnitřními otvory), ne šířka×výška, takže se díly do sebe zaklesávají v konkávních kapsách a vzduch ve výřezech, který opsaný obdélník promrhá, se získá zpět — na reprezentativní zakázce 6 desek tam, kde tytéž díly podle opsaného obdélníku potřebují 9. Je to jiná třída algoritmu (geometrické kolizní jádro, ne gilotinový packer), pro řezání laserem, plazmou a vodním paprskem. Součástí jsou dvě věci, které obdélníkové API vyjádřit neumí: vyloučené zóny po jednotlivých deskách (stock[].exclusions — vada, otisk upínky, předtištěná plocha; zóna s quality 0 je zakázaná oblast pro jakýkoli díl) a otvory podle skutečného tvaru. material partition a průchod meta fungují jako všude jinde. Příklad níže je jedno skutečně zachycené volání — osm dílů na jedné desce s vyloučeným poškozeným rohem.

Nest — odpověď

{
  "engine": "lbf",
  "engineVersion": "1.0.0+nest-d4046d5-07546022",
  "contractVersion": "1",
  "deterministic": true,
  "sheets": [
    {
      "w": 2440,
      "h": 1220,
      "price": 12.5,
      "density": 0.1217,
      "parts": [
        { "name": "bracket", "sheet": 0, "x": 300.003, "y": 400.226, "rotation": -180 },
        { "name": "bracket", "sheet": 0, "x": 300.133, "y": 700.617, "rotation": -180 },
        { "name": "bracket", "sheet": 0, "x": 300.061, "y": 1000.969, "rotation": -180 },
        { "name": "bracket", "sheet": 0, "x": 400.095, "y": 1102.332, "rotation": -180 },
        { "name": "gusset", "sheet": 0, "x": 530.102, "y": 50.205, "rotation": 90 },
        { "name": "gusset", "sheet": 0, "x": 300.058, "y": 380.171, "rotation": -90 },
        { "name": "gusset", "sheet": 0, "x": 580.15, "y": 380.193, "rotation": 90 },
        { "name": "gusset", "sheet": 0, "x": 300.204, "y": 660.982, "rotation": -90 }
      ],
      "exclusions": [{ "polygon": [[0, 0], [300, 0], [0, 300]], "quality": 0 }]
    }
  ],
  "metrics": { "sheetCount": 1, "density": 0.1217, "placed": 8, "total": 8, "totalPrice": 12.5 },
  "unplaced": [],
  "warnings": [],
  "timing": { "solveMs": 44.19 }
}

Každá položka v sheets je jedna použitá deska; umístěný díl nese tuhou transformaci (rotation ve stupních, pak posun x/y), NIKOLI znovu vygenerovaný polygon — otočte svůj vstupní obrys o rotation kolem jeho počátku a přičtěte (x, y), čímž umístění přesně zrekonstruujete. rotation může být záporná; rekonstrukce je přesná bez ohledu na znaménko. ⚠️ density je plocha umístěného POLYGONU vůči ploše použité desky — poctivé zaplnění, kde se konkávní kapsy počítají jako prázdné — a NENÍ srovnatelná s yieldPct obdélníkového packeru (který počítá každý opsaný obdélník jako plný, takže u horšího výsledku vychází vyšší); srovnatelnou metrikou mezi oběma je sheetCount na týchž dílech. Rozvržení je deterministické: nastavte options.seed, chcete-li ho zopakovat. exclusions se vrací u každé desky kvůli vykreslení.

Díly ze souboru (SVG · DXF)

Díl nemusí přijít jako souřadnice. Vložte dokument SVG nebo DXF do parts[].source a server z něj vytáhne obrys — i s jeho otvory — stejným čtečem, jaký používá aplikace CutOptim, když na její režim Nesting přetáhnete výkres. Soubor nahrazuje POUZE geometrii: qty, material, allowedRotations, minQuality, priority a meta se chovají přesně jako u dílu polygon, takže knihovna dílů, která už existuje jako CAD soubory, nevyžaduje váš vlastní rozklad křivek a oblouků. Jedno source popisuje JEDEN díl; výkres s několika samostatnými součástmi vrátí 400 a odkáže na importní endpoint níže. Odpověď pak nese blok imported: kolik řádků přišlo ze souboru, kolik vrcholů vytvořily a jaké jednotky ty soubory deklarovaly — hlášeno, nikdy použito, protože toto API nic nepřepočítává.

Nic se neukládá. Bajty existují pouze jako tělo požadavku, zpracují se v paměti a zmizí, jakmile je odpověď zapsána: žádný disk, žádná databáze, žádný dočasný soubor, žádný řádek v logu. Poté není co mazat a nic nezůstává — stejná bezstavovost, jakou drží každý jiný endpoint.

POST /v1/optimize/nest

{
  "parts": [
    {
      "source": {
        "content": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 400 200\">\n  <path d=\"M0 0 H120 V80 H0 Z\"/>\n  <path d=\"M40 30 H80 V50 H40 Z\"/>\n</svg>",
        "filename": "washer-plate.svg"
      },
      "qty": 4,
      "meta": { "erpId": "ART-8891" }
    }
  ],
  "stock": [{ "w": 2440, "h": 1220 }]
}

Názvy polí a jejich typy jsou součástí kontraktu, takže tabulky níže zůstávají ve všech jazycích v angličtině — přeložený název pole by dokumentoval API, které neexistuje.

{
  "imported": { "parts": 1, "vertices": 8, "units": [] },
  "parts_after_import": [
    {
      "name": "washer-plate",
      "polygon": [[0, 0], [120, 0], [120, 80], [0, 80]],
      "holes": [[[40, 30], [80, 30], [80, 50], [40, 50]]],
      "qty": 4,
      "meta": { "erpId": "ART-8891" }
    }
  ]
}

POST /v1/import/nest — jeden soubor, všechny obrysy

Když jeden výkres obsahuje několik různých dílů, nejprve jej importujte: tento endpoint vrátí každý uzavřený obrys, který obsahuje, od největšího, přesně v podobě, jakou očekává řádek parts[]. Vložte ty, které potřebujete, doplňte vlastní qty a material a to pošlete na /v1/optimize/nest. Je to také způsob, jak zjistit, co v souboru je, dřív než na něj vydáte výpočet. Vyžaduje klíč — rozklad libovolné geometrie je skutečná práce procesoru a anonymní procesor je špatný obchod — ale nic nerezervuje: vaše kvóta zůstává nedotčená a nevracejí se hlavičky rate limit, přesně jako při dotazování úlohy.

POST /v1/import/nest
Authorization: Bearer co_live_…

{
  "content": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 400 200\">\n  <path d=\"M0 0 H120 V80 H0 Z\"/>\n  <path d=\"M40 30 H80 V50 H40 Z\"/>\n</svg>",
  "filename": "washer-plate.svg"
}

{
  "format": "svg",
  "parts": [
    {
      "name": "washer-plate",
      "polygon": [[0, 0], [120, 0], [120, 80], [0, 80]],
      "holes": [[[40, 30], [80, 30], [80, 50], [40, 50]]]
    }
  ],
  "vertices": 8,
  "warnings": [],
  "engineEnabled": true,
  "contractVersion": "1"
}

Jádra

• heuristic (výchozí) — gilotinový rozmisťovací algoritmus s více strategiemi. Nejvyšší využití, každé rozvržení je řezatelné na pile, vždy plný cutPlan.
• balanced — rozmisťovací algoritmus MaxRects s volným nestingem. Na velkých zakázkách výrazně rychlejší (naměřeno ~25× při 2 000 dílech) za cenu malé ztráty využití a jeho rozvržení často nejsou gilotinová (guillotineValid: false, cutPlan: null). Nemodeluje tolerance, minimizeCost, grainGroup, maxCutStages ani minimizeRotations — když některou nastavíte, upozornění vám řekne, že byla ignorována.
• max — asynchronní vrstva s prohledáváním stromu (jen 2D): dosahuje prokázaného optima u mnohem více zakázek za cenu sekund až minuty na jeden výpočet. Stále deterministické a gilotinové. Plán nevrací přímo — viz Asynchronní úlohy níže. Modeluje JEDINÝ formát materiálu v plné velikosti desky, v neomezeném množství a s pevným 3fázovým gilotinovým vzorem: druhý řádek materiálu, trim, respectStock, material nebo grainGroup jsou odmítnuty kódem 400 ještě před rezervací volání; tolerance, minimizeCost, maxCutStages, minimizeRotations, firstCut a effort projdou, ale jsou ignorovány s varováním, a výsledek max nehlásí žádné odřezky. Takové zakázky posílejte do jádra heuristic.

Asynchronní úlohy (engine = max)

Výpočet max trvá sekundy až minutu, takže POST /v1/optimize/2d s engine:"max" nevrací plán — vrací 202 Accepted s jobId a volání se započítá při odeslání. Dotazujte se na GET /v1/jobs/{id}, dokud status není "succeeded" (result nese stejnou 2D odpověď jako synchronní výpočet) nebo "failed" (error nese zprávu). Dotazování nespotřebovává kvótu; vidíte jen své vlastní úlohy. Tam, kde tato vrstva na dané instalaci není zapnutá, selže engine:"max" s 503 (fail closed).

Determinismus a verzování

Každá odpověď nese engineVersion. Algoritmus je deterministický, takže jeho zlepšení změní výstup pro stejný vstup — a to je pro toho, kdo cachuje, nekompatibilní změna. Chování si zafixujete tím, že budete engine posílat explicitně a sledovat engineVersion; verze v cestě /v1/ se mění jen tehdy, když se změní podoba odpovědi.

Každé jádro se verzuje samostatně, takže změna jednoho nikdy neposune verzi druhého.

Chyby

Tělo chyby

Každá chyba, kterou vytvoří samotné jádro, používá stejnou obálku. Rozhodujte se podle error, což je stabilní kód; nikdy podle message, jehož formulace se mezi vydáními může změnit. details je přítomné u invalid_request, kde path pojmenovává problematické pole, a u too_large, kde max a got udávají limit a to, co jste poslali.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "invalid_request",
  "message": "parts[0].h: must be greater than 0",
  "details": { "path": "parts[0].h" }
}

HTTP/1.1 402 Payment Required
Retry-After: 41400
Content-Type: application/json; charset=utf-8

{ "error": "quota_exceeded", "message": "monthly quota exhausted" }

• 402 i 429 nesou hlavičku Retry-After v sekundách. U 402 odpočítává čas do resetu kvóty v 00:00 UTC prvního dne následujícího měsíce; u 429 jde o krátké počkání a 429 nikdy nespotřebuje kvótu — rezervované volání se vrací zpět.
• Chyba směrování odpovídá kódem not_found, který záměrně není v seznamu výše, protože jej vytváří router, a ne kontrakt API. Když je cesta správná, ale metoda špatná, dostanete 404, a ne 405: všechny čtyři optimalizační endpointy přijímají jen POST.
• Na obdélníkových cestách přichází 504 z reverzní proxy, ne z jádra, takže jeho tělo patří proxy, a ne této JSON obálce; v rámci vstupních limitů níže by nemělo být možné jej vůbec dostat. Výjimkou je /v1/optimize/nest: ten výpočet je podproces s vlastním rozpočtem, záměrně drženým pod limitem proxy — vypršení času tam tedy používá tuto obálku, s kódem solve_timeout.

Hlavičky rate limitu

Úspěšné volání optimalizace nese X-RateLimit-Limit (měsíční strop ÚČTU — všechny klíče účtu sdílejí jeden) a X-RateLimit-Remaining (kolik volání účtu v tomto měsíci zbývá po tomto). Posílají je pouze optimalizační endpointy: počítadlo se rezervuje jako součást autorizace výpočtu, takže /v1/usage a /v1/health nemají co hlásit.

GET /v1/usage

{
  "plan": "studio",
  "used": 137,
  "limit": 10000,
  "remaining": 9863,
  "periodEnd": "2026-08-01",
  "keyPrefix": "co_live_ab12",
  "contractVersion": "1"
}

Jen pro čtení: nespotřebuje volání a neposílá hlavičky rate limitu. ⚠️ used a limit popisují ÚČET, ne klíč, kterým jste volali: každý aktivní klíč účtu čerpá z jedné společné kvóty, takže více klíčů neznamená více kvóty. used počítá probíhající kalendářní měsíc UTC přes všechny, remaining je limit minus used a nikdy neklesne pod nulu, periodEnd je den vynulování jako prosté datum YYYY-MM-DD a keyPrefix je nerizikový zobrazovací prefix použitého klíče. Samotný klíč nevrací žádný endpoint — ukládá se jen jeho hash, ztracený klíč se tedy nahrazuje, ne obnovuje.

GET /v1/health

{
  "status": "healthy",
  "service": "cutoptim-engine",
  "contractVersion": "1",
  "engineVersion": "1.0.0+10e0c941",
  "engines": ["heuristic", "balanced"],
  "modes": ["2d", "1d", "wood", "nest"],
  "nestEngines": ["lbf"],
  "maxEngines": ["max"],
  "uptimeSec": 16
}

Bez klíče, bez kvóty, bez databáze. Záměrně se nedotýká ničeho stavového, takže výpadek úložiště klíčů nemůže službu ukázat orchestrátoru jako mrtvou. engines vypisuje id, která tato instalace přijímá v engine, a engineVersion je verze výchozího jádra.

Limity

• 2,000 dílů na požadavek (celkové množství, po rozepsání qty)
• 50 řádků materiálu · tělo požadavku až 1 MB
• 10 aktivních klíčů na účet — sdílejí JEDNU měsíční kvótu: klíče oddělují prostředí a integrace, kvótu nezvyšují
• 10 MB těla požadavku na těch dvou nest cestách, které mohou nést výkres (/v1/optimize/nest a /v1/import/nest); jeden soubor source nejvýše 4 000 000 znaků, 8 000 000 na požadavek
• souběžnost je omezena na straně serveru — burst dostane 429, nikdy pomalou frontu. Endpointy validate bez klíče mají navíc strop na adresu (429 s Retry-After); s klíčem k takovému škrcení nikdy nedojde. Účet může mít současně 5 úloh max ve stavu queued/running.

Specifikace OpenAPI

Strojově čitelný dokument OpenAPI 3.1 popisuje všech dvanáct endpointů, každé tělo požadavku, každou podobu odpovědi a každou chybu. Nasměrujte na něj svůj generátor klienta místo toho, abyste přepisovali tuto stránku. Samotný dokument je jen v angličtině: skládá se z tokenů kontraktu a OpenAPI žádný lokalizační mechanismus nemá.

curl -s https://cutoptim.com/engine/openapi.json > cutoptim-engine.json

Otevřít dokument OpenAPI 3.1 →