Dokumentacja API

Bazowy URL https://api.cutoptim.com · wersja kontraktu v1

Utwórz klucz w swoim panelu, a następnie przesyłaj go jako Authorization: Bearer <key>.

Specyfikacja OpenAPI: /engine/openapi.json

Endpointy

Jednostki

API nie narzuca jednostek. Wybierz jedną jednostkę — milimetry, cale, cokolwiek — używaj jej w każdej przesyłanej liczbie, a każda liczba, którą otrzymasz z powrotem, będzie w tej samej jednostce. Nic nie jest przeliczane po stronie serwera i żadna nazwa pola nie zakłada konkretnej jednostki.

Dotyczy to wymiarów elementów i materiału bazowego, kerf, tolerance, trim oraz minOffcut na wejściu, a także każdej współrzędnej, pozycji, pozostałej długości, resztki i długości cięcia na wyjściu. Mieszanie jednostek w jednym zapytaniu daje plan, który przechodzi walidację, a fizycznie jest błędny — i serwer nie jest w stanie tego wykryć.

Układ współrzędnych

Początek układu to lewy górny narożnik płyty: x rośnie w prawo wzdłuż szerokości płyty, y rośnie w dół wzdłuż wysokości płyty. Pola x i y elementu wskazują jego lewy górny narożnik, a w i h to wymiary w takim ułożeniu, w jakim element został rozmieszczony — już zamienione, gdy rotated ma wartość true — więc prostokąt x, y, w, h to gotowy obrys na płycie, bez żadnych dalszych obliczeń. Prostokąty resztek korzystają z tego samego układu.

Okrawanie przesuwa rozmieszczenia: trim.left przesuwa każdy element w prawo, a trim.top przesuwa każdy element w dół, ponieważ elementy są rozmieszczane wewnątrz obszaru użytkowego, a następnie przesuwane z powrotem na całą płytę. trim.right i trim.bottom zmniejszają obszar użytkowy, nie przesuwając początku układu. Pola w i h płyty to zawsze pełne wymiary materiału bazowego, razem z okrawaniem — i właśnie dlatego okrawanie liczy się jako odpad w yieldPct.

2D — zapytanie

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

Pola elementu

Pola materiału bazowego

w oraz h są wymagane. qty domyślnie wynosi 1 i jest twardym limitem tylko przy respectStock. price dotyczy jednej płyty i zasila totalPrice oraz tryb kosztowy. priority (wartość logiczna) zużywa ten materiał w pierwszej kolejności; material (dowolny ciąg znaków) ogranicza go do elementów o tym samym materiale.

Opcje

include robi dwie rzeczy. PRZYCINANIE — "cutPlan" i "offcuts" są domyślnie włączone; obecna tablica zachowuje wyłącznie te tokeny przycinania, które wymienia (pusta tablica usuwa oba). EKSPORT DODATKOWY — "svg", "csv" i "dxf" dodają do odpowiedzi dany eksport jako CIĄG ZNAKÓW: svg to samodzielny rysunek układu 2D (tylko 2D — zapytanie 1d/wood zwraca zamiast tego ostrzeżenie), dxf to rysunek R12/AC1009 na warstwach STOCK/PARTS/LABELS, csv to lista cięć. Tokeny eksportu nie wpływają na przycinanie, więc include:["svg"] dodaje svg i — nie wymieniając żadnego tokenu przycinania — usuwa cutPlan/offcuts; użyj ["cutPlan","offcuts","svg"], aby zachować wszystko i dodać svg.

Opcja effort równoważy czas obliczeń z wykorzystaniem. Oto ten kompromis, zmierzony na jednym wymagającym zleceniu — każda liczba pochodzi z prawdziwego packera.

I tak jest szybko: nawet największe zlecenia produkcyjne — 2000 elementów i więcej — rozwiązywane są w kilka sekund na domyślnym silniku, z zapasem mieszcząc się w budżecie czasu API.

2D — odpowiedź

{
  "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 scala cięcia współliniowe (jedno ustawienie prowadnicy); sawPasses liczy każde przejście. To dwie uczciwe miary tego samego planu, a nie deklaracja zgodności z liczbami któregokolwiek konkurenta.
• guillotineValid / cutPlan — Gdy układu nie da się pociąć od krawędzi do krawędzi, guillotineValid ma wartość false, a cutPlan jest null. To realna informacja — takiego układu nie wykonasz na pile panelowej — a nie błąd.
• unplaced + warnings — Niewykonalne zlecenie zwraca 200 z elementami wypisanymi w unplaced i adnotacją w warnings. Plan, na którym można działać, jest wart więcej niż kod statusu.
• edgeBanding — Gdy jakikolwiek element niesie edgeBanding, odpowiedź dodaje blok edgeBanding: metry bieżące, które zużywa każde oznaczenie typu, w rozbiciu na element i jako suma dla całego zlecenia. To dokładna geometria bez naddatku na odpad — własny naddatek dokłada warsztat — i zakłada wejście w milimetrach (÷1000 na metry). Przy zleceniu bez okleinowania klucz w ogóle nie występuje.
• materials / unmatchedMaterials — Gdy jakikolwiek element lub materiał bazowy niesie material, odpowiedź dodaje materials (zestawienie per materiał — material, sheetCount/rodCount, yieldPct, placed, total, totalPrice) oraz unmatchedMaterials (zapotrzebowanie, którego material nie ma pasującego materiału bazowego). W drewnie material jedzie zamiast tego per sekcja przekroju. Oba klucze nie występują przy zleceniu bez materiału, które pozostaje bajt w bajt identyczne.

Pola odpowiedzi

Nazwy i typy pól są częścią kontraktu, dlatego poniższe tabele pozostają po angielsku we wszystkich językach — przetłumaczona nazwa pola dokumentowałaby API, które nie istnieje.

2D · edgeBanding

Gdy jakikolwiek element niesie edgeBanding, odpowiedź dodaje blok edgeBanding: metry bieżące, które zużywa każde oznaczenie typu, w rozbiciu na element i jako suma dla całego zlecenia. To dokładna geometria bez naddatku na odpad — własny naddatek dokłada warsztat — i zakłada wejście w milimetrach (÷1000 na metry). Przy zleceniu bez okleinowania klucz w ogóle nie występuje.

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

Gdy jakikolwiek element lub materiał bazowy niesie material, odpowiedź dodaje materials (zestawienie per materiał — material, sheetCount/rodCount, yieldPct, placed, total, totalPrice) oraz unmatchedMaterials (zapotrzebowanie, którego material nie ma pasującego materiału bazowego). W drewnie material jedzie zamiast tego per sekcja przekroju. Oba klucze nie występują przy zleceniu bez materiału, które pozostaje bajt w bajt identyczne.

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 fizycznie oznacza jeden krok

Jeden step to jeden ruch piły, a lista jest w takiej kolejności, w jakiej faktycznie da się ciąć: cięcie nadrzędne przed cięciami wewnątrz kawałka, który z niego powstał, bo paska nie przetniesz w poprzek, dopóki go nie odetniesz. axis "h" oznacza, że piła przesuwa się wzdłuż x i oddziela górę od dołu; axis "v" oznacza, że przesuwa się wzdłuż y i oddziela lewą stronę od prawej. pos to krawędź rzazu o NIŻSZEJ współrzędnej — wartość y dla "h", wartość x dla "v" — a nie jego linia środkowa: rzaz zajmuje przedział od pos do pos + kerf, więc piła zabiera materiał w kierunku rosnącej współrzędnej, czyli w dół dla "h" i w prawo dla "v". Materiał po stronie niższej współrzędnej — nad linią dla "h", po jej lewej stronie dla "v" — to kawałek, który uwalnia to cięcie. length to droga, jaką piła przebywa w tym jednym cięciu: rozpiętość obszaru, przez który przechodzi, a nie szerokość całej płyty.

stage to jedno przejście maszyny. Zaczyna się od 1 i zwiększa się tylko wtedy, gdy axis zmienia się względem cięcia nadrzędnego, więc rozcięcie płyty na sześć pasków to jeden etap, a ich poprzeczne przecięcie to następny. To właśnie tak rozumie się „cięcie trzyetapowe” na pile panelowej — nie jako głębokość drzewa cięć — i właśnie to ogranicza opcja maxCutStages. sheet to liczony od 0 indeks w sheets, a step zaczyna się od 1 na każdej płycie, zamiast biec przez całe zlecenie.

cutPlan ma wartość null — nie brakuje go i nie jest pusty — zawsze wtedy, gdy guillotineValid ma wartość false: układ, którego nie da się pociąć od krawędzi do krawędzi, nie ma sekwencji cięcia do zwrócenia. W odpowiedzi nie ma go w ogóle, jeśli pominięto go w include.

1D — liniowe

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

Elementy przyjmują length (oraz qty, name, priority); materiał bazowy przyjmuje length, qty i price. Zarówno elementy, jak i materiał bazowy przyjmują też opcjonalny znacznik material (materiał bazowy również priority) — material ogranicza element do materiału bazowego o tym samym materiale, a odpowiedź dodaje wtedy materials i unmatchedMaterials jak w 2D. Dostępne opcje to kerf, tolerance, trim.start / trim.end, minimizeCost, respectStock i minOffcut. Odpowiedź zwraca rods zamiast sheets, każdy z przypisanymi elementami, pozostałą długością i resztkami.

1D — odpowiedź

{
  "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 zastępuje sheets i nie ma pola guillotineValid, ponieważ cięcie liniowe zawsze da się wykonać. Pole pos każdego elementu to odległość jego bliższego końca od tego końca pręta, który okrawa trim.start, więc pierwszy element zaczyna się dokładnie na trim.start, a każde kolejne pos dodaje jedną szerokość rzazu. remaining to UŻYTECZNA resztka: szerokość rzazu tego cięcia, które uwalnia ją od ostatniego elementu, jest już odjęta, więc jest to długość możliwa do odzyskania, a nie surowa przerwa. Jest raportowane dla każdego pręta, nawet gdy jest mniejsze niż minOffcut — minOffcut filtruje wyłącznie tablicę offcuts, która zawiera najwyżej jeden wpis. W planie cięcia sheet to indeks pręta, axis ma zawsze wartość "v", stage ma zawsze wartość 1, a length zawsze 0: poprzeczne przecięcie pręta nie ma drogi przejazdu, którą można by zaraportować — i właśnie dlatego metrics dla 1D zawiera cuts, ale nie cutLength.

Drewno — przekrój

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

Drewno ma tożsamość, której nie ma zwykły pręt: elementu 50×150 nie da się wyciąć z materiału 50×100, niezależnie od tego, ile długości zostało. Elementy i materiał niosą więc sw i sh, dwa boki przekroju, w dowolnej kolejności — 50×100 i 100×50 to ta sama belka obrócona i trafiają do jednego przekroju. Zlecenie jest dzielone według przekroju, każdy przekrój jest dopasowywany do własnego materiału i rozwiązywany osobno, a jedno wywołanie zwraca całość. Elementy i materiał bazowy przyjmują też opcjonalny znacznik material (materiał bazowy również priority): dzięki niemu dąb 50×100 i sosna 50×100 stają się dwiema osobnymi sekcjami, a każda sekcja niesie swój materiał. Opcje są takie same jak w 1D.

Drewno — odpowiedź

{
  "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 zastępuje rods na najwyższym poziomie: każdy wpis to jeden przekrój z własnymi rods (identycznymi w formie jak w 1D) i własnymi metrics, więc wartości dla danego materiału są od razu dostępne, bez przeliczania. unmatched nie ma odpowiednika w 1D — to zapotrzebowanie, dla którego przekroju nie podałeś żadnego materiału. To inny problem niż unplaced (elementy, które miały materiał i się nie zmieściły) i wymaga innej korekty, dlatego oba nigdy się nie mieszają. metrics.total liczy każdy zamówiony element, łącznie z tymi z unmatched. W planie cięcia każdy krok podaje też swoją section, a sheet to indeks pręta W OBRĘBIE tego przekroju, a nie licznik dla całego zlecenia.

Nesting kształtów rzeczywistych

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

Trzy powyższe tryby pakują prostokąty. POST /v1/optimize/nest pakuje DOWOLNE WIELOKĄTY: element to obrys (polygon, z opcjonalnymi wewnętrznymi holes), a nie szerokość×wysokość, więc elementy wsuwają się we wklęsłe kieszenie sąsiadów, a powietrze wcięć, które marnuje prostokąt otaczający, jest odzyskiwane — na reprezentatywnym zleceniu 6 płyt tam, gdzie te same elementy według prostokąta otaczającego potrzebują 9. To inna klasa algorytmu (geometryczny silnik kolizji, a nie packer gilotynowy), do cięcia laserem, plazmą i strumieniem wody. W komplecie dwie rzeczy, których prostokątne API nie potrafi wyrazić: strefy wykluczeń na każdą płytę (stock[].exclusions — wada, ślad docisku, obszar zadrukowany; strefa o quality równym 0 to obszar zakazany dla dowolnego elementu) oraz otwory kształtów rzeczywistych. Podział na material i przekazywanie meta działają jak wszędzie indziej. Odstęp ustawiany jest dwukrotnie: options.minSeparation między elementami i options.edgeClearance przy krawędzi płyty (domyślnie przyjmuje wartość minSeparation). Gdy dla jednego materiału jest kilka rozmiarów materiału bazowego, oba silniki porównują je i zachowują najlepszy plan — według powierzchni płyty, albo według ceny z minimizeCost — i mogą mieszać rozmiary (do połowy pusta ostatnia płyta przechodzi na mniejszy rozmiar), więc wynik nie zależy od kolejności, w jakiej je podasz. Domyślny silnik, lbf, odpowiada natychmiast; engine "max" uruchamia to samo zadanie asynchronicznie i szuka układu z mniejszą liczbą płyt (patrz Zadania asynchroniczne). Poniższy przykład to jedno prawdziwe przechwycone wywołanie — osiem elementów na jednej płycie z wykluczonym uszkodzonym narożnikiem.

Nest — odpowiedź

{
  "engine": "lbf",
  "engineVersion": "1.0.0+nest-d4046d5-3780cda5",
  "contractVersion": "1",
  "deterministic": true,
  "sheets": [
    {
      "w": 2440,
      "h": 1220,
      "stock": 0,
      "price": 12.5,
      "density": 0.1217,
      "cutLength": 8623.919,
      "pierces": 8,
      "usedWidth": 580.204,
      "usedHeight": 1102.332,
      "usedArea": 639577.44,
      "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,
    "cutLength": 8623.919,
    "pierces": 8
  },
  "stockUsage": [
    {
      "stock": 0,
      "w": 2440,
      "h": 1220,
      "sheetCount": 1,
      "totalPrice": 12.5,
      "density": 0.1217,
      "usedArea": 639577.44
    }
  ],
  "unplaced": [],
  "warnings": [],
  "timing": { "solveMs": 26.34 }
}

Każdy wpis w sheets to jedna użyta płyta; rozmieszczony element niesie transformację sztywną (rotation w stopniach, a następnie przesunięcie x/y), a NIE ponownie wyemitowany wielokąt — obróć wejściowy obrys o rotation wokół jego początku i dodaj (x, y), aby dokładnie odtworzyć rozmieszczenie. rotation może być ujemne; odtworzenie jest dokładne niezależnie od znaku. ⚠️ density to powierzchnia rozmieszczonego WIELOKĄTA względem powierzchni użytej płyty — uczciwe wypełnienie, w którym wklęsłe kieszenie liczą się jako puste — i NIE jest porównywalne z yieldPct packera prostokątnego (który liczy każdy prostokąt otaczający jako pełny, więc wypada wyżej dla gorszego wyniku); miarą porównywalną między nimi jest sheetCount na tych samych elementach. Układ jest deterministyczny: ustaw options.seed, aby go odtworzyć. exclusions jest zwracane na każdej płycie na potrzeby renderowania. Każda płyta niesie stock — indeks wiersza materiału bazowego, z którego została wycięta — a odpowiedź sumuje w stockUsage płyty, cenę i gęstość dla każdego wiersza materiału bazowego, dzięki czemu wycenę można ustalić dla każdego rozmiaru płyty. Każda płyta niesie też cutLength i pierces (metrics sumuje oba): sumę obwodów obrysów i otworów rozmieszczonych na niej elementów oraz jedno przebicie na każdy zamknięty kontur — wartości geometryczne, bez cięcia wspólną linią ani najazdów. Każda płyta niesie też usedWidth i usedHeight — najdalszy punkt, do którego sięgają jej rozmieszczone elementy od narożnika początkowego płyty, czyli wykorzystany prostokąt otaczający do naliczania opłaty za część arkusza — oraz usedArea (stockUsage sumuje to dla każdego wiersza); oba silniki domyślnie zagęszczają najsłabiej wypełnioną płytę w kierunku tego narożnika, z podzbiorami obrotów dopuszczonych dla każdego elementu (options.compact: false to wyłącza; options.compactFor wybiera wielkość do zminimalizowania — "box" (domyślnie) wykorzystaną powierzchnię, "horizontal" wykorzystaną wysokość dla naliczania opłaty za pas na pełną szerokość, "vertical" wykorzystaną szerokość dla pasa na pełną wysokość; liczba płyt i cena nigdy się nie zmieniają). Poproś o include:["svg","dxf"], a odpowiedź poniesie też samodzielny rysunek SVG oraz plik DXF R12 uzyskanego nestingu, w treści.

Elementy z pliku (SVG · DXF)

Element nie musi przychodzić jako współrzędne. Umieść dokument SVG lub DXF w parts[].source, a serwer wyciągnie z niego obrys — wraz z otworami — tym samym czytnikiem, którego aplikacja CutOptim używa, gdy upuścisz rysunek na jej tryb Nesting. Plik zastępuje WYŁĄCZNIE geometrię: qty, material, allowedRotations, minQuality, priority i meta zachowują się dokładnie tak jak przy elemencie polygon, więc biblioteka elementów istniejąca już jako pliki CAD nie wymaga własnego spłaszczania krzywych i łuków. Jedno source opisuje JEDEN element; rysunek zawierający kilka oddzielnych części zwraca 400 i kieruje do poniższego endpointu importu. Odpowiedź niesie wtedy blok imported: ile wierszy pochodzi z pliku, ile wierzchołków wytworzyły i jakie jednostki te pliki zadeklarowały — zgłoszone, nigdy zastosowane, bo to API niczego nie przelicza.

Nic nie jest przechowywane. Bajty istnieją wyłącznie jako treść żądania, są przetwarzane w pamięci i znikają, gdy odpowiedź zostaje zapisana: żadnego dysku, żadnej bazy danych, żadnego pliku tymczasowego, żadnego wpisu w logu. Nie ma potem czego usuwać i nic nie zostaje — ta sama bezstanowość, którą utrzymuje każdy inny 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 }]
}

Nazwy i typy pól są częścią kontraktu, dlatego poniższe tabele pozostają po angielsku we wszystkich językach — przetłumaczona nazwa pola dokumentowałaby API, które nie istnieje.

{
  "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 plik, wszystkie obrysy

Gdy jeden rysunek zawiera kilka różnych elementów, najpierw go zaimportuj: ten endpoint zwraca każdy zamknięty obrys, jaki zawiera, od największego, dokładnie w postaci, jakiej oczekuje wiersz parts[]. Wklej te, których potrzebujesz, dodaj własne qty i material i wyślij to do /v1/optimize/nest. To także sposób, by zobaczyć, co jest w pliku, zanim wydasz na niego obliczenie. Wymaga klucza — spłaszczanie dowolnej geometrii to realna praca procesora, a anonimowy procesor to zły interes — ale niczego nie rezerwuje: Twój limit pozostaje nienaruszony i nie wracają nagłówki rate limit, dokładnie jak przy odpytywaniu zadania.

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

Silniki

• heuristic (domyślny) — wielostrategiowy algorytm pakowania gilotynowego. Najwyższe wykorzystanie, każdy układ da się pociąć na pile, zawsze pełny cutPlan.
• balanced — algorytm pakowania MaxRects ze swobodnym nestingiem. Znacznie szybszy przy dużych zleceniach (zmierzone ~25× przy 2000 elementów) za cenę niewielkiego spadku wykorzystania, a jego układy często nie są gilotynowe (guillotineValid: false, cutPlan: null). Nie modeluje tolerance, minimizeCost, grainGroup, maxCutStages ani minimizeRotations — po ustawieniu któregoś z nich ostrzeżenie poinformuje, że został zignorowany.
• max — asynchroniczny poziom. W 2D to przeszukiwanie drzewa, które osiąga dowiedzione optimum przy znacznie większej liczbie zleceń kosztem sekund do minuty na obliczenie. Nadal deterministyczny i gilotynowy. Nie zwraca planu bezpośrednio — patrz Zadania asynchroniczne poniżej. Modeluje JEDEN format materiału w pełnym rozmiarze płyty, w nieograniczonej ilości, ze stałym 3-etapowym schematem gilotynowym: drugi wiersz materiału, trim, respectStock, material lub grainGroup są odrzucane kodem 400, zanim wywołanie zostanie zarezerwowane; tolerance, minimizeCost, maxCutStages, minimizeRotations, firstCut i effort przechodzą, ale są ignorowane z ostrzeżeniem, a wynik max nie raportuje ścinków. Takie zlecenia kieruj do silnika heuristic. W nestingu kształtów rzeczywistych (POST /v1/optimize/nest) max najpierw wykonuje przebieg lbf, a następnie przeszukuje, w granicach options.timeBudgetMs (domyślnie 60 s, od 10 do 180), szukając układu z mniejszą liczbą płyt — nigdy więcej; jego wyniki nestingu niosą deterministic: false. Tam przyjmuje kilka rozmiarów płyt na materiał oraz respectStock i zachowuje swój wynik tylko wtedy, gdy jest lepszy w rankingu niż wynik lbf (według ceny z minimizeCost, w przeciwnym razie według powierzchni płyty); płyta w kształcie wielokąta albo strefy wykluczeń są obsługiwane przez lbf wewnątrz zadania, z ostrzeżeniem.

Zadania asynchroniczne (engine = max)

Obliczenie max trwa od sekund do minuty, więc POST /v1/optimize/2d albo /v1/optimize/nest z engine:"max" nie zwraca wyniku — zwraca 202 Accepted z polem jobId, a wywołanie jest naliczane przy zgłoszeniu. Odpytuj GET /v1/jobs/{id}, aż status będzie "succeeded" (result zawiera wtedy tę samą odpowiedź, którą zwraca obliczenie synchroniczne danego trybu — plan 2D albo nest; mode mówi który) albo "failed" (error zawiera komunikat). Odpytywanie nie zużywa limitu; widzisz wyłącznie własne zadania. Tam, gdzie ten poziom nie jest włączony we wdrożeniu, engine:"max" jest odrzucane — fail closed — z kodem 503.

Determinizm i wersjonowanie

Każda odpowiedź zawiera engineVersion. Algorytmy są deterministyczne (jeden wyjątek, ograniczone czasowo przeszukiwanie max w nestingu, raportuje deterministic: false), więc ulepszenie jednego z nich zmienia wynik dla tych samych danych wejściowych — a to zmiana łamiąca zgodność, jeśli buforujesz wyniki. Przypnij zachowanie, przesyłając engine jawnie i obserwując engineVersion; wersja w ścieżce /v1/ zmienia się tylko wtedy, gdy zmienia się struktura odpowiedzi.

Każdy silnik jest wersjonowany niezależnie, więc zmiana w jednym nigdy nie przesuwa wersji drugiego.

Błędy

Treść błędu

Każdy błąd generowany przez sam silnik korzysta z tej samej koperty. Rozgałęziaj logikę na polu error, które jest stabilnym kodem; nigdy na message, którego brzmienie może się zmienić między wydaniami. details występuje przy invalid_request, gdzie path wskazuje pole, które wywołało błąd, oraz przy too_large, gdzie max i got podają limit i to, co zostało przesłane.

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

• Zarówno 402, jak i 429 zwracają nagłówek Retry-After w sekundach. Przy 402 odlicza on czas do zerowania limitu o 00:00 UTC pierwszego dnia następnego miesiąca; przy 429 jest to krótkie wstrzymanie, a 429 nigdy nie zużywa limitu — zarezerwowane wywołanie jest oddawane.
• Błąd routingu odpowiada kodem not_found, który celowo znajduje się poza powyższą listą, bo generuje go router, a nie kontrakt API. Otrzymasz 404, a nie 405, gdy ścieżka jest poprawna, ale metoda nie: wszystkie cztery endpointy optymalizacji przyjmują wyłącznie POST.
• Na ścieżkach prostokątnych 504 pochodzi z reverse proxy, a nie z silnika, więc jego treść należy do proxy i nie jest tą kopertą JSON; pojedyncze zadanie w granicach poniższych limitów wejściowych mieści się w nim z dużym zapasem, ale kilka najcięższych zadań naraz może go przekroczyć w kolejce — a wywołanie, z którego proxy zrezygnowało, nie jest naliczane. Wyjątkiem jest /v1/optimize/nest: to obliczenie jest podprocesem z własnym budżetem, celowo utrzymanym poniżej limitu proxy — przekroczenie czasu używa tam tej koperty, z kodem solve_timeout.

Nagłówki limitu zapytań

Udane wywołanie optymalizacji zwraca X-RateLimit-Limit (miesięczny limit KONTA — wszystkie klucze konta dzielą jeden) oraz X-RateLimit-Remaining (liczba wywołań pozostałych kontu w tym miesiącu, już po tym wywołaniu). Wysyłają je wyłącznie endpointy optymalizacji: licznik jest rezerwowany w ramach autoryzacji obliczeń, więc /v1/usage i /v1/health nie mają o czym raportować.

GET /v1/usage

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

Tylko do odczytu: nie zużywa wywołania i nie wysyła nagłówków limitu. ⚠️ used i limit opisują KONTO, a nie klucz, którym wywołałeś: każdy aktywny klucz konta czerpie z jednej wspólnej puli, więc tworzenie kolejnych kluczy nie tworzy dodatkowego limitu. used liczy bieżący miesiąc kalendarzowy UTC dla wszystkich, remaining to limit minus used i nigdy nie schodzi poniżej zera, periodEnd to dzień zerowania jako zwykła data YYYY-MM-DD, a keyPrefix to jawny prefiks użytego klucza. Sam klucz nie jest zwracany przez żaden endpoint — przechowywany jest wyłącznie jego hash, więc zgubiony klucz się wymienia, a nie odzyskuje.

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", "max"],
  "maxEngines": ["max"],
  "uptimeSec": 16
}

Bez klucza, bez limitu, bez bazy danych. Celowo nie sięga do niczego, co przechowuje stan, więc awaria magazynu kluczy nie może sprawić, że usługa wygląda dla orkiestratora na martwą. engines wypisuje identyfikatory, które to wdrożenie przyjmuje w polu engine, a engineVersion to wersja silnika domyślnego.

Limity

• 2,000 elementów na zapytanie (łączna ilość, po rozwinięciu qty)
• 50 wierszy materiału bazowego · treść zapytania do 1 MB
• 10 aktywnych kluczy na konto — dzielą JEDEN miesięczny limit: klucze oddzielają środowiska i integracje, nie zwiększają puli
• 10 MB treści żądania na dwóch ścieżkach nest, które mogą nieść rysunek (/v1/optimize/nest i /v1/import/nest); jeden plik source najwyżej 4 000 000 znaków, 8 000 000 na żądanie
• współbieżność jest ograniczona po stronie serwera — obliczenia idą pojedynczo za krótką kolejką (ok. 8 s); burst ponad nią dostaje 429, a odrzucone żądanie nigdy nie jest naliczane. Endpointy validate bez klucza mają dodatkowo limit na adres (429 z Retry-After); z działającym kluczem nigdy nie ma takiego dławienia. Adres, który w ciągu minuty wyśle ponad 30 nieznanych kluczy API, dostaje 429 do końca tej minuty — jeszcze przed sprawdzeniem klucza. Konto może mieć jednocześnie 5 zadań max w stanie queued/running.

Specyfikacja OpenAPI

Czytelny maszynowo dokument OpenAPI 3.1 opisuje wszystkie dwanaście endpointów, każdą treść zapytania, każdą strukturę odpowiedzi i każdy błąd. Skieruj na niego swój generator klienta, zamiast przepisywać tę stronę. Sam dokument jest wyłącznie w języku angielskim: składa się z elementów kontraktu, a OpenAPI nie ma mechanizmu lokalizacji.

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

Otwórz dokument OpenAPI 3.1 →