API HandyLay

HandyLay udostępnia jeden publiczny adres HTTP, który planuje układ płytek albo paneli w opisanym pomieszczeniu. W odpowiedzi wraca liczba płytek z podziałem na całe i docinane, udział odpadu, rysunek w skali oraz link otwierający gotowy plan w planerze. Nie trzeba klucza ani konta.

Całe API to jeden adres

Zapytanie jest zwykłym GET-em, więc można je wkleić do przeglądarki albo podać asystentowi, który potrafi pobrać stronę. Poniższy adres planuje płytkę 60 × 60 cm z fugą 2 mm w pokoju 420 × 360 cm.

GET https://handylay.app/api/plan?outline=E420 S360 W420 N360&pattern=squares&tileSize=600&joint=2

Pokój ze skosem albo z wnęką opisuje się tak samo, tylko dłuższym obchodem. Ten przykład to kształt L ze słupem 40 × 40 cm w środku, wyłożony jodełką z paneli 90 × 600 mm.

GET https://handylay.app/api/plan?outline=E500 S300 W200 S200 W300 N500&subtract=200,150,40,40&pattern=herringbone&tileWidth=90&tileHeight=600

Ten sam zestaw pól przyjmuje również POST z ciałem JSON, jeśli wygodniej wywołać to z kodu.

POST /api/plan

Pomieszczenie w centymetrach, płytki w milimetrach

Wymiary pomieszczenia i punkt startowy układu podaje się w centymetrach, a rozmiary płytek i szerokość fugi w milimetrach. Ten podział odpowiada temu, skąd te liczby pochodzą: ściany mierzy się miarą, a płytkę bierze z katalogu producenta.

Pomyłka w jednostce przechodzi bez ostrzeżenia, bo płytka 20 mm jest równie poprawna co 200 mm. Kiedy wynik wygląda absurdalnie, to zwykle pierwsza rzecz do sprawdzenia.

Pomieszczenie opisuje się obchodem ścian

Parametr outline to lista ścian w kolejności, w jakiej się je mija. Każda ściana to kierunek i długość w centymetrach: E w prawo, S w dół, W w lewo, N w górę. Prostokąt 420 × 360 cm zapisuje się jako E420 S360 W420 N360.

Obchód musi wrócić do punktu startu, inaczej odpowiedź mówi, o ile się nie domyka. Kształt L to E500 S300 W200 S200 W300 N500, a każdy inny kształt złożony z prostych ścian powstaje przez dopisanie kolejnych odcinków. Ścianę pod kątem zapisuje się jako A azymut dwukropek długość, gdzie azymut liczy się w stopniach od kierunku wschodniego, zgodnie z ruchem wskazówek zegara.

Słupy, szachty i inne wycięcia odejmuje się prostokątami w parametrze subtract. Pomieszczenie, którego nie da się obejść prostymi ścianami, podaje się wprost jako listę wierzchołków w parametrze polygon.

Poza opisem pomieszczenia wszystko jest opcjonalne

Nazwy spoza poniższej listy trafiają do wzoru jako jego własne parametry, na przykład tileWidth dla jodełki. Skąd wziąć ich listę, opisuje sekcja o wzorach.

Nazwa	Znaczenie
`outline`	Ściany pomieszczenia w kolejności obchodu, na przykład E420 S360 W420 N360.
`polygon`	Wierzchołki obrysu jako pary x,y rozdzielone spacjami. Alternatywa dla outline.
`holes`	Otwory w podłodze zapisane jak polygon; kolejne pierścienie rozdziela średnik.
`subtract`	Prostokątne wycięcia w formacie x,y,szerokość,wysokość w centymetrach, rozdzielone średnikiem.
`pattern`	Układ do ułożenia. Domyślnie squares.
`joint`	Szerokość fugi w milimetrach. Domyślnie wartość własna wzoru.
`color`	Jeden kolor heksadecymalny dla wszystkich płytek motywu.
`gapColor`	Kolor fugi, heksadecymalnie.
`start`	Punkt startowy układu jako x,y w centymetrach. Ten parametr decyduje o tym, jak wypadną docinki przy ścianach.
`width`	Szerokość rysunku w pikselach.
`walls`	Rysuje pas ściany i długości ścian wokół pomieszczenia. Domyślnie włączone.
`format`	json zwraca liczby, svg sam rysunek.
`inlineSvg`	Dokłada rysunek do odpowiedzi JSON.
`credit`	Podpis handylay.app w marginesie rysunku. Domyślnie włączony.
`link`	Tworzy link do planera. Wyłącz przy porównywaniu wariantów.
`lang`	Język nazw wzorów i linku do planera: en, pl, es albo zh.

Odpowiedź niesie liczby, nie tylko obrazek

Domyślnie wraca JSON. Rysunek jest w nim adresem, a nie treścią, żeby odpowiedź dało się przeczytać bez przewijania kilku kilobajtów znaczników. Parametr inlineSvg wkleja go do środka, a format=svg zwraca sam obrazek pod tym samym adresem.

Pole warnings jest tym, na co warto zareagować przed pokazaniem planu komukolwiek. Mówi, że przy ścianach wychodzą paski nie do użycia albo że odpad jest wysoki. Zwykle wystarczy przesunąć start o pół płytki i zapytać ponownie.

Nazwa	Znaczenie
`surface.areaM2`	Powierzchnia podłogi po odjęciu wycięć, w metrach kwadratowych.
`surface.perimeterM`	Obwód pomieszczenia w metrach.
`surface.wallsCm`	Długości kolejnych ścian w centymetrach.
`pattern.parameters`	Parametry wzoru faktycznie użyte, razem z domyślnymi.
`pattern.jointMm`	Szerokość fugi w milimetrach.
`pattern.startCm`	Punkt startowy układu w centymetrach.
`tiles.total`	Liczba płytek, które trzeba kupić na ten układ.
`tiles.whole`	Z tego układanych w całości.
`tiles.cut`	Z tego wymagających docięcia.
`tiles.wastePercent`	Udział kupionego materiału, który zostaje odpadem.
`tiles.narrowestCutMm`	Najkrótszy bok docinanego kawałka. Mała wartość oznacza pasek.
`tiles.sliverCount`	Docinki wychodzące poniżej jednej dziesiątej całej płytki.
`warnings`	Co jest nie tak z tym układem i co zwykle to naprawia.
`svgUrl`	Ten sam rysunek pod własnym adresem.
`plannerUrl`	Otwiera gotowy plan w planerze, gdzie punkt startowy można przeciągnąć.

GET https://handylay.app/api/plan?outline=E420 S360 W420 N360&pattern=bricks&format=svg

Wzory opisują swoje parametry same

Każdy wzór ma własne parametry, na przykład jodełka przyjmuje tileWidth, tileHeight i direction. Zamiast zgadywać nazwy, pobiera się je z osobnego adresu, który zwraca wszystkie wzory razem z zakresami, wartościami domyślnymi i przetłumaczonymi etykietami.

GET /api/plan/patterns

Wzory dostępne w tej chwili:

squares-pattern
bricks-pattern
vertical-bricks-pattern
hexagons-pattern
flat-top-hexagons-pattern
diamonds-pattern
rhombus-pattern
isometric-cubes-pattern
herringbone-pattern
chevron-pattern

Bez klucza, ale z ograniczeniami

Endpoint jest otwarty, bo asystent idący za linkiem nie ma gdzie przechować klucza. Koszt ograniczają limity wejścia: najwyżej 20 000 płytek na jeden plan, 64 ściany w obchodzie, 32 wycięcia i pułap na wielkość pomieszczenia. Przekroczenie któregoś kończy się komunikatem mówiącym, co przysłać zamiast tego.

Liczba zapytań z jednego adresu jest ograniczona do trzydziestu na minutę. Przy porównywaniu kilku punktów startowych dopisuje się link=false, ponieważ każde zapytanie zwracające link do planera zapisuje projekt. Link bierze się dopiero z tego wywołania, którego plan idzie dalej.

Opis maszynowy leży pod dwoma adresami

Opis OpenAPI nadaje się do wpięcia endpointu jako narzędzia w asystencie albo we własnym kodzie. Plik llms.txt streszcza, czym jest HandyLay i co potrafi to API, w formie pomyślanej do czytania przez model.