# Mozaic

<img src="frontend/public/icon-192.png" alt="Ikona aplikácie Mozaic" width="144" align="left" hspace="16" style="margin: 0 16px 8px 0;">

**Online verzia:** [https://mozaic.tpsoft.org](https://mozaic.tpsoft.org)

Mozaic je webová aplikácia na prácu s fotografiami mozaík, maľovaných predlôh a ďalších obrazov rozdelených na samostatné farebné plochy. Používateľ kliknutím označuje jednotlivé uzavreté plochy a aplikácia pre každú z nich nájde súvislú oblasť, vypočíta reprezentatívnu farbu a priradí ju do farebnej skupiny.

Cieľom je uľahčiť identifikáciu podobných farieb, zoradiť ich od najtmavšej po najsvetlejšiu a očíslovať príslušné plochy. Takýto prehľad môže pomôcť pri plánovaní miešania farieb a pri systematickom maľovaní alebo skladaní mozaiky po jednotlivých farebných skupinách.

Aplikácia je určená najmä autorom mozaík, maliarom a každému, kto potrebuje z členitého farebného návrhu pripraviť praktickú paletu a očíslovanú pracovnú predlohu. Aktuálna verzia je lokálne fungujúce MVP: plochy sa označujú jednotlivo kliknutím, nejde o automatické rozpoznanie všetkých plôch celého obrázka naraz.

<br clear="left">

## Ukážka rozhrania

![Editor Mozaic s označenými plochami a farebnými skupinami](doc/Screenshot-2026-08-01-200944.png)

## Na čo Mozaic slúži

Typický pracovný postup začína načítaním fotografie alebo návrhu mozaiky. Používateľ klikne dovnútra uzavretej farebnej plochy a Mozaic pomocou flood fill algoritmu vyhľadá jej súvislé pixely. Z viacerých vnútorných pixelov určí reprezentatívnu farbu, porovná ju s už nájdenými farbami a zaradí plochu do zodpovedajúcej skupiny.

Farebné skupiny sa automaticky číslujú a zoraďujú podľa svetlosti. Výberom skupiny možno zvýrazniť všetky jej plochy a ostatné plochy ponechať, stlmiť alebo skryť. Používateľ tak môže pri práci s fyzickou mozaikou alebo obrazom spracovať všetky plochy jedného čísla, potom prejsť k svetlejšej farbe a zvolenú farbu postupne meniť alebo zosvetľovať. Aplikácia samotná nesleduje stav vymaľovania jednotlivých plôch.

Výsledok možno upraviť, exportovať ako očíslovaný obrázok a uložiť spolu s farebnou paletou alebo projektovými dátami na neskoršie pokračovanie.

## Hlavné funkcie

- **Načítanie obrázka:** podporované sú súbory PNG, JPEG a WebP vybrané cez tlačidlo alebo pretiahnuté do vyznačenej plochy.
- **Canvas editor:** obrázok sa zobrazí so zachovaným pomerom strán; koliesko myši mení priblíženie, ťahanie posúva pohľad a tlačidlo `Prispôsobiť` obnoví vhodné zobrazenie.
- **Označenie plochy kliknutím:** kliknutie do obrázka spustí iteratívny flood fill nad pixelmi pôvodného rozlíšenia.
- **Nastaviteľný výber:** používateľ môže meniť toleranciu výberu v rozsahu 0 až 100, 4- alebo 8-smerovú susednosť a prah tmavosti obrysov.
- **Reprezentatívna farba:** farba nevychádza iba z kliknutého pixelu; počíta sa medián vzoriek z vnútra nájdenej plochy.
- **Zoskupovanie podobných farieb:** plochy sa porovnávajú v priestore CIE Lab pomocou farebnej vzdialenosti Delta E 1976. Prah podobnosti je nastaviteľný.
- **Zoradenie a číslovanie:** skupiny sa automaticky zoradia podľa hodnoty svetlosti `L` od najtmavšej po najsvetlejšiu a ich čísla sa zobrazia na označených plochách.
- **Pozícia čísla:** v rozšírených nastaveniach možno zapnúť `Zobrazovať čísla na pozícii kliknutia`. Bez tejto voľby aplikácia naďalej používa automaticky vypočítanú vnútornú pozíciu.
- **Zvýraznenie skupiny:** vybraná skupina sa na obrázku zvýrazní; ostatné skupiny možno zobraziť normálne, stlmiť alebo skryť.
- **Manuálne opravy:** plochu možno odstrániť, presunúť do inej skupiny alebo oddeliť do novej skupiny. Skupiny možno zlúčiť a ich reprezentatívnu farbu zmeniť.
- **Prepočítanie skupín:** tlačidlo `Prepočítať` znovu vytvorí skupiny podľa aktuálnej tolerancie podobnosti.
- **Undo a redo:** história obsahuje najviac 30 krokov pre pridanie alebo odstránenie plochy, presuny, rozdelenie a zlúčenie skupín a vymazanie výsledkov.
- **Export PNG:** vytvorí obrázok v pôvodnom rozlíšení s číslami skupín a voliteľným polopriehľadným farebným prekrytím.
- **Export CSV:** uloží zoradenú paletu s HEX, RGB a Lab hodnotami, počtom plôch a celkovým počtom pixelov.
- **Export a import JSON:** uloží nastavenia, plochy, skupiny, rozmery a komprimované masky projektu. Import sa spúšťa tlačidlom `Import JSON`.
- **Automatická obnova:** posledná rozpracovaná práca sa priebežne ukladá do IndexedDB a po obnovení stránky ju aplikácia ponúkne na pokračovanie.

## Ako aplikáciu používať

1. **Otvorte aplikáciu.** Pri lokálnom vývoji ju sprístupní Vite na adrese uvedenej v termináli.
2. **Načítajte obrázok.** Použite `Načítať obrázok`, `Vybrať obrázok` alebo presuňte súbor PNG, JPEG či WebP do editora.
3. **Nastavte toleranciu výberu.** Hodnota `0` vyberá iba susedné pixely s presne rovnakou RGB farbou ako kliknutý pixel. Hodnota `1` používa ako referenciu medián farby z okolia 5 × 5 pixelov. Od hodnoty `2` sa používa pôvodný spôsob porovnania s farbou kliknutého pixelu. Ak výber uniká cez hranice, hodnotu znížte; ak sa plocha vyberie iba čiastočne, zvýšte ju.
4. **Označujte plochy.** Klikajte dovnútra jednotlivých uzavretých plôch. Ťahaním obrázok posúvajte a kolieskom ho približujte alebo odďaľujte. Ak chcete čísla ponechať priamo na miestach kliknutia, v sekcii `Rozšírené` zapnite `Zobrazovať čísla na pozícii kliknutia`.
5. **Skontrolujte farebné skupiny.** Pravý panel zobrazuje HEX, RGB, svetlosť a počet plôch každej skupiny. Zoradenie od najtmavšej po najsvetlejšiu prebieha automaticky.
6. **Upravte podobnosť farieb.** Posuvník `Podobnosť farieb (ΔE)` určuje, ktoré farby sa spoja. Po jeho zmene sa skupiny prepočítajú.
7. **Zvýraznite pracovnú skupinu.** Kliknite na farebnú skupinu a v nastavení `Ostatné skupiny` vyberte normálne zobrazenie, stlmenie alebo skrytie.
8. **Opravte nepresnosti.** V zozname plôch možno plochu preradiť, rozdeliť do novej skupiny alebo odstrániť. V detaile skupiny možno zmeniť farbu alebo skupinu zlúčiť s inou.
9. **Exportujte výsledok.** Použite `Očíslované PNG`, `Paleta CSV` alebo `Projekt JSON`. Pred PNG exportom možno zapnúť možnosť `Zahrnúť farebné prekrytie do PNG`.

Projekt JSON možno neskôr otvoriť cez `Import JSON`. Ak súbor neobsahuje pôvodný obrázok, aplikácia požiada o jeho opätovný výber; rozmery sa musia zhodovať s uloženým projektom.

### Klávesové skratky

| Skratka | Funkcia |
| --- | --- |
| `Ctrl+Z` | krok späť |
| `Ctrl+Y` alebo `Ctrl+Shift+Z` | krok znova |
| `Delete` | odstránenie vybratej plochy |
| `Escape` | zrušenie výberu plochy a skupiny |

## Ako aplikácia určuje farby

Po kliknutí Mozaic určí referenčnú farbu a hľadá susedné pixely s dostatočne podobnou RGB farbou. Pri tolerancii `0` je referenciou presná farba kliknutého pixelu a farebná vzdialenosť musí byť nulová. Pri tolerancii `1` sa pre každý kanál R, G a B vypočíta medián z okolia `<-2, +2>` v oboch osiach, teda najviac z 25 pixelov. Medián obmedzuje vplyv jedného šumového alebo kompresného artefaktu. Pri tolerancii `2` a vyššej je referenciou opäť farba kliknutého pixelu.

Tmavé pixely pod nastaveným prahom slúžia pri farebnom výbere ako bariéra, čo pomáha zabrániť pretečeniu cez tmavé obrysové čiary. Ak pixel už patrí staršiemu regiónu, ale jeho farba sa podľa aktuálnej tolerancie líši, nová plocha sa môže zo starej masky oddeliť. Pri rovnakej farbe aplikácia zabráni duplicitnému označeniu.

Reprezentatívna farba sa neurčuje z jediného bodu. Algoritmus zbiera vzorky z vnútorných častí scanline segmentov, obmedzuje ich počet a pre každý RGB kanál vypočíta medián. Tým sa znižuje vplyv okrajov, drobného šumu a časti kompresných artefaktov.

Na porovnanie plôch sa RGB farby prevedú cez XYZ do priestoru CIE Lab. V ňom sa vypočíta Delta E 1976 (`ΔE76`), ktorá vyjadruje vzdialenosť dvoch farieb. Plochy pod nastaveným prahom sa zoskupia a skupiny sa zoradia podľa zložky `L`, teda približnej svetlosti.

## Ochrana súkromia

Obrázky sa načítavajú a analyzujú výhradne lokálne v prehliadači. Projekt nemá backend, databázový server ani cloudové API a obrázky nikam neodosiela.

Rozpracovaný stav sa môže ukladať iba do lokálneho IndexedDB úložiska daného prehliadača. Exportované PNG, CSV a JSON súbory sa vytvárajú v prehliadači a sťahujú priamo do zariadenia používateľa.

## Tipy pre kvalitný výsledok

- Použite ostrú fotografiu s dostatočným rozlíšením a jasne uzavretými hranicami plôch.
- Fotografujte čo najkolmejšie na obraz, aby sa obmedzilo perspektívne skreslenie.
- Uprednostnite rovnomerné neutrálne osvetlenie bez tieňov, farebných odrazov a lesklých odleskov.
- Ak výber preteká cez obrys, znížte toleranciu výberu alebo upravte prah tmavosti obrysu.
- Ak sa jedna plocha rozdelí na viac výberov, toleranciu mierne zvýšte alebo použite kvalitnejší zdrojový obrázok.
- Automaticky vytvorené farebné skupiny pred exportom skontrolujte a podľa potreby manuálne opravte.
- Pri farebne kritickej práci používajte fotografiu so správnym vyvážením bielej; aplikácia nevykonáva kalibráciu fotoaparátu ani monitora.

## Aktuálne obmedzenia

- Všetky plochy sa označujú postupne kliknutím. Automatická segmentácia celého obrázka nie je implementovaná.
- Flood fill funguje najlepšie na uzavretých plochách s výraznými hranicami. Medzera v obryse môže spôsobiť pretečenie výberu.
- Jemné prechody, textúry, tiene, odlesky a JPEG artefakty môžu jednu plochu rozdeliť alebo ovplyvniť jej farbu.
- Tmavá hranica sa rozpoznáva iba podľa nastavenej svetlosti; zložité alebo farebné obrysy môžu vyžadovať inú toleranciu.
- Analýza prebieha na hlavnom vlákne bez Web Workera. Veľké súvislé plochy preto môžu dočasne znížiť odozvu rozhrania.
- Pri obrázkoch nad 24 miliónov pixelov aplikácia zobrazí výkonnostné upozornenie. Obrázky nad 80 miliónov pixelov odmietne.
- Výber pokrývajúci viac než 92 % obrázka sa považuje za pravdepodobnú chybu a neuloží sa. Pri toleranciách `0` a `1` je povolený aj jednopixelový región; od tolerancie `2` sa regióny menšie než 12 pixelov neuložia.
- Výsledná farba závisí od kvality a osvetlenia fotografie; nejde o fyzicky kalibrované meranie farby.
- Projektový JSON obsahuje pôvodný obrázok iba vtedy, keď má najviac 5 MiB. Pri väčšom obrázku ho treba pri importe znovu vybrať v rovnakých rozmeroch.

---

# Technické informácie

## Použité technológie

- [Vue 3](https://vuejs.org/) s Composition API a komponentmi `<script setup lang="ts">`
- TypeScript
- Vite
- Pinia pre globálny stav editora
- Vue Router; projekt ho inicializuje, aktuálne však nemá definované aplikačné trasy
- HTML Canvas API a natívne browser API (`ImageData`, `createImageBitmap`, `IndexedDB`, `FileReader`, Blob a Object URL)
- ESLint, Oxlint a Prettier pre kontrolu a formátovanie kódu

Aplikácia nepoužíva backend, OpenCV ani externú knižnicu na spracovanie obrázkov.

## Požiadavky

- Node.js presne podľa `engines` v `frontend/package.json`: `^22.18.0 || >=24.12.0`
- npm nie je v projekte pevne pripnuté; použite verziu dodanú s podporovanou verziou Node.js
- moderný prehliadač s podporou Canvas 2D, `createImageBitmap`, IndexedDB a ES modulov

Ďalšie systémové služby ani databázový server nie sú potrebné.

## Inštalácia a lokálne spustenie

Po klonovaní alebo otvorení repozitára prejdite do frontendového projektu, nainštalujte závislosti a spustite vývojový server:

```bash
cd frontend
npm install
npm run dev
```

Vite štandardne sprístupní aplikáciu na `http://localhost:5173/`. Ak je port obsadený, zvolí iný a vypíše jeho adresu v termináli.

## Produkčný build

```bash
cd frontend
npm run build
```

Skript spustí TypeScript kontrolu a produkčný Vite build paralelne. Výsledné statické súbory sa vytvoria v `frontend/dist/`.

Lokálny náhľad hotového buildu:

```bash
npm run preview
```

## Kontrola kvality kódu

Všetky dostupné kontrolné skripty sú definované v `frontend/package.json`:

```bash
npm run type-check
npm run lint
npm run format
```

- `type-check` spúšťa `vue-tsc --build`.
- `lint` postupne spúšťa Oxlint a ESLint. Obe lint úlohy používajú automatické opravy, takže môžu zmeniť kontrolované súbory.
- `format` formátuje obsah `frontend/src/` pomocou Prettieru.

Projekt momentálne nemá nakonfigurovaný testovací runner ani npm skript `test`.

## Štruktúra projektu

```text
Mozaic/
├── frontend/
│   ├── public/                  # verejné favicony a ikony
│   ├── src/
│   │   ├── assets/              # zdrojové vizuálne súbory
│   │   ├── components/          # editor, toolbar a pravý ovládací panel
│   │   ├── composables/         # ovládanie canvas viewportu
│   │   ├── router/              # inicializácia Vue Routera
│   │   ├── stores/              # Pinia store a stav projektu
│   │   ├── types/               # TypeScript dátové modely
│   │   ├── utils/               # farby, flood fill, masky, export a IndexedDB
│   │   ├── views/               # hlavné rozloženie editora
│   │   ├── App.vue
│   │   └── main.ts
│   ├── index.html
│   ├── package.json
│   ├── tsconfig.app.json
│   └── vite.config.ts
├── LICENSE
└── README.md
```

Najdôležitejšie implementačné body:

- `src/stores/mosaic.ts` koordinuje obrázok, plochy, skupiny, výber, históriu, import/export a automatické uloženie.
- `src/components/MosaicCanvas.vue` vykresľuje obrázok, prekrytia a čísla a prepočítava udalosti ukazovateľa na obrazové súradnice.
- `src/utils/floodFill.ts` obsahuje iteratívny scanline flood fill.
- `src/utils/colors.ts` obsahuje prevody RGB → XYZ → Lab, `ΔE76`, svetlosť a HEX formátovanie.
- `src/utils/colorGroups.ts` zoskupuje plochy a zoraďuje skupiny podľa svetlosti.
- `src/utils/regionMask.ts` pracuje s pamäťovo úspornou RLE reprezentáciou masiek.
- `src/utils/projectExport.ts` a `src/utils/projectStorage.ts` zabezpečujú exporty a lokálne ukladanie.

## Technický princíp fungovania

1. Prehliadač dekóduje súbor pomocou `createImageBitmap` a vykreslí ho do interného canvasu v pôvodnom rozlíšení.
2. Store načíta `ImageData` raz a uchová ho mimo hlbokej reaktivity. Zobrazený canvas používa samostatný viewport pre zoom a posun.
3. Kliknutie sa prepočíta zo súradníc obrazovky na súradnice pôvodného obrázka.
4. Referenčná RGB farba závisí od tolerancie: presný kliknutý pixel pri `0`, medián 5 × 5 pri `1` a kliknutý pixel pri hodnotách od `2`. Iteratívny scanline flood fill potom vyhľadá súvislú oblasť podľa rovnakej euklidovskej RGB tolerancie, zvolenej susednosti, prahu tmavého obrysu a masiek už označených plôch.
5. Výsledok sa uloží ako RLE riadky v `Uint32Array`. Zároveň sa vypočíta počet pixelov, bounding box a automatická vnútorná `labelPosition`; samostatná `userClickPosition` uchová obrazové súradnice kliknutia.
6. Z najviac 8 000 vnútorných vzoriek sa vypočíta medián RGB kanálov reprezentatívnej farby.
7. RGB farba sa prevedie do CIE Lab a porovná s existujúcimi skupinami pomocou `ΔE76`.
8. Skupiny dostanú váženú reprezentatívnu farbu, zoradia sa podľa Lab `L` a prečíslujú sa.
9. Canvas aj PNG export vykreslia číslo na `labelPosition` alebo, pri zapnutom nastavení, na `userClickPosition`. Staršie regióny bez kliknutej pozície bezpečne použijú `labelPosition`.
10. Export vytvorí výsledné dáta priamo v prehliadači bez serverovej komunikácie.

## Dáta a ukladanie

Aktívny stav spravuje Pinia store. Veľké objekty `HTMLCanvasElement`, `ImageData`, `Blob`, masky a zoznam plôch sa ukladajú cez `shallowRef` alebo `markRaw`, aby ich Vue zbytočne neobalilo hlbokou reaktivitou.

Po načítaní obrázka a po zmenách výsledkov sa projekt s krátkym oneskorením uloží do IndexedDB databázy `mozaic-analyzer`, úložiska `projects`, pod kľúčom `last-project`. Automatická záloha obsahuje serializovaný projekt aj pôvodný obrazový Blob. Pri ďalšom otvorení aplikácia ponúkne obnovenie alebo zahodenie poslednej práce. Ak prehliadač IndexedDB nepovolí, chyba automatického uloženia neblokuje editor.

Exportovaný JSON obsahuje verziu formátu, dátum vytvorenia, názov a rozmery obrázka, nastavenia, farebné skupiny a plochy vrátane RLE masiek, farieb, počtu pixelov, bounding boxov, automatických pozícií čísiel a pozícií kliknutia. Ukladá sa aj nastavenie `useUserClickPositionForLabels`. Starší projekt bez týchto polí použije hodnotu `false` a automatickú `labelPosition`. Obrázok do 5 MiB sa vloží ako data URL. Pri väčšom obrázku JSON obsahuje iba projektové dáta a pri importe treba znovu vybrať pôvodný obrázok s rovnakými rozmermi.

História undo/redo je iba v pamäti aktuálnej relácie a nie je súčasťou exportovaného projektu.

## Vývojové poznámky

- Analýza vždy používa pixely pôvodného rozlíšenia; zoom ovplyvňuje iba zobrazenie.
- RLE maska ukladá trojice `y`, `xStart`, `xEnd` namiesto objektu pre každý pixel.
- Masky sú po vytvorení nemenné, preto ich história môže bezpečne zdieľať bez kopírovania veľkých binárnych polí.
- Výpočtová logika je oddelená od Vue komponentov v `src/utils/`, čo umožňuje jej neskoršie samostatné testovanie.
- Flood fill aktuálne beží na hlavnom vlákne. Pri prípadnom presune do Web Workera treba zachovať prácu s pôvodným `ImageData` a minimalizovať kopírovanie veľkých polí.
- Router je zapojený, no hlavná aplikácia sa momentálne vykresľuje priamo cez `App.vue` a nevyužíva samostatné trasy.