Stitch Surgeon — používateľský manuál

1. Na čo je Stitch Surgeon

Stitch Surgeon je texture atlas packer a sprite-sheet builder — nie nástroj na švy dlaždíc a nie map editor. Prinesieš jednotlivé obrázky spritov; appka ich zloží na jeden sheet (alebo na ďalšie sheety, keď sa nezmestia) a vie k nemu zapísať metadata framov.

• Shelf packing — sprity sedia vo vodorovných radoch (poličkách). Dobré pri zmiešaných veľkostiach.
• Fixed cell grid — každý sprite má rovnakú bunku. Dobré pre jednotné ikony, dlaždice alebo animačné framely.
• Extra sheets — zvyšok, čo sa nezmestí do Max W/H, ide na atlas-2, atlas-3, … (fajka vedľa Shelf / Fixed Cell; vypnuté = overflow na prvom sheete).
• Výstup — PNG, lossless alebo lossy WebP, nekomprimované PVR, GPU PVR (PVRTC / ETC2 / ASTC) alebo KTX2, plus voliteľný JSON a PNG nástroje (pngquant, oxipng).

2. Upozornenie a limity

• Tvoj obsah ostáva tvoj. Exportované atlasy, JSON a projekty, ktoré vytvoríš, ostávajú tvojím majetkom. Za legalitu importovaných obrázkov zodpovedáš ty.
• Nie je to blender dlaždíc. Štvorcové / izometrické / hex autotily patria Tile Surgeonu. Táto appka skladá obdĺžniky na sheet.
• Projekt ukladá cesty, nie pixely. Súbor .atlas.json si pamätá umiestnenie spritov (relatívne k projektu) a nastavenia packingu. Autosave draft ostáva na absolútnych cestách. Ak súbory presunieš alebo premenuješ, pri otvorení uvidíš varovanie.
• Overflow je reálny. Sprite väčší než Max W/H sa nezmestí. S vypnutým Extra sheets ostane zvyšok ako overflow na prvom sheete (pri exporte treba potvrdiť). So zapnutým Extra sheets ide zvyšok na atlas-2, atlas-3, …
• Licencia. 1 nákup = 1 seat (honor system, bez kľúča). Tú seat môžeš nainštalovať na stroje, ktoré osobne používaš. Oficiálne podmienky: EULA v appke. Tento manuál je dokumentácia a EULA nemení.

3. Rýchly štart (5 minút)

1. Klikni Load Samples (alebo Add Sprites… / pretiahni obrázky na okno).
2. Vyber Shelf Packing alebo Fixed Cell Grid. Fajka Extra sheets je v tom istom riadku (predvolene zapnutá).
3. Nastav Max Width / Max Height (alebo Power of 2).
4. Uprav Sprite Border a Extrude, ak potrebuješ padding proti bleed.
5. Sleduj LIVE PREVIEW vpravo — zoom kolieskom, pan stredným tlačidlom myši.
6. Voliteľne zapni Export JSON metadata pre Phaser-style hash loadery. Unity a Godot zvyčajne režu PNG.
7. Klikni Export v toolbare alebo Build & Export Atlas dole v Export Options a vyber priečinok. Obrázok (a JSON) sa píšu zvlášť od uloženia projektu.

Často ukladaj cez Ctrl+S. To uloží nastavenia + cesty k spritom ako .atlas.json, nie samotný atlas.

4. Prehľad UI

Predvolené okno je 1440×900. Väčší monitor pomáha; ľavý stĺpec sa scrolluje samostatne.

5. Pridávanie spritov

• Add Sprites… — jeden alebo viac súborov.
• Add Folder… — prejde priečinok a berie podporované obrázky.
• Drag and drop na okno (Windows inštalátor).
• Load Samples — vyskúšaj packing bez vlastného umenia.
• Clear List / Sort A→Z — vyprázdni alebo zorad stack.

Import: .png, .jpg / .jpeg, .webp, .bmp, .tga, .tif / .tiff, .gif, .avif, .pvr, .ktx2. Animovaný GIF / AVIF / WebP berie prvý frame. GPU .pvr / .ktx2 dekóduje bundled PVRTexToolCLI.

Stav zoznamu ukazuje unique vs listed. Značky:

• ≡ — alias (identické pixely; balí sa raz, v JSON je každý názov)
• ⚙ — sprite má overridy (škála, pivot, zarovnanie bunky…)
• Overflow — sprite sa nezmestí na žiadny sheet (väčší než Max W/H, alebo je Extra sheets vypnuté). Pri extra sheetech je pod ┌ Overflow.
• So zapnutým Extra sheets zoznam zoskupí riadky pod ┌ Sheet 1, ┌ Sheet 2, …

6. Výber a zmena poradia

• Klik na riadok v zozname alebo na sprite v preview ho vyberie. Klik do prázdna v preview (alebo pod zoznamom) výber zruší.
• Keď je vybraných viac spritov, klik na jeden riadok v zozname nechá len ten (Shift / Ctrl stále pridáva alebo prepína).
• V preview Shift+klik alebo Shift+lasso (ťahanie prázdneho miesta) pridá do výberu.
• Ťahaním v zozname alebo v preview zmeníš poradie packingu.
• Delete alebo Backspace odstráni výber z projektu (súbory na disku nemaže).
• Escape zruší prebiehajúce lasso alebo drag.

7. Layout a packing

7.1 Módy

V tom istom riadku je Extra sheets (predvolene zapnuté). Zvyšok ide na atlas-2, atlas-3, … Keď extra sheety prvýkrát pribudnú, dialóg ponúkne Extra sheets (nechať plniť) alebo One sheet (vypnúť Extra sheets; zvyšok ostane overflow na prvom atlase). Extra sheets vieš neskôr znova zaškrtnúť v tom riadku. Sprite väčší než Max W/H sa nezmestí ani tak.

7.2 Limity veľkosti

• Free size — sheet rastie do Max Width × Max Height.
• Power of 2 (POT) — 512, 1024, 2048, 4096, 8192, 16384. Prepoj W/H, ak chceš štvorcový POT.
• Fixed size — exportuje plné rozmery atlasu, aj keď sprity sheet nevyplnia.

7.3 Padding

• Atlas Outer Border — prázdny okraj okolo celého sheetu.
• Sprite Border — medzera medzi spritmi.
• Extrude — opakuje pixely hrany (pomáha proti bleed pri GPU filtrovaní). V engine max 32 px.

7.4 Len shelf

Align rows — hore / stred / dole v poličke, keď sa výšky líšia.

7.5 Len fixed-cell

• Šírka × výška bunky, Auto, Auto-max, Fit (škála spritu do bunky).
• Globálne 9-grid zarovnanie, plus override per sprite a offset X/Y.

8. Vybraný sprite a features

• Sprite Scale Override — zmenši alebo zväčši jeden sprite pred packingom (presety 0.25–2.0).
• Share identical sprites in atlas — rovnaké pixely zdieľajú jeden slot; JSON stále vypíše každý názov. Odškrtni, ak chceš kópie baliť zvlášť.
• Enable Pivot Customization — normalizovaný pivot X/Y (0–1) s 3×3 mriežkou. Ide do JSON pre enginy, ktoré čítajú pivot.
• Trim transparent pixels (Sprite Features) — orezanie na viditeľné pixely pred packingom (menšie bunky / tesnejšie poličky).

9. Atlas Adjust

Hue, saturácia, jas, kontrast (percentá) a gamma (faktor, napr. 2.2) platia na celý atlas v live preview aj v exportovanom obrázku. Zdrojové súbory neprepisuje. Reset na slideri (alebo Reset karty) vráti predvolené hodnoty.

Farebná úprava je náhľad exportu: PNG / WebP / nekomprimované PVR dostanú to, čo vidíš. GPU kompresia začína z tohto upraveného RGBA.

10. Live preview

Pravé plátno sa prekresľuje pri zmene nastavení. Stavový riadok hlási export W×H, počet overflow, alebo Extra sheets active, keď je viac atlasov.

• Koliesko myši zoomuje; ťahanie stredným tlačidlom panuje.
• 1:1, Fit, Auto Fit — natívny alebo zarovnaný pohľad.
• Display outlines — vodítka spritu (a bunky).
• Under Layer — Checker, biela alebo čierna.
• Pager sheetov — keď Extra sheets zbalí viac atlasov, < Sheet i/n > je vpravo v riadku Under Layer. Ľavá šípka je predchádzajúci sheet, pravá ďalší. Pri jednom sheete sa schová.

11. Projekty, autosave, undo

• Ctrl+S Save / Ctrl+Shift+S Save As… → .atlas.json (formát atlas-builder-project, verzia 2).
• Uložený projekt drží cesty k spritom relatívne k súboru projektu, keď sú na rovnakom disku. Presuň .atlas.json aj priečinok spritov spolu a Open ich nájde.
• Autosave draft po páde ostáva na absolútnych cestách (nie je na kopírovanie medzi PC).
• Ctrl+O otvorí projekt. Chýbajúce cesty dajú varovanie; ostatné sprity sa načítajú.
• Zatvorenie špinavého projektu sa spýta na uloženie. Autosave vie obnoviť prácu po páde (v balíku: %LOCALAPPDATA%\StitchSurgeon\).
• Ctrl+Z / Ctrl+Y undo a redo packingu a layoutu (nie výberu). História je ohraničená (okolo 40 krokov).

12. Export

1. Vyber Texture Format (tabuľka nižšie).
2. Voliteľne Export JSON metadata.
3. Pri PNG: voliteľne Optimize PNG (8-bit Quantization) (pngquant) a/alebo Lossless PNG recompress (oxipng). Obe sú v utils/.
4. Pri GPU PVR / KTX2: voliteľne Premultiply alpha a Flip PVR / KTX2 (zvislé otočenie — vyžaduje Unity a niektoré iné enginy).
5. Nastav výstupný priečinok a klikni Build & Export Atlas (alebo toolbar Export). Pri overflow (sprite, ktorý sa stále nezmestí) potvrď, či pokračovať. So zapnutým Extra sheets pribudnú name-2, name-3 vedľa zvolenej cesty (rovnaký basename, JSON ak je zapnutý).

Slidery WebP quality / alpha quality platia len pre WebP (Lossy). Live preview nemenia. Dlhý export vieš zrušiť z progress ovládača v päte preview.

13. JSON metadata

Keď je zapnuté, JSON má rovnaký basename ako obrázok atlasu. Je to hash JSON (framy podľa mena, recty, trim, pivot). Phaser 3 a podobné hash loadery ho vedia zjesť. Unity a Godot zvyčajne použijú exportovaný obrázok (Sprite Editor / AtlasTexture), nie tento súbor ako natívny importer. Pred batchom over jeden frame v engine.

• meta.app — "Stitch Surgeon"
• meta.version — verzia appky (napr. 1.2.0)
• meta.format — pixelový formát (napr. RGBA8888, PVRTC4, ETC2)
• meta.image, meta.size, meta.bounds, meta.scale, meta.overflow
• frames — každý sprite: frame, spriteSourceSize, sourceSize, pivot, trimmed, rotated

14. Skratky

15. FAQ a tipy

Sprity sa nezmestia

Nechaj zapnuté Extra sheets (riadok vedľa Shelf / Fixed Cell) — zvyšok pôjde na ďalšie atlasy. Ak si v dialógu zvolil One sheet, zaškrtni Extra sheets znova tam. Zväčši Max Width/Height, daj väčší POT, zníž škálu, alebo zapni trim. Sprite väčší než Max W/H sa nezmestí. Overflow svieti v zozname pod ┌ Overflow.

Filtrovanie / halo na hranách

Zvýš Extrude a trochu Sprite Border. Ak engine vyžaduje POT, použi ho.

Unity PVR / KTX2 je hore nohami

Zapni Flip PVR / KTX2 na karte Export pred buildom.

PVRTC sheet je väčší, než čakáš

PVRTC vždy dopĺňa na štvorcový power-of-two. To je obmedzenie formátu, nie chyba packingu.

Drag-and-drop nič nerobí

Použi Add Sprites… / Add Folder…. Dodaný Windows build podporuje drop na okno.

Optimize PNG nič nerobí

pngquant / oxipng sú v utils/ vedľa appky. Ak chýbajú, export aj tak zapíše 32-bit PNG a stavový riadok to povie.

GPU export hlási chýbajúce CLI

Daj PVRTexToolCLI.exe do utils/ (inštalátor to už robí). Nekomprimované PVR ide aj bez neho.

Projekt sa otvoril prázdny

Zdrojové súbory sa presunuli. Vráť ich, alebo sprity pridaj znova a Save As nový projekt. Relatívne cesty pomôžu len ak ide projekt aj sprity spolu.

Crash log

Balík: %LOCALAPPDATA%\StitchSurgeon\error.log. Dev: .atlas_builder_data\error.log.