ai-virtual-mouse-controller 1.2.0__tar.gz → 1.3.0__tar.gz

{ai_virtual_mouse_controller-1.2.0 → ai_virtual_mouse_controller-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-virtual-mouse-controller
-Version: 1.2.0
+Version: 1.3.0
 Summary: Controle de cursor por gestos da mao via webcam, com holograma 3D opcional.
 Author: Guilherme Moraes Franco
 License: MIT
@@ -32,10 +32,8 @@ Requires-Dist: opencv-contrib-python<5.0.0,>=4.10.0
 Requires-Dist: mediapipe>=0.10.18
 Requires-Dist: pyautogui<1.0.0,>=0.9.54
 Requires-Dist: numpy>=1.26.0
-Requires-Dist: moderngl>=5.10.0
 Requires-Dist: PySide6>=6.6.0
 Provides-Extra: hologram
-Requires-Dist: moderngl>=5.10.0; extra == "hologram"
 Requires-Dist: PySide6>=6.6.0; extra == "hologram"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
@@ -89,7 +87,7 @@ O **AI Virtual Mouse Controller** é um mouse virtual com reconhecimento de gest
 
 100% local. Sem nuvem, sem telemetria, sem persistir nada da webcam.
 
-**Stack:** Python 3.10+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · ModernGL/PySide6 (opcional)
+**Stack:** Python 3.10+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · PySide6 (holograma 3D via OpenGL do Qt)
 
 ---
 
@@ -202,12 +200,13 @@ Toda a calibração vive em [`config.py`](config.py) — constantes nomeadas com
 | Seção | O que controla |
 |---|---|
 | `CAMERA` | índice da câmera, resolução, FPS alvo |
+| `PROFILE` | perfil inicial do painel: `smooth`, `precise`, `responsive`, `stable` |
 | `CURSOR_ANCHOR` | qual ponto da mão o cursor segue (`-2` = âncora robusta, default) |
-| `PINCH` | thresholds de detecção de clique (com escala adaptativa por tamanho da mão) |
+| `PINCH` | thresholds de detecção de clique (escala adaptativa por tamanho da mão + histerese pra soltar) |
 | `DPI` / `SMOOTHING` | sensibilidade do cursor + filtro OneEuro |
 | `SCREEN_MARGIN_*` | margens assimétricas (top/bottom < lateral) pra alcançar cantos |
 | `CURSOR_FOLLOWTHROUGH_*` | cinematic prediction quando a mão sai do FOV |
-| `HOLOGRAM` | backend (GL/QPainter), cor, opacidade, FPS |
+| `HOLOGRAM` | estilo (`quest`, `graphite`, `neon`), backend (OpenGL/QPainter), tamanho, opacidade, FPS |
 
 Ajustes em tempo de execução também ficam disponíveis no painel (tecla `S`) — perfis prontos: *smooth*, *precise*, *responsive*, *stable*.
 
@@ -240,7 +239,7 @@ webcam → MediaPipe Hands (21 landmarks)
      CursorController  ← PyAutoGUI move o cursor real
 ```
 
-Componentes auxiliares: `HologramOverlay` (renderização 3D opcional via ModernGL), `RuntimeSettings` (perfis e sliders), `PerfTelemetry` (timing p50/p99 por estágio).
+Componentes auxiliares: `HologramOverlay` (mão 3D estilo headset VR: `hand_pose` → `hand_mesh` → shader OpenGL do Qt, com fallback 2D QPainter), `RuntimeSettings` (perfis e sliders), `PerfTelemetry` (timing p50/p99 por estágio).
 
 Estrutura de pastas:
 
@@ -249,7 +248,8 @@ core/        # camera, hand_tracker, gesture_detector, hand_anchor, smoothing
 services/    # orquestração do loop principal
 config.py    # constantes de calibração documentadas
 main.py      # entry point
-tests/       # cobertura dos módulos puros (sem cv2/mediapipe)
+scripts/     # eval_motion.py: mede jitter/atraso/cliques com mãos sintéticas
+tests/       # unitários + gate de qualidade de movimento
 docs/        # site estático + assets
 ```
 
@@ -269,7 +269,7 @@ make test-gpu   # só testes que precisam de display/GPU real
 make test-cov   # com coverage HTML
 ```
 
-Testes marcados com `gpu` (overlay PySide6/ModernGL) ficam fora do `pytest` default — eles requerem display real e podem crashar em ambientes headless. Rode-os explicitamente com `make test-gpu` quando estiver mexendo no holograma.
+Testes marcados com `gpu` (overlay PySide6/OpenGL) ficam fora do `pytest` default — eles requerem display real e podem crashar em ambientes headless. Rode-os explicitamente com `make test-gpu` quando estiver mexendo no holograma.
 
 ---
 

{ai_virtual_mouse_controller-1.2.0 → ai_virtual_mouse_controller-1.3.0}/README.md

@@ -42,7 +42,7 @@ O **AI Virtual Mouse Controller** é um mouse virtual com reconhecimento de gest
 
 100% local. Sem nuvem, sem telemetria, sem persistir nada da webcam.
 
-**Stack:** Python 3.10+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · ModernGL/PySide6 (opcional)
+**Stack:** Python 3.10+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · PySide6 (holograma 3D via OpenGL do Qt)
 
 ---
 
@@ -155,12 +155,13 @@ Toda a calibração vive em [`config.py`](config.py) — constantes nomeadas com
 | Seção | O que controla |
 |---|---|
 | `CAMERA` | índice da câmera, resolução, FPS alvo |
+| `PROFILE` | perfil inicial do painel: `smooth`, `precise`, `responsive`, `stable` |
 | `CURSOR_ANCHOR` | qual ponto da mão o cursor segue (`-2` = âncora robusta, default) |
-| `PINCH` | thresholds de detecção de clique (com escala adaptativa por tamanho da mão) |
+| `PINCH` | thresholds de detecção de clique (escala adaptativa por tamanho da mão + histerese pra soltar) |
 | `DPI` / `SMOOTHING` | sensibilidade do cursor + filtro OneEuro |
 | `SCREEN_MARGIN_*` | margens assimétricas (top/bottom < lateral) pra alcançar cantos |
 | `CURSOR_FOLLOWTHROUGH_*` | cinematic prediction quando a mão sai do FOV |
-| `HOLOGRAM` | backend (GL/QPainter), cor, opacidade, FPS |
+| `HOLOGRAM` | estilo (`quest`, `graphite`, `neon`), backend (OpenGL/QPainter), tamanho, opacidade, FPS |
 
 Ajustes em tempo de execução também ficam disponíveis no painel (tecla `S`) — perfis prontos: *smooth*, *precise*, *responsive*, *stable*.
 
@@ -193,7 +194,7 @@ webcam → MediaPipe Hands (21 landmarks)
      CursorController  ← PyAutoGUI move o cursor real
 ```
 
-Componentes auxiliares: `HologramOverlay` (renderização 3D opcional via ModernGL), `RuntimeSettings` (perfis e sliders), `PerfTelemetry` (timing p50/p99 por estágio).
+Componentes auxiliares: `HologramOverlay` (mão 3D estilo headset VR: `hand_pose` → `hand_mesh` → shader OpenGL do Qt, com fallback 2D QPainter), `RuntimeSettings` (perfis e sliders), `PerfTelemetry` (timing p50/p99 por estágio).
 
 Estrutura de pastas:
 
@@ -202,7 +203,8 @@ core/        # camera, hand_tracker, gesture_detector, hand_anchor, smoothing
 services/    # orquestração do loop principal
 config.py    # constantes de calibração documentadas
 main.py      # entry point
-tests/       # cobertura dos módulos puros (sem cv2/mediapipe)
+scripts/     # eval_motion.py: mede jitter/atraso/cliques com mãos sintéticas
+tests/       # unitários + gate de qualidade de movimento
 docs/        # site estático + assets
 ```
 
@@ -222,7 +224,7 @@ make test-gpu   # só testes que precisam de display/GPU real
 make test-cov   # com coverage HTML
 ```
 
-Testes marcados com `gpu` (overlay PySide6/ModernGL) ficam fora do `pytest` default — eles requerem display real e podem crashar em ambientes headless. Rode-os explicitamente com `make test-gpu` quando estiver mexendo no holograma.
+Testes marcados com `gpu` (overlay PySide6/OpenGL) ficam fora do `pytest` default — eles requerem display real e podem crashar em ambientes headless. Rode-os explicitamente com `make test-gpu` quando estiver mexendo no holograma.
 
 ---
 

{ai_virtual_mouse_controller-1.2.0 → ai_virtual_mouse_controller-1.3.0}/ai_virtual_mouse_controller.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-virtual-mouse-controller
-Version: 1.2.0
+Version: 1.3.0
 Summary: Controle de cursor por gestos da mao via webcam, com holograma 3D opcional.
 Author: Guilherme Moraes Franco
 License: MIT
@@ -32,10 +32,8 @@ Requires-Dist: opencv-contrib-python<5.0.0,>=4.10.0
 Requires-Dist: mediapipe>=0.10.18
 Requires-Dist: pyautogui<1.0.0,>=0.9.54
 Requires-Dist: numpy>=1.26.0
-Requires-Dist: moderngl>=5.10.0
 Requires-Dist: PySide6>=6.6.0
 Provides-Extra: hologram
-Requires-Dist: moderngl>=5.10.0; extra == "hologram"
 Requires-Dist: PySide6>=6.6.0; extra == "hologram"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
@@ -89,7 +87,7 @@ O **AI Virtual Mouse Controller** é um mouse virtual com reconhecimento de gest
 
 100% local. Sem nuvem, sem telemetria, sem persistir nada da webcam.
 
-**Stack:** Python 3.10+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · ModernGL/PySide6 (opcional)
+**Stack:** Python 3.10+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · PySide6 (holograma 3D via OpenGL do Qt)
 
 ---
 
@@ -202,12 +200,13 @@ Toda a calibração vive em [`config.py`](config.py) — constantes nomeadas com
 | Seção | O que controla |
 |---|---|
 | `CAMERA` | índice da câmera, resolução, FPS alvo |
+| `PROFILE` | perfil inicial do painel: `smooth`, `precise`, `responsive`, `stable` |
 | `CURSOR_ANCHOR` | qual ponto da mão o cursor segue (`-2` = âncora robusta, default) |
-| `PINCH` | thresholds de detecção de clique (com escala adaptativa por tamanho da mão) |
+| `PINCH` | thresholds de detecção de clique (escala adaptativa por tamanho da mão + histerese pra soltar) |
 | `DPI` / `SMOOTHING` | sensibilidade do cursor + filtro OneEuro |
 | `SCREEN_MARGIN_*` | margens assimétricas (top/bottom < lateral) pra alcançar cantos |
 | `CURSOR_FOLLOWTHROUGH_*` | cinematic prediction quando a mão sai do FOV |
-| `HOLOGRAM` | backend (GL/QPainter), cor, opacidade, FPS |
+| `HOLOGRAM` | estilo (`quest`, `graphite`, `neon`), backend (OpenGL/QPainter), tamanho, opacidade, FPS |
 
 Ajustes em tempo de execução também ficam disponíveis no painel (tecla `S`) — perfis prontos: *smooth*, *precise*, *responsive*, *stable*.
 
@@ -240,7 +239,7 @@ webcam → MediaPipe Hands (21 landmarks)
      CursorController  ← PyAutoGUI move o cursor real
 ```
 
-Componentes auxiliares: `HologramOverlay` (renderização 3D opcional via ModernGL), `RuntimeSettings` (perfis e sliders), `PerfTelemetry` (timing p50/p99 por estágio).
+Componentes auxiliares: `HologramOverlay` (mão 3D estilo headset VR: `hand_pose` → `hand_mesh` → shader OpenGL do Qt, com fallback 2D QPainter), `RuntimeSettings` (perfis e sliders), `PerfTelemetry` (timing p50/p99 por estágio).
 
 Estrutura de pastas:
 
@@ -249,7 +248,8 @@ core/        # camera, hand_tracker, gesture_detector, hand_anchor, smoothing
 services/    # orquestração do loop principal
 config.py    # constantes de calibração documentadas
 main.py      # entry point
-tests/       # cobertura dos módulos puros (sem cv2/mediapipe)
+scripts/     # eval_motion.py: mede jitter/atraso/cliques com mãos sintéticas
+tests/       # unitários + gate de qualidade de movimento
 docs/        # site estático + assets
 ```
 
@@ -269,7 +269,7 @@ make test-gpu   # só testes que precisam de display/GPU real
 make test-cov   # com coverage HTML
 ```
 
-Testes marcados com `gpu` (overlay PySide6/ModernGL) ficam fora do `pytest` default — eles requerem display real e podem crashar em ambientes headless. Rode-os explicitamente com `make test-gpu` quando estiver mexendo no holograma.
+Testes marcados com `gpu` (overlay PySide6/OpenGL) ficam fora do `pytest` default — eles requerem display real e podem crashar em ambientes headless. Rode-os explicitamente com `make test-gpu` quando estiver mexendo no holograma.
 
 ---
 

{ai_virtual_mouse_controller-1.2.0 → ai_virtual_mouse_controller-1.3.0}/ai_virtual_mouse_controller.egg-info/SOURCES.txt

@@ -17,8 +17,11 @@ core/cursor_controller.py
 core/finger_posture.py
 core/gesture_detector.py
 core/hand_anchor.py
+core/hand_gl_renderer.py
 core/hand_mesh.py
+core/hand_pose.py
 core/hand_renderer.py
+core/hand_soft_renderer.py
 core/hand_tracker.py
 core/hologram_gl_backend.py
 core/hologram_overlay.py
@@ -33,17 +36,26 @@ core/windows_path.py
 core/models/hand_landmarker.task
 services/__init__.py
 services/virtual_mouse_service.py
+tests/test_camera.py
 tests/test_click_burst.py
 tests/test_cursor_bottom_reach.py
 tests/test_cursor_click_at.py
+tests/test_cursor_feel.py
 tests/test_gesture_detector.py
+tests/test_gesture_detector_behavior.py
 tests/test_hand_anchor_bottom.py
+tests/test_hand_mesh.py
+tests/test_hand_pose.py
 tests/test_hand_renderer.py
+tests/test_hand_renderers.py
 tests/test_hand_tracker.py
 tests/test_hologram_overlay.py
+tests/test_motion_quality.py
 tests/test_overlay_smoke.py
 tests/test_perf_telemetry.py
 tests/test_presentation_controller.py
+tests/test_runtime_settings.py
+tests/test_service_camera_loss.py
 tests/test_settings_panel.py
 tests/test_smoothing.py
 tests/test_windows_path.py

{ai_virtual_mouse_controller-1.2.0 → ai_virtual_mouse_controller-1.3.0}/ai_virtual_mouse_controller.egg-info/requires.txt

@@ -2,7 +2,6 @@ opencv-contrib-python<5.0.0,>=4.10.0
 mediapipe>=0.10.18
 pyautogui<1.0.0,>=0.9.54
 numpy>=1.26.0
-moderngl>=5.10.0
 PySide6>=6.6.0
 
 [dev]
@@ -13,5 +12,4 @@ mypy>=1.10.0
 pre-commit>=3.7.0
 
 [hologram]
-moderngl>=5.10.0
 PySide6>=6.6.0

{ai_virtual_mouse_controller-1.2.0 → ai_virtual_mouse_controller-1.3.0}/config.py

@@ -146,6 +146,17 @@ DPI_MULTIPLIER_MIN: float = 0.7
 DPI_MULTIPLIER_MAX: float = 1.4
 DPI_FIXED_MULTIPLIER: float = 1.00
 
+DPI_SIZE_SMOOTHING_S: float = 0.6
+"""Constante de tempo (s) do tamanho da mao usado no DPI adaptativo.
+
+O tamanho da mao no frame estima a DISTANCIA ate a camera — algo que muda
+devagar. Frame a frame ele oscila quando o pulso inclina/gira e com o
+ruido do tracker; como o DPI escala a posicao a partir do centro da tela,
+isso fazia o cursor andar sozinho com a mao parada (ate ~50 px longe do
+centro). 0.6 s filtra a inclinacao e ainda acompanha quem aproxima ou
+afasta a mao da camera. 0 = comportamento antigo (cru).
+"""
+
 # ---------------------------------------------------------------------
 # SUAVIZACAO
 # ---------------------------------------------------------------------
@@ -155,9 +166,18 @@ SMOOTHING_STRATEGY: SmoothingStrategy = "one_euro"
 
 SMOOTHING_FACTOR: float = 0.6
 
+PROFILE: str = "smooth"
+"""Perfil inicial do painel: 'smooth', 'precise', 'responsive' ou
+'stable'. Define suavizacao, sensibilidade, pinca, aim assist, sticky e a
+trava no clique (ver core/runtime_settings.PROFILES)."""
+
 ONE_EURO_FREQ: float = 60.0
+# min_cutoff e beta efetivos vem do PERFIL (painel, slider Suavizacao) —
+# os dois abaixo ficam como referencia do perfil 'recommended'.
+# beta esta na escala das coordenadas normalizadas (0-1): valores ~0.02
+# deixavam o filtro sem adaptacao e o cursor arrastando atras da mao.
 ONE_EURO_MIN_CUTOFF: float = 1.2
-ONE_EURO_BETA: float = 0.020
+ONE_EURO_BETA: float = 5.7
 ONE_EURO_D_CUTOFF: float = 1.0
 DEAD_ZONE_PIXELS: int = 1
 
@@ -192,9 +212,22 @@ vem do debounce de 2 frames + threshold.
 
 PINCH_VELOCITY_THRESHOLD: float = 0.008
 
+PINCH_RELEASE_RATIO: float = 1.25
+"""Histerese da pinca (Schmitt trigger): pra SOLTAR a pinca, polegar e
+indicador precisam abrir ate threshold * 1.25 (entrar continua em
+threshold). Vale tambem pro clique direito.
+
+Com limiar unico, o ruido do tracker com os dedos perto da borda fazia a
+pinca "piscar": clique extra no encostar seguinte ou drag caindo sozinho.
+Mesma tecnica dos detectores de pinca da Ultraleap (distancias separadas
+de ativar/desativar). 1.0 = comportamento antigo (limiar unico).
+Suba (1.35) se ainda notar clique duplo acidental; desca (1.15) se soltar
+o drag ficar dificil.
+"""
+
 PINCH_MIN_HOLD_SECONDS: float = 0.015
-"""Tempo minimo da pinca pra contar como click. 15ms permite cliques
-rapidos e fluidos sem disparar em encontros acidentais."""
+"""Sem efeito no modelo press-to-click (o clique sai no encostar).
+Mantido so pra nao quebrar configs existentes."""
 
 # ---------------------------------------------------------------------
 # CLIQUE DIREITO — pinca polegar+medio
@@ -416,6 +449,13 @@ alvos pequenos errarem.
 0.12s cobre o intervalo entre a deteccao do raw shape PINCH e a
 estabilizacao da pose. Aumente pra 0.15-0.20s se ainda notar deriva.
 Diminua pra 0.08s se sentir cursor "preso" apos clicks consecutivos.
+
+Em runtime o valor vem do PERFIL (slider "Trava no clique" do painel);
+este e' o valor de referencia do perfil 'smooth'/'recommended'.
+
+Ao destravar, o cursor NAO salta pra onde a mao foi durante a trava: a
+diferenca e' absorvida aos poucos conforme a mao se move (ver
+CursorController._reconcile_offset). Vale tambem pro fim do drag.
 """
 
 DRAG_PRECISION_FACTOR: float = 0.55
@@ -511,25 +551,42 @@ parece magica; em uso prolongado pode distrair.
 HOLOGRAM_BACKEND: str = "auto"
 """Backend de renderizacao do holograma.
 
-- "auto"     : tenta GL primeiro; cai pra QPainter se driver falhar
-- "gl"       : forca ModernGL (mesh 3D + GLSL shader)
-- "qpainter" : forca pipeline 2D vetorial (compatibilidade/debug)
+- "auto"     : OpenGL 3D se houver OpenGL 3.3 (testado na inicializacao);
+               senao cai pro renderer 2D QPainter no mesmo estilo
+- "gl"       : forca OpenGL (mesh 3D + shader)
+- "qpainter" : forca o renderer 2D (compatibilidade/debug)
+
+O OpenGL e' o do proprio Qt (PySide6) — nao depende de moderngl/
+glcontext, cuja DLL o Smart App Control do Windows pode bloquear.
+Em ambientes sem GPU/driver (RDP, VM sem aceleracao) o "auto" ja cai
+pro QPainter sozinho.
+"""
+
+HOLOGRAM_STYLE: str = "quest"
+"""Aparencia da mao.
+
+- "quest"    : mao 3D estilo headset VR — azul-acinzentado claro, luz
+               suave, borda luminosa, antebraco em fade, pontas brilham
+               na pinca (default)
+- "graphite" : mesma mao, grafite translucido com contorno claro (fundos
+               claros)
+- "neon"     : visual antigo (silhueta neon + particulas, so 2D)
 
-ModernGL renderiza a mao como mesh 3D real (palm ellipsoide + finger
-capsules) com shader holografico (fresnel rim, depth fade, cyan
-volumetric). Requer driver OpenGL 3.3+. Em ambientes sem GPU/driver
-(RDP, VM sem aceleracao), usar "qpainter".
+Nos estilos 3D a mao segue a pose real: aspecto correto da camera,
+profundidade de cada articulacao e escala estavel pela palma (fechar a
+mao nao a "infla"). Ver core/hand_pose.py.
 """
 
 HOLOGRAM_TOGGLE_KEY: str = "h"
 """Tecla pra alternar o holograma em runtime."""
 
-HOLOGRAM_OPACITY: float = 0.70
-"""Opacidade base. Camadas (palm/finger outline, particles, tips) usam
-fracoes desse valor."""
+HOLOGRAM_OPACITY: float = 0.90
+"""Opacidade da mao. No estilo "quest" o corpo fica ~72% opaco (borda
+mais forte); no "neon" as camadas usam fracoes deste valor."""
 
 HOLOGRAM_HAND_SIZE_PX: int = 180
-"""Tamanho do bounding box da mao em pixels."""
+"""Tamanho da mao na tela (px): comprimento da mao aberta, do pulso a
+ponta do dedo medio. Nao muda com o gesto."""
 
 HOLOGRAM_FPS: int = 30
 """Taxa de redesenho. 30 Hz e' suave + economico em CPU."""

{ai_virtual_mouse_controller-1.2.0 → ai_virtual_mouse_controller-1.3.0}/core/__init__.py

@@ -10,5 +10,5 @@ Versao do pacote vive em `__version__` e e' a fonte unica de verdade
 
 from __future__ import annotations
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 __all__ = ["__version__"]

{ai_virtual_mouse_controller-1.2.0 → ai_virtual_mouse_controller-1.3.0}/core/camera.py

@@ -24,7 +24,7 @@ from __future__ import annotations
 import logging
 import threading
 import time
-from typing import Optional
+from typing import Optional, Tuple
 
 import cv2
 import numpy as np
@@ -71,41 +71,56 @@ class ThreadedCamera:
 
         self._cap: Optional[cv2.VideoCapture] = None
         self._frame: Optional[np.ndarray] = None
-        self._lock = threading.Lock()
+        # Numero de sequencia do frame: deixa o consumidor processar cada
+        # frame da webcam UMA vez (sem reprocessar duplicatas).
+        self._seq: int = 0
+        self._cond = threading.Condition()
         self._stop_event = threading.Event()
         self._thread: Optional[threading.Thread] = None
         self._opened = False
+        # True quando a webcam parou de entregar frames (desconectada ou
+        # tomada por outro app). O thread tenta reabrir sozinho.
+        self._stalled = False
 
     # -----------------------------------------------------------------
     # Lifecycle
     # -----------------------------------------------------------------
 
-    def open(self) -> "ThreadedCamera":
-        """
-        Abre a webcam e inicia o thread de captura.
-
-        Tenta primeiro com backend nativo do SO; se falhar, usa default.
-        """
+    def _open_capture(self) -> Optional[cv2.VideoCapture]:
+        """Abre o dispositivo (DirectShow primeiro, depois default)."""
         # Tenta backend especifico do SO (mais estavel)
         cap = cv2.VideoCapture(self.index, cv2.CAP_DSHOW)
         if not cap.isOpened():
             logger.debug("CAP_DSHOW falhou, tentando default")
+            cap.release()
             cap = cv2.VideoCapture(self.index)
-
         if not cap.isOpened():
-            raise CameraOpenError(
-                f"Nao foi possivel abrir a webcam (index={self.index}). "
-                "Verifique se ela esta conectada e nao ocupada por outro app."
-            )
+            cap.release()
+            return None
 
         cap.set(cv2.CAP_PROP_FRAME_WIDTH, self.width)
         cap.set(cv2.CAP_PROP_FRAME_HEIGHT, self.height)
         cap.set(cv2.CAP_PROP_FPS, self.fps)
         # Buffer minimo = sempre frame mais recente
         cap.set(cv2.CAP_PROP_BUFFERSIZE, 1)
+        return cap
+
+    def open(self) -> "ThreadedCamera":
+        """
+        Abre a webcam e inicia o thread de captura.
+
+        Tenta primeiro com backend nativo do SO; se falhar, usa default.
+        """
+        cap = self._open_capture()
+        if cap is None:
+            raise CameraOpenError(
+                f"Nao foi possivel abrir a webcam (index={self.index}). "
+                "Verifique se ela esta conectada e nao ocupada por outro app."
+            )
 
         self._cap = cap
         self._opened = True
+        self._stalled = False
 
         # Aquece a webcam (descarta primeiros frames pretos)
         time.sleep(self.warmup_seconds)
@@ -129,6 +144,8 @@ class ThreadedCamera:
             return
 
         self._stop_event.set()
+        with self._cond:
+            self._cond.notify_all()
         if self._thread is not None:
             self._thread.join(timeout=2.0)
             self._thread = None
@@ -150,31 +167,70 @@ class ThreadedCamera:
     # Loop interno
     # -----------------------------------------------------------------
 
+    _MAX_FAILURES: int = 30
+    _REOPEN_INTERVAL_S: float = 1.0
+
     def _capture_loop(self) -> None:
-        """Roda em thread separada lendo frames sem parar."""
+        """Roda em thread separada lendo frames sem parar.
+
+        Se a webcam parar de responder (cabo USB solto, outro app pegou o
+        dispositivo), marca `stalled`, descarta o ultimo frame (pra ninguem
+        processar imagem congelada como se fosse ao vivo) e tenta reabrir
+        a cada segundo ate voltar ou ate close().
+        """
         consecutive_failures = 0
-        max_failures = 30
 
         while not self._stop_event.is_set():
-            if self._cap is None:
-                break
+            cap = self._cap or self._try_reopen()
+            if cap is None:
+                continue
 
-            ok, frame = self._cap.read()
+            ok, frame = cap.read()
             if not ok or frame is None:
                 consecutive_failures += 1
-                if consecutive_failures >= max_failures:
+                if consecutive_failures >= self._MAX_FAILURES:
                     logger.error(
-                        "Webcam falhou %d frames consecutivos, parando thread",
-                        max_failures,
+                        "Webcam falhou %d frames consecutivos — tentando "
+                        "reconectar", self._MAX_FAILURES,
                     )
-                    break
+                    self._mark_stalled()
+                    consecutive_failures = 0
+                    continue
                 time.sleep(0.01)
                 continue
 
             consecutive_failures = 0
-
-            with self._lock:
+            with self._cond:
                 self._frame = frame
+                self._seq += 1
+                self._cond.notify_all()
+
+    def _mark_stalled(self) -> None:
+        with self._cond:
+            self._stalled = True
+            self._frame = None
+            self._cond.notify_all()
+        if self._cap is not None:
+            self._cap.release()
+            self._cap = None
+
+    def _try_reopen(self) -> Optional[cv2.VideoCapture]:
+        """Uma tentativa de reabrir. None = esperou o intervalo e falhou."""
+        if self._stop_event.wait(self._REOPEN_INTERVAL_S):
+            return None
+        cap = self._open_capture()
+        if cap is None:
+            return None
+        if self._stop_event.is_set():
+            # close() chegou durante a abertura (DirectShow pode levar
+            # segundos): nao deixar o dispositivo aberto sem dono.
+            cap.release()
+            return None
+        self._cap = cap
+        with self._cond:
+            self._stalled = False
+        logger.info("Webcam %d reconectada", self.index)
+        return cap
 
     # -----------------------------------------------------------------
     # API publica
@@ -190,7 +246,7 @@ class ThreadedCamera:
         Returns:
             Frame BGR (numpy array) ou None se nada disponivel ainda.
         """
-        with self._lock:
+        with self._cond:
             if self._frame is None:
                 return None
             frame = self._frame.copy()
@@ -199,6 +255,47 @@ class ThreadedCamera:
             frame = cv2.flip(frame, 1)
         return frame
 
+    def read_new(
+        self,
+        last_seq: int,
+        timeout: float,
+        mirror: bool = True,
+    ) -> Tuple[Optional[np.ndarray], int]:
+        """
+        Espera ate `timeout` por um frame MAIS NOVO que `last_seq`.
+
+        O loop principal costuma rodar mais rapido que a webcam (30 fps
+        e' o comum). Com read() ele reprocessava o mesmo frame varias
+        vezes: inferencia desperdicada e, pior, frames repetidos com
+        velocidade zero distorciam histerese, sticky e follow-through.
+
+        Returns:
+            (frame, seq) — frame None se nada novo chegou no prazo; nesse
+            caso seq volta igual a `last_seq`.
+        """
+        with self._cond:
+            if self._seq == last_seq or self._frame is None:
+                self._cond.wait_for(
+                    lambda: (
+                        (self._seq != last_seq and self._frame is not None)
+                        or self._stop_event.is_set()
+                    ),
+                    timeout=timeout,
+                )
+            if self._seq == last_seq or self._frame is None:
+                return None, last_seq
+            frame = self._frame.copy()
+            seq = self._seq
+
+        if mirror:
+            frame = cv2.flip(frame, 1)
+        return frame, seq
+
+    @property
+    def is_stalled(self) -> bool:
+        """Webcam parou de entregar frames e esta tentando reconectar."""
+        return self._stalled
+
     @property
     def is_opened(self) -> bool:
         """Camera aberta e thread ativa."""