Engine API

Mindaz, amit a CutOptim a böngésződben végez, egyetlen számításból indul ki: adott ez a darablista és ez az alapanyag — mi a legjobb módja felszabni őket? Az Engine API pontosan ezt a számítást teszi elérhetővé az interneten, hogy egy másik program is feltehesse a kérdést, és megkapja rá a választ — böngésző nélkül, kattintás nélkül, bejelentkezett felhasználó nélkül.

Ez a teljes lényeg. Nem új optimalizáló, nem jobb optimalizáló, és nem is egy nagyobb csomag. Ugyanaz a motor, amelyet ember helyett szoftver ér el.

Nekem szól ez?

A CutOptim felhasználóinak elsöprő többségénél az őszinte válasz: nem. Ha a munkanapod abból áll, hogy megnyitod a CutOptimot, beírod a darabokat és az alapanyagot, majd kinyomtatod vagy exportálod a tervet, akkor az app maga a termék, és ez az oldal nem érint téged.

Az Engine API egyetlen helyzetre szól: a vágástervnek egy olyan szoftverben kell megjelennie, amelyet már használsz, anélkül hogy bárki felkeresné a CutOptimot. A gyakorlatban ez kétféle embert jelent:

• Már használsz olyan szoftvert, amelybe a vágásterv tartozik. Egy ERP-t, amely a megrendeléseidet tartja nyilván, egy árazó eszközt, amely a munkákat kalkulálja, vagy magának a gépnek a szoftverét. Ahelyett, hogy egy kezelő újra begépelné ugyanazt a darablistát a CutOptimba, az a program közvetlenül a motort kérdezi meg, és ott mutatja a tervet, ahol a munka egyébként is zajlik.
• Szoftvert fejlesztetsz magadnak. Házon belüli fejlesztővel, egy helyi szoftvercéggel vagy a géped beszállítójával. Az Engine API az, amihez ők csatlakoznak.

Ha nem vagy biztos benne, melyik oldalon állsz, itt egy jó próba: megjelenhet-e a terv anélkül, hogy bárki kérné? Ha igen, akkor az API szóba jöhet. Ha mindig egy ember dönt úgy, hogy vágástervet készít, akkor az app már most is a megfelelő eszköz.

Mit ad

A szoftvered ugyanazt a két dolgot küldi be JSON formában, amit az appba is beírnál: a darabok listáját és az alapanyag listáját. A motor pedig teljes választ ad vissza:

• A teljes elrendezést. Minden darab a saját helyén, egy konkrét táblán vagy rúdon, azzal együtt, hogy el kellett-e forgatni.
• A vágástervet. Nem csak téglalapok képét: a tényleges guillotine vágási sorrendet, lépésenként, hogy a terv panelfűrészen végrehajtható legyen.
• A számokat. Hány táblát vagy rudat visz el a munka, mennyi a kihasználás százalékban, hány vágás kell hozzá, és mennyi a felhasznált anyag teljes ára. Lapoknál megkapod a kétféle őszinte vágásszámot is — a vágásvonalakat, amelyek összevonják az egy ütköző-beállításba eső vágásokat, és a fűrészeléseket, amelyek minden áthaladást számolnak —, valamint a teljes vágáshosszt.
• Opcionálisan a rajzot. Kérj include: ["svg","csv","dxf"] értéket, és a válasz kész fájlként is viszi az elrendezést — önálló 2D SVG rajzot, R12/AC1009 DXF-et vagy CSV vágásjegyzéket —, a JSON-ba ágyazva, tárolás és második hívás nélkül. (Az SVG csak 2D.) 2D-kérésnél kérhető még a labels (darabonkénti címkeadat), a planHash (a terv ujjlenyomata), a pdf (a vágási terv PDF-je) és a labelsPdf (a címke-PDF) is — a PDF-ek base64-kódolva, ugyanazzal a kóddal rajzolva, mint az appban.
• A saját azonosítóidat, visszaadva. Csatolj egy meta objektumot — egy cikkszámot, egy rendelés-sort, egy vevői hivatkozást — bármelyik darab- vagy alapanyag-sorhoz, és változatlanul visszakapod minden elhelyezett darabon és minden táblán vagy rúdon, így a terv egyezik a saját rendszereddel. Ezt a mezőt használd akkor is, ha az összes tábládat beküldöd, mindegyiket a saját kódoddal jelölöd meg, és vissza akarod olvasni, melyik táblát választotta az optimalizáló — tedd a kódot a stock[].meta mezőbe, és a sheets[].meta mezőn kapod vissza. Az elhelyezést soha nem befolyásolja. Azonosításra ne a material mezőt használd: a material kemény szétválasztás — egy darab kizárólag azonos material értékű alapanyagból vágódik ki —, így ha minden alapanyag-sort megjelölsz vele, de a darabokat nem, akkor minden darab unmatched státusszal jön vissza, az eredmény pedig üres lesz.

Négy számítás van, és mind a négy az app egy-egy módjának felel meg — egy a 2D lapokra, egy az 1D lineáris anyagra (rúd, profil, cső), egy a faanyagra, amelynek keresztmetszete van, és egy a true-shape neszelésre (POST /v1/optimize/nest), amely tetszőleges poligonokat illeszt össze lézer-, plazma- és vízsugárvágáshoz. Minden optimalizáló végponthoz tartozik egy ingyenes ellenőrző végpont is, amely megoldás nélkül ellenőrzi a kérést (lásd lentebb).

Végpontok

Az alap-URL a https://api.cutoptim.com. Az optimalizáló és a usage végpont egy kulcsot visz az Authorization: Bearer <key> fejlécben; a validate és a health végponthoz nem kell kulcs.

A legtöbb hívásra közvetlenül a kész eredmény a válasz. Az egyetlen kivétel az aszinkron max motor (lásd lentebb a Három motor szakaszt): egy max beküldés egy feladatazonosítót ad vissza, amelyet a GET /v1/jobs/{id} végponttal kérdezel le, amíg a terv el nem készül.

A validate végpontok ugyanazt a törzset veszik át, mint a hozzájuk tartozó optimalizáló végpont, és a megoldás lefuttatása nélkül ellenőrzik: egy hibás kérés 400-zal tér vissza, megnevezve a pontos hibás mezőt, egy jól formázott pedig valid: true értéket ad, plusz megvalósíthatósági figyelmeztetéseket (például egy darab, amely egyetlen alapanyagba sem fér bele). Semmibe nem kerülnek, és nem kell hozzájuk kulcs, tehát az integráció fejlesztése közben — még mielőtt egyáltalán kulcsod lenne — ellenőrizheted a törzseidet, és megbizonyosodhatsz róla, hogy egy kérést nem utasítunk el, anélkül hogy elköltenél egy havi hívást.

Szálirány lapoknál

A rétegelt lemeznek és a furnérozott tábláknak szálirányuk van, és egy látszó darabot úgy kell kivágni, hogy ez a megfelelő irányba fusson. A POST /v1/optimize/2d hívásban küldj grain mezőt egy alapanyag-soron — "w" vagy "h", a lap azon oldala, amely mentén a szálirány fut —, és egy darabon is: a darab azon oldala, amely mentén a szálnak futnia kell. Minden ilyen darab úgy kerül elhelyezésre, hogy a szála a lapjának szálával párhuzamos legyen: szükség esetén 90°-kal elfordítva (rotated: true az elhelyezésen, mint bármely elforgatásnál), a rotatable mezőt pedig ilyenkor figyelmen kívül hagyja. A grain nélküli darab továbbra is szabadon forog, a grain nélküli alapanyag-soron (MDF, melamin) is; egy grain-nel megadott darab viszont ilyen soron is megtartja azt az irányt, amit a szálas sorok adnak neki — a szálas és sima lapokat a material választja szét. Ha egy darab csak a szál ellenére, 90°-kal elforgatva férne el, az unplaced a küldött méretében adja vissza, egy warnings sor megnevezi, és a POST /v1/validate/2d már hívás előtt jelzi.

Az eltérő irányba futó szálú alapanyag-sorok egy kérésben is szerepelhetnek — egy 2440 × 1220-as "w"-vel és egy 1220 × 2440-es "h"-val —, és minden lap a saját sora irányával jön vissza, a grain mezővel megismételve a sheets[] elemein. A material megadásakor a darab csak akkor kötött szálirányhoz, ha a saját anyagának van szálirányos lapja. Ha egy darab grain mezejéhez nincs szálirányos alapanyag a kérésben, annak nincs hatása, és a warnings egy sora ezt jelzi. Az options.trim és a kényszerített options.firstCut minden lapra a saját sora irányában érvényes, a szálirány szerint másfelé futó soron is. A CutOptim app Szálirány módja ugyanezt a kódot futtatja. (2026-10-02 óta.)

Erezet egyeztetés lapoknál (szettek)

A szálirány minden darab szálát a megfelelő irányba állítja. Egyes frontoknak ennél több kell: egy két ajtó fölötti fiókelőlap, amelynek mintázata átfut az egyikből a másikba, mintha a három még mindig egyetlen tábla lenne. A POST /v1/optimize/2d hívásban adj ezeknek a darab-soroknak egy id mezőt, és nevezd meg őket a matchedSets listában:

{
  "parts": [
    { "id": "DF", "name": "Drawer front", "w": 48.125, "h": 6 },
    { "id": "DOOR", "name": "Door", "w": 24, "h": 30, "qty": 2 },
    { "name": "Shelf", "w": 22.5, "h": 11.25, "qty": 4 }
  ],
  "stock": [{ "w": 96, "h": 48, "qty": 2, "grain": "w" }],
  "options": { "kerf": 0.125 },
  "matchedSets": [
    { "id": "base-1", "name": "Base cabinet fronts", "grain": "w",
      "layout": { "dir": "rows", "lines": [["DF"], ["DOOR", "DOOR"]] } }
  ]
}

• Mi az a szett. A layout.lines a tagokat a parts[].id szerint sorolja fel. A dir: "rows" esetén minden sor egymás mellett álló tagok sora, a sorok fentről lefelé egymás alatt állnak, így a [["DF"], ["DOOR", "DOOR"]] egy fiókelőlap két ajtó fölött; a "cols" esetén minden sor egy oszlop, az oszlopok egymás mellett állnak. Egy darab egy szettben többször is szerepelhet (Door, Door), de csak egyetlen szetthez tartozhat. A qty (alapérték 1) azt adja meg, hány példány kell — három egyforma szekrény qty: 3 —, a darabok saját qty értékének pedig minden példányt fedeznie kell. Egy szettnek legalább 2 és legfeljebb 24 tagja van, egy kérés legfeljebb 50 szettet fogad.
• Hogyan vágódik. A szett egyetlen téglalapként — a blokkként — megy át az optimalizálón, és a tagjaiként jön vissza, pontosan egy fűrészrésnyi távolságra, egyetlen darab lapból. A szett grain értéke ("w" vagy "h", a blokk szélessége vagy magassága mentén) dönt minden tag irányáról; a tag saját grain értékét a szetten belül nem használja, és egy figyelmeztetés megnevezi azt a tagot, amelyet felülír. Szett-grain nélkül a blokk elfordulhat, ha minden tag rotatable. Az installGap a tagok közti hézag a szekrényen (alapérték: a fűrészrés); a lapon továbbra is egy fűrészrésnyire vannak egymástól.
• Mi jön vissza. Minden elhelyezett tag viseli a matchedSet mezőt: a szett id értékét, hogy melyik instance, és a position értékét a szekrényelőlapon olvasási sorrendben — fentről lefelé, balról jobbra, 1-től —, plusz egy hint mezőt, például "left" vagy "right", ahol ez egyértelmű. A válasz kap egy matchedSets összesítést, szettenként egy elemmel: a letter (A, B … a kérés sorrendjében), hány példányt vágtak egy blokkban (asBlock), darabonként vagy hagytak elhelyezetlenül, a blokk mérete és a szett warnings sorai. Ha egy blokk egyik alapanyag-lapra sem fér, az onMiss: "split" (az alapérték) figyelmeztetéssel egyenként helyezi el a tagokat, az onMiss: "unplaced" pedig az unplaced listában sorolja fel őket.
• Figyelmeztetések, nem hibák. Az az eltérés, amelynél a méretek nem illeszkednek, a szett figyelmeztetése, nem elutasítás. Minden sor a kódjával kezdődik — align: (a vonalak nem egy síkban vannak), gap: (a fűrészrés szélesebb az installGap értékénél), grain:, split:, unplaced:, unmatched: (nincs a szett anyagából készlet), priority: és grainGroup: —, az align és a gap pedig az egységed 1/64-e vagy a fűrészrés negyede szerint ítélődik meg, amelyik kisebb. Az a szett, amelyet egyáltalán nem lehet kirakni — egy olyan tag-azonosító, amelyet egyetlen darab sem visel, egy hivatkozott azonosító két darabon, kettőnél kevesebb tag, a qty-hez túl kevés darab —, 400, amely megnevezi a pontos mezőt, még a hívás terhelése előtt.
• A parts[].id biztonságosan küldhető. Csak az az azonosító ellenőrzött, amelyre egy szett hivatkozik (egy nem üres, nyomtatható karakterekből álló, legfeljebb 64 karakteres szöveg, vagy egy egész szám, pontosan egy darabon). Minden más azonosítót figyelmen kívül hagy, bármi áll benne, így az ERP-cikkszámaid ott maradhatnak a sorokon. És a szettek nélküli kérésnél semmi nem változik: csak a nem üres matchedSets tömb kapcsolja be a funkciót — a hiányzó, a null, az [] vagy bármely nem tömb értékre pontosan úgy válaszol, mint eddig.
• Exportok. Szettekkel a csv kap Set és Position oszlopot a végén, az svg kiírja a pozíciókódot (A1, A2 …) a darabfeliratokra, és minden szett keretét egy külön matched-sets csoportba rajzolja — az options.setOutlines: false kihagyja ezt a csoportot —, a dxf pedig a pozíciókódot a LABELS rétegen viszi. A pdf és a labelsPdf nem jelöli a szetteket: a tagokat közönséges darabokként rajzolják, és ezt a warnings jelzi; a szett-jelölések a sheets[].parts[].matchedSet mezőben, a csv-ben és az svg-ben vannak.
• Motorok és végpontok. A heuristic és a balanced motor rakja ki a szetteket (a balanced nem rangsorolja a priority értéket, így respectStock mellett egy szett elveszítheti a helyét, priority: figyelmeztetéssel). A max motor a nem üres matchedSets listát 400-zal utasítja el, amelynek details.unsupported mezője megnevezi, még a hívás terhelése előtt; az üres lista egy közönséges max feladat. A matchedSets és a parts[].id csak 2D-ben él: az 1D, a fa és a nest végpont figyelmen kívül hagyja őket.
• A grainGroup elavult. Továbbra is elfogadott, és pontosan úgy működik, mint eddig: az azonos csoportba tartozó darabok egy lapon maradnak. Egymás mellé sosem rakta őket, ezért nem ad folytonos szálat köztük — ahhoz használd a matchedSets-et.

A CutOptim app Erezet egyeztetése ugyanezzel a maggal rakja ki a szetteket.

Miért van a fának saját végpontja

A lineáris anyag egy dimenziót ismer, a hosszt, tehát bármelyik rúd bármelyik darabot adhatja. A faanyagnál ez nem így van: egy 50×150-es darab nem jöhet ki egy 50×100-as rúdból, akármennyi hossz marad is rajta. A fa-végpont ezért minden darabnál és minden készlet-sornál átveszi a keresztmetszet mindkét oldalát, keresztmetszetenként szétválasztja a munkát, minden szekcióhoz a saját készletét párosítja, és a szekciókat külön adja vissza — mindegyiket a saját rúdjaival és a saját összesítésével, a teljes munka számai mellett.

Két részlet, amit érdemes tudni az integrálás előtt:

• A keresztmetszet két oldala tetszőleges sorrendben küldhető. Az 50×100 és a 100×50 ugyanaz a gerenda megfordítva, és egy szekcióba kerül. Így az, hogy az adataid éppen hogyan lettek felvéve, nem tüntethet el alapanyagot.

• A „nincs ilyen keresztmetszetű készlet” és a „nem fért el” külön jelenik meg. Az első hiányzó anyag, a második kapacitás-probléma, és másképp kell javítani — egy listába keverve rossz helyre küldenék a felhasználódat.

Ezt közelíthetnéd több saját 1d hívással is, ha magad csoportosítod a darabokat. Az keresztmetszetenként egy kérésbe kerülne a kvótádból egy helyett az egész munkára, a készlet-párosítást a te kódodba tolná, és olyan összesítést adna, amit magadnak kellene összeraknod — és ami nem feltétlenül egyezne azzal, amit a CutOptim app mutat ugyanarra a munkára.

Darabok CAD-fájlból

A nesting végpont nem csak koordinátákat fogad. Egy darab source mezőt is vihet helyettük — egy SVG- vagy DXF-dokumentumot —, és a szerver ebből olvassa ki a kontúrt és a benne lévő lyukakat. Ugyanaz a beolvasó, amit az alkalmazás használ, amikor a Nesting módjára ejtesz egy rajzot, tehát egy CAD-fájlokban már meglévő darab-könyvtárat nem kell előbb koordináta-listákká alakítani.

A fájl csak a geometriát váltja ki. A darabszám, az anyag, az engedélyezett forgatások és a saját metaadatod ugyanolyan mezők maradnak a darab során, mint amikor koordinátákat küldesz. Egy fájl egy darabot ír le; ha egyetlen rajz több különálló alkatrészt tartalmaz, a POST /v1/import/nest előbb kész darab-sorokra bontja — és ez a hívás kulcsot igényel, de nem fogyaszt kérést a havi keretedből.

Semmi nem tárolódik. A fájl kizárólag magaként a kérésként létezik: a memóriában olvassuk be, és mire a válasz megíródik, megszűnik. Nem marad másolat lemezen vagy adatbázisban, nem kerül naplóba, és utólag nincs mit törölni. A mértékegységgel ugyanígy bánunk — egy DXF deklarálhat millimétert vagy hüvelyket, és mi jelentjük, amit mondott, de a koordinátákat sosem váltjuk át, mert ebben az API-ban egyetlen érték sem hordoz mértékegységet.

Mindig ugyanaz a válasz

A motor determinisztikus: ugyanaz a bemenet mindig ugyanazt a kimenetet adja. Nincs véletlenszerűség, és nincs óra az algoritmusban.

Ez elméletinek hangzik, de éppen ez a gyakorlati oka annak, hogy érdemes rá építeni. Azt jelenti, hogy az eredmények cache-elhetők — ha ugyanerre a munkára már rákérdeztél, biztonsággal újrahasználhatod a választ ahelyett, hogy megint megkérdeznéd. Azt is jelenti, hogy az integráció tesztelhető: egy terv összehasonlítható egy ismerten helyes eredménnyel, és ha eltérés van, az valódi eltérés, nem zaj. Az a szoftver, amely hétfőn árat ad a vevőnek, pénteken is ugyanazt az árat fogja adni.

Van egy opt-in kivétel, és ezt a válasz ki is mondja: a nesting max motorja (lentebb) fix időkeretet fordít keresésre, tehát hogy meddig jut, attól függ, mennyi munka fér bele ebbe az időbe. A válaszai deterministic: false értéket visznek. Minden más motor — a nesting alapértelmezettjét, az lbf-et is beleértve — determinisztikus.

Biztonságos újrapróbálás. Ha megszakad a kapcsolat, nem tudni, megérkezett-e a kérés. Küldjön Idempotency-Key fejlécet — egy munkánként választott értéket —, és ugyanazzal a kulccsal próbálja újra: 24 órán belül ugyanaz a kérés a tárolt választ adja vissza Idempotency-Replayed: true jelöléssel, és nem számít második hívásnak. Egy max job sem kerül kétszer sorba. A nyilvános demókulcs ezt a fejlécet figyelmen kívül hagyja. (2026-10-15 óta.)

Webhookok az async jobokhoz. A GET /v1/jobs/{id} pollozása helyett regisztrálj egy végpontot (https:// URL) a vezérlőpulton, és aláírt POST-ot kapsz — job.succeeded vagy job.failed —, amikor egy async max job befejeződik. Ellenőrizd a CutOptim-Signature fejlécet a kapott titokkal, válaszolj 10 másodpercen belül, a tervet pedig a GET /v1/jobs/{id} adja. A sikertelen kézbesítést újrapróbáljuk: 8 próba 24 óra alatt. (2026-10-19 óta.)

Hivatalos SDK-k. Nyílt forráskódú kliensek TypeScripthez, Pythonhoz és PHP-hoz — npm install @cutoptim/engine, pip install cutoptim, composer require cutoptim/engine — típusos kérésekkel, újrapróbálással, amit sosem számolunk fel kétszer (minden hívás Idempotency-Key-t visz), várakozó segédfüggvénnyel az async jobokhoz és webhook-ellenőrzéssel. A forrás a GitHubon; részletek az SDK-útmutatóban (angolul).

MCP-szerver AI-asszisztensekhez. A Claude Code, a Cursor, a VS Code és a Claude Desktop eszközként hívhatja a motort a https://api.cutoptim.com/mcp címen futó Model Context Protocol-szerveren át, ugyanazzal az API-kulccsal (Authorization: Bearer …) és ugyanabból a kvótából: egy eszközhívás egy API-hívás, a validate_* eszközök ingyenesek. Helyben is futtatható a npx -y @cutoptim/mcp csomaggal (kulcs a CUTOPTIM_API_KEY változóban), a hivatalos MCP Registryben pedig io.github.cutoptim/engine néven szerepel. A kliensbeállítások az MCP-útmutatóban vannak (angolul).

Három motor

Az API motorválasztást kínál. Az első kettő szinkron módon fut; a harmadik aszinkron. A különbség nem minőségi kérdés: kompromisszum a sebesség, aközött, hogy az eredmény felszabható-e panelfűrészen, és aközött, hogy mennyire közelíti meg az elméleti minimumot.

• A heuristic az alapértelmezett, és ugyanaz, amit az app is használ. Guillotine elrendezéseket ad: legjobb kihasználás, minden elrendezés fűrésszel vágható, és mindig teljes vágásterv. Szinkron.
• A balanced külön kérésre kapcsol be. Helyette szabad beágyazást használ, ami nagy munkákon jóval gyorsabb — 2000 darabos munkán mérve körülbelül 25× — kissé rosszabb kihasználás árán. A fontos csavar: az elrendezései gyakran nem vághatók éltől élig, ezért azoknál egyáltalán nem ad vágástervet. Szinkron.
• A max külön kérésre kapcsol be, 2D lapokhoz (és külön, a true-shape nestinghez is — lásd lentebb). 2D-n szerver-oldali fakeresés, amely az alapértelmezettnél jóval több munkán éri el a bizonyított optimumot, és az elrendezései továbbra is guillotine-vághatók. Az ára az idő: egy max számítás másodpercektől egy percig tart, ezért nem a válaszban felel. Helyette a POST /v1/optimize/2d az engine: "max" értékkel egy feladatazonosítót ad vissza, amelyet a GET /v1/jobs/{id} végponttal kérdezel le, amíg el nem készül. Továbbra is determinisztikus. Akkor nyúlj hozzá, ha egy nagy, értékes munkánál megéri várni az utolsó néhány tábláért. Egyetlen készlet-formátumot modellez, teljes lapméreten, korlátlan darabszámmal, ezért ha a kérés ezen felül második készlet-formátumot, oldalankénti trim-et, korlátozott készletet (respectStock), anyagot, szálirány-csoportot vagy nem üres matchedSets listát is visz, azt előre elutasítja egy 400-zal, ami pontosan megnevezi, mit nem tud — még mielőtt a hívás terhelődne. Az ilyen munkákat küldd a heuristic motornak, az mindegyiket kezeli.

Nesting: lbf és max

A true-shape nestingnek saját két motorja van. Az lbf az alapértelmezett: azonnali, szinkron és determinisztikus. A max külön kérésre kapcsol be, és aszinkron, pontosan úgy, mint a 2D max — a POST /v1/optimize/nest az engine: "max" értékkel egy feladatazonosítót ad vissza, amelyet a GET /v1/jobs/{id} végponttal kérdezel le.

A nesting max előbb lefuttatja az lbf lépést, tehát mindig van kéznél egy érvényes válasz. Ezután egy időkeretet (options.timeBudgetMs, alapértelmezésben 60 másodperc, 10 és 180 között) fordít arra, hogy kevesebb táblát igénylő elrendezést keressen, egyszerre egy táblát töltve fel. Sosem ad vissza több táblát, mint az lbf: ha a keresés nem talál jobbat, az lbf elrendezést kapod, egy ezt kimondó figyelmeztetéssel. Mivel a keresés időkorlátos, a válaszai deterministic: false értéket visznek. Elfogad több lapméretet is anyagonként, valamint a respectStock beállítást, és ugyanazzal a szabállyal rangsorolja az eredményét, mint az lbf (lentebb): csak akkor cseréli le az lbf tervet, ha az jobb — sosem csupán azért, mert kevesebb táblát tartalmaz. A poligon alakú táblát vagy a kizárási zónákat, amelyeket a sáv-keresése nem tud modellezni, a munkán belül az lbf lépés szolgálja ki, figyelmeztetéssel — sosem utasítja el. A régebbi sparrow nevet a rendszer a max aliasaként elfogadja.

A téglalap alakú darabok egzakt rácsot kapnak (2026-09-28 óta). Az lbf mintavételezéssel keresi a pozíciókat, ami szinte sosem talál rá egy hézag nélküli rácsra: három 500 mm-es darab egy 1500 mm-es tábla szélességében, nulla távolsággal pontosan elfér, a mintavételező keresés viszont kettőt helyez el. Ezért mindkét motor két alternatívát is kipróbál, és ugyanazzal a szabállyal a legjobban rangsorolót tartja meg: a darabokat a megengedett derékszögekre korlátozva, illetve a darabok befoglaló téglalapjait egy egzakt téglalap-pakolóval elrendezve (az egymást nem fedő téglalapok nem tartalmazhatnak egymást fedő darabokat, tehát ez bármilyen körvonalra érvényes). Döntetlennél — azonos táblák, azonos lapterület — az a terv nyer, amelyik elölről hátrafelé tölti ki a tábláit, azután az, amelyikben kevesebb darab tér el a derékszögektől. Semmit nem kell bekapcsolni, és a rangsor szerint az eredmény csak jobb lehet; ha a téglalapok egy tervet arra a legkisebb táblaszámra hoznak le, amit a darabok területe megenged, a max is azonnal válaszol, keresés helyett.

Egy néhány tucat darabos munkához általában elég körülbelül 15 másodperc időkeret (timeBudgetMs: 15000); a munka nagyjából egy-két másodperccel az időkeret után készül el, plusz amennyi ideig a sorban várakozott. Kérdezd le a GET /v1/jobs/{id} végpontot két-három másodpercenként — a lekérdezés nem fogyaszt kvótát. Egyetlen időkeret sem ígérhet konkrét táblaszámot.

Nesting: a tábla szélén tartott távolság, lapméretek és tábla-költségek

• A tábla szélén tartott távolság. Az options.minSeparation a darabok közti távolság, és önmagában a tábla szélén is ezt alkalmazza. Az options.edgeClearance a szélt külön állítja be — például 5 a darabok közt, és 0 vagy 10 a szélen. Ha kihagyod, a szél változatlanul a minSeparation értéket tartja, pontosan úgy, mint eddig. Mindkét motoron működik, téglalap alakú táblát igényel (w és h), és a kizárási zónák a minSeparation értéket tartják, mint a darabok. Egy poligon alakú táblát, vagy olyan értéket, amely nem hagy helyet a táblán, a rendszer 400-zal elutasít, még mielőtt a hívás terhelődne.
• Lapméret választása. Ha egy anyaghoz két vagy több alapanyag-sor tartozik, az lbf kipróbálja őket a beírt sorrendedben, majd egyenként a méreteket, valamint egy legolcsóbb-elöl sorrendben is, és a legjobbat tartja meg — így az eredmény már nem függ attól, milyen sorrendben írod be a sorokat. A rangsor: a legtöbb elhelyezett kötelezően kivágandó darab (lásd lentebb), majd a legtöbb elhelyezett darab, majd a legkisebb összes lap-terület (anyag), majd a legkevesebb tábla. Az options.minimizeCost mellett helyette a legkisebb összes ár szerint rangsorol (price, vagy cost egy ár nélküli sornál) — de csak akkor, ha az adott anyag minden sorának van ára; különben visszaesik a területre, és ezt a warnings mezőben ki is mondja.
• Méretek keverése. Ezután minden táblát — a legkevésbé kitöltöttel kezdve — egyenként újraneszel az olcsóbb vagy kisebb sorokra, és lecseréli, ha attól a teljes terv jobban rangsorol. Így a méretek keveredhetnek egy anyagon belül: jellemzően két nagy tábla és egy kisebb utolsó, ott, ahol a félig üres utolsó tábla korábban egy nagy volt. Az options.respectStock mellett egyetlen sor sem használódik a qty értékénél többször. A max motor ugyanezt a rangsort alkalmazza.
• Kötelezően kivágandó darabok. A parts[].priority: true egy kötelezően kivágandó darabot jelöl. Az options.respectStock mellett számít — egy korlátozott készletnél, ahol nem biztos, hogy minden darab elfér —: a kötelezően kivágandó darabok ilyenkor elsőként kerülnek elhelyezésre, így egy sima darab sosem foglalja el azt a helyet a táblán, amire egy kötelezően kivágandó darabnak szüksége van, és a fenti rangsor azt a tervet helyezi előrébb, amelyik többet tart meg belőlük, még akkor is, ha összesen kevesebb darabot helyez el. Mindkét motor tiszteletben tartja (a max megtartja az lbf elrendezést, amikor bármi kimarad elhelyezetlenül). A respectStock nélkül minden ráférő darab úgyis elhelyeződik, tehát a jelző semmit nem változtat. Egy kötelezően kivágandó darab, amely egyáltalán egyik táblára sem fér rá, továbbra is az unplaced listában szerepel. (2026-09-22 óta — előtte a nesting motor elfogadta a mezőt, de figyelmen kívül hagyta.)
• Korlátozott készlet, amelyre nem fér fel minden. options.respectStock mellett, ha a terv még darabot hagy ki, a motor a darabok befoglaló téglalapjaival laponként is feltölti a lapokat — mindegyiket annyira, amennyire lehet, és az a darab, amely csak egy lapméretre fér, oda kerül először (a magas oldallap az egyetlen nagy lapra, nem egy maradék-csíkra). Ezt a tervet csak akkor veszi át, ha több darabot helyez el (a kötelezőket előre) vagy kevesebb anyagot használ; amelyik munkán minden elfér, az pontosan úgy jön vissza, mint eddig. Betartja a darabok megengedett forgatásait, a minSeparation-t és az edgeClearance-t. (2026-10-14 óta.)
• Mennyibe kerültek az egyes táblák. Minden tábla viszi a stock mezőt — a kérés azon alapanyag-sorának indexét, amelyből kivágták —, és a válasz kiegészül a stockUsage mezővel: egy bejegyzés minden felhasznált alapanyag-soronként, a táblaszámával, összárával és sűrűségével. Az egység az alapanyag-sor, nem a méret: két azonos méretű, de eltérő árú vagy meta-jú sor két bejegyzést jelent.
• Vágáshossz és beszúrások. Minden tábla viszi a cutLength mezőt — az elhelyezett darabok körvonalainak és lyukainak összegzett kerülete, a te mértékegységedben —, valamint a pierces mezőt, egy beszúrást minden zárt kontúrra; a metrics összesíti mindkettőt. Ez a geometriai kontúrhossz: nincs benne közös vonalú vágás, be-/kivezetés vagy mikro-híd — ezeket a saját CAM szoftvered adja hozzá.
• Felhasznált terület, a tábla egy részének leszámlázásához. Minden tábla viszi a usedWidth és a usedHeight mezőt — a legtávolabbi pont, ameddig bármelyik elhelyezett darab elér a tábla origó-sarkától, a te mértékegységedben, a valós táblán (edgeClearance mellett a szélhagyás is beleszámít) —, valamint a usedArea mezőt, a szorzatukat; a stockUsage[].usedArea alapanyag-soronként összesíti. Ez az a szám, amire egy ERP-nek szüksége van, ha egy vízszintes vágást (usedHeight × a tábla szélessége), egy függőleges vágást (usedWidth × a tábla magassága) vagy a befoglaló téglalapot (usedArea) akarja leszámlázni a teljes tábla helyett — a számlázási szabály a tiéd marad. Hogy ezek a számok kicsik legyenek, mindkét motor alapértelmezésben tömöríti minden anyag legkevésbé kitöltött tábláját: a darabjait ugyanarra a táblára újraneszeli, az elforgatásnak azzal a részhalmazával, amit az adott darab megenged — 0/180, 0/90/180/270, és egyetlen tájolás minden példányra, egy diszkrét allowedRotations-szel metszve, sosem egy új szöggel —, és azt az elrendezést tartja meg, amelynek a legkisebb a felhasznált területe. engine: "max" esetén ezt a táblát utána maga a keresés is újrarakja — a tábla magassága mentén, egytáblás tervnél a szélessége mentén is —, és ugyanazon szabály szerint a szorosabb elrendezést tartja meg. A táblaszám, a méretek, az ár és az elhelyezett darabok sosem változnak; az options.compact: false a tömörítetlen elrendezést adja vissza. Ha egy sávot számlázol a befoglaló téglalap helyett, állítsd be az options.compactFor mezőt ennek megfelelően: a "horizontal" a legkisebb usedHeight értékű elrendezést tartja meg (egy sáv a tábla teljes szélességén át), a "vertical" a legkisebb usedWidth értékűt (egy sáv a tábla teljes magasságán át); az alapértelmezett "box" a legkisebb usedArea-t tartja meg. A sáv-módok minden példányt negyedfordulattal (90° vagy 270°) elforgatva is kipróbálnak, ahol az allowedRotations megengedi. Az, hogy mennyire kicsi lesz a felhasznált terület, a daraboktól függ. (2026-09-22 óta.)

Korlátok

Minden kérésnek van felső határa, így egy elszaladó munka világosan elbukik, nem pedig lefagy:

Hogyan kapok hozzáférést

Kezdd az Engine API oldalon. Az Engine API az app csomagjaitól külön számlázódik, és nincs olyan csomagváltás, amely bekapcsolná.

1. Próbáld ki, aztán fizess elő — vagy kérdezz. Fizetés előtt is hívhatod az API-t: az API-referencia Példa futtatása gombjai egy nyilvános demókulcsot használnak, fiók nélkül, és minden bejelentkezett fiók készíthet ingyenes teszt-kulcsot az irányítópulton (saját, kis havi keret, soha nem számlázódik, előfizetés nem kell hozzá). Ha készen állsz, az Engine API oldalon történő előfizetés a leggyorsabb út — a belépő csomag, a Studio ingyenes próbaidővel indul, és a hozzáférés magától felkerül a fiókodra. Ha inkább előbb leírnád az integrációdat, vagy a standard csomagnál nagyobb mennyiség kell, vedd fel velünk a kapcsolatot, és írd le, mit szeretnél összekötni, és körülbelül hány vágástervre lesz szüksége havonta.
2. A hozzáférés felkerül a fiókodra. A fiókodon semmi más nem változik.
3. Készíts kulcsot. Az API-kulcsok kártya minden bejelentkezett fiók irányítópultján ott van: előfizetés nélkül teszt-kulcsokat készít, API-hozzáféréssel éles kulcsokat is. A kulcsokat ott magad készíted el, nevezed el és törlöd.
4. Másold ki a kulcsot azonnal. A teljes kulcsot pontosan egyszer mutatjuk meg: a létrehozás pillanatában.

A kulcsot kezeld úgy, mint egy jelszót: a szoftvered konfigurációjában van a helye, nem e-mailben, táblázatban vagy képernyőképen.

Mit csinál az API-kulcsok kártya az irányítópultodon

Négy vezérlő — és érdemes pontosan kimondani, melyik mit változtat, különösen az utolsót, amiről sokan azt hiszik, a számlázáshoz nyúl. Nem nyúl.

• Csomag, Váltás és Számlázás. A Csomag sor megmutatja, melyik csomagon van a fiók (Studio vagy Scale). A Váltás: Scale (vagy Váltás: Studio) gomb megerősítés után megváltoztatja a csomagot, és a fiók havi kvótája azonnal módosul. A Számlázás megnyitja a számlázási beállításaidat, ahol kártyát cserélhetsz, számlákat nézhetsz meg vagy lemondhatod az előfizetést.
• Kulcs létrehozása. Létrehoz egy új kulcsot, és egyetlen egyszer meg is mutatja, ott helyben. A név (ERP-integráció, staging) kizárólag arra való, hogy később meg tudd különböztetni a kulcsaidat. Fiókonként legfeljebb 10 aktív kulcs. A teszt-kulcsokat ugyanígy készíted, és külön számolódnak: saját, kis havi keretük van, és soha nem számlázódnak.
• A használati sáv. Két szám: a fiókod havi összesített felhasználása a kvótához mérve, és kulcsonként az, hogy az a kulcs mennyit fogyasztott. A kulcsonkénti szám arra válaszol, hogy melyik integráció eszi a keretet — nem külön költségvetés.
• Visszavonás. A következő hívástól kezdve leállítja azt az egy kulcsot. A sor látható marad, hogy az előzménye ne vesszen el.

Egy kvóta a fiókra, nem kulcsonként egy

A fiókod minden aktív kulcsa ugyanabból a havi keretből fogyaszt. Egy második kulcs nem hoz létre második kvótát — a kulcsok arra valók, hogy szétválaszd a stagingot az élestől, minden integrációnak saját azonosítót adj, és egyet visszavonhass anélkül, hogy a többit zavarnád.

A GET /v1/usage a fiók állását adja vissza (used, limit, remaining), tehát arra a kérdésre válaszol, ami valóban érdekel — mennyi maradt, mielőtt a hívások elkezdenek elhasalni —, függetlenül attól, melyik kulccsal kérdeztél. Ha elfogy a keret, minden kulcs 402-t ad, nem csak az, amelyik elhasználta.

Csomagok, ár és kvóta

Az Engine API-t az app csomagjaitól külön számlázzuk, havonta, euróban, két csomaggal:

Minden más azonos mindkettőn: ugyanazok a motorok, mind a négy mód, minden beállítás, ugyanazok a válaszok. Minden kérés ugyanannyit számít — egy nesting-munka egy kérésbe kerül, pont úgy, mint egy 2D vagy 1D.

• Kemény plafon, túlhasználat nélkül. Amikor a havi kvóta elfogy, a hívások 402-t adnak, amíg a kvóta a következő hónap első napján vissza nem áll. Nincs váratlan számla.
• Két e-mail, hogy a plafon ne lepjen meg. A kvóta 90 százalékánál e-mailt küldünk a fióknak, és még egyet, amikor elfogyott.
• A csomagváltás egyetlen gomb az irányítópultod API-kulcsok kártyáján (Váltás: Scale / Váltás: Studio); az új kvóta azonnal érvényes. A magasabb csomagra váltást a hátralévő időszakra azonnal felszámoljuk; az alacsonyabbra váltásnál nincs visszatérítés, az alacsonyabb díj a következő megújulástól jár. A váltás a próbaidő után érhető el.
• A Scale-nél nagyobb mennyiségeket egyedileg áraljuk — vedd fel velünk a kapcsolatot.

Az aktuális árakat és kvótákat az Engine API oldal tartalmazza — az az oldal az árazási konfigurációnkból olvassa ki őket, tehát ott mindig a pontos szám szerepel.

A technikai részletekhez — a pontos kérés- és válaszszerkezethez, minden beállításhoz, az összes hibakódhoz és a verziózás működéséhez — lásd az API-referenciát.

Nyílt forráskódú komponensek

A CutOptim motorjai nyílt forráskódú könyvtárakra épülnek, változatlan formában, a szervereinken:

• jagua-rs — a true-shape nesting mögötti geometriai ütközésmotor (MPL-2.0).
• sparrow — a nesting max motorja mögötti keresés (MIT, KU Leuven).
• PackingSolver — a 2D max motor mögötti fakeresés (MIT).

Minden, ami körülöttük van — az API, a szerződés és e motorok közti leképezés, a téglalapos pakolók és maga az app — a CutOptim saját kódja.

Amit ez nem változtat meg

Érdemes világosan kimondani, mert az Engine API-t könnyű a termék megváltozásának félreolvasni:

• Az appban futó optimalizáló változatlan. Ugyanúgy a böngésződben fut, mint eddig.
• Az Ingyenes, a Pro és a Műhely csomagot nem érinti. Továbbra is tartalmazzák az appban futó optimalizálót, a korábbi korlátokkal. Semmi nem került az API mögé.
• Amit az appban teszel, az nem fogyaszt API-kérést. A havi API-kvótához csak a saját szoftvered hívásai nyúlnak hozzá.

Az Engine API azoknak szóló kiegészítés, akik a CutOptimot más szoftverbe illesztik. Ha nem közéjük tartozol, számodra semmi nem változott.