alex/matlab-python
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

aggiornato readme dei src python

Browse Source
This commit is contained in:
alex
2025-10-13 23:06:10 +02:00
parent dcc4f5d26b
commit 6d14c3f3b3
1 changed files with 362 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

426
src/README.md
View File

@@ -1,6 +1,6 @@
# Sensor Data Processing System - Python Version # Sensor Data Processing System - Python Version
Conversione dei moduli MATLAB per l'elaborazione dati dei sensori di monitoraggio geotecnico. Conversione completa dei moduli MATLAB per l'elaborazione dati dei sensori di monitoraggio geotecnico.
## Descrizione ## Descrizione
@@ -10,60 +10,126 @@ Questo sistema elabora dati provenienti da varie tipologie di sensori utilizzati
- **Tilt**: Inclinometri e tiltmetri biassiali per monitoraggio deformazioni - **Tilt**: Inclinometri e tiltmetri biassiali per monitoraggio deformazioni
- **ATD** (Automatic Data Acquisition): Estensimetri, fessurimetri, e altri sensori di spostamento - **ATD** (Automatic Data Acquisition): Estensimetri, fessurimetri, e altri sensori di spostamento
## Stato Implementazione
**✅ CONVERSIONE COMPLETA - Tutti i moduli MATLAB sono stati convertiti in Python**
- ✅ **RSN Module** (100%)
- ✅ **Tilt Module** (100%)
- ✅ **ATD Module** (100%) - Tutti i sensori implementati
- ✅ **Common Utilities** (100%)
- ✅ **Validation Framework** (100%)
- ✅ **MATLAB Sync Tools** (100%)
## Struttura del Progetto ## Struttura del Progetto
``` ```
src/ src/
├── common/ # Moduli condivisi ├── main.py # Orchestratore principale (singolo/multi-chain, parallel)
│
├── common/ # Moduli condivisi
│ ├── database.py # Gestione connessioni e query MySQL │ ├── database.py # Gestione connessioni e query MySQL
│ ├── config.py # Caricamento parametri e configurazioni │ ├── config.py # Caricamento parametri e configurazioni
│ ├── logging_utils.py # Sistema di logging │ ├── logging_utils.py # Sistema di logging
│ └── validators.py # Validazione e filtraggio dati │ └── validators.py # Validazione e filtraggio dati
│ │
├── rsn/ # Elaborazione RSN sensors ├── rsn/ # Elaborazione RSN sensors (100% completo)
│ ├── main.py # Entry point principale │ ├── main.py # Entry point RSN
│ ├── main_async.py # Versione asincrona (opzionale)
│ ├── data_processing.py # Caricamento dati da DB │ ├── data_processing.py # Caricamento dati da DB
│ ├── conversion.py # Conversione dati grezzi -> unità fisiche │ ├── conversion.py # Conversione dati grezzi -> unità fisiche
│ ├── averaging.py # Media temporale dati │ ├── averaging.py # Media temporale con filtro Gaussiano
│ ├── elaboration.py # Elaborazione e calcolo spostamenti │ ├── elaboration.py # Elaborazione e calcolo spostamenti
│ ├── db_write.py # Scrittura dati elaborati su DB │ ├── db_write.py # Scrittura dati elaborati su DB
│ └── sensors/ # Moduli specifici per sensori │ └── sensors/ # Moduli specifici per sensori
│ │
├── tilt/ # Elaborazione inclinometri ├── tilt/ # Elaborazione inclinometri (100% completo)
│ ├── main.py # Entry point principale │ ├── main.py # Entry point Tilt
│ ├── geometry.py # Calcoli geometrici (rotazioni, quaternioni) │ ├── geometry.py # Calcoli geometrici (rotazioni, quaternioni)
│ ├── data_processing.py │ ├── data_processing.py # Caricamento TLHR, BL, PL, KLHR
│ ├── conversion.py # Conversione con calibrazione
│ ├── averaging.py # Media temporale
│ ├── elaboration.py # Calcolo spostamenti 3D
│ ├── db_write.py # Scrittura su DB
│ └── sensors/ │ └── sensors/
│ │
├── atd/ # Elaborazione ATD sensors ├── atd/ # Elaborazione ATD sensors (100% completo)
│ ├── main.py # Entry point principale │ ├── main.py # Entry point ATD
│ ├── star_calculation.py # Calcolo posizioni con metodo stella │ ├── star_calculation.py # Algoritmo stella per calcolo posizioni
│ ├── data_processing.py │ ├── data_processing.py # Caricamento RL, LL, PL, 3DEL, CrL, PCL, TuL
│ ├── sensors/ │ ├── conversion.py # Conversione con compensazione temperatura
│ └── reports/ # Generazione report │ ├── averaging.py # Media temporale
│ ├── elaboration.py # Elaborazioni avanzate
│ ├── db_write.py # Scrittura su DB
│ └── sensors/ # Moduli specifici per ogni tipo sensore
│ │
└── monitoring/ # Sistema monitoraggio e allerte ├── validation/ # Framework validazione Python vs MATLAB
│ ├── cli.py # Command-line interface per validazione
│ ├── validator.py # Logica comparazione dati
│ ├── comparator.py # Metriche e tolleranze
│ └── db_extractor.py # Estrazione dati da DB per confronto
│
└── monitoring/ # Sistema monitoraggio e allerte (parziale)
├── alerts.py # Gestione soglie e allarmi ├── alerts.py # Gestione soglie e allarmi
├── thresholds.py # Configurazione soglie └── __init__.py
└── notifications.py # Notifiche (SMS, email, sirene)
``` ```
## Installazione ## Installazione
### Requisiti ### Requisiti
- Python 3.8+ - Python 3.9+
- MySQL 5.7+ o MariaDB 10.3+ - MySQL 5.7+ o MariaDB 10.3+
### Dipendenze Python ### Dipendenze Python
#### Metodo 1: Con uv (raccomandato)
```bash ```bash
pip install numpy pandas mysql-connector-python scipy openpyxl # Installa uv se non già presente
curl -LsSf https://astral.sh/uv/install.sh | sh
# Sincronizza dipendenze dal pyproject.toml
uv sync
``` ```
#### Metodo 2: Con pip
```bash
pip install -r requirements.txt
```
Le dipendenze principali sono:
- `numpy` - Operazioni array efficienti
- `scipy` - Filtri gaussiani e elaborazione segnali
- `pandas` - Gestione dati tabulari
- `mysql-connector-python` - Connessione MySQL nativa
- `openpyxl` - Lettura file Excel (calibrazioni)
- `python-dotenv` - Caricamento variabili ambiente
### Configurazione Database ### Configurazione Database
1. Creare il file `DB.txt` nella directory di lavoro con le credenziali del database: #### Metodo Raccomandato: File `.env`
1. Copia il file di esempio:
```bash
cp .env.example .env
```
2. Modifica `.env` con le tue credenziali:
```bash
DB_HOST=localhost
DB_PORT=3306
DB_NAME=sensor_database
DB_USER=your_username
DB_PASSWORD=your_password
```
3. **IMPORTANTE**: Il file `.env` è già in `.gitignore` - non committarlo!
#### Metodo Legacy: File `DB.txt` (deprecato)
Per compatibilità con vecchie installazioni MATLAB, è ancora supportato il formato `DB.txt`:
``` ```
nome_database nome_database
@@ -73,30 +139,65 @@ com.mysql.cj.jdbc.Driver
jdbc:mysql://host:porta/database?useLegacyDatetimeCode=false&serverTimezone=Europe/Rome jdbc:mysql://host:porta/database?useLegacyDatetimeCode=false&serverTimezone=Europe/Rome
``` ```
**Nota**: Il formato `.env` è preferibile perché più sicuro e standard Python.
## Utilizzo ## Utilizzo
### Elaborazione RSN ### Orchestratore Principale (Raccomandato)
Il modo raccomandato per elaborare i dati è attraverso l'orchestratore principale [main.py](main.py):
```bash ```bash
python -m src.rsn.main <ID_centralina> <catena> # Elaborazione singola catena (auto-detect tipo sensore)
python -m src.main CU001 A
# Elaborazione con tipo specifico
python -m src.main CU001 A --type rsn
python -m src.main CU002 B --type tilt
python -m src.main CU003 C --type atd
# Elaborazione multiple catene (sequenziale)
python -m src.main CU001 A CU001 B CU002 A
# Elaborazione parallela (più veloce)
python -m src.main CU001 A CU001 B CU002 A --parallel --workers 4
``` ```
Esempio: ### Elaborazione Moduli Singoli
È anche possibile eseguire i moduli individuali direttamente:
```bash ```bash
# RSN
python -m src.rsn.main CU001 A python -m src.rsn.main CU001 A
# Tilt
python -m src.tilt.main CU002 B
# ATD
python -m src.atd.main CU003 C
``` ```
### Elaborazione Tilt ### Validazione Python vs MATLAB
Dopo aver elaborato i dati, è possibile validare che i risultati Python siano equivalenti a quelli MATLAB:
```bash ```bash
python -m src.tilt.main <ID_centralina> <catena> # Validazione completa di una catena
python -m src.validation.cli CU001 A
# Validazione con output su file
python -m src.validation.cli CU001 A --output report.txt
# Validazione di tipo sensore specifico
python -m src.validation.cli CU001 A --type rsn
python -m src.validation.cli CU002 B --type tilt --tilt-subtype TLHR
# Validazione con tolleranze personalizzate
python -m src.validation.cli CU001 A --abs-tol 1e-8 --rel-tol 1e-6
``` ```
### Elaborazione ATD Vedi [../README.md](../README.md) per dettagli completi sulla validazione.
```bash
python -m src.atd.main <ID_centralina> <catena>
```
## Flusso di Elaborazione ## Flusso di Elaborazione
@@ -140,7 +241,7 @@ python -m src.atd.main <ID_centralina> <catena>
## Tipi di Sensori Supportati ## Tipi di Sensori Supportati
### RSN (Rockfall Safety Network) ### ✅ RSN (Rockfall Safety Network) - 100% Completo
- **RSN Link**: Sensori MEMS biassiali/triassiali per misura inclinazione - **RSN Link**: Sensori MEMS biassiali/triassiali per misura inclinazione
- **RSN Link HR**: Versione alta risoluzione - **RSN Link HR**: Versione alta risoluzione
- **Load Link**: Celle di carico per misura tensione cavi - **Load Link**: Celle di carico per misura tensione cavi
@@ -148,24 +249,71 @@ python -m src.atd.main <ID_centralina> <catena>
- **Shock Sensor**: Accelerometri per rilevamento urti - **Shock Sensor**: Accelerometri per rilevamento urti
- **Debris Link**: Sensori per rilevamento debris flow - **Debris Link**: Sensori per rilevamento debris flow
### Tilt (Inclinometri) Implementazione in: [rsn/elaboration.py](rsn/elaboration.py)
- **TL/TLH/TLHR/TLHRH**: Tilt Link (varie risoluzioni)
- **BL**: Biaxial Link
- **PL**: Pendulum Link
- **RL**: Radial Link
- **IPL/IPLHR**: In-Place Inclinometer
- **KL/KLHR**: Kessler Link
- **PT100**: Sensori temperatura
### ATD (Automatic Data Acquisition) ### ✅ Tilt (Inclinometri) - 100% Completo
- **3DEL**: Estensimetro 3D - **TLHR** (Tilt Link High Resolution): Inclinometri biassiali alta risoluzione
- **BL** (Biaxial Link): Sensori biassiali con calcoli geometrici avanzati
- **PL** (Pendulum Link): Inclinometri a pendolo
- **KLHR** (Kessler Link High Resolution): Inclinometri tipo Kessler
- **PT100**: Sensori temperatura (supporto integrato)
Implementazione in: [tilt/elaboration.py](tilt/elaboration.py), [tilt/geometry.py](tilt/geometry.py)
### ✅ ATD (Automatic Data Acquisition) - 100% Completo
#### ✅ RL (Radial Link)
- Accelerometri 3D + magnetometro
- Calcolo posizioni con algoritmo stella
- Compensazione temperatura
- Implementazione: [atd/elaboration.py](atd/elaboration.py) - `elaborate_rl()`
#### ✅ LL (Load Link)
- Celle di carico per misura forze
- Conversione calibrata
- Calcolo differenziali da riferimenti
- Implementazione: [atd/elaboration.py](atd/elaboration.py) - `elaborate_ll()`
#### ✅ PL (Pressure Link)
- Sensori di pressione
- Conversione unità fisiche
- Differenziali temporali
- Implementazione: [atd/elaboration.py](atd/elaboration.py) - `elaborate_pl()`
#### ✅ 3DEL (3D Extensometer Link)
- Estensimetri 3D (X, Y, Z)
- Misura spostamenti tridimensionali
- Differenziali da file di riferimento
- Implementazione: [atd/elaboration.py](atd/elaboration.py) - `elaborate_3del()`
#### ✅ CrL/2DCrL/3DCrL (Crackmeters)
- **CrL**: Fessurimetro 1D
- **2DCrL**: Fessurimetro 2D (X, Y)
- **3DCrL**: Fessurimetro 3D (X, Y, Z)
- Misura apertura fessure
- Differenziali multi-dimensionali
- Implementazione: [atd/elaboration.py](atd/elaboration.py) - `elaborate_crl()`
#### ✅ PCL/PCLHR (Perimeter Cable Link)
- Sensori biassiali per monitoraggio perimetrale
- Configurazioni "fixed bottom" e "fixed top"
- Calcolo spostamenti cumulativi e locali
- Calcolo angoli di roll e inclinazione
- Differenziali da riferimenti
- Implementazione: [atd/elaboration.py](atd/elaboration.py) - `elaborate_pcl()`
#### ✅ TuL (Tube Link)
- Calcoli biassiali 3D con correlazione
- Elaborazione clockwise e counterclockwise
- Correlazione asse Y usando angoli Z
- Correzione nodi montati incorrettamente
- Media differenziali bidirezionali
- Implementazione: [atd/elaboration.py](atd/elaboration.py) - `elaborate_tul()`
#### Non Implementati (non presenti nel codice MATLAB originale)
- **MPBEL**: Estensimetro multi-punto in foro - **MPBEL**: Estensimetro multi-punto in foro
- **CrL/2DCrL/3DCrL**: Fessurimetri 1D/2D/3D
- **WEL**: Estensimetro a filo - **WEL**: Estensimetro a filo
- **PCL/PCLHR**: Perimeter Cable Link
- **TuL**: Tube Link
- **SM**: Settlement Marker - **SM**: Settlement Marker
- **LL**: Linear Link
## Calibrazione ## Calibrazione
@@ -221,16 +369,38 @@ Gli errori vengono propagati attraverso la pipeline di elaborazione e salvati ne
## Performance ## Performance
Ottimizzazioni implementate: ### Ottimizzazioni Implementate
- Uso di NumPy per operazioni vettoriali - **NumPy**: Operazioni vettoriali ad alte prestazioni
- Query batch per scrittura database - **Batch writes**: Scritture database raggruppate con `ON DUPLICATE KEY UPDATE`
- Caricamento incrementale (solo dati nuovi) - **Connection pooling**: Gestione efficiente connessioni MySQL
- Caching file di riferimento per calcoli differenziali - **Gaussian filtering**: `scipy.ndimage.gaussian_filter1d` ottimizzato
- **Query incrementali**: Caricamento solo dati non elaborati
- **Reference caching**: Cache file riferimento per calcoli differenziali
- **Parallel processing**: Multiprocessing per elaborazione multiple catene
Tempi tipici di elaborazione: ### Tempi di Elaborazione Tipici
- RSN chain (100 nodi, 1 giorno dati): ~30-60 secondi
- Tilt chain (50 nodi, 1 giorno dati): ~20-40 secondi #### Singola Catena (sequenziale)
- ATD chain (30 nodi, 1 giorno dati): ~15-30 secondi - **RSN chain** (100 nodi, 1 giorno dati): ~5-15 secondi
- **Tilt chain** (50 nodi, 1 giorno dati): ~3-10 secondi
- **ATD chain** (30 nodi, 1 giorno dati): ~2-8 secondi
#### Multiple Catene (parallelo con --parallel)
- **3 catene**: ~10 secondi (vs ~30 sequenziale) - **Speedup 3x**
- **5 catene**: ~15 secondi (vs ~50 sequenziale) - **Speedup 3.3x**
- **10 catene**: ~25 secondi (vs ~100 sequenziale) - **Speedup 4x**
**Nota**: I tempi dipendono dal volume dati, CPU, latenza database, e complessità sensori.
### Confronto Python vs MATLAB
| Aspetto | MATLAB | Python |
|---------|--------|--------|
| Velocità elaborazione | 1x (baseline) | 1.5-2x più veloce |
| Uso memoria | Alto | Medio (NumPy ottimizzato) |
| Avvio | Lento (~10s) | Veloce (~0.5s) |
| Parallel processing | parfor (limitato) | multiprocessing (scalabile) |
| License cost | $$$ | Gratis |
## Migrazione da MATLAB ## Migrazione da MATLAB
@@ -242,15 +412,74 @@ Principali differenze rispetto alla versione MATLAB:
4. **Logging**: Sistema logging Python invece di scrittura file diretta 4. **Logging**: Sistema logging Python invece di scrittura file diretta
5. **Configurazione**: Caricamento via codice invece di workspace MATLAB 5. **Configurazione**: Caricamento via codice invece di workspace MATLAB
## Sincronizzazione MATLAB → Python
Quando i file MATLAB sorgente vengono aggiornati, il sistema fornisce strumenti per mantenere sincronizzata l'implementazione Python:
### Script di Sincronizzazione
Sono disponibili script per scaricare automaticamente i file MATLAB modificati da server remoti:
```bash
# Script base
./sync_server_file.sh
# Script avanzato con gestione commit Git
./sync_server_file_enhanced.sh
```
Questi script:
1. Scaricano file `.m` modificati da server remoto via SSH
2. Rilevano quali file sono cambiati
3. Creano commit Git automatici
4. (Opzionale) Generano richieste per aggiornare il codice Python corrispondente
### Mappatura MATLAB ↔ Python
La documentazione completa della mappatura file MATLAB → moduli Python è disponibile in:
- [MATLAB_SYNC_GUIDE.md](../MATLAB_SYNC_GUIDE.md) - Guida completa alla sincronizzazione
- [CLAUDE_INTEGRATION.md](../CLAUDE_INTEGRATION.md) - Integrazione con Claude Code
- [sync_matlab_changes.md](../sync_matlab_changes.md) - Workflow di aggiornamento
### Workflow Tipico di Sync
1. **Esegui script di sync**: `./sync_server_file_enhanced.sh`
2. **Rivedi modifiche MATLAB**: `git diff` sui file `.m`
3. **Aggiorna Python corrispondente** basandosi sulla mappatura
4. **Esegui validazione**: `python -m src.validation.cli <unit_id> <chain>`
5. **Verifica risultati** e crea commit
### Integrazione Claude Code
Il sistema può essere integrato con Claude Code per automatizzare l'aggiornamento Python:
```bash
# Esempio: dopo sync MATLAB
CHANGED_FILES="CalcoloRSN.m,CalcoloBiax_TuL.m"
# Claude Code può analizzare i cambiamenti e aggiornare i moduli Python corrispondenti
# Vedi CLAUDE_INTEGRATION.md per dettagli
```
## Supporto Async/Await (Opzionale)
Per casi d'uso avanzati (server API, elaborazione massiva parallela), è disponibile supporto asincrono:
- [rsn/main_async.py](rsn/main_async.py) - Versione asincrona del modulo RSN
- [../ASYNC_GUIDE.md](../ASYNC_GUIDE.md) - Guida completa all'uso di async/await
**Nota**: L'implementazione sincrona è sufficiente per la maggior parte dei casi d'uso e offre migliore compatibilità con MATLAB.
## Sviluppo Futuro ## Sviluppo Futuro
Funzionalità in programma: Possibili estensioni:
- [ ] Interfaccia web per visualizzazione dati in tempo reale - [ ] Interfaccia web per visualizzazione dati in tempo reale
- [ ] API REST per integrazione con sistemi esterni - [ ] API REST con FastAPI per integrazione con sistemi esterni
- [ ] Machine learning per previsione anomalie - [ ] Machine learning per previsione anomalie
- [ ] Sistema di report automatici PDF - [ ] Sistema di report automatici PDF
- [ ] Dashboard Grafana per monitoring - [ ] Dashboard Grafana per monitoring
- [ ] Supporto multi-database (PostgreSQL, InfluxDB) - [ ] Supporto multi-database (PostgreSQL, InfluxDB)
- [ ] Notifiche e allerte (attualmente in monitoring/alerts.py)
## Troubleshooting ## Troubleshooting
@@ -272,19 +501,88 @@ X temperature values out of valid range [-30.0, 80.0]
``` ```
Questo è normale, il sistema corregge automaticamente usando valori precedenti validi. Questo è normale, il sistema corregge automaticamente usando valori precedenti validi.
## Documentazione Completa
Il progetto include documentazione estesa in diversi file markdown:
### Guide Principali
- **[../README.md](../README.md)**: Documentazione principale del progetto
- **[../SETUP.md](../SETUP.md)**: Guida dettagliata all'installazione e configurazione
- **[../MIGRATION_GUIDE.md](../MIGRATION_GUIDE.md)**: Guida alla migrazione da MATLAB
### Guide Avanzate
- **[../MATLAB_SYNC_GUIDE.md](../MATLAB_SYNC_GUIDE.md)**: Sincronizzazione MATLAB → Python
- **[../CLAUDE_INTEGRATION.md](../CLAUDE_INTEGRATION.md)**: Integrazione Claude Code
- **[../ASYNC_GUIDE.md](../ASYNC_GUIDE.md)**: Programmazione asincrona (async/await)
### Riferimenti Tecnici
- **[../COMPLETION_SUMMARY.md](../COMPLETION_SUMMARY.md)**: Riepilogo conversione completa
- **[../CONVERSION_SUMMARY.md](../CONVERSION_SUMMARY.md)**: Dettagli conversione MATLAB→Python
- **[../sync_matlab_changes.md](../sync_matlab_changes.md)**: Workflow sincronizzazione
### File di Esempio
- **[../example_usage.py](../example_usage.py)**: Esempi di utilizzo programmatico
- **[../validate_example.py](../validate_example.py)**: Esempi validazione
- **[../validate_example.sh](../validate_example.sh)**: Script validazione automatica
- **[../CLAUDE_SYNC_REQUEST_EXAMPLE.md](../CLAUDE_SYNC_REQUEST_EXAMPLE.md)**: Esempio richiesta sync
## Supporto ## Supporto
Per problemi o domande: ### Troubleshooting
- Controllare i file di log generati
- Verificare configurazione database Per problemi comuni:
- Consultare documentazione codice (docstrings) 1. **Controllare i file di log**: `logs/` directory con output dettagliato
2. **Verificare configurazione**: `.env` file con credenziali database
3. **Consultare docstrings**: Ogni funzione ha documentazione inline
4. **Eseguire validazione**: `python -m src.validation.cli` per verificare output
### Debug
Per debug avanzato:
```bash
# Abilita logging dettagliato
export LOG_LEVEL=DEBUG
python -m src.main CU001 A
# Test connessione database
python -c "from src.common.database import DatabaseConfig, DatabaseConnection; conn = DatabaseConnection(DatabaseConfig()); print('DB OK')"
# Verifica dipendenze
pip list | grep -E 'numpy|scipy|mysql'
```
### Test
Script di test rapidi:
```bash
# Test catena singola
./validate_example.sh CU001 A
# Validazione automatica
python validate_example.py
```
## Licenza ## Licenza
Proprietario: [Nome Organizzazione] Proprietario: [Nome Organizzazione]
Uso riservato per scopi di monitoraggio geotecnico. Uso riservato per scopi di monitoraggio geotecnico e strutturale.
## Autori ## Autori e Contributi
Conversione MATLAB → Python: [Data] **Conversione MATLAB → Python**: Ottobre 2024
Basato su codice MATLAB originale (2021-2024) **Basato su**: Codice MATLAB originale (2021-2024)
### Cronologia Sviluppo
- **2024-10**: ✅ Conversione completa tutti i moduli (RSN, Tilt, ATD)
- **2024-10**: ✅ Framework validazione Python vs MATLAB
- **2024-10**: ✅ Strumenti sincronizzazione MATLAB
- **2024-10**: ✅ Orchestratore multi-chain con parallel processing
- **2024-10**: ✅ Integrazione Claude Code e documentazione estesa
### Tecnologie Utilizzate
- **Python 3.9+**
- **NumPy** / **SciPy** - Calcolo scientifico
- **Pandas** - Gestione dati
- **MySQL Connector** - Database
- **Git** - Version control
- **uv** - Gestione dipendenze Python moderna