riconoscitore-oggetti 2.0.2
Riconoscitore di oggetti in tempo reale con Teachable Machine, overlay grafico e sintesi vocale italiana
License: MIT
Requires Python: >=3.9

# 🎯 Riconoscitore Oggetti

**Riconoscimento oggetti in tempo reale con modelli Teachable Machine, overlay grafico e sintesi vocale italiana.**

[![PyPI version](https://badge.fury.io/py/riconoscitore-oggetti.svg)](https://pypi.org/project/riconoscitore-oggetti/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Pensato per la didattica e per progetti di accessibilità. Usa modelli `.tflite` esportati da [Google Teachable Machine](https://teachablemachine.withgoogle.com/).

---

## ✨ Funzionalità

- 📷 Riconoscimento in tempo reale dalla webcam
- 🗣️ Sintesi vocale italiana (TTS) in thread separato — il video non si blocca mai
- 📊 Smoothing predizioni su N frame (anti-flickering con voto di maggioranza)
- 🎚️ Soglia di confidenza configurabile
- 🖥️ Overlay grafico con barra confidenza, FPS e log riconoscimenti
- ⌨️ Tasti rapidi: **Q** esci, **M** muto, **S** screenshot, **P** pausa
- 🔇 Cooldown vocale anti-ripetizione

## 📦 Installazione

```bash
pip install riconoscitore-oggetti
```

> ⚠️ Richiede **Python 3.9+** e una webcam collegata.

### Dipendenze installate automaticamente

- `opencv-python` — acquisizione e visualizzazione video
- `tensorflow` — interprete TFLite per l'inferenza
- `numpy` — elaborazione array
- `pyttsx3` — sintesi vocale offline

## 🚀 Uso

### Da terminale (CLI)

```bash
riconoscitore
```

Oppure:

```bash
python -m riconoscitore_oggetti
```

Si aprirà un file dialog per selezionare il modello `.tflite` e il file etichette `.txt`.

### Da codice Python

```python
from riconoscitore_oggetti import avvia

# Modalità interattiva (file dialog)
avvia()

# Percorsi espliciti
avvia("mio_modello.tflite", "etichette.txt")

# Con configurazione personalizzata
avvia(
    model_path="modello.tflite",
    labels_path="labels.txt",
    camera_index=0,
    config={
        "SOGLIA_CONFIDENZA": 0.85,
        "VELOCITA_VOCE": 180,
        "BUFFER_FRAME": 9,
    }
)
```

### Uso avanzato delle classi

```python
from riconoscitore_oggetti import Classificatore, MotoreVocale

# Usa solo il classificatore
clf = Classificatore("modello.tflite", ["gatto", "cane", "standard"], buffer_size=5)
etichetta, confidenza, raw = clf.predici(frame_opencv)
etichetta_stabile, conf_stabile = clf.predizione_stabile()

# Usa solo il motore vocale
voce = MotoreVocale(velocita=150, volume=0.9)
voce.parla("Ciao mondo!")
```

## 🎓 Come creare il modello

1. Vai su [Teachable Machine](https://teachablemachine.withgoogle.com/)
2. Crea un progetto **Image** → addestra le classi con la webcam
3. Esporta come **TensorFlow Lite** (quantizzato float)
4. Scarica il `.tflite` e il `labels.txt`
5. Lancia il riconoscitore e seleziona i due file!

> 💡 Aggiungi una classe chiamata `standard` come sfondo neutro (non verrà annunciata).

## ⌨️ Comandi durante l'esecuzione

| Tasto | Azione |
|-------|--------|
| **Q** | Esci dall'applicazione |
| **M** | Attiva/disattiva muto |
| **S** | Salva screenshot |
| **P** | Pausa/riprendi |

## ⚙️ Configurazione

Puoi sovrascrivere qualsiasi parametro passando un dizionario `config` ad `avvia()`:

| Parametro | Default | Descrizione |
|-----------|---------|-------------|
| `SOGLIA_CONFIDENZA` | `0.70` | Soglia minima per annunci vocali |
| `BUFFER_FRAME` | `7` | Frame per smoothing (dispari) |
| `COOLDOWN_VOCE_SEC` | `2.5` | Secondi tra annunci ripetuti |
| `VELOCITA_VOCE` | `150` | Parole al minuto TTS |
| `VOLUME_VOCE` | `0.9` | Volume TTS (0.0–1.0) |
| `ETICHETTA_NEUTRA` | `"standard"` | Classe ignorata dal TTS |
| `LARGHEZZA_FINESTRA` | `800` | Larghezza finestra video |

## 📄 Licenza

MIT — Prof. Giuseppe Aleci, ITIS Q. Sella, Biella — A.S. 2025/2026