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

open tools/asset_gallery.html

Option B: Preko lokalnega serverja

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):

python3 scripts/smart_asset_organizer.py

2. Prikaži strukturo kategorij:

python3 scripts/smart_asset_organizer.py --preview

3. DEJANSKO izvedi organizacijo:

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:

// 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:

open tools/asset_gallery.html

Za Organizacijo Assetov:

# 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:

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!

# 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!

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.