feat: Visual Asset Management System - Gallery, Organization & Smart Labeling
IMPLEMENTED SYSTEMS: ✅ Thumbnail Grid Gallery (1,166 images, searchable, filterable) ✅ Smart Asset Organizer (auto-categorize, rename, organize into Slovenian folders) ✅ Hover Preview documentation (VS Code integration) ✅ Smart Auto-Labeling (descriptive naming convention) FILES: - tools/asset_gallery.html: Interactive web gallery with modal preview - scripts/smart_asset_organizer.py: Automated organization script - docs/VISUAL_ASSET_SYSTEM.md: Complete documentation FEATURES: - Live search & category filters - Modal image preview - Dry-run mode for safe testing - Slovenian folder structure (liki, biomi, zgradbe, oprema, etc.) - Auto-labeling with {category}_{description}_style32.png format - Organization manifest tracking Asset Count: 1,166 images (576 MB) Ready for ADHD-friendly visual workflow
This commit is contained in:
300
docs/VISUAL_ASSET_SYSTEM.md
Normal file
300
docs/VISUAL_ASSET_SYSTEM.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# 🎨 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.
|
||||
Reference in New Issue
Block a user