From 93deacf418afaa3f3d2f50bfe23d7e76b1526d08 Mon Sep 17 00:00:00 2001 From: Alberto Balbo Date: Tue, 21 Oct 2025 10:00:55 +0200 Subject: [PATCH] Rinominato progetto da "Ganimede" a "Converter" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rinominato file soluzione da `Ganimede.sln` a `Converter.sln` - Rinominato file progetto da `Ganimede.csproj` a `Converter.csproj` - Aggiornato namespace da `Ganimede.Properties` a `Converter.Properties` - Aggiunte proprietà `DefaultExtractionMode` e `SingleFrameUseSubfolder` - Aggiunto file `README.md` con documentazione dettagliata - Mantenuta struttura del progetto con aggiornamenti per il nuovo nome --- Ganimede/{Ganimede.sln => Converter.sln} | 2 +- .../{Ganimede.csproj => Converter.csproj} | 0 .../Ganimede/Properties/Settings.Designer.cs | 7 +- README.md | 853 ++++++++++++++++++ 4 files changed, 857 insertions(+), 5 deletions(-) rename Ganimede/{Ganimede.sln => Converter.sln} (87%) rename Ganimede/Ganimede/{Ganimede.csproj => Converter.csproj} (100%) create mode 100644 README.md diff --git a/Ganimede/Ganimede.sln b/Ganimede/Converter.sln similarity index 87% rename from Ganimede/Ganimede.sln rename to Ganimede/Converter.sln index 2981449..b721991 100644 --- a/Ganimede/Ganimede.sln +++ b/Ganimede/Converter.sln @@ -3,7 +3,7 @@ Microsoft Visual Studio Solution File, Format Version 12.00 # Visual Studio Version 17 VisualStudioVersion = 17.14.36408.4 MinimumVisualStudioVersion = 10.0.40219.1 -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Ganimede", "Ganimede\Ganimede.csproj", "{94D2BB13-2831-0E3F-70BC-3385A57E87F3}" +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Converter", "Ganimede\Converter.csproj", "{94D2BB13-2831-0E3F-70BC-3385A57E87F3}" EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution diff --git a/Ganimede/Ganimede/Ganimede.csproj b/Ganimede/Ganimede/Converter.csproj similarity index 100% rename from Ganimede/Ganimede/Ganimede.csproj rename to Ganimede/Ganimede/Converter.csproj diff --git a/Ganimede/Ganimede/Properties/Settings.Designer.cs b/Ganimede/Ganimede/Properties/Settings.Designer.cs index 7a12c26..9d0ff23 100644 --- a/Ganimede/Ganimede/Properties/Settings.Designer.cs +++ b/Ganimede/Ganimede/Properties/Settings.Designer.cs @@ -8,7 +8,7 @@ // //------------------------------------------------------------------------------ -namespace Ganimede.Properties { +namespace Converter.Properties { [global::System.Runtime.CompilerServices.CompilerGeneratedAttribute()] @@ -118,8 +118,7 @@ namespace Ganimede.Properties { this["DefaultCustomPrefix"] = value; } } - - // NEW: default extraction mode (Full, SingleFrame, Auto) + [global::System.Configuration.UserScopedSettingAttribute()] [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] [global::System.Configuration.DefaultSettingValueAttribute("Full")] @@ -131,7 +130,7 @@ namespace Ganimede.Properties { this["DefaultExtractionMode"] = value; } } - + [global::System.Configuration.UserScopedSettingAttribute()] [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] [global::System.Configuration.DefaultSettingValueAttribute("False")] diff --git a/README.md b/README.md new file mode 100644 index 0000000..de3904d --- /dev/null +++ b/README.md @@ -0,0 +1,853 @@ +# Ganimede - Estrattore Frame Video + +![.NET 8](https://img.shields.io/badge/.NET-8.0-blue) +![WPF](https://img.shields.io/badge/WPF-Windows-lightgrey) +![FFmpeg](https://img.shields.io/badge/FFmpeg-Required-green) + +**Ganimede** è un'applicazione desktop Windows avanzata per l'estrazione automatica di frame da file video. Progettata con WPF e .NET 8, offre un'interfaccia moderna, gestione coda multi-video e configurazioni personalizzabili per ogni job. + +--- + +## 📋 Indice + +- [Caratteristiche Principali](#-caratteristiche-principali) +- [Requisiti di Sistema](#-requisiti-di-sistema) +- [Installazione](#-installazione) +- [Guida Rapida](#-guida-rapida) +- [Interfaccia Utente](#-interfaccia-utente) +- [Modalità di Estrazione](#-modalità-di-estrazione) +- [Configurazione Avanzata dei Job](#-configurazione-avanzata-dei-job) +- [Pattern di Naming](#-pattern-di-naming) +- [Impostazioni Globali](#-impostazioni-globali) +- [Gestione della Coda](#-gestione-della-coda) +- [Casi d'Uso Comuni](#-casi-duso-comuni) +- [Risoluzione Problemi](#-risoluzione-problemi) +- [Architettura Tecnica](#-architettura-tecnica) + +--- + +## 🚀 Caratteristiche Principali + +### Funzionalità Core +- ✅ **Estrazione batch multi-video** con gestione coda intelligente +- 🎯 **Tre modalità di estrazione**: Completa, Singolo Frame e Auto (con analisi euristica) +- 🔧 **Configurazione granulare** per singolo job o globale +- 📁 **Importazione massiva** da cartella con filtri automatici +- 🖼️ **Anteprima thumbnails** in tempo reale +- ⚙️ **6 pattern di naming** configurabili con prefissi custom +- 🔄 **Gestione sovrascrittura** (Chiedi, Salta, Sovrascrivi) +- 📐 **Ridimensionamento frame** con 5 preset (da 320x180 a Full HD) +- 📊 **Monitoraggio avanzato**: progressi in tempo reale, statistiche, log dettagliati +- 🎨 **Interfaccia moderna** dark-themed con feedback visivi immediati + +### Modalità di Estrazione Intelligente + +#### 🔹 **Modalità Completa** (Full) +Estrae **tutti i frame** del video in immagini PNG sequenziali. +- **Ideale per**: analisi frame-by-frame, time-lapse, dataset ML, animazioni +- **Output**: 1 immagine PNG per ogni frame (es. video 60fps 10s = 600 immagini) + +#### 🔹 **Modalità Singolo Frame** (SingleFrame) +Estrae **un unico frame rappresentativo** dal centro del video. +- **Ideale per**: thumbnails, anteprime, screenshot rapidi +- **Output**: 1 singola immagine PNG +- **Ottimizzazione**: può evitare la creazione di sottocartelle (configurabile) + +#### 🔹 **Modalità Auto** (Auto) +Analizza il video tramite **euristica intelligente** e decide automaticamente: +- **Criteri di decisione**: + - ✓ Video ≤ 2 secondi → SingleFrame + - ✓ Video 3-45s con bitrate basso → SingleFrame (possibile video statico) + - ✓ Altri casi → Full extraction +- **Ideale per**: processamento batch di video eterogenei +- **Feedback**: suggerisce la modalità anche se Full è selezionato + +--- + +## 💻 Requisiti di Sistema + +### Software +- **Sistema Operativo**: Windows 10/11 (x64) +- **Runtime**: .NET 8 Desktop Runtime ([Download](https://dotnet.microsoft.com/download/dotnet/8.0)) +- **FFmpeg**: Versione 4.4+ (binari `ffmpeg.exe` e `ffprobe.exe`) + +### Hardware Minimo +- **CPU**: Dual-core 2.0 GHz +- **RAM**: 4 GB +- **Spazio Disco**: 100 MB (applicazione) + spazio per frame estratti + +### Formati Video Supportati +`MP4`, `AVI`, `MOV`, `MKV`, `WMV`, `FLV`, `WEBM` + +--- + +## 📦 Installazione + +### 1. Installare .NET 8 Runtime +```powershell +# Verifica versione installata +dotnet --list-runtimes + +# Se non installato, scarica da: +# https://dotnet.microsoft.com/download/dotnet/8.0 +``` + +### 2. Installare FFmpeg + +#### Opzione A: Installazione Manuale +1. Scarica FFmpeg da [ffmpeg.org](https://ffmpeg.org/download.html) o [gyan.dev](https://www.gyan.dev/ffmpeg/builds/) +2. Estrai l'archivio (es. in `C:\ffmpeg\`) +3. Copia i binari da `bin\`: + - `ffmpeg.exe` + - `ffprobe.exe` +4. Configura il percorso in Ganimede → **⚙ Impostazioni** → **Configurazione FFmpeg** + +#### Opzione B: Installazione con Chocolatey +```powershell +choco install ffmpeg +``` + +#### Opzione C: Variabile PATH (Opzionale) +Aggiungi la cartella `bin` di FFmpeg alla variabile d'ambiente `PATH` per il rilevamento automatico. + +### 3. Avviare Ganimede +```powershell +# Dalla directory di build +cd Ganimede\bin\Release\net8.0-windows +.\Ganimede.exe +``` + +--- + +## 🎯 Guida Rapida + +### Workflow Base (5 minuti) + +1. **Seleziona cartella output** + ``` + Toolbar → 🗂 Seleziona Cartella Output → Scegli destinazione + ``` + +2. **Aggiungi video** + ``` + Toolbar → ➕ Aggiungi Video → Seleziona uno o più file + ``` + Oppure: + ``` + Toolbar → 📁 Importa Cartella → Importa tutti i video dalla cartella + ``` + +3. **Avvia elaborazione** + ``` + Toolbar → ▶ Avvia Coda + ``` + +4. **Monitora progressi** + - Barra di avanzamento per ogni job + - Statistiche in tempo reale nella barra di stato + - Anteprima thumbnails nel pannello destro + +### Workflow Avanzato + +1. **Seleziona video** (checkbox nei job) +2. **Configura selezionati** + ``` + Toolbar → ⚙ Configura Selezionati → Imposta parametri custom + ``` +3. **Avvia coda** e monitora l'elaborazione differenziata + +--- + +## 🖥️ Interfaccia Utente + +### Toolbar Principale + +| Pulsante | Funzione | Shortcut | +|----------|----------|----------| +| **➕ Aggiungi Video** | Apre dialog selezione file multipli | - | +| **📁 Importa Cartella** | Importa tutti i video da una cartella | - | +| **🗂 Seleziona Cartella Output** | Imposta cartella destinazione globale | - | +| **⚙ Configura Selezionati** | Apre finestra configurazione job selezionati | Solo se ≥1 selezionato | +| **▶ Avvia Coda** | Inizia elaborazione job in stato "Pending" | Disabilitato durante elaborazione | +| **⏹ Ferma** | Interrompe elaborazione corrente | Solo durante elaborazione | +| **🧹 Pulisci Completati** | Rimuove job completati/falliti/cancellati | - | +| **🗑 Pulisci Tutto** | Svuota l'intera coda (conferma richiesta) | - | +| **⚙ Impostazioni** | Apre finestra impostazioni globali | - | + +### Pannello Coda Job + +Ogni job mostra: +- ☑️ **Checkbox**: Selezione per configurazione batch +- 📹 **Nome video** + percentuale progresso +- 📊 **Barra di avanzamento**: Progresso in tempo reale +- 📝 **Stato**: Messaggio dettagliato operazione corrente +- 📋 **Configurazione**: + - 📁 Cartella output (Default o custom) + - 📐 Dimensione frame (Original, 320x180, etc.) + - 🔄 Modalità sovrascrittura (Ask, Skip, Overwrite) + - 🏷 Pattern naming (VideoNameProgressive, etc.) + - 🎯 Modalità estrazione (Full, SingleFrame, Auto) +- ✕ **Rimuovi**: Elimina job dalla coda + +### Pannello Laterale Destro + +#### Impostazioni Globali +- **Cartella Output**: Path globale per nuovi job (modificabile) +- **Anteprima Thumbnails**: + - Mostra fino a 60 frame dell'ultimo video completato + - Scroll verticale per navigare + - Dimensioni: 90x52px per thumbnail + +### Barra di Stato + +Informazioni in tempo reale: +``` +Pronto | Job: In attesa: 3 | In corso: 1 | Completati: 5 | Falliti: 0 +``` + +--- + +## 🎯 Modalità di Estrazione + +### Comparazione Modalità + +| Caratteristica | Full | SingleFrame | Auto | +|---------------|------|-------------|------| +| **Frame estratti** | Tutti | 1 (centrale) | Variabile | +| **Analisi preliminare** | ❌ | ❌ | ✅ | +| **Tempo elaborazione** | Alto | Minimo | Variabile | +| **Uso disco** | Alto | Minimo | Variabile | +| **Sottocartelle** | Sempre* | Opzionale* | Automatico | +| **Caso d'uso** | Analisi dettagliata | Thumbnails | Batch misti | + +*Configurabile nelle impostazioni globali + +### Algoritmo Euristica Modalità Auto + +``` +1. Analizza metadata video (FFProbe) + ├─ Durata + ├─ Framerate + ├─ Bitrate + └─ Risoluzione + +2. Applica regole euristiche: + ├─ SE durata ≤ 2s + │ └─> SUGGERIMENTO: SingleFrame + ├─ SE 3s < durata < 45s AND bitrate < (pixels * 0.3) + │ └─> SUGGERIMENTO: SingleFrame (video statico probabile) + └─ ALTRIMENTI + └─> SUGGERIMENTO: Full + +3. Applica suggerimento e processa +``` + +### Configurazione Sottocartelle (SingleFrame) + +**Comportamento predefinito:** +- `Full/Auto→Full`: Crea sempre sottocartella `OutputFolder\VideoName\` +- `SingleFrame`: Opzionale (impostazione `SingleFrameUseSubfolder`) + +**Esempio Output:** +``` +✓ Full extraction (CreateSubfolder=true): + C:\Output\Video1\frame_000001.png + C:\Output\Video1\frame_000002.png + ... + +✓ Single Frame (SingleFrameUseSubfolder=false): + C:\Output\Video1_000001.png + +✓ Single Frame (SingleFrameUseSubfolder=true): + C:\Output\Video1\Video1_000001.png +``` + +--- + +## ⚙️ Configurazione Avanzata dei Job + +### Finestra "Configura Selezionati" + +Accessibile tramite **⚙ Configura Selezionati** dopo aver selezionato ≥1 job. + +#### Sezione 1: Cartella di Output (Override) +- ☑️ **Usa cartella di output personalizzata** + - Sovrascrive la cartella globale per i job selezionati + - Include pulsante **Sfoglia** per selezione visuale +- ☑️ **Crea sottocartella per ogni video** + - Se abilitato: `OutputFolder\VideoName\frames...` + - Se disabilitato: `OutputFolder\frames...` (rischio collisione!) + +#### Sezione 2: Modalità di Estrazione +``` +○ Completa → Estrae tutti i frame +○ Singolo Frame → Estrae solo frame centrale +○ Auto → Decide automaticamente via euristica +``` + +#### Sezione 3: Pattern Nome File (Override) +- ☑️ **Usa pattern di naming personalizzato** +- **Dropdown pattern**: 6 opzioni disponibili (vedi [Pattern di Naming](#-pattern-di-naming)) +- **Prefisso Custom**: Campo testo per `CustomProgressive` pattern +- **Anteprima Live**: Mostra esempio filename in tempo reale + +#### Sezione 4: Modalità Sovrascrittura (Override) +- ☑️ **Usa comportamento di sovrascrittura personalizzato** +- **Opzioni**: + - `Chiedi`: Dialog conferma per ogni job con file esistenti + - `Salta`: Ignora frame già esistenti (velocizza re-run) + - `Sovrascrivi`: Forza sovrascrittura senza chiedere + +#### Sezione 5: Ridimensionamento Frame (Override) +- ☑️ **Usa dimensione frame personalizzata** +- **Preset disponibili**: + - `Risoluzione Originale` (default) + - `320x180` (Veloce, ~56KB/frame) + - `640x360` (Media, ~150KB/frame) + - `1280x720` (HD, ~400KB/frame) + - `1920x1080` (Full HD, ~800KB/frame) + +**Nota**: Ridimensionamenti maggiori aumentano tempo elaborazione e uso CPU. + +--- + +## 🏷️ Pattern di Naming + +### Pattern Disponibili + +#### 1. **VideoNameProgressive** (Default) +``` +Formato: {NomeVideo}_{Progressivo6Cifre}.png +Esempio: Video1_000001.png, Video1_000002.png, ... +Uso: Sequenze ordinate identificabili +``` + +#### 2. **FrameProgressive** +``` +Formato: frame_{Progressivo6Cifre}.png +Esempio: frame_000001.png, frame_000002.png, ... +Uso: Naming generico, compatibilità universal +``` + +#### 3. **VideoNameTimestamp** +``` +Formato: {NomeVideo}_{TimestampMs}.png +Esempio: Video1_000000ms.png, Video1_033ms.png, ... +Uso: Ricostruzione timeline esatta, sincronizzazione +``` + +#### 4. **CustomProgressive** +``` +Formato: {PrefissoCustom}_{Progressivo6Cifre}.png +Esempio: dataset_000001.png, train_000001.png, ... +Uso: Organizzazione dataset ML, batch naming +``` + +#### 5. **TimestampOnly** +``` +Formato: {Ore}h{Minuti}m{Secondi}s{Millisecondi}ms.png +Esempio: 00h00m00s000ms.png, 00h12m34s567ms.png, ... +Uso: Timeline pura, analisi temporale +``` + +#### 6. **VideoNameFrameProgressive** +``` +Formato: {NomeVideo}_frame_{Progressivo6Cifre}.png +Esempio: Video1_frame_000001.png, Video1_frame_000002.png, ... +Uso: Massima chiarezza, identificazione immediata +``` + +### Configurazione Prefisso Custom + +Nel pattern **CustomProgressive**, il prefisso si configura: +- **Globale**: Impostazioni → Naming File → `Prefisso Custom Predefinito` +- **Per Job**: Configura Selezionati → Pattern Nome File → `Prefisso` + +**Caratteri validi**: `a-z A-Z 0-9 _ -` + +--- + +## 🌐 Impostazioni Globali + +Accesso: **⚙ Impostazioni** (Toolbar) + +### Sezione: Configurazione FFmpeg + +#### Cartella Binari FFmpeg +- **Path**: Percorso assoluto alla cartella contenente `ffmpeg.exe` e `ffprobe.exe` +- **Validazione**: Controllo esistenza binari in tempo reale +- **Fallback**: Se path vuoto, cerca FFmpeg nel `PATH` di sistema +- **Status Indicator**: + - ✅ Verde: Binari trovati e validi + - ❌ Rosso: Binari mancanti o non validi + +**Esempio path validi:** +``` +C:\ffmpeg\bin +C:\Program Files\FFmpeg\bin +D:\Tools\ffmpeg-6.0\bin +``` + +### Sezione: Output + +#### Crea sottocartella per ogni video +- **Default**: ✅ Abilitato +- **Comportamento**: + - ✅ ON: `C:\Output\Video1\frames...` + - ❌ OFF: `C:\Output\frames...` (tutti i video nella stessa cartella) +- **Nota**: Disabilitare aumenta rischio collisione nomi file + +#### Cartella Output Predefinita +- **Path**: Cartella globale per nuovi job aggiunti +- **Persistenza**: Salvata in `Settings.Default.LastOutputFolder` +- **Override**: Configurabile per job singoli + +### Sezione: Impostazioni di Elaborazione + +#### Dimensione Frame Predefinita +- **Preset**: 5 opzioni (vedi [Ridimensionamento](#sezione-5-ridimensionamento-frame-override)) +- **Default**: `Dimensione Originale` +- **Impatto performance**: + - Original: 0% overhead + - 320x180: +10% tempo + - 1920x1080: +40% tempo (resize algoritmico) + +#### Comportamento Sovrascrittura Predefinito +- **Opzioni**: `Chiedi` | `Salta` | `Sovrascrivi` +- **Default**: `Chiedi` +- **Uso consigliato**: + - `Chiedi`: Primo run, prudenza + - `Salta`: Re-run incrementali, resume jobs + - `Sovrascrivi`: Ri-elaborazione forzata, pulizia output + +#### Modalità di Estrazione Predefinita +- **Opzioni**: `Completa` | `Singolo Frame` | `Auto` +- **Default**: `Completa` +- **Impatto**: Si applica a tutti i nuovi job aggiunti + +#### Singolo Frame: salvataggio +- ☑️ **Crea sottocartella anche per job a singolo frame** +- **Default**: ❌ Disabilitato (salva diretto in cartella output) +- **Se abilitato**: Crea `OutputFolder\VideoName\frame.png` anche per SingleFrame + +### Sezione: Naming File + +#### Pattern di Naming Predefinito +- **Dropdown**: 6 pattern disponibili +- **Preview Live**: Mostra esempio aggiornato in tempo reale +- **Apply**: Si applica a tutti i nuovi job (job esistenti invariati) + +#### Prefisso Custom Predefinito +- **Campo testo**: Stringa alfanumerica (default: `custom`) +- **Uso**: Pattern `CustomProgressive` +- **Anteprima dinamica**: Aggiornamento preview pattern istantaneo + +**Esempio Anteprima:** +``` +Pattern: CustomProgressive +Prefisso: dataset +Preview: dataset_000001.png +``` + +--- + +## 📊 Gestione della Coda + +### Stati Job + +| Stato | Icona | Descrizione | Azioni Disponibili | +|-------|-------|-------------|-------------------| +| **Pending** | ⏳ | In attesa di elaborazione | Configura, Rimuovi, Avvia | +| **Processing** | ▶️ | Elaborazione in corso | Ferma (cancel) | +| **Completed** | ✅ | Completato con successo | Rimuovi, Pulisci | +| **Failed** | ❌ | Errore durante elaborazione | Rimuovi, Pulisci | +| **Cancelled** | ⏹ | Annullato dall'utente | Rimuovi, Pulisci | + +### Operazioni sulla Coda + +#### ▶ Avvia Coda +- Elabora **sequenzialmente** tutti i job in stato `Pending` +- Disabilita pulsante durante elaborazione +- Continua finché coda vuota o `Ferma` premuto + +#### ⏹ Ferma +- Cancella job corrente dopo il frame in elaborazione +- Non interrompe immediatamente (attende completamento frame) +- Job corrente passa in stato `Cancelled` + +#### 🧹 Pulisci Completati +- Rimuove job in stato: `Completed`, `Failed`, `Cancelled` +- Mantiene job `Pending` e `Processing` +- Operazione istantanea senza conferma + +#### 🗑 Pulisci Tutto +- **Se nessun job in elaborazione**: + - Conferma → Svuota coda completamente +- **Se job in elaborazione**: + - Dialog tri-opzione: + - `Sì`: Ferma tutto e svuota + - `No`: Rimuovi solo job non in elaborazione + - `Annulla`: Annulla operazione + +#### ⚙ Configura Selezionati +- Disponibile solo con ≥1 job selezionato (checkbox) +- Applica configurazioni custom in batch +- Job non selezionati rimangono invariati + +### Statistiche Coda (Barra di Stato) + +``` +Job: In attesa: 3 | In corso: 1 | Completati: 5 | Falliti: 0 +``` + +- **In attesa**: Count job `Pending` +- **In corso**: Count job `Processing` (max 1) +- **Completati**: Count job `Completed` +- **Falliti**: Count job `Failed` + +--- + +## 💡 Casi d'Uso Comuni + +### 1. Creazione Dataset Machine Learning + +**Obiettivo**: Estrarre 10.000 frame da 50 video per training CNN. + +``` +1. Importa Cartella → Seleziona cartella video +2. Configura Selezionati (seleziona tutti): + - Modalità: Completa + - Dimensione: 640x360 (Media) + - Naming: CustomProgressive + - Prefisso: train + - Sovrascrittura: Sovrascrivi +3. Avvia Coda +4. Output: train_000001.png ... train_010000.png +``` + +**Risultato**: Dataset uniforme pronto per ingestion. + +### 2. Thumbnails Video Gallery + +**Obiettivo**: Generare 1 thumbnail per ogni video in una libreria di 200 video. + +``` +1. Importa Cartella → Seleziona libreria video +2. Impostazioni → Modalità Estrazione: Singolo Frame +3. Impostazioni → Singolo Frame: Disabilita sottocartelle +4. Impostazioni → Dimensione: 320x180 +5. Impostazioni → Naming: VideoNameProgressive +6. Avvia Coda +7. Output: Video1_000001.png, Video2_000001.png, ... +``` + +**Risultato**: 200 thumbnails in cartella unica, pronti per web gallery. + +### 3. Time-Lapse Frame Extraction + +**Obiettivo**: Estrarre tutti i frame da video timelapse per post-processing. + +``` +1. Aggiungi Video → Seleziona timelapse.mp4 +2. Configura Selezionato: + - Modalità: Completa + - Dimensione: Original + - Naming: VideoNameFrameProgressive + - Sovrascrittura: Chiedi +3. Avvia Coda +4. Post-processing: import in DaVinci Resolve / After Effects +``` + +**Risultato**: Sequenza frame originali per grading/compositing. + +### 4. Batch Eterogeneo (Screenshot + Sequenze) + +**Obiettivo**: 10 video misti (documentari + clip brevi) → estrazione intelligente. + +``` +1. Importa Cartella → Seleziona 10 video +2. Configura Selezionati (seleziona tutti): + - Modalità: Auto + - Dimensione: 1280x720 + - Naming: VideoNameProgressive +3. Avvia Coda +4. Sistema analizza ogni video e: + - Clip 3s staticità → 1 frame + - Documentari 30min → full extraction +``` + +**Risultato**: Ottimizzazione automatica tempo/spazio. + +### 5. Resume Job Interrotto + +**Obiettivo**: Riprendere estrazione interrotta senza ri-elaborare frame esistenti. + +``` +1. (Job precedente interrotto, 1500/5000 frame estratti) +2. Configura Job: + - Sovrascrittura: Salta +3. Avvia Coda +4. Sistema salta frame 1-1500, riprende da 1501 +``` + +**Risultato**: Risparmio tempo, nessuna duplicazione. + +### 6. Multi-Resolution Export + +**Obiettivo**: Estrarre stessi frame in 3 risoluzioni (thumbnails, web, archivio). + +``` +1. Aggiungi Video → video.mp4 (3 volte nella coda) +2. Configura Job 1: + - Output: C:\Output\thumbnails\ + - Dimensione: 320x180 +3. Configura Job 2: + - Output: C:\Output\web\ + - Dimensione: 1280x720 +4. Configura Job 3: + - Output: C:\Output\archive\ + - Dimensione: Original +5. Avvia Coda +``` + +**Risultato**: 3 set di frame ottimizzati per uso specifico. + +--- + +## 🔧 Risoluzione Problemi + +### Problema: "FFmpeg not found" + +**Sintomi**: Errore all'avvio elaborazione, log "FFmpeg binary not found". + +**Soluzioni**: +1. **Verifica installazione**: + ```powershell + ffmpeg -version + ffprobe -version + ``` +2. **Configura path manualmente**: + - Impostazioni → Configurazione FFmpeg → Sfoglia → Seleziona cartella `bin` +3. **Reinstalla FFmpeg**: + - Scarica build completa da [gyan.dev](https://www.gyan.dev/ffmpeg/builds/) + - Estrai e configura path in Ganimede + +### Problema: Elaborazione lentissima + +**Cause comuni**: +- Ridimensionamento attivo (1920x1080 → overhead +40%) +- Video ad altissima risoluzione (4K+) +- HDD lento (frame scritti su disco meccanico) +- CPU sottodimensionata + +**Soluzioni**: +- Usa dimensione frame `640x360` o inferiore +- Salva output su SSD +- Processa pochi video alla volta (ridurre I/O concorrente) +- Modalità `Auto` o `SingleFrame` per video brevi + +### Problema: "Access Denied" durante salvataggio frame + +**Cause**: +- Cartella output in directory protetta (`C:\Program Files`, etc.) +- File aperti in altro programma (viewer immagini, etc.) +- Permessi insufficienti + +**Soluzioni**: +- Seleziona cartella output in `Documents` o `Desktop` +- Chiudi programmi che potrebbero bloccare file +- Esegui Ganimede come amministratore (click destro → Esegui come amministratore) + +### Problema: Frame estratti sono neri/corrotti + +**Cause**: +- Codec video non supportato da FFmpeg build +- Video corrotto nel filesystem +- Timestamp seeking errato + +**Soluzioni**: +- Aggiorna FFmpeg all'ultima versione +- Verifica integrità video (riproduci in VLC) +- Prova pattern naming `VideoNameTimestamp` (seeking alternativo) + +### Problema: Applicazione crash all'avvio + +**Cause**: +- .NET 8 Runtime non installato +- File di configurazione corrotti +- Dipendenze mancanti + +**Soluzioni**: +1. **Verifica .NET**: + ```powershell + dotnet --list-runtimes + # Cerca "Microsoft.WindowsDesktop.App 8.0.x" + ``` +2. **Reset configurazione**: + ```powershell + # Elimina file settings (path utente) + del %LOCALAPPDATA%\Ganimede\user.config + ``` +3. **Reinstalla applicazione** + +### Problema: Thumbnails non vengono mostrati + +**Causa**: Limite 60 thumbnails, o cartella output vuota. + +**Verifica**: +- Controlla che job sia in stato `Completed` +- Verifica esistenza file PNG in cartella output +- Thumbnails mostrano ultimi 60 frame del job completato + +--- + +## 🏗️ Architettura Tecnica + +### Stack Tecnologico + +``` +Frontend: WPF (Windows Presentation Foundation) +Runtime: .NET 8 (Windows Desktop) +UI Pattern: MVVM (Model-View-ViewModel) +Encoding: FFMpegCore (wrapper .NET per FFmpeg) +Storage: Settings.settings (ApplicationSettings) +``` + +### Componenti Principali + +#### 1. **MainWindow.xaml** / **MainWindow.xaml.cs** +- Controller principale UI +- Gestione toolbar, coda visuale, thumbnails +- Event handlers per interazioni utente +- Binding a `VideoProcessingService` via `ObservableCollection` + +#### 2. **VideoProcessingService.cs** +- Core business logic +- Gestione coda asincrona (`async/await`) +- Processamento sequenziale job con `SemaphoreSlim` +- Eventi: `JobCompleted`, `JobFailed`, `ProcessingStarted`, `ProcessingStopped` +- Integrazione FFMpegCore per extraction + +#### 3. **VideoJob.cs** (Model) +- Entità dati job +- Implementa `INotifyPropertyChanged` per binding real-time +- Proprietà: + - Config base: `VideoPath`, `OutputFolder`, `Status`, `Progress` + - Custom overrides: `CustomOutputFolder`, `CustomFrameSize`, etc. + - Modalità: `ExtractionMode`, `SuggestedExtractionMode` +- Display properties per UI (`OutputFolderDisplay`, `FrameSizeDisplay`, etc.) + +#### 4. **NamingHelper.cs** +- Utility statica per generazione nomi file +- Implementazione 6 pattern naming +- Metodi helper: `GetPatternDescription()`, `GetPatternExample()` + +#### 5. **JobConfigWindow.xaml** / **JobConfigWindow.xaml.cs** +- Dialog configurazione batch job selezionati +- Validazione input real-time +- Preview pattern naming dinamica + +#### 6. **SettingsWindow.xaml** / **SettingsWindow.xaml.cs** +- Gestione impostazioni globali persistenti +- Integrazione `Properties.Settings` (.NET Settings Framework) +- Validazione path FFmpeg + +#### 7. **StatusColorConverter.cs** +- Value converter XAML per colori stati job +- Mapping: `Pending`→Grigio, `Processing`→Blu, `Completed`→Verde, etc. + +### Flusso Elaborazione + +``` +[MainWindow] Utente preme "Avvia Coda" + ↓ +[VideoProcessingService] StartProcessingAsync() + ↓ +[Loop] GetNextPendingJob() + ↓ +[ProcessJobAsync] Per ogni job: + ├─ FFProbe.AnalyseAsync() → Metadata video + ├─ Euristica Auto (se ExtractionMode = Auto) + ├─ Directory.CreateDirectory() → Crea output folder + ├─ SE SingleFrame: + │ └─ ExtractFrameAsync() → 1 frame centrale + ├─ SE Full: + │ └─ Loop ExtractFrameAsync() → Tutti i frame + ├─ Aggiornamento Progress ogni 10 frame + └─ JobCompleted/JobFailed event + ↓ +[MainWindow] Riceve evento → Aggiorna UI, carica thumbnails +``` + +### Threading & Async + +- **UI Thread**: WPF Dispatcher per binding updates +- **Background Thread**: `Task.Run` / `async/await` per FFmpeg calls +- **Sincronizzazione**: `SemaphoreSlim(1,1)` per processing seriale +- **Cancellation**: `CancellationTokenSource` per stop graceful + +### Persistenza Dati + +```csharp +// Settings salvate in ApplicationData utente +Settings.Default.LastOutputFolder // string +Settings.Default.LastVideoPath // string +Settings.Default.FFmpegBinFolder // string +Settings.Default.FrameSize // string (es. "1280,720") +Settings.Default.DefaultOverwriteMode // string (enum serializzato) +Settings.Default.DefaultNamingPattern // string (enum serializzato) +Settings.Default.DefaultExtractionMode // string (enum serializzato) +Settings.Default.CreateSubfolder // bool +Settings.Default.SingleFrameUseSubfolder // bool +Settings.Default.DefaultCustomPrefix // string + +// Percorso file (Windows): +%LOCALAPPDATA%\Ganimede\user.config +``` + +### Dipendenze NuGet + +```xml + + +``` + +--- + +## 📄 Licenza + +Questo progetto è distribuito con licenza **MIT**. Consulta il file `LICENSE` per i dettagli completi. + +--- + +## 👤 Autore + +**Ganimede Team** +📧 Contatto: [Inserire email/GitHub] + +--- + +## 🙏 Ringraziamenti + +- **FFmpeg Team** per il potente framework multimediale open-source +- **FFMpegCore** per il wrapper .NET elegante e performante +- Community .NET per supporto e feedback + +--- + +## 🔄 Versioni e Changelog + +### v1.0.0 (2025-01-XX) +- ✅ Release iniziale +- ✅ 3 modalità di estrazione (Full, SingleFrame, Auto) +- ✅ 6 pattern naming configurabili +- ✅ Configurazione granulare per job +- ✅ UI dark-themed moderna +- ✅ Sistema coda con stati avanzati +- ✅ Thumbnails preview real-time + +--- + +**🚀 Buon Lavoro con Ganimede!** + +Per segnalazioni bug, richieste feature o contributi, apri una issue nel repository GitHub del progetto.