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 (Qwen3.5 4B via Ollama)
• 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

Dopo l'installazione tramite wizard (vedi installer/INSTALL_GUIDE.md), avvia OffGallery dall'icona desktop o dalla voce nel menu applicazioni. 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. Avvia OffGallery dal collegamento creato dall'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 7 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 7 tab orizzontali nella parte superiore della finestra:

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

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 Elaborazione

Il tab Elaborazione è 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	Elabora solo le immagini non ancora presenti nel database. Le foto già analizzate vengono saltate.
Riprocessa tutte	Rianalizza tutte le immagini nella sorgente, anche quelle già nel database. Utile dopo aver aggiornato un modello o cambiato parametri.
Riprocessa tutte + Solo Gen. AI	Modalità speciale: rigenera solo tag, descrizione e titolo (LLM) sulle immagini già nel database. Salta EXIF ed embedding. 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 spuntato, sovrascrive tag/descrizione/titolo esistenti. Se non spuntato: per i tag fa merge (aggiunge solo i nuovi); per descrizione e titolo salta se già presenti.

4.4 Modalità "Solo Gen. AI"

La modalità Solo Gen. AI è accessibile attivando prima "Riprocessa tutte" e poi spuntando il checkbox "Solo Gen. AI" che appare accanto.

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

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 Galleria

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

---

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 Esportazione

Il tab Esportazione è 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.

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.5:4b-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 LLM

OffGallery utilizza un sistema di plugin per la generazione di tag, descrizioni e titoli tramite modelli LLM Vision. I plugin vengono rilevati automaticamente dalla cartella plugins/ all'avvio.

Plugin disponibili

I plugin LLM sono distribuiti separatamente dal codice sorgente di OffGallery.

Plugin	Backend	Endpoint default	Note
OffGallery Ollama Plugin	Ollama locale	http://localhost:11434	Ottimizzato per qwen3-VL, llava, gemma3. Supporto think=false, diagnostica timing, warmup/unload VRAM automatici
OffGallery LM Studio Plugin	LM Studio server	http://localhost:1234	Ottimizzato per API OpenAI-compatible. Supporto AMD/DirectML, unload via CLI lms. Modelli VL consigliati: qwen3-VL
BioNomen	—	—	Nomi comuni e scientifici di specie biologiche (Aves, Mammalia, Insecta, Plantae…). Database offline scaricabile da GBIF. Configurabile da Config → Plugin → BioNomen

I plugin sono distribuiti tramite la repo privata OffGallery_BETA, accessibile ai beta tester autorizzati. Per richiedere l'accesso: offgallery.ai.info@gmail.com

L'indirizzo email fornito sarà utilizzato esclusivamente per l'invio dell'accesso ai plugin e per eventuali notifiche di aggiornamento. Non verrà usato per altri scopi né condiviso con terze parti.

Installazione plugin (dalla repo beta)

Le istruzioni complete si trovano nel file plugins/INSTALL.md all'interno della repo beta. In sintesi:

1. Clona la repo beta in una cartella qualsiasi (non dentro OffGallery):

   git clone https://github.com/HEGOM61ita/OffGallery_BETA.git offgallery-beta
   cd offgallery-beta

2. Esegui l'installer per il tuo sistema operativo:
   • Windows — doppio clic su install_plugins.bat
   • macOS — doppio clic su install_plugins.command
   • Linux — bash install_plugins.sh
   L'installer individua automaticamente la tua installazione OffGallery e copia i plugin nella posizione corretta.
3. Riavvia OffGallery — i plugin vengono rilevati automaticamente all'avvio. Nel pannello Log vedrai:

   Plugin LLM attivo: Ollama
   Plugin LLM attivo: LM Studio
   BioNomen: plugin disponibile

Plugin BioNomen — database specie

Il database delle specie biologiche non è incluso nella repo: va scaricato dall'utente scegliendo i taxa di interesse. Il download avviene da GBIF e richiede internet solo la prima volta; l'uso successivo è completamente offline.

1. Avvia OffGallery
2. Vai in Config → Plugin → BioNomen → Configura
3. Seleziona i taxa di interesse (Aves, Mammalia, Reptilia, Amphibia, Insecta, Plantae)
4. Clicca Scarica database

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

---

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 qwen3.5:4b-q4_K_M sia scaricato (ollama pull qwen3.5:4b-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 (vedi INSTALL_GUIDE.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.5:4b, llava:7b, minicpm-v, moondream. 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

OffGallery non ha un installer tradizionale: è una cartella estratta con un ambiente conda associato. La rimozione completa si esegue in due passi: eliminare l'ambiente conda e rimuovere la cartella dell'applicazione.

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

OffGallery  ·  Manuale Utente v1.0  ·  Marzo 2026  ·  github.com/HEGOM61ita/OffGallery