riconoscitore-oggetti 2.0.0

Riconoscitore di oggetti in tempo reale con Teachable Machine, overlay grafico e sintesi vocale italiana

🎯 Riconoscitore Oggetti

Riconoscimento oggetti in tempo reale con modelli Teachable Machine, overlay grafico e sintesi vocale italiana.

Pensato per la didattica e per progetti di accessibilità. Usa modelli .tflite esportati da Google Teachable Machine.

---

✨ 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

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)

riconoscitore

Oppure:

python -m riconoscitore_oggetti

Si aprirà un file dialog per selezionare il modello .tflite e il file etichette .txt.

Da codice 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

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
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