novafarma/docs/VISUAL_ASSET_SYSTEM.md

# 🎨 Vizualni Sistem za Preglednost Assetov

**Status**: ✅ IMPLEMENTIRANO  
**Datum**: 2026-01-04  
**Asseti**: 1,166 slik (576 MB)

---

## 🎯 Pregled Sistemov

Ta dokument opisuje **4 sisteme** za lažjo vizualno preglednost vseh assetov v DolinaSmrti projektu:

1. **Thumbnail Grid Gallery** - spletna galerija vseh slik
2. **Smart Asset Organization** - avtomatska organizacija v logične folderje
3. **Hover Preview** (zahteva IDE nastavitve)
4. **Smart Auto-Labeling** - avtomatsko poimenovanje po vsebini

---

## 1️⃣ Thumbnail Grid Gallery

### 📍 Lokacija
`/tools/asset_gallery.html`

### 🚀 Kako Odpreti

**Option A: Direktno v brskalniku**
```bash
open tools/asset_gallery.html
```

**Option B: Preko lokalnega serverja**
```bash
cd tools
python3 -m http.server 8080
# Odpri: http://localhost:8080/asset_gallery.html
```

### ✨ Funkcionalnosti

- **Thumbnail Grid**: Pregled vseh 1,166 slik v mreži
- **🔍 Iskanje**: Išči po imenu datoteke
- **📁 Filtri**: Filter po kategorijah (Style 32, animations, NPCs, buildings, itd.)
- **🖼️ Modal Preview**: Klikni na sliko za povečavo
- **📊 Live Stats**: Statistika koliko slik je prikazanih

### 🎨 Kategorije

- **Vse (1166)** - vsi asseti
- **Style 32 (344)** - Style 32 Session Jan 04
- **Slike Folder (817)** - originalni slike folder
- **Animacije (112)** - animation spritesheets
- **Rastline (144)** - plants & vegetation
- **Kreature (271)** - creatures & mutants
- **Predmeti (105)** - items & props
- **Demo Assets (63)** - demo scene assets
- **Buildings** - zgradbe in stavbe
- **NPCs** - character sprites
- **Terrain** - terrain tiles
- **Interior** - interior objects
- **Weapons** - orožje
- **Tools** - orodja

---

## 2️⃣ Smart Asset Organization

### 📍 Lokacija
`/scripts/smart_asset_organizer.py`

### 🚀 Kako Uporabiti

**1. Preveri kaj bi se zgodilo (DRY RUN):**
```bash
python3 scripts/smart_asset_organizer.py
```

**2. Prikaži strukturo kategorij:**
```bash
python3 scripts/smart_asset_organizer.py --preview
```

**3. DEJANSKO izvedi organizacijo:**
```bash
python3 scripts/smart_asset_organizer.py --execute
```

### 📂 Nova Struktura Folderjev

```
assets/slike 🟢/
├── liki/                    # Characters
│   ├── gronk/
│   ├── kai/
│   ├── ana/
│   ├── zombiji/
│   └── npcs/
├── biomi/                   # Biomes
│   ├── desert/
│   ├── gore/
│   ├── džungla/
│   ├── močvirje/
│   └── arktika/
├── zgradbe/                 # Buildings
│   ├── hiše/
│   ├── javne/
│   ├── kmetijske/
│   └── delavnice/
├── objekti/                 # Props
│   ├── pohištvo/
│   ├── shranjevanje/
│   ├── razsvetljava/
│   └── dekoracije/
├── narava/                  # Nature
│   ├── rastline/
│   ├── pridelki/
│   └── živali/
├── oprema/                  # Equipment
│   ├── orožje/
│   ├── orodja/
│   └── zaščita/
├── vmesnik/                 # UI
│   ├── gumbi/
│   ├── ikone/
│   ├── vrstice/
│   └── okna/
├── teren/                   # Terrain tiles
├── notranjost/             # Interior objects
├── učinki/                 # VFX
└── kreature_mutanti/       # Mutants
```

### 🏷️ Smart Naming Convention

**Format**: `{kategorija}_{podfolder}_{opis}_style32.png`

**Primeri**:
- `liki_kai_idle_style32.png`
- `zgradbe_javne_church_complete_style32.png`
- `oprema_orožje_sword_weapon_style32.png`
- `narava_živali_cow_farm_animal_style32.png`

### 📊 Manifest

Po organizaciji se ustvari `docs/ASSET_ORGANIZATION_MANIFEST.json` z:
- Seznam vseh premakjenih datotek
- Original → Nova lokacija
- Kategorija in podfolder za vsak asset
- Statistika (moved, renamed, skipped)

---

## 3️⃣ Hover Preview (IDE Feature)

### 🔧 Nastavitve v VS Code

**1. Namesti razširitev:**
- Install: "Image Preview" by Kiss Tamás

**2. Aktiviraj hover preview:**
```json
// settings.json
{
  "imagePreview.hoverPreview": true,
  "imagePreview.maxHeight": 256,
  "imagePreview.maxWidth": 256
}
```

**3. Uporaba:**
- Pridi z miško čez `'path/to/image.png'` v kodi
- Prikaže se preview slike! 🖼️

---

## 4️⃣ Smart Auto-Labeling

Auto-labeling je integriran v `smart_asset_organizer.py` script.

### Kako Deluje

1. **Scan**: Prebere ime datoteke
2. **Detect**: Zazna kategorijo (buildings, NPCs, tools, itd.)
3. **Generate**: Ustvari novo ime z opisnimi keywords
4. **Rename**: Preimenuje datoteko

### Pravila Poimenovanja

- **Odstranjeni**: timestampi (`_1767549405033`)
- **Dodani**: kategorija in podfolder
- **Ohranjen**: original content description
- **Dodano**: `_style32` za Style 32 assete

---

## 🎯 Hitri Začetek

### Za Pregled Vseh Slik:
```bash
open tools/asset_gallery.html
```

### Za Organizacijo Assetov:
```bash
# 1. Preveri najprej (dry run)
python3 scripts/smart_asset_organizer.py

# 2. Izvrši organizacijo
python3 scripts/smart_asset_organizer.py --execute
```

### Za Hover Preview:
1. Odpri VS Code
2. Install "Image Preview" extension
3. Hover čez pot do slike v kodi

---

## 📊 Trenutno Stanje

- **Skupaj slik**: 1,166
- **Velikost**: 576 MB
- **Style 32 asseti**: 344 slik
- **Originalni slike folder**: 817 slik
- **Organizirano**: ❌ (čaka na `--execute`)

---

## ⚙️ Napredne Možnosti

### Dodaj Novo Kategorijo

Uredi `smart_asset_organizer.py`:

```python
TARGET_STRUCTURE = {
    # ... obstoječe kategorije ...
    "nova_kategorija": ["keyword1", "keyword2", "keyword3"]
}
```

### Prilagodi Naming Convention

Uredi funkcijo `generate_smart_name()` v `smart_asset_organizer.py`.

---

## 🚨 Pomembna Opozorila

⚠️ **BACKUP PRED ORGANIZACIJO!**
```bash
# Backup assetov
cp -r assets/ assets_backup_$(date +%Y%m%d)/
```

⚠️ **DRY RUN NAJPREJ!**
Vedno najprej zaženi brez `--execute` da vidiš kaj se bo zgodilo.

⚠️ **GIT COMMIT PRED SPREMEMBAMI!**
```bash
git add .
git commit -m "backup: Before asset reorganization"
```

---

## 🎬 Video Tutorial

(Coming soon - screen recording kako uporabljati vse sisteme)

---

## 🐛 Troubleshooting

### Gallery Ne Prikaže Slik?
- Preveri da si v project root direktoriju
- Uporabi local server (`python3 -m http.server`)
- Preveri browser console za napake (F12)

### Hover Preview Ne Deluje?
- Preveri da imaš "Image Preview" extension nameščen
- Preveri `settings.json` za pravilne nastavitve
- Restart VS Code

### Organizacija Script Crashne?
- Preveri Python version (3.8+)
- Run z `--preview` za debugging
- Preveri da imaš write permissions na `assets/` folder

---

**Dokumentacija verzija**: 1.0  
**Zadnja posodobitev**: 2026-01-04  
**Maintainer**: Antigravity Agent

---

## 🙏 Credits

Developed as part of **Mrtva Dolina v1.0 - Director Mode** implementation.