API referenca

Osnovni URL https://api.cutoptim.com · verzija ugovora v1

Kreirajte ključ na svojoj nadzornoj ploči, zatim ga pošaljite kao Authorization: Bearer <key>.

OpenAPI specifikacija: /engine/openapi.json

Endpointi

Jedinice

API je neovisan o jedinicama. Odaberite jednu jedinicu — milimetre, inče, bilo što — koristite je za svaki broj koji šaljete, i svaki broj koji dobijete natrag u istoj je jedinici. Ništa se ne pretvara na strani poslužitelja i nijedan naziv polja ne određuje jedinicu.

To obuhvaća dimenzije dijelova i zalihe, kerf, tolerance, trim i minOffcut na ulazu, te svaku koordinatu, poziciju, preostalu duljinu, ostatak i duljinu reza na izlazu. Miješanje jedinica unutar jednog zahtjeva daje plan koji prolazi validaciju, a fizički je pogrešan — i poslužitelj to ne može otkriti.

Koordinatni sustav

Ishodište je gornji lijevi kut ploče: x raste udesno duž širine ploče, y raste prema dolje duž visine ploče. x i y dijela njegov su gornji lijevi kut, a w i h dimenzije su kako je postavljen — već zamijenjene kada je rotated true — tako da je pravokutnik x, y, w, h otisak na ploči bez daljnjeg računanja. Pravokutnici ostataka koriste isti sustav.

Obrez pomiče postavljanja: trim.left pomiče svaki dio udesno, a trim.top pomiče svaki dio prema dolje, jer se dijelovi ugnježđuju unutar iskoristive površine, a zatim se ponovno pomiču natrag na cijelu ploču. trim.right i trim.bottom smanjuju iskoristivu površinu bez pomicanja ishodišta. w i h ploče uvijek su pune dimenzije zalihe, uključujući obrez — zbog čega se obrez u yieldPct broji kao otpad.

2D — zahtjev

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

Polja dijela

Polja zalihe

w i h su obavezni. qty je zadano 1 i čvrsto je ograničenje samo uz respectStock. price je po ploči i pokreće totalPrice i način troška. priority (boolean) troši ovu zalihu prvu; material (slobodan niz) ograničava je na dijelove istog materijala.

Opcije

include radi dvije stvari. SUŽAVANJE — "cutPlan" i "offcuts" uključeni su prema zadanom; prisutan niz zadržava samo tokene sužavanja koje navodi (prazan niz izbacuje oba). ADITIVNI IZVOZ — "svg", "csv" i "dxf" svaki dodaje taj izvoz u odgovor kao STRING: svg samostalni 2D crtež rasporeda (samo 2D — 1d/wood zahtjev umjesto toga vraća upozorenje), dxf R12/AC1009 crtež na slojevima STOCK/PARTS/LABELS, csv popis rezanja. Tokeni izvoza ne utječu na sužavanje, pa include:["svg"] dodaje svg i — ne imenujući nijedan token sužavanja — izbacuje cutPlan/offcuts; koristite ["cutPlan","offcuts","svg"] da zadržite sve i dodate svg.

Opcija effort odmjerava vrijeme izračuna naspram iskoristivosti. Evo tog kompromisa, izmjerenog na jednom zahtjevnom zadatku — svaka brojka dolazi iz stvarnog packera.

I ionako je brzo: čak i najveći proizvodni poslovi — 2.000 dijelova i više — rješavaju se u nekoliko sekundi na zadanom motoru, ugodno unutar vremenskog proračuna API-ja.

2D — odgovor

{
  "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 spaja kolinearne rezove (jedna postavka graničnika); sawPasses broji svaki prolaz. Dvije poštene mjere istog plana, a ne tvrdnja da se poklapaju s brojem bilo kojeg konkurenta.
• guillotineValid / cutPlan — Kada se raspored ne može izrezati od ruba do ruba, guillotineValid je false, a cutPlan je null. To je stvarna informacija — ne može se izraditi na pili za ploče — a ne greška.
• unplaced + warnings — Neizvediv zadatak vraća 200 s komadima navedenima u unplaced i napomenom u warnings. Plan po kojem možete djelovati vrijedi više od statusnog koda.
• edgeBanding — Kada bilo koji dio nosi edgeBanding, odgovor dodaje edgeBanding blok: linearne metre koje svaka referenca tipa troši, po dijelu i kao ukupno za narudžbu. To je točna geometrija bez dodatka za otpad — radionica ga dodaje sama — i pretpostavlja unos u milimetrima (÷1000 za metre). Ključ potpuno izostaje za zadatak bez kantiranja.
• materials / unmatchedMaterials — Kada bilo koji dio ili zaliha nosi material, odgovor dodaje materials (zbroj po materijalu — material, sheetCount/rodCount, yieldPct, placed, total, totalPrice) i unmatchedMaterials (potražnja čiji material nema odgovarajuću zalihu). Kod drva material umjesto toga ide po odjeljku poprečnog presjeka. Oba ključa izostaju za zadatak bez materijala, koji ostaje bajt-istovjetan.

Polja odgovora

Nazivi i tipovi polja su ugovor, pa donje tablice ostaju na engleskom u svakom jeziku — prevedeni naziv polja dokumentirao bi API koji ne postoji.

2D · edgeBanding

Kada bilo koji dio nosi edgeBanding, odgovor dodaje edgeBanding blok: linearne metre koje svaka referenca tipa troši, po dijelu i kao ukupno za narudžbu. To je točna geometrija bez dodatka za otpad — radionica ga dodaje sama — i pretpostavlja unos u milimetrima (÷1000 za metre). Ključ potpuno izostaje za zadatak bez kantiranja.

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

Kada bilo koji dio ili zaliha nosi material, odgovor dodaje materials (zbroj po materijalu — material, sheetCount/rodCount, yieldPct, placed, total, totalPrice) i unmatchedMaterials (potražnja čiji material nema odgovarajuću zalihu). Kod drva material umjesto toga ide po odjeljku poprečnog presjeka. Oba ključa izostaju za zadatak bez materijala, koji ostaje bajt-istovjetan.

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 — što jedan step fizički znači

step je jedno kretanje lista pile, a popis je poredan kako zapravo možete piliti: nadređeni rez prije rezova unutar komada koji je proizveo, jer ne možete poprečno rezati traku prije nego što ste je uzdužno odvojili. axis "h" znači da list pile putuje duž x i odvaja gornje od donjeg; axis "v" znači da putuje duž y i odvaja lijevo od desnog. pos je rub lista pile s NAJNIŽOM koordinatom — vrijednost y za "h", vrijednost x za "v" — a ne njegova središnja linija: kerf zauzima od pos do pos + kerf, pa list pile jede u smjeru u kojem koordinata raste, što je prema dolje za "h" i udesno za "v". Materijal na niskoj strani linije — iznad nje za "h", lijevo od nje za "v" — komad je koji taj rez oslobađa. length je koliko daleko list pile putuje pri tom jednom rezu: opseg područja koje prelazi, a ne širina cijele ploče.

stage je prolaz stroja. Počinje od 1 i povećava se samo kada axis promijeni smjer u odnosu na nadređeni rez, pa je uzdužno rezanje ploče u šest traka jedna faza, a njihovo poprečno rezanje sljedeća. To je smisao „trostupanjskog rezanja“ kod pile za ploče, a ne dubina stabla rezanja, i upravo to ograničava maxCutStages. sheet je indeks u sheets s bazom 0, a step se ponovno pokreće od 1 na svakoj ploči umjesto da teče kroz cijeli zadatak.

cutPlan je null — ne nedostajuće, ne prazno — kad god je guillotineValid false: raspored koji se ne može izrezati od ruba do ruba nema slijed rezanja za vratiti. Potpuno izostaje iz sadržaja ako ste ga izostavili iz include.

1D — linearno

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

Dijelovi uzimaju length (uz qty, name, priority); zaliha uzima length, qty i price. I dijelovi i zaliha također prihvaćaju opcionalnu oznaku material (zaliha i priority) — material ograničava dio na zalihu istog materijala, a odgovor tada dodaje materials i unmatchedMaterials kao u 2D-u. Opcije su kerf, tolerance, trim.start / trim.end, minimizeCost, respectStock i minOffcut. Odgovor vraća rods umjesto sheets, svaki sa svojim dijelovima, preostalom duljinom i ostacima.

1D — odgovor

{
  "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 zamjenjuje sheets i nema guillotineValid, jer je linearni rez uvijek izvediv. pos svakog dijela je pomak njegovog bližeg kraja od onog kraja šipke koji trim.start reže, pa prvi dio počinje točno na trim.start, a svaki sljedeći pos dodaje jedan kerf. remaining je ISKORISTIVI ostatak: kerf reza koji ga oslobađa od posljednjeg komada već je odbijen, pa je to duljina koja se može ponovno iskoristiti, a ne sirovi razmak. Prijavljuje se na svakoj šipki čak i kad je ispod minOffcut — minOffcut filtrira samo polje offcuts, koje sadrži najviše jedan unos. U planu rezanja, sheet je indeks šipke, axis je uvijek "v", stage je uvijek 1, a length je uvijek 0: poprečni rez šipke nema udaljenost putovanja za prijaviti, zbog čega 1D metrike nose cuts, ali ne i cutLength.

Drvo — poprečni presjek

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

Drvo ima identitet koji obična šipka nema: dio 50×150 ne može izaći iz zalihe 50×100, koliko god duljine preostalo. Dijelovi i zaliha stoga nose sw i sh, dvije strane poprečnog presjeka, bilo kojim redom — 50×100 i 100×50 ista su okrenuta greda i usklađuju se kao jedan presjek. Zadatak se dijeli prema poprečnom presjeku, svaki se presjek usklađuje s vlastitom zalihom i rješava zasebno, a jedan poziv vraća cjelinu. Dijelovi i zaliha također prihvaćaju opcionalnu oznaku material (zaliha i priority): s njom, hrast 50×100 i bor 50×100 postaju dva zasebna odjeljka, a svaki odjeljak nosi svoj materijal. Opcije su iste kao kod 1D.

Drvo — odgovor

{
  "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 zamjenjuje rods na najvišoj razini: svaki unos je jedan poprečni presjek s vlastitim rods (identičnog oblika kao 1D) i vlastitim metrics, pa su brojke po materijalu tu bez ponovnog izračuna. unmatched nema ekvivalent u 1D — to je potražnja za čiji poprečni presjek uopće niste dali zalihu, što je drugačiji problem od unplaced (dijelovi koji su imali zalihu i nisu stali) i ima drugačije rješenje, pa se to dvoje nikada ne miješa. metrics.total broji svaki komad koji ste tražili, uključujući unmatched. U planu rezanja svaki step također imenuje svoj section, a sheet je indeks šipke UNUTAR tog presjeka, a ne brojač za cijeli zadatak.

True-shape ugnježđivanje

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

Tri gornja načina rada pakiraju pravokutnike. POST /v1/optimize/nest pakira PROIZVOLJNE POLIGONE: dio je obris (polygon, s neobaveznim unutarnjim holes), a ne širina×visina, pa se dijelovi uklapaju u konkavne džepove jedan drugoga i zrak u urezu koji granični okvir troši ponovno se iskorištava — na reprezentativnom zadatku, 6 ploča ondje gdje isti dijelovi prema graničnom okviru trebaju 9. To je drugačija klasa algoritma (geometrijski motor kolizija, a ne giljotinski pakirač), za rezanje laserom, plazmom i vodenim mlazom. Uz to dolaze dvije stvari koje pravokutni API ne može izraziti: zone isključenja po ploči (stock[].exclusions — defekt, otisak stezaljke, prethodno otisnuto područje; zona s quality 0 zabranjeno je područje za bilo koji dio) i true-shape rupe. material particija i prosljeđivanje meta rade kao i svugdje drugdje. Primjer u nastavku jedan je stvarni zabilježeni poziv — osam dijelova na jednoj ploči s isključenim oštećenim kutom.

Nest — odgovor

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

Svaki unos u sheets jedna je iskorištena ploča; postavljeni dio nosi kruti transform (rotation u stupnjevima, zatim x/y translaciju), a NE ponovno ispisani poligon — zakrenite svoj ulazni obris za rotation oko njegovog ishodišta i dodajte (x, y) da točno rekonstruirate postavljanje. rotation može biti negativan; rekonstrukcija je točna bez obzira na predznak. ⚠️ density je površina postavljenog POLIGONA naspram površine iskorištene ploče — pošteno popunjenje, uz konkavne džepove brojene kao prazne — i NIJE usporediva s yieldPct pravokutnog pakirača (koji svaki granični okvir broji kao pun, pa čita više za lošiji rezultat); usporediva metrika između njih dvije jest sheetCount na istim dijelovima. Raspored je determinističan: postavite options.seed da ga reproducirate. exclusions se ponavlja na svakoj ploči za prikaz.

Dijelovi iz datoteke (SVG · DXF)

Dio ne mora stići kao koordinate. Stavite SVG ili DXF dokument u parts[].source i poslužitelj iz njega izvlači obris — i njegove rupe — istim čitačem koji CutOptim aplikacija koristi kad crtež ispustite na njezin Nesting način. Datoteka zamjenjuje SAMO geometriju: qty, material, allowedRotations, minQuality, priority i meta ponašaju se točno kao na polygon dijelu, pa knjižnica dijelova koja već postoji kao CAD datoteke ne traži vlastito rastavljanje krivulja i lukova. Jedan source opisuje JEDAN dio; crtež s više odvojenih komponenti vraća 400 i upućuje na uvozni endpoint niže. Odgovor tada nosi imported blok: koliko je redaka došlo iz datoteke, koliko su vrhova proizveli i koje su jedinice te datoteke deklarirale — prijavljeno, nikad primijenjeno, jer ovaj API ništa ne pretvara.

Ništa se ne pohranjuje. Bajtovi postoje isključivo kao tijelo zahtjeva, obrađuju se u memoriji i nestaju kad se odgovor ispiše: bez diska, bez baze podataka, bez privremene datoteke, bez zapisa u dnevniku. Poslije nema što obrisati i ništa ne ostaje — ista bezstanjnost koju drži svaki drugi 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 }]
}

Nazivi i tipovi polja su ugovor, pa donje tablice ostaju na engleskom u svakom jeziku — prevedeni naziv polja dokumentirao bi API koji ne postoji.

{
  "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 — jedna datoteka, svi obrisi

Kad jedan crtež sadrži više različitih dijelova, prvo ga uvezite: ovaj endpoint vraća svaki zatvoreni obris koji sadrži, počevši od najvećeg, točno u obliku koji redak parts[] očekuje. Zalijepite one koji vam trebaju, dodajte vlastiti qty i material i to pošaljite na /v1/optimize/nest. To je i način da vidite što je u datoteci prije nego na nju potrošite izračun. Traži ključ — rastavljanje proizvoljne geometrije stvaran je posao procesora, a anonimni procesor loša je pogodba — ali ništa ne rezervira: vaša kvota ostaje netaknuta i ne vraćaju se rate limit zaglavlja, jednako kao pri dohvaćanju joba.

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

Motori

• heuristic (zadano) — giljotinski pakirač s više strategija. Najveća iskoristivost, svaki raspored može se izrezati na pili, uvijek potpuni cutPlan.
• balanced — MaxRects pakirač sa slobodnim ugnježđivanjem. Znatno brži na velikim zadacima (izmjereno ~25× pri 2.000 dijelova) uz malu cijenu iskoristivosti, a njegovi rasporedi često nisu giljotinski (guillotineValid: false, cutPlan: null). Ne modelira tolerance, minimizeCost, grainGroup, maxCutStages ni minimizeRotations — postavite jedno i upozorenje vam kaže da je zanemareno.
• max — asinkroni sloj s pretraživanjem stabla (samo 2D): doseže dokazani optimum na znatno više zadataka po cijenu od nekoliko sekundi do minute po izračunu. I dalje determinističan i giljotinski valjan. Ne vraća plan izravno — vidi Asinkroni poslovi u nastavku. Modelira JEDAN format zaliha u punoj veličini ploče, u neograničenoj količini i s fiksnim 3-faznim giljotinskim uzorkom: drugi redak zaliha, trim, respectStock, material ili grainGroup odbijaju se kodom 400 prije nego što se poziv rezervira; tolerance, minimizeCost, maxCutStages, minimizeRotations, firstCut i effort prolaze, ali se zanemaruju uz upozorenje, a max rezultat ne prijavljuje otpatke. Takve poslove šaljite motoru heuristic.

Asinkroni poslovi (engine = max)

max izračun traje od nekoliko sekundi do minute, pa POST /v1/optimize/2d s engine:"max" ne vraća plan — vraća 202 Accepted s jobId, a poziv se naplaćuje pri predaji. Ispitujte GET /v1/jobs/{id} dok status ne bude "succeeded" (result tada sadrži isti 2D odgovor koji vraća sinkroni izračun) ili "failed" (error sadrži poruku). Ispitivanje ne troši kvotu; vidite samo vlastite poslove. Ondje gdje sloj nije omogućen na instalaciji, engine:"max" odbija se — fail closed — s 503.

Determinizam i verzioniranje

Svaki odgovor nosi engineVersion. Algoritam je determinističan, pa njegovo poboljšanje mijenja izlaz za isti ulaz — što je breaking change ako predmemorirate. Fiksirajte ponašanje tako da eksplicitno šaljete engine i pratite engineVersion; verzija putanje /v1/ mijenja se samo ako se promijeni struktura odgovora.

Svaki se motor verzionira neovisno, pa promjena jednog nikada ne pomiče verziju drugog.

Greške

Tijelo greške

Svaka greška koju sam motor proizvede koristi istu omotnicu. Grananje radite prema error, koji je stabilan kod; nikada prema message, čiji se tekst može promijeniti između izdanja. details je prisutan kod invalid_request, gdje path imenuje problematično polje, i kod too_large, gdje max i got daju ograničenje i ono što ste 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 oboje nose Retry-After zaglavlje u sekundama. Kod 402 odbrojava do resetiranja kvote u 00:00 UTC prvog dana sljedećeg mjeseca; kod 429 riječ je o kratkom odgađanju, a 429 nikada ne troši kvotu — rezervirani poziv se vraća.
• Greška usmjeravanja odgovara s not_found, kodom namjerno izvan gornjeg popisa jer ga proizvodi usmjerivač, a ne API ugovor. Dobivate 404, a ne 405, kada je putanja ispravna, ali je metoda pogrešna: sva četiri endpointa za optimizaciju primaju isključivo POST.
• Na pravokutnim rutama 504 dolazi od reverse proxyja, ne od motora, pa je njegovo tijelo proxyjevo, a ne ova JSON omotnica; unutar donjih ograničenja ulaza trebao bi biti nedostižan. Iznimka je /v1/optimize/nest: taj je izračun podproces s vlastitim proračunom, namjerno držanim ispod granice proxyja, pa istek vremena ondje koristi ovu omotnicu, s kodom solve_timeout.

Zaglavlja ograničenja brzine

Uspješan poziv optimizacije nosi X-RateLimit-Limit (mjesečno ograničenje RAČUNA — svi ključevi računa dijele jedno) i X-RateLimit-Remaining (preostali pozivi računa ovaj mjesec, nakon ovoga). Šalju ih samo endpointi za optimizaciju: brojač se rezervira kao dio autorizacije izračuna, pa /v1/usage i /v1/health nemaju što prijaviti.

GET /v1/usage

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

Samo za čitanje: ne troši poziv i ne šalje zaglavlja ograničenja brzine. ⚠️ used i limit opisuju RAČUN, a ne ključ kojim ste pozvali: svaki aktivni ključ na računu crpi iz jedne zajedničke dozvole, pa stvaranje više ključeva ne stvara više kvote. used broji tekući UTC kalendarski mjesec kroz sve njih, remaining je limit minus used i nikada nije negativan, periodEnd je dan resetiranja kao obični YYYY-MM-DD datum, a keyPrefix je netajni prikazni prefiks ključa kojim ste pozvali. Sam ključ nijedan endpoint nikada ne vraća — pohranjuje se samo njegov hash, pa se izgubljeni ključ zamjenjuje, a ne obnavlja.

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 ključa, bez kvote, bez baze podataka. Namjerno ne dodiruje ništa sa stanjem, tako da ispad u pohrani ključeva ne može učiniti da usluga izgleda mrtvo orkestratoru. engines navodi id-ove koje ova instalacija prihvaća u engine, a engineVersion je verzija zadanog motora.

Ograničenja

• 2,000 dijelova po zahtjevu (ukupna količina, nakon proširenja qty)
• 50 redaka zalihe · tijelo zahtjeva do 1 MB
• 10 aktivnih ključeva po računu — dijele JEDNU mjesečnu kvotu, pa ključevi razdvajaju okruženja i integracije, ne dodaju dozvolu
• 10 MB tijela zahtjeva na dvije nest rute koje mogu nositi crtež (/v1/optimize/nest i /v1/import/nest); jedna source datoteka najviše 4.000.000 znakova, 8.000.000 po zahtjevu
• konkurentnost je ograničena na poslužitelju — burst dobiva 429, nikad sporu čekaonicu. Validate krajnje točke bez ključa dodatno imaju gornju granicu po adresi (429 s Retry-After); s ključem se nikad tako ne ograničava. Račun može imati 5 max poslova istovremeno u queued/running.

OpenAPI specifikacija

Strojno čitljiv OpenAPI 3.1 dokument opisuje svih dvanaest endpointa, svako tijelo zahtjeva, svaku strukturu odgovora i svaku grešku. Usmjerite svoj generator klijenta na njega umjesto da prepisujete ovu stranicu. Sam dokument je samo na engleskom: sastoji se od ugovornih tokena, a OpenAPI nema mehanizam lokalizacije.

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

Otvorite OpenAPI 3.1 dokument →