fabioantonini/forensic-graphology

1# Documentazione Tecnica - Applicazione di Grafologia Forense2 3## Architettura del Sistema4 5L'applicazione di Grafologia Forense è strutturata in moduli indipendenti che lavorano insieme per fornire un'analisi completa di firme e documenti. L'architettura è basata su Python con un'interfaccia utente Gradio.6 7### Struttura delle Directory8 9```10forensic_graphology/11├── app.py                 # Punto di ingresso dell'applicazione12├── requirements.txt       # Dipendenze Python13├── README.md              # Documentazione generale14├── hf-space.yaml          # Configurazione per Hugging Face Spaces15├── src/                   # Codice sorgente16│   ├── preprocessing.py   # Pre-elaborazione delle immagini17│   ├── signature_analysis.py # Analisi delle firme18│   ├── font_analysis.py   # Analisi di font e inchiostro19│   ├── measurement.py     # Strumenti di misurazione20│   ├── image_enhancer.py  # Miglioramento delle immagini21│   ├── ml_models.py       # Modelli di machine learning22│   └── rag_system.py      # Sistema RAG23├── models/                # Directory per i modelli addestrati24├── uploads/               # Directory per i file caricati25├── results/               # Directory per i risultati generati26├── vector_store/          # Directory per il vector store27└── docs/                  # Documentazione28    ├── user_guide.md      # Guida utente29    └── technical_docs.md  # Documentazione tecnica30```31 32## Moduli Principali33 34### 1. Preprocessing (preprocessing.py)35 36Questo modulo gestisce la pre-elaborazione delle immagini di firme e documenti.37 38**Classi principali:**39- `ImagePreprocessor`: Classe per la pre-elaborazione delle immagini40 41**Metodi principali:**42- `load_image(image_path)`: Carica un'immagine da un percorso43- `convert_to_grayscale(image)`: Converte un'immagine in scala di grigi44- `normalize_image(image)`: Normalizza un'immagine45- `denoise_image(image)`: Riduce il rumore in un'immagine46- `binarize_image(image)`: Converte un'immagine in bianco e nero47- `preprocess_signature(image_path)`: Applica tutte le fasi di pre-elaborazione a un'immagine di firma48 49### 2. Signature Analysis (signature_analysis.py)50 51Questo modulo fornisce funzionalità per l'analisi e la comparazione di firme.52 53**Classi principali:**54- `SignatureAnalyzer`: Classe per l'analisi delle firme55 56**Metodi principali:**57- `extract_features_orb(image)`: Estrae caratteristiche ORB da un'immagine58- `extract_signature_metrics(image)`: Estrae metriche grafometriche da una firma59- `compare_signatures(image1_path, image2_path)`: Confronta due firme60- `visualize_comparison(comparison_result)`: Visualizza il risultato del confronto61- `generate_comparison_report(comparison_result)`: Genera un report testuale del confronto62 63### 3. Font Analysis (font_analysis.py)64 65Questo modulo analizza il tipo di font e l'inchiostro utilizzato nei documenti.66 67**Classi principali:**68- `FontAnalyzer`: Classe per l'analisi di font e inchiostro69 70**Metodi principali:**71- `detect_text_regions(image)`: Rileva le regioni di testo in un'immagine72- `extract_text(image, regions)`: Estrae il testo dalle regioni rilevate73- `analyze_font(image, regions)`: Analizza il tipo di font74- `analyze_ink(image)`: Analizza il tipo di inchiostro75 76### 4. Measurement (measurement.py)77 78Questo modulo fornisce strumenti per la misurazione di vari aspetti dei documenti.79 80**Classi principali:**81- `MeasurementTool`: Classe per la misurazione dei documenti82 83**Metodi principali:**84- `measure_line_spacing(image)`: Misura lo spazio tra le linee85- `measure_word_spacing(image)`: Misura lo spazio tra le parole86- `measure_margins(image)`: Misura i margini del documento87- `measure_character_slant(image)`: Misura l'inclinazione dei caratteri88- `create_digital_ruler(image)`: Crea un righello digitale89- `generate_measurement_report(image)`: Genera un report completo di misurazione90 91### 5. Image Enhancer (image_enhancer.py)92 93Questo modulo fornisce funzionalità per il miglioramento delle immagini.94 95**Classi principali:**96- `ImageEnhancer`: Classe per il miglioramento delle immagini97 98**Metodi principali:**99- `enhance_contrast(image, method)`: Migliora il contrasto di un'immagine100- `sharpen_image(image, kernel_size, strength)`: Applica un filtro di sharpening101- `apply_edge_detection(image, method)`: Applica un rilevatore di bordi102- `highlight_pressure_points(image)`: Evidenzia i punti di pressione103- `apply_emboss_effect(image)`: Applica un effetto di rilievo104- `create_signature_heatmap(image)`: Crea una mappa di calore della firma105 106### 6. Machine Learning Models (ml_models.py)107 108Questo modulo implementa modelli di machine learning per l'analisi delle firme.109 110**Classi principali:**111- `SignatureFeatureExtractor`: Estrae caratteristiche dalle firme112- `AnomalyDetector`: Rileva anomalie nelle firme usando Isolation Forest113- `SignatureVerifier`: Verifica l'autenticità delle firme usando una rete siamese114- `SiameseNetwork`: Implementazione della rete neurale siamese115 116**Metodi principali:**117- `extract_features(image_path)`: Estrae caratteristiche da un'immagine di firma118- `fit(signatures_df)`: Addestra il modello di rilevamento anomalie119- `predict(signature_path)`: Predice se una firma è anomala120- `verify(image_path1, image_path2)`: Verifica se due firme sono della stessa persona121 122### 7. RAG System (rag_system.py)123 124Questo modulo implementa un sistema RAG per la consultazione di documenti.125 126**Classi principali:**127- `DocumentProcessor`: Elabora e estrae testo dai documenti128- `VectorStore`: Gestisce il vector store per il sistema RAG129- `RAGSystem`: Implementa il sistema RAG completo130 131**Metodi principali:**132- `extract_text(file_path)`: Estrae il testo da un documento133- `process_document(file_path)`: Elabora un documento e lo divide in chunk134- `add_document(document_info)`: Aggiunge un documento al vector store135- `search(query, k)`: Cerca documenti simili a una query136- `query(query_text)`: Esegue una query sul sistema RAG137 138## Interfaccia Utente (app.py)139 140L'interfaccia utente è implementata utilizzando Gradio, una libreria Python per la creazione di interfacce web per modelli di machine learning.141 142**Funzioni principali:**143- `preprocess_image(image)`: Pre-elabora un'immagine144- `compare_signatures(image1, image2)`: Confronta due firme145- `analyze_font_and_ink(image)`: Analizza font e inchiostro146- `measure_document(image)`: Misura un documento147- `enhance_image(image, enhancement_type)`: Migliora un'immagine148- `detect_anomalies(image)`: Rileva anomalie in una firma149- `verify_signatures(image1, image2)`: Verifica due firme150- `upload_document(file)`: Carica un documento nel sistema RAG151- `query_rag(query_text)`: Esegue una query sul sistema RAG152 153## Dipendenze Principali154 155- **OpenCV**: Elaborazione delle immagini156- **NumPy**: Operazioni numeriche157- **Pandas**: Manipolazione dei dati158- **Matplotlib**: Visualizzazione159- **Scikit-learn**: Algoritmi di machine learning160- **PyTorch**: Deep learning161- **Gradio**: Interfaccia utente162- **LangChain**: Framework per il sistema RAG163- **Sentence-Transformers**: Modelli di embedding164- **ChromaDB**: Database vettoriale165- **PyMuPDF, python-docx, python-pptx**: Estrazione di testo da documenti166- **pytesseract**: OCR per l'estrazione di testo dalle immagini167 168## Deployment169 170L'applicazione è progettata per essere deployata su Hugging Face Spaces, una piattaforma per l'hosting di applicazioni di machine learning.171 172**File di configurazione:**173- `requirements.txt`: Elenca tutte le dipendenze Python174- `hf-space.yaml`: Configura l'ambiente Hugging Face Spaces175- `README.md`: Contiene metadati per Hugging Face Spaces176 177## Estensione dell'Applicazione178 179### Aggiungere Nuove Funzionalità180 181Per aggiungere nuove funzionalità all'applicazione:182 1831. Creare un nuovo modulo in `src/` o estendere un modulo esistente1842. Implementare la logica della nuova funzionalità1853. Aggiungere una nuova funzione in `app.py` che utilizza la nuova funzionalità1864. Aggiungere un nuovo tab o elemento UI in `create_interface()` in `app.py`187 188### Addestrare Nuovi Modelli189 190Per addestrare nuovi modelli di machine learning:191 1921. Raccogliere un dataset di firme (autentiche e false per il verificatore, solo autentiche per il rilevatore di anomalie)1932. Utilizzare le classi `AnomalyDetector` o `SignatureVerifier` per addestrare i modelli1943. Salvare i modelli addestrati nella directory `models/`1954. Aggiornare l'applicazione per utilizzare i nuovi modelli196 197## Considerazioni sulla Sicurezza198 199- L'applicazione non memorizza le immagini caricate a lungo termine200- I documenti caricati nel sistema RAG sono memorizzati localmente201- Non vengono utilizzate API esterne per l'elaborazione dei dati202- Il sistema RAG funziona in modalità di sola ricerca per evitare la necessità di token API203 204## Limitazioni Tecniche205 206- L'OCR potrebbe non funzionare correttamente con testi in lingue non latine207- I modelli di machine learning richiedono un addestramento specifico per casi d'uso particolari208- L'analisi del font e dell'inchiostro ha una precisione limitata209- Il sistema RAG funziona in modalità di sola ricerca, senza generazione di risposte AI210 211## Risoluzione dei Problemi212 213- **Errori di memoria**: Ridurre la dimensione delle immagini o utilizzare batch più piccoli214- **Errori di OCR**: Migliorare la qualità delle immagini o utilizzare pre-elaborazione215- **Prestazioni lente**: Ottimizzare i parametri dei modelli o utilizzare hardware più potente216 217## Riferimenti218 219- [OpenCV Documentation](https://docs.opencv.org/)220- [Scikit-learn Documentation](https://scikit-learn.org/stable/documentation.html)221- [PyTorch Documentation](https://pytorch.org/docs/stable/index.html)222- [Gradio Documentation](https://gradio.app/docs/)223- [LangChain Documentation](https://python.langchain.com/docs/get_started/introduction)224