1Cos'è OffGallery

OffGallery è un sistema di catalogazione e ricerca fotografica completamente offline. Analizza automaticamente ogni immagine con modelli AI locali, generando embedding semantici, tassonomia biologica, tag, descrizioni e score estetici — tutto senza inviare un singolo pixel a servizi cloud.

È progettato per fotografi che gestiscono archivi di migliaia di file RAW e vogliono trovare qualsiasi foto in secondi usando linguaggio naturale: "ritratto controluce al tramonto", "airone cenerino in volo", "paesaggio con neve e montagne".

Cosa può fare OffGallery

• Analizza 25+ formati RAW (Canon CR2/CR3, Nikon NEF, Sony ARW, Fuji RAF e altri) e formati standard (JPG, PNG, TIFF, WEBP, HEIC)
• Genera embedding semantici CLIP (768 dimensioni) per ricerca in linguaggio naturale
• Calcola embedding DINOv2 per ricerca per similarità visiva
• Classifica automaticamente flora e fauna con BioCLIP2 (~450.000 specie, 7 livelli tassonomici)
• Genera tag, descrizioni e titoli tramite modello LLM Vision locale (es. Qwen3-VL via Ollama o LM Studio)
• Valuta la qualità artistica con score estetico (0–10) e tecnica (nitidezza/rumore)
• Geocodifica offline le coordinate GPS in gerarchia Continente › Paese › Regione › Città
• Si integra con Lightroom tramite import/export XMP bidirezionale
• Processa direttamente cataloghi .lrcat di Lightroom come sorgente di input

2Primo Avvio

Windows: dopo aver eseguito OffGallerySetup.exe, avvia OffGallery tramite il collegamento creato sul Desktop. Linux/macOS: usa il launcher corrispondente (vedi installer/INSTALL_GUIDE_IT.md). Al primo avvio l'applicazione scarica automaticamente i modelli AI (~6,7 GB totali). Un pannello di progresso mostra l'avanzamento. Questo passaggio avviene una volta sola.

1. Windows: fai doppio click sul collegamento OffGallery sul Desktop, creato da OffGallerySetup.exe. Linux/macOS: usa il launcher nella cartella installer/.

2. Al primo avvio appare una splash screen che scarica i modelli AI. Connessione internet necessaria solo in questo momento.

3. Al termine del download l'interfaccia principale appare con 8 tab.

4. (Opzionale) Assicurati che Ollama sia in esecuzione se vuoi generare tag e descrizioni LLM. Su Windows avvia l'app Ollama; su macOS/Linux il daemon parte automaticamente.

3Panoramica Interfaccia

L'interfaccia è organizzata in 8 tab orizzontali nella parte superiore della finestra:

Tab	Funzione Principale
Configurazione	Impostazioni modelli AI, LLM, lingua UI e output, editor esterni
Processing	Analisi AI delle immagini: embedding, BioCLIP, LLM, score estetico/tecnico, geotag
Ricerca	Query semantica in linguaggio naturale + filtri EXIF/score/data/colore
Gallery	Visualizzazione risultati con badge, anteprima e ordinamento avanzato
Export	Export XMP, copia file con struttura originale, sync con Lightroom
Statistiche	Analisi del database: tipologia, date, obiettivi, score, rating
Log	Monitoraggio in tempo reale dei processi di elaborazione
Plugin	Gestione plugin standalone: avvio, configurazione e monitoraggio progresso

3.1 Indicatori di Stato Modelli

Nell'angolo in alto a destra della finestra principale è presente una barra fissa con indicatori colorati per ogni componente AI. A colpo d'occhio puoi verificare cosa è attivo senza entrare in Configurazione.

Colore	Significato
● Verde	Componente caricato in VRAM (GPU) — prestazioni ottimali
● Ambra	Componente caricato su CPU — funzionante, ottimale per modelli leggeri (DINOv2, MUSIQ) o come fallback per modelli pesanti se la VRAM è insufficiente
● Rosso	Componente abilitato ma non caricato — errore di caricamento (es. modello non trovato, VRAM esaurita senza fallback)
● Grigio	Componente disabilitato nella configurazione

I componenti monitorati sono: CLIP, DINOv2, BioCLIP, Aesthetic, Technical (MUSIQ), LLM Vision, ExifTool e Database.

Nota: Il colore dell'indicatore riflette il device configurato per ogni modello. Con l'allocazione per-modello (vedi sezione Device), alcuni modelli possono essere intenzionalmente su CPU (ambra) per sfruttare il parallelismo dei thread. BioCLIP ha un fallback automatico su CPU se la VRAM è insufficiente.

L'indicatore LLM mostra il nome del backend rilevato (Ollama o LM Studio) e si aggiorna automaticamente ogni 30 secondi. Con il backend impostato su auto (default), OffGallery rileva automaticamente quale server è attivo senza configurazione manuale.

---

4Tab Processing

Il tab Processing è il centro operativo di OffGallery. Da qui si avviano le sessioni di analisi AI che popolano il database con embedding, tag, descrizioni e metadati.

4.1 Sorgente Immagini

Nella parte superiore del tab è possibile scegliere due tipi di sorgente:

Sorgente: Directory

Comportamento predefinito. OffGallery scansiona la cartella selezionata (e le sue sottocartelle) cercando tutti i formati supportati. Usa il pulsante Sfoglia per selezionare la directory, oppure inserisci il percorso manualmente.

Sorgente: Catalogo Lightroom (.lrcat)

Seleziona direttamente un file .lrcat di Lightroom. OffGallery legge il catalogo in sola lettura tramite SQLite: estrae la lista completa dei file indicizzati (con percorso assoluto) e li usa come sorgente senza toccare il catalogo originale.

Questo approccio è ideale per:

• Elaborare l'intera libreria Lightroom esistente senza spostare file
• Mantenere la struttura di cartelle originale multi-disco
• Combinare il catalogo Lightroom con i tag/descrizioni generati da OffGallery

4.2 Modalità di Elaborazione

Tre modalità selezionabili tramite radio button:

Modalità	Comportamento
Solo nuove immagini	Elabora solo le immagini non ancora presenti nel database. Le foto già analizzate vengono saltate.
Nuove + errori precedenti	Elabora le immagini nuove e riprova quelle che avevano dato errore in una sessione precedente.
Completa / Riprocessa tutte	Elabora tutte le foto (nuove e catalogate). Con Sovrascrivi OFF: aggiunge solo i dati mancanti — ideale per completare un import interrotto o per applicare un modello che non era attivo la volta precedente. Con Sovrascrivi ON: ricalcola tutto da capo. Attivando questa modalità appare il checkbox Solo Gen. AI: vedi § 4.4.

4.3 Opzioni AI (Generazione LLM)

Il riquadro Generazione AI controlla il comportamento del modello LLM Vision:

Opzione	Descrizione
Genera Tag	Attiva la generazione di parole chiave descrittive dell'immagine
Genera Descrizione	Attiva la generazione di una descrizione narrativa
Genera Titolo	Attiva la generazione di un titolo breve
Max tag	Numero massimo di tag da generare (default: 10)
Sovrascrivi	Se selezionato, sovrascrive tag/descrizione/titolo esistenti. Se non selezionato: per i tag fa merge (aggiunge solo i nuovi); per descrizione e titolo salta se già presenti.

Griglia: effetto di Sovrascrivi per tipo di campo

Campo	Sovrascrivi OFF (default)	Sovrascrivi ON
Tag	Merge: aggiunge solo i tag non già presenti (case-insensitive). I tag esistenti restano invariati.	Replace totale: i tag esistenti vengono sostituiti integralmente con quelli generati dal LLM.
Descrizione	Skip: se la descrizione è già presente nel DB, il LLM non viene chiamato per questo campo.	Genera sempre: sovrascrive la descrizione esistente con quella generata dal LLM.
Titolo	Skip: se il titolo è già presente nel DB, il LLM non viene chiamato per questo campo.	Genera sempre: sovrascrive il titolo esistente con quello generato dal LLM.
Embedding CLIP/DINOv2	Salta le foto che lo hanno già nel DB.	Ricalcola anche se già presente.
BioCLIP tassonomia	Salta le foto che la hanno già nel DB.	Ricalcola anche se già presente.
Score estetico / tecnico	Salta le foto che li hanno già nel DB.	Ricalcola anche se già presente.

Griglia combinata: Modalità × Sovrascrivi

Modalità	Sovrascrivi	Tag	Descrizione	Titolo	Embedding / BioCLIP / Score
Solo nuove immagini	OFF	Merge (solo nuovi tag)	Skip se presente	Skip se presente	Solo per immagini nuove
	ON	Replace totale	Genera sempre	Genera sempre
Nuove + errori precedenti	OFF	Merge (solo nuovi tag)	Skip se presente	Skip se presente	Solo per immagini nuove o con errori
	ON	Replace totale	Genera sempre	Genera sempre
Completa / Riprocessa tutte	OFF	Merge (solo nuovi tag)	Skip se presente	Skip se presente	Solo se mancanti nel DB
	ON	Replace totale	Genera sempre	Genera sempre	Sempre rigenerati
Completa / Riprocessa tutte + Solo Gen. AI	OFF / ON	Merge / Replace	Skip / Genera	Skip / Genera	Non toccati (EXIF, embedding, BioCLIP, score saltati)

4.4 Modalità "Solo Gen. AI"

Il checkbox Solo Gen. AI appare accanto a "Riprocessa tutte" quando questa modalità è selezionata. Spuntandolo si attiva una modalità speciale che agisce solo sulla generazione LLM.

Questa modalità è pensata per un caso d'uso molto frequente: hai già analizzato le foto ma vuoi aggiornare tag, descrizioni e titoli con un modello LLM migliore, senza dover rieseguire tutta la pipeline (EXIF, embedding CLIP/DINOv2, BioCLIP, aesthetic score, ecc.).

Cosa fa "Solo Gen. AI"

• Filtra solo le immagini già presenti nel database (le nuove foto vengono ignorate)
• Estrae una miniatura a 512px dall'originale per il modello LLM
• Chiama il modello LLM Vision con il prompt configurato
• Aggiorna nel database solo i campi: tags, description, title
• Salta completamente: EXIF, embedding CLIP/DINOv2, BioCLIP, score estetico/tecnico, geotag

Cosa non fa "Solo Gen. AI"

• Non tocca il campo bioclip_taxonomy (rimane invariato)
• Non aggiorna embedding (le ricerche semantiche precedenti rimangono valide)
• Non elabora foto nuove non ancora nel database

Quando usarla

1. Hai aggiornato Ollama a un modello più capace (es. da 4B a 7B)
2. Vuoi rigenerare i tag in una lingua diversa
3. I tag generati con il modello precedente erano insoddisfacenti
4. Vuoi aggiungere descrizioni a foto già importate senza descrizione

4.5 Avvio e Monitoraggio

Premi il pulsante Avvia per iniziare l'elaborazione. Durante l'analisi:

• Una barra di progresso mostra l'avanzamento (file corrente / totale)
• Il pannello Log (tab Log) mostra in tempo reale ogni operazione
• Il pulsante cambia in Interrompi per fermare l'elaborazione in modo sicuro

Le elaborazioni complete e quelle interrotte dall'utente sono sicure: il database viene aggiornato dopo ogni immagine completata.

---

5Tab Ricerca

Il tab Ricerca è il cuore della discovery fotografica. Combina ricerca semantica (linguaggio naturale) con filtri avanzati su metadati, score e date.

5.1 Ricerca Semantica (CLIP)

La ricerca semantica usa embedding CLIP per trovare immagini il cui contenuto visivo è simile al concetto espresso nella query, indipendentemente dalle parole usate.

1. Digita la query in italiano nel campo di testo principale: es. "tramonto sul mare con barche".

2. OffGallery traduce automaticamente la query in inglese (via Argostranslate offline) e la codifica con il modello CLIP.

3. I risultati vengono ordinati per similarità coseno con tutti gli embedding nel database.

4. Regola il cursore Soglia per filtrare risultati poco pertinenti (default ~0.20).

5.2 Ricerca per Tag

La ricerca per tag usa fuzzy matching per trovare immagini che contengono specifiche parole chiave. La ricerca è:

• Case-insensitive: "Uccello" e "uccello" sono equivalenti
• Fuzzy: "flamingo" trova anche "fenicottero" se il modello ha usato entrambi
• Multilingua: funziona nella lingua in cui sono stati generati i tag

Puoi combinare più tag separati da virgola per una ricerca AND.

5.3 Filtri Avanzati

I filtri si accumulano: attivarne più di uno restringe progressivamente i risultati.

Categoria	Filtri Disponibili
EXIF	Camera (marca/modello), Obiettivo, Focale (mm), ISO, Tempo di posa, Diaframma (f/)
Score	Score estetico minimo (0–10), Score tecnico minimo (0–10)
Rating	Stelle Lightroom: da 0 a 5 (compatibile con import/export XMP)
Colore	Etichetta colore (rosso, giallo, verde, blu, viola) o Bianco/Nero rilevato automaticamente
Data	Intervallo date scatto (da → a)
Formato	Solo RAW, Solo JPEG, o tutti
Luogo	Città o regione con autocompletamento dai valori presenti nel DB (plugin GeoNames). Ricerca per contenuto, case-insensitive.
GPS	4 stati: Tutte · Solo con GPS · GPS modificato manualmente · Senza GPS (plugin GeoNames)
Nome comune	Filtra per nome comune biologico con autocompletamento (plugin BioNomen). Ricerca per contenuto sul campo.
Habitat	Tipo di habitat ESA WorldCover (bosco, macchia, prato, urbano, acqua…) — plugin NaturArea
Area protetta	Testo libero sul nome dell'area protetta WDPA — plugin NaturArea
Condizione meteo	Sereno · Parzialmente nuvoloso · Nuvoloso · Nebbia · Pioggerella · Pioggia · Neve · Temporale — plugin Meteo

5.4 Ricerche Salvate

Puoi salvare la configurazione completa di una ricerca (query + tutti i filtri attivi) con un nome personalizzato. Le ricerche salvate sono richiamabili in un click dal menu a tendina.

1. Configura la ricerca desiderata (query, soglia, filtri).

2. Clicca Salva ricerca e assegna un nome.

3. Per richiamarla in futuro: selezionala dal menu a tendina "Ricerche salvate" e premi Carica.

Le ricerche vengono salvate in database/saved_searches.json.

---

6Tab Gallery

La Galleria visualizza i risultati della ricerca corrente. Ogni immagine è mostrata come miniatura con badge informativi sovrapposti.

6.1 Badge e Indicatori

Badge	Significato
★ 4.2	Score estetico (0–10). Colore: verde >7, giallo 5–7, grigio <5
⚙ 8.1	Score tecnico (nitidezza/rumore, solo immagini non-RAW)
★★★★	Rating Lightroom (stelle 1–5)
B/N	Immagine in bianco e nero rilevata automaticamente
●	Etichetta colore Lightroom (rosso/giallo/verde/blu/viola)

Tooltip al passaggio del mouse

Passando il mouse su una miniatura appare un tooltip con:

• Titolo e descrizione generati dal LLM
• Lista completa dei tag
• Tassonomia BioCLIP (se rilevata): es. Animalia › Aves › Ardeidae › Ardea cinerea
• Gerarchia geografica: es. GeOFF | Europe | Italy | Sardegna | Oristano
• Metadati EXIF principali (camera, obiettivo, ISO, tempo)

6.2 Ordinamento

Il menu Ordina per offre 7 criteri:

1. Rilevanza (score similarità CLIP — predefinito nelle ricerche semantiche)
2. Data scatto (crescente o decrescente)
3. Nome file
4. Rating (stelle)
5. Score estetico
6. Score tecnico
7. Score composito (estetico + tecnico)

Per ogni criterio è possibile scegliere direzione ASC o DESC.

6.3 Menu Contestuale

Click destro su qualsiasi miniatura apre il menu contestuale con le azioni disponibili:

Azione	Descrizione
Apri in editor esterno	Apre il file originale in Lightroom, Capture One, o altro editor configurato
Mostra in Esplora Risorse	Apre la cartella contenente il file originale
Trova immagini simili	Avvia una ricerca per similarità visiva (DINOv2) usando questa immagine come query
Modifica tag	Apre un editor inline per aggiungere/rimuovere tag manualmente
Rigenera AI	Rigenera tag, descrizione e titolo per questa singola immagine
Export XMP	Esporta subito il file XMP per questa immagine
Esegui GeoNames	Aggiorna la gerarchia geografica da GPS per questa immagine (plugin GeoNames)
Esegui NaturArea	Rileva area protetta e habitat dalla posizione GPS (plugin NaturArea)
Esegui Meteo	Recupera le condizioni meteo storiche al momento dello scatto (plugin Meteo — richiede internet)
Esegui BioNomen	Aggiunge i nomi comuni biologici nella lingua configurata (plugin BioNomen)

---

7Tab Statistiche

Il tab Statistiche offre una panoramica analitica dell'intero archivio indicizzato:

• Distribuzione formati: quante RAW, quante JPEG, PNG, ecc.
• Timeline scatti: distribuzione temporale per anno/mese
• Strumentazione: le fotocamere e gli obiettivi più usati
• Parametri di scatto: distribuzioni di ISO, tempo, diaframma
• Score estetici e tecnici: istogrammi e medie
• Rating: distribuzione stelle 0–5
• Tag cloud: le parole chiave più frequenti nell'archivio

---

8Tab Export

Il tab Export è organizzato in tre sezioni distinte — Metadati XMP, Foglio dati CSV e File immagini — combinabili liberamente. In cima al riquadro trovi la barra dei Preset per salvare e richiamare configurazioni complete.

8.1 Preset Export

Ogni configurazione dell'intero tab (tutti i flag attivi, le opzioni avanzate) può essere salvata con un nome e richiamata in seguito.

• 💾 Salva preset: salva la configurazione corrente con un nome a tua scelta. Se il nome esiste già, viene chiesto se sovrascrivere.
• 📋 Preset salvati: apre la lista dei preset salvati. Doppio clic o pulsante Carica per applicare; pulsante Elimina per rimuovere.

8.2 Metadati XMP

Scrive file .xmp sidecar o embedded compatibili con Lightroom, DxO, Capture One e qualsiasi software che rispetta lo standard XMP/IPTC.

Opzione	Descrizione
XMP Sidecar	File .xmp separato accanto all'originale
XMP Embedded	Metadati scritti direttamente nel file immagine
Includi DNG	Permette l'embedded anche nei file DNG (disabilitato di default per sicurezza)

I campi esportati includono: tag utente e LLM (dc:subject), tassonomia BioCLIP (lr:hierarchicalSubject con prefisso AI|Taxonomy|), gerarchia geografica (GeOFF|), stelle, descrizione e titolo LLM. I dati dei plugin (habitat, area protetta, meteo, nome comune) vengono scritti come campi XMP aggiuntivi se presenti.

Griglia: campi esportati in XMP per tipo di dato

Dato	Campo XMP	Standard	Visibile in Lightroom come
Tag utente + LLM	dc:subject	Dublin Core	Parole chiave piatte
Tassonomia BioCLIP	lr:hierarchicalSubject	Lightroom	Gerarchia AI > Taxonomy > ...
Gerarchia geografica (GeoNames)	lr:hierarchicalSubject	Lightroom	Gerarchia GeOFF > Europe > Italy > ...
Descrizione LLM	dc:description	Dublin Core	Didascalia / Caption
Titolo LLM	dc:title	Dublin Core	Titolo
Rating stelle	xmp:Rating	XMP Basic	Stelle 1–5
Etichetta colore	xmp:Label	XMP Basic	Etichetta colore

Griglia: comportamento import XMP → DB

Campo nel file XMP	Importato?	Note
Tag (dc:subject) senza prefisso speciale	✅ Sì	Aggiunti ai tag esistenti nel DB (merge case-insensitive)
Tag con prefisso AI|Taxonomy|	❌ No	Filtrati: la tassonomia BioCLIP è gestita solo internamente
Tag con prefisso GeOFF|	❌ No	Filtrati: la gerarchia geografica è gestita solo internamente
Rating (xmp:Rating)	✅ Sì	Aggiorna il campo stelle nel DB
Etichetta colore (xmp:Label)	✅ Sì	Aggiorna il campo color_label nel DB
Descrizione (dc:description)	✅ Sì	Aggiorna il campo description nel DB
Titolo (dc:title)	✅ Sì	Aggiorna il campo title nel DB
Namespace proprietari (Darktable, Capture One…)	⚠️ Preservati	Copiati nel nuovo XMP senza interpretazione — nessun dato proprietario viene perso

Griglia: formato output XMP per editor fotografico

Editor	Formato sidecar	Opzione in OffGallery	Note
Lightroom	nomefile.xmp	Output format: Lightroom	Sidecar accanto al RAW, convenzione standard
Darktable	nomefile.EXT.xmp	Output format: Darktable	Es. IMG_001.NEF.xmp — estensione doppia
Capture One	nomefile.xmp	Output format: Lightroom	Legge il formato standard Lightroom
digiKam / ACDSee / FastRawViewer	nomefile.xmp	Output format: Lightroom	Compatibili con il formato standard

Destinazione XMP

Puoi scegliere tra Accanto all'originale (il file .xmp viene creato nella stessa cartella del RAW) e Cartella unica (tutti gli XMP in una directory a tua scelta).

8.3 Foglio dati CSV

Esporta un file CSV completo con tutti i metadati del database (46 campi: dati file, camera, obiettivo, impostazioni di scatto, date, GPS, valutazioni AI, tag, ecc.).

Opzione	Descrizione
Escludi GPS	Omette le colonne GPS dal CSV (coordinate, città, paese)
Escludi EXIF	Omette i dati tecnici EXIF (camera, obiettivo, esposizione, ISO, flash, ecc.)

Entrambe le opzioni sono disabilitate di default: il CSV include tutto. Le colonne rimangono presenti nel file anche quando escluse (schema fisso), ma i valori sono vuoti — utile per importatori che si aspettano uno schema predefinito.

8.4 File immagini

Copia i file originali in una destinazione mantenendo la gerarchia di cartelle originale, anche quando le foto provengono da dischi diversi.

Opzione	Descrizione
Escludi GPS	Rimuove i tag GPS dalla copia tramite ExifTool. L'originale non viene mai modificato.
Escludi EXIF	Rimuove tutti i metadati EXIF dalla copia (camera, obiettivo, impostazioni). L'originale non viene mai modificato.
Mantieni struttura	Ricrea la gerarchia di cartelle originale nella destinazione
Sovrascrivi esistenti	Sovrascrive i file se già presenti nella destinazione

Esempio con foto su due dischi:

Sorgente:
  C:\Foto\2024\Sardegna\IMG_001.NEF
  D:\Archivio\2023\Toscana\DSC_999.NEF

Destinazione (es. E:\Backup):
  E:\Backup\C_drive\Foto\2024\Sardegna\IMG_001.NEF
  E:\Backup\D_drive\Archivio\2023\Toscana\DSC_999.NEF

Su macOS il prefisso usa il nome del volume, su Linux il mount point.

---

9Tab Configurazione

Il tab Configurazione permette di personalizzare i parametri di tutti i modelli AI e le preferenze dell'applicazione. Le impostazioni vengono salvate in config_new.yaml.

Sezione: Connessione LLM

Parametro	Descrizione	Default
Backend	Plugin LLM da utilizzare (Ollama, LM Studio)	Ollama
Endpoint	URL del server LLM	Dipende dal plugin selezionato
Modello	Nome del modello da utilizzare	qwen3-vl:8b-instruct-q4_K_M
Timeout	Secondi massimi per risposta	180

Sezione: Lingua

Impostazione	Descrizione
Lingua interfaccia	Lingua dei menu e pulsanti dell'app (IT/EN/FR/DE/ES/PT)
Lingua output LLM	Lingua in cui il modello LLM genera tag e descrizioni (indipendente dalla UI)

Sezione: Editor esterno

Configura il percorso dell'editor fotografico esterno (Lightroom, Capture One, ecc.) per aprire i file originali direttamente dalla Galleria.

Sezione: Allocazione Device per Modello

Questa sezione permette di assegnare ogni modello AI a GPU o CPU individualmente. Una tabella mostra tutti i modelli con la stima VRAM e un selettore GPU/CPU per ciascuno.

Elemento	Descrizione
Tabella modelli	Ogni riga mostra modello, stima VRAM (~GB) e selettore GPU/CPU
Barra budget VRAM	Mostra in tempo reale la VRAM totale utilizzata (modelli + LLM) rispetto alla VRAM disponibile. Colore: verde (≤80%), ambra (≤95%), rosso (>95%)
Riga LLM	Mostra la VRAM occupata dal modello LLM (Ollama/LM Studio), rilevata automaticamente o stimata dal nome del modello
Auto-ottimizza	Calcola la distribuzione ottimale GPU/CPU in base all'hardware rilevato, al budget VRAM e alla VRAM del LLM

Sezione: Modelli AI

Percorso della directory dei modelli AI (Models/). Può essere relativo alla root di OffGallery o un percorso assoluto (es. su un disco esterno capiente).

---

9bPlugin

OffGallery include un sistema di plugin auto-discovery: i plugin vengono rilevati automaticamente dalla cartella plugins/ all'avvio, senza configurazione manuale. I plugin si dividono in due categorie: LLM (generazione testo) e Dati (arricchimento contestuale).

9b.1 Plugin LLM — generazione testo

Abilitano la generazione automatica di tag, descrizioni e titoli tramite modelli LLM Vision locali. Configurazione dal tab Configurazione → Connessione LLM.

Plugin	Backend	Endpoint default	Note
Ollama	Ollama locale	http://localhost:11434	Ottimizzato per qwen3-VL, llava, gemma3. Supporto think=false, diagnostica timing, warmup/unload VRAM automatici. Consigliato per GPU NVIDIA e Apple Silicon.
LM Studio	LM Studio server Plugin di Riccardo Merlotti	http://localhost:1234	API OpenAI-compatible. Supporto AMD/DirectML, unload via CLI lms. Consigliato per GPU AMD o chi preferisce un'interfaccia grafica per la gestione modelli.

Modelli consigliati

Modello	Backend	VRAM richiesta	Qualità output
qwen3-vl:8b-instruct-q4_K_M	Ollama	~6 GB	Eccellente — consigliato
qwen3-vl:4b-instruct-q4_K_M	Ollama	~4 GB	Buona — per GPU con poca VRAM
llava:7b	Ollama	~5 GB	Discreta
qwen3-VL (qualsiasi quantizzazione)	LM Studio	variabile	Eccellente

Come cambiare backend

1. Vai nel tab Configurazione
2. Nella sezione Connessione LLM, seleziona il backend dal menu a tendina
3. Verifica che endpoint e modello siano corretti per il backend scelto
4. Clicca Test Connessione per verificare il collegamento

9b.2 Plugin Dati — arricchimento contestuale

Arricchiscono le foto già nel database con informazioni aggiuntive derivate da GPS, data/ora e tassonomia BioCLIP. Si eseguono dalla Gallery (menu contestuale) o in batch dal tab Processing.

Plugin	Funzione	Richiede	Output nel DB
GeoNames	Gerarchia geografica completa da GPS: Continente → Paese → Regione → Città. Dati GeoNames bundled, nessuna API.	GPS nella foto	Campo geo_hierarchy. Abilita filtro Luogo e filtro GPS a 4 stati nella Ricerca.
GeoSpecies	Restringe il campo di ricerca di BioCLIP alle sole specie biologiche attese nella posizione GPS (dati GBIF/eBird). Riduce da ~450k specie globali a un sottoinsieme geografico pertinente. Si attiva automaticamente durante l'elaborazione batch — non eseguibile manualmente dalla Gallery.	GPS + BioCLIP già eseguito	Aggiorna bioclip_taxonomy con classificazione più precisa.
NaturArea	Identifica se la foto è stata scattata in un'area protetta (database WDPA) e il tipo di habitat (ESA WorldCover: bosco, macchia, prato, urbano, acqua…).	GPS	Campi protected_area e habitat. Abilita filtri Habitat e Area protetta nella Ricerca.
Meteo	Recupera le condizioni meteo storiche (Open-Meteo) al momento esatto dello scatto: temperatura, umidità, vento, precipitazioni, condizione.	GPS + data/ora + connessione internet	Campo weather_context (JSON). Abilita filtro Condizione meteo nella Ricerca.
BioNomen	Aggiunge i nomi comuni biologici nella lingua configurata (GBIF, 6 lingue). Esempio: Ardea cinerea → "Airone cenerino" (IT), "Grey Heron" (EN).	BioCLIP già eseguito	Campo vernacular_name. Abilita filtro Nome comune con autocompletamento nella Ricerca.

Griglia: combinazioni plugin dati e prerequisiti

Plugin	GPS presente	BioCLIP eseguito	Internet	Risultato
GeoNames	✅ Sì	—	No	Gerarchia geografica completa
GeoNames	❌ No	—	—	Saltato — log avviso
GeoSpecies	✅ Sì	✅ Sì	No	BioCLIP raffinato per area geografica
GeoSpecies	❌ No	✅ Sì	—	Saltato — GPS necessario
GeoSpecies	✅ Sì	❌ No	—	Saltato — BioCLIP necessario
NaturArea	✅ Sì	—	No	Area protetta + habitat rilevati
NaturArea	❌ No	—	—	Saltato — GPS necessario
Meteo	✅ Sì	—	✅ Sì	Condizioni meteo storiche recuperate
Meteo	❌ No	—	—	Saltato — GPS necessario
Meteo	✅ Sì	—	❌ No	Errore connessione — log warning
BioNomen	—	✅ Sì	No (dopo prima config)	Nomi comuni aggiunti nella lingua configurata
BioNomen	—	❌ No	—	Saltato — BioCLIP necessario

9b.3 Plugin Contesto Prompt — personalizzazione del prompt LLM

Il plugin Contesto Prompt inietta un blocco CONTEXT personalizzato nel prompt Vision-Language di OffGallery, orientando il modello verso il dominio fotografico specifico dell'archivio. Senza un preset attivo il comportamento è identico al prompt standard.

Preset disponibili

Icona	Nome	Dominio
⬜	Standard	Prompt standard OffGallery — nessun contesto aggiuntivo
🦋	Archivio Naturalistico	Specie, habitat, comportamento animale — fotografia scientifica
🏔	Paesaggio e Territorio	Geomorfologia, luce naturale, stagione, contesto geografico
🔭	Astrofotografia	Oggetti celesti, costellazioni, condizioni atmosferiche
🔬	Macro Scientifico	Dettaglio estremo, strutture microscopiche, entomologia
🐠	Subacqueo	Specie marine, comportamento, condizioni di visibilità
📰	Reportage e Documentario	Contesto sociale, narrativa visiva, documentazione storica
🛍	Commerciale e Prodotto	Prodotto, brand, comunicazione visiva, composizione tecnica
🌆	Street e Urbano	Vita urbana, architettura, luce ambientale, interazione sociale

Come selezionare un preset

1. Vai nel tab Plugin e clicca Configura ▸ nella card Contesto Prompt
2. Seleziona un preset dalla lista
3. Clicca ✅ Attiva — il preset diventa attivo per tutte le elaborazioni successive
4. Per tornare al prompt standard seleziona ⬜ Standard e premi Attiva

Il preset attivo è mostrato accanto alla card nel tab Plugin e nel dropdown Contesto prompt del tab Elaborazione. Le impostazioni vengono ricordate tra le sessioni.

Preset utente

È possibile generare preset personalizzati tramite il modello LLM locale configurato in OffGallery:

1. Nel dialog Configura, espandi la sezione Genera nuovo preset
2. Descrivi il dominio fotografico nel campo testo (es. "archivio di fotografia subacquea in acque dolci, con focus su invertebrati e alghe")
3. Clicca Genera — il modello LLM crea il blocco CONTEXT ottimizzato
4. Rivedi il testo generato, dai un nome al preset e clicca Salva

I preset utente sono contrassegnati con ★ nella lista e possono essere eliminati con il pulsante 🗑 Elimina. I preset built-in non possono essere eliminati.

9b.4 Accesso beta e installazione

Installazione plugin (zip ricevuto)

1. Estrarre il contenuto dello zip nella cartella plugins/ della propria installazione OffGallery.
2. La struttura risultante deve essere:

   plugins/
   └── nome_plugin/
       ├── manifest.json
       └── nome_plugin.py  (o file principale indicato nel manifest)

3. Riavvia OffGallery — il plugin viene rilevato automaticamente. Nel pannello Log vedrai conferma del caricamento.

Plugin BioNomen — configurazione database specie

Il database delle specie biologiche va scaricato scegliendo i taxa di interesse (richiede internet solo la prima volta):

1. Avvia OffGallery
2. Vai nella tab Plugin e clicca Configura nella card BioNomen
3. Seleziona i taxa di interesse (Aves, Mammalia, Reptilia, Amphibia, Insecta, Plantae)
4. Clicca Scarica database

---

10Tab Log

Il tab Log è il pannello di monitoraggio centralizzato dell'applicazione. Cattura in tempo reale tutti i messaggi prodotti da qualsiasi modulo — compresi gli output di print() e stderr — e li mostra in un'area di testo scorrevole con sintassi colorata.

Contenuto del log

• Log di avvio dell'applicazione (caricati dalla splash screen, sezione ═══ LOG AVVIO ═══)
• Ogni file in elaborazione: operazione corrente (EXIF, embedding CLIP/DINOv2, BioCLIP, LLM, geotag, score estetico/tecnico)
• Avvisi WARNING per file non elaborabili (RAW senza anteprima estraibile, timeout Ollama)
• Errori ERROR con dettagli tecnici per il troubleshooting
• Messaggi di sistema e di configurazione al cambio di impostazioni

Formato di ogni riga

[HH:MM:SS] LEVEL    - nome.modulo - messaggio

Controlli disponibili

Controllo	Funzione
Checkbox DEBUG	Mostra/nasconde messaggi di debug dettagliati (molto verbosi, utili per diagnosi)
Checkbox INFO	Mostra/nasconde messaggi informativi normali (operazioni in corso)
Checkbox WARNING	Mostra/nasconde avvisi (file saltati, parametri fuori range)
Checkbox ERROR	Mostra/nasconde errori critici. Copre anche CRITICAL
Pulsante 🗑️ Clear	Svuota il log dalla visualizzazione e dalla memoria

---

11BioCLIP e Tassonomia Biologica

BioCLIP2 è un modello Vision specializzato nel riconoscimento di specie biologiche. È stato addestrato su ~450.000 specie del Tree of Life e produce una classificazione tassonomica completa a 7 livelli:

Regnum › Phylum › Classis › Ordo › Familia › Genus › Species
  es: Animalia › Chordata › Aves › Pelecaniformes › Ardeidae › Ardea › Ardea cinerea

Dove appare la tassonomia

• Galleria (tooltip): sezione "Tassonomia" separata dai tag
• Export XMP: come HierarchicalSubject con prefisso AI|Taxonomy|...
• Database: campo dedicato bioclip_taxonomy (mai mescolato con i tag)

12Geotag Offline

OffGallery legge le coordinate GPS dai metadati EXIF e le converte in una gerarchia geografica leggibile, usando dati GeoNames bundled (~130.000 città): nessuna API esterna, nessuna connessione necessaria.

Il formato output è:

GeOFF | Europe | Italy | Sardegna | Trinità d'Agultu

In export XMP appare come HierarchicalSubject con prefisso GeOFF|, visibile in Lightroom come gerarchia separata dalle keyword utente.

13Sync State XMP

OffGallery traccia lo stato di sincronizzazione di ogni immagine con il suo file XMP:

Stato	Significato
PERFECT_SYNC	Il file XMP esiste ed è aggiornato con il contenuto del database
DIRTY	Il database è stato aggiornato dopo l'ultimo export XMP — il file XMP è obsoleto
NO_XMP	Nessun file XMP ancora esportato per questa immagine
XMP_NEWER	Il file XMP è stato modificato esternamente (es. da Lightroom) dopo l'ultimo import

14Supporto Multilingua

OffGallery gestisce tre livelli di lingua indipendenti:

1. Lingua dell'interfaccia: pulsanti, menu, etichette (6 lingue: IT, EN, FR, DE, ES, PT)
2. Lingua output LLM: lingua in cui il modello genera tag e descrizioni (configurabile separatamente)
3. Lingua query: le query di ricerca vengono tradotte automaticamente offline via Argostranslate — puoi cercare in italiano anche se i tag sono in inglese

---

15FAQ — Domande Frequenti

Ollama non risponde / timeout

Verifica che Ollama sia in esecuzione. Su Windows: cerca "Ollama" nel system tray. Su macOS/Linux: esegui ollama list nel terminale. Assicurati che il modello configurato sia scaricato (es. ollama pull qwen3-vl:8b-instruct-q4_K_M).

I tag generati sono in inglese ma voglio l'italiano

Vai in Configurazione → Lingua output LLM e seleziona "Italiano". Usa poi "Solo Gen. AI" per rigenerare i tag su tutte le foto già nel database.

La ricerca semantica non trova foto pertinenti

Gli embedding CLIP potrebbero essere stati generati con una versione incompatibile del modello. Rielabora le foto con "Riprocessa tutte" dopo aver verificato le versioni delle librerie. Su Windows e Linux reinstalla tramite il wizard (OffGallerySetup.exe o OffGallerySetup); su macOS vedi installer/INSTALL_GUIDE_IT.md per i requisiti di versione.

Una foto RAW non viene elaborata

Alcuni formati RAW high-efficiency (es. NEF con compressione loss-less) non contengono un'anteprima JPEG estraibile. In questi casi OffGallery salva i metadati EXIF ma salta embedding e LLM. Controlla il tab Log per i dettagli.

Come aggiorno OffGallery?

Scarica il nuovo ZIP da GitHub ed estrai sovrascrivendo la cartella esistente. I tuoi dati (database/, INPUT/, cache/) non sono inclusi nello ZIP e restano intatti. Se hai installato con git clone, basta eseguire git pull dalla cartella di OffGallery.

Posso usare un modello o backend LLM diverso?

Sì. In Configurazione puoi selezionare un backend diverso (Ollama o LM Studio) e cambiare il modello. Modelli testati con Ollama: qwen3-vl:8b-instruct-q4_K_M (consigliato), qwen3-vl:4b-instruct-q4_K_M, llava:7b, minicpm-v. Con LM Studio: qwen3-VL (consigliato). Risultati migliori con modelli vision multimodali.

Come passo a LM Studio?

Installa LM Studio, scarica un modello vision (consigliato: qwen3-VL) e avvia il server. In OffGallery, vai in Configurazione e seleziona LM Studio: l'indirizzo si aggiorna automaticamente a http://localhost:1234. Inserisci il nome del modello e clicca Test. Nessun file da modificare a mano.

LM Studio funziona con GPU NVIDIA?

Sì. LM Studio rileva automaticamente le GPU NVIDIA e usa CUDA. Non serve configurare nulla di diverso. LM Studio è particolarmente utile per chi ha GPU AMD (supporto DirectML), dove Ollama non funziona bene. Con NVIDIA entrambi i backend funzionano.

Dopo l'aggiornamento devo riconfigurare il backend LLM?

No. Se usavi Ollama, continua a funzionare automaticamente. Il sistema rileva Ollama come backend predefinito anche se il tuo file di configurazione non ha ancora la voce corrispondente. Il selettore del backend appare nel tab Configurazione solo per chi vuole cambiare.

I dati BioCLIP appaiono come keyword in Lightroom

È il comportamento atteso. Appariranno come gerarchia separata AI > Taxonomy > ... nella struttura parole chiave di Lightroom. Non interferisce con le tue keyword.

16Troubleshooting

Problema	Causa probabile	Soluzione
Score CLIP sempre vicini a zero	Embedding generati con versione errata di transformers	Esegui pip install transformers==4.57.3 e reimporta le foto
Geotag errato (città sbagliata)	GPS con longitudine Ovest non interpretata correttamente	Rielabora le foto con versione ≥ 10 Mar 2026
App si avvia ma non mostra finestra (macOS)	Segfault Qt/Cocoa al primo avvio	Usa il launcher aggiornato che scarica i modelli in processo separato
Errore "mat1 and mat2 shapes cannot be multiplied"	Incompatibilità versione transformers con CLIP ViT-L/14	Installa le versioni pinnate: transformers==4.57.3 huggingface-hub==0.36.0 open-clip-torch==3.2.0
Import XMP non importa alcuni tag	Tag con prefisso AI|Taxonomy| o GeOFF| vengono filtrati intenzionalmente	È il comportamento corretto. Questi tag sono gestiti internamente da OffGallery.
Conda non trovato all'avvio (macOS)	Architettura Miniconda sbagliata (x86_64 su Apple Silicon)	Reinstalla Miniconda con architettura arm64. Vedi README sezione Installazione.

17Disinstallazione

Windows: OffGallerySetup.exe non include una funzione di disinstallazione automatica. La rimozione si esegue manualmente in due passi: eliminare l'ambiente conda e rimuovere la cartella dell'applicazione. Linux/macOS: stessa procedura — cartella estratta con ambiente conda associato.

Windows

1. Apri il Prompt di Anaconda (Anaconda Prompt) dal menu Start.
2. Rimuovi l'ambiente conda:

   conda deactivate
   conda env remove -n OffGallery

3. Elimina la cartella dell'applicazione (es. C:\OffGallery-main o dove l'hai estratta) tramite Esplora File oppure da prompt:

   rmdir /s /q C:\OffGallery-main

4. Se hai creato un collegamento sul Desktop, eliminalo manualmente.

macOS

1. Apri il Terminale.
2. Rimuovi l'ambiente conda:

   conda deactivate
   conda env remove -n OffGallery

3. Elimina la cartella dell'applicazione (es. /Applications/OffGallery-main):

   rm -rf /Applications/OffGallery-main

4. Rimuovi eventuali file di configurazione nella home:

   rm -rf ~/.offgallery

Linux

1. Apri il terminale.
2. Rimuovi l'ambiente conda:

   conda deactivate
   conda env remove -n OffGallery

3. Elimina la cartella dell'applicazione:

   rm -rf ~/OffGallery-main

   (sostituisci con il percorso effettivo dove hai estratto l'app)
4. Rimuovi eventuali file di configurazione:

   rm -rf ~/.offgallery

Cosa rimane dopo la disinstallazione

Elemento	Posizione	Rimosso dai passi sopra?
Ambiente conda OffGallery	~/miniconda3/envs/OffGallery/	Sì — conda env remove
Cartella applicazione	Dove l'hai estratta	Sì — rimossa manualmente
Database immagini	Dentro la cartella app (database/)	Sì — rimosso con la cartella
Modelli AI scaricati	Dentro la cartella app (Models/) o percorso custom in config_new.yaml	Solo se nella cartella app; altrimenti rimuovere manualmente
Cache HuggingFace	~/.cache/huggingface/ (Linux/macOS) · %USERPROFILE%\.cache\huggingface\ (Windows)	No — va rimossa manualmente se desiderato
Miniconda / conda stesso	~/miniconda3/	No — conda rimane installato per altri ambienti
File XMP sidecar	Accanto alle foto originali	No — sono tuoi dati, non vengono toccati

18Reinstallazione

Se hai rimosso OffGallery e vuoi reinstallarlo da zero, segui questi passi nell'ordine indicato per evitare conflitti con residui della vecchia installazione.

1. Verifica che la vecchia installazione sia rimossa completamente (Windows e Linux)

Controlla che non rimangano residui della precedente installazione:

1. Cartella applicazione: verifica che la cartella di OffGallery (es. C:\Users\nome\OffGallery o dove l'avevi installata) sia stata eliminata. Se esiste ancora, cancellala manualmente prima di procedere.
2. Ambiente conda: apri il Prompt di Anaconda dal menu Start e verifica:

   conda env list

   Se compare OffGallery nella lista, rimuovilo:

   conda env remove -n OffGallery

   Un ambiente rimasto corrotto dalla vecchia installazione può causare errori anche nella nuova.

Windows — reinstallazione con Miniconda esistente

Se Miniconda è già installato e funzionante, puoi procedere direttamente:

1. Scarica il nuovo OffGallerySetup.exe dal sito — non riutilizzare un installer scaricato in precedenza.
2. Avvia l'installer. Se Windows mostra l'avviso "App non riconosciuta" (SmartScreen), clicca Ulteriori informazioni → Esegui comunque: è normale per applicazioni senza firma digitale.
3. Il wizard rileverà Miniconda già presente e creerà solo il nuovo ambiente OffGallery.

Windows — reinstallazione completa da zero (incluso Miniconda)

Se vuoi ripartire completamente da zero o Miniconda è corrotto:

1. Disinstalla Miniconda dal Pannello di Controllo → Programmi.
2. Scarica il nuovo OffGallerySetup.exe dal sito.
3. Avvialo: installerà Miniconda, creerà l'ambiente OffGallery e scaricherà tutti i modelli AI (~8 GB).

macOS — reinstallazione manuale

Su macOS non è disponibile un installer grafico. Segui i passi descritti in installer/INSTALL_GUIDE_IT.md incluso nell'archivio dell'applicazione. In sintesi:

1. Scarica l'archivio sorgente più recente da GitHub Releases ed estrailo.
2. Apri il Terminale ed esegui lo script di installazione:

   bash installer/install.sh

3. Lo script creerà l'ambiente conda OffGallery e scaricherà i modelli AI.

Linux — reinstallazione

Scarica il nuovo OffGallerySetup (binario Linux) dal sito, rendilo eseguibile e avvialo:

chmod +x OffGallerySetup
./OffGallerySetup

OffGallery  ·  Manuale Utente v1.0  ·  Aprile 2026  ·  github.com/HEGOM61ita/OffGallery  ·  Crediti e licenze