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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/PKG-INFO +46 -19
  2. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/README.md +39 -12
  3. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/ai_virtual_mouse_controller.egg-info/PKG-INFO +46 -19
  4. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/ai_virtual_mouse_controller.egg-info/SOURCES.txt +18 -1
  5. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/ai_virtual_mouse_controller.egg-info/requires.txt +3 -5
  6. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/ai_virtual_mouse_controller.egg-info/top_level.txt +1 -0
  7. ai_virtual_mouse_controller-1.3.0/avmc.py +15 -0
  8. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/config.py +74 -17
  9. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/__init__.py +1 -1
  10. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/camera.py +122 -25
  11. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/cursor_controller.py +32 -16
  12. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/gesture_detector.py +65 -40
  13. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/hand_anchor.py +89 -5
  14. ai_virtual_mouse_controller-1.3.0/core/hand_gl_renderer.py +347 -0
  15. ai_virtual_mouse_controller-1.3.0/core/hand_mesh.py +501 -0
  16. ai_virtual_mouse_controller-1.3.0/core/hand_pose.py +217 -0
  17. ai_virtual_mouse_controller-1.3.0/core/hand_soft_renderer.py +262 -0
  18. ai_virtual_mouse_controller-1.3.0/core/hand_tracker.py +292 -0
  19. ai_virtual_mouse_controller-1.3.0/core/hologram_gl_backend.py +334 -0
  20. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/hologram_overlay.py +53 -4
  21. ai_virtual_mouse_controller-1.3.0/core/models/hand_landmarker.task +0 -0
  22. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/presentation_controller.py +3 -2
  23. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/runtime_settings.py +24 -16
  24. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/settings_panel.py +1 -1
  25. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/smoothing.py +37 -0
  26. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/ui_overlay.py +2 -2
  27. ai_virtual_mouse_controller-1.3.0/core/windows_path.py +161 -0
  28. ai_virtual_mouse_controller-1.3.0/main.py +115 -0
  29. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/pyproject.toml +25 -18
  30. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/services/virtual_mouse_service.py +212 -127
  31. ai_virtual_mouse_controller-1.3.0/tests/test_camera.py +118 -0
  32. ai_virtual_mouse_controller-1.3.0/tests/test_cursor_feel.py +92 -0
  33. ai_virtual_mouse_controller-1.3.0/tests/test_gesture_detector_behavior.py +200 -0
  34. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_hand_anchor_bottom.py +33 -0
  35. ai_virtual_mouse_controller-1.3.0/tests/test_hand_mesh.py +75 -0
  36. ai_virtual_mouse_controller-1.3.0/tests/test_hand_pose.py +111 -0
  37. ai_virtual_mouse_controller-1.3.0/tests/test_hand_renderers.py +98 -0
  38. ai_virtual_mouse_controller-1.3.0/tests/test_hand_tracker.py +139 -0
  39. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_hologram_overlay.py +3 -3
  40. ai_virtual_mouse_controller-1.3.0/tests/test_motion_quality.py +87 -0
  41. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_overlay_smoke.py +4 -2
  42. ai_virtual_mouse_controller-1.3.0/tests/test_runtime_settings.py +50 -0
  43. ai_virtual_mouse_controller-1.3.0/tests/test_service_camera_loss.py +59 -0
  44. ai_virtual_mouse_controller-1.3.0/tests/test_windows_path.py +131 -0
  45. ai_virtual_mouse_controller-1.1.2/core/hand_mesh.py +0 -794
  46. ai_virtual_mouse_controller-1.1.2/core/hand_tracker.py +0 -238
  47. ai_virtual_mouse_controller-1.1.2/core/hologram_gl_backend.py +0 -964
  48. ai_virtual_mouse_controller-1.1.2/main.py +0 -80
  49. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/LICENSE +0 -0
  50. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/ai_virtual_mouse_controller.egg-info/dependency_links.txt +0 -0
  51. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/ai_virtual_mouse_controller.egg-info/entry_points.txt +0 -0
  52. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/click_burst.py +0 -0
  53. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/finger_posture.py +0 -0
  54. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/hand_renderer.py +0 -0
  55. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/perf_telemetry.py +0 -0
  56. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/utils.py +0 -0
  57. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/services/__init__.py +0 -0
  58. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/setup.cfg +0 -0
  59. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_click_burst.py +0 -0
  60. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_cursor_bottom_reach.py +0 -0
  61. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_cursor_click_at.py +0 -0
  62. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_gesture_detector.py +0 -0
  63. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_hand_renderer.py +0 -0
  64. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_perf_telemetry.py +0 -0
  65. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_presentation_controller.py +0 -0
  66. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_settings_panel.py +0 -0
  67. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_smoothing.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ai-virtual-mouse-controller
3
- Version: 1.1.2
3
+ Version: 1.3.0
4
4
  Summary: Controle de cursor por gestos da mao via webcam, com holograma 3D opcional.
5
5
  Author: Guilherme Moraes Franco
6
6
  License: MIT
@@ -18,22 +18,22 @@ Classifier: Operating System :: Microsoft :: Windows
18
18
  Classifier: Operating System :: POSIX :: Linux
19
19
  Classifier: Operating System :: MacOS :: MacOS X
20
20
  Classifier: Programming Language :: Python :: 3
21
+ Classifier: Programming Language :: Python :: 3.10
21
22
  Classifier: Programming Language :: Python :: 3.11
22
23
  Classifier: Programming Language :: Python :: 3.12
23
24
  Classifier: Programming Language :: Python :: 3.13
25
+ Classifier: Programming Language :: Python :: 3.14
24
26
  Classifier: Topic :: Multimedia :: Video :: Capture
25
27
  Classifier: Topic :: Scientific/Engineering :: Image Recognition
26
- Requires-Python: <3.14,>=3.11
28
+ Requires-Python: >=3.10
27
29
  Description-Content-Type: text/markdown
28
30
  License-File: LICENSE
29
- Requires-Dist: opencv-python<5.0.0,>=4.10.0
30
- Requires-Dist: mediapipe<0.10.30,>=0.10.18
31
+ Requires-Dist: opencv-contrib-python<5.0.0,>=4.10.0
32
+ Requires-Dist: mediapipe>=0.10.18
31
33
  Requires-Dist: pyautogui<1.0.0,>=0.9.54
32
- Requires-Dist: numpy<2.2.0,>=1.26.0
33
- Requires-Dist: moderngl>=5.10.0
34
+ Requires-Dist: numpy>=1.26.0
34
35
  Requires-Dist: PySide6>=6.6.0
35
36
  Provides-Extra: hologram
36
- Requires-Dist: moderngl>=5.10.0; extra == "hologram"
37
37
  Requires-Dist: PySide6>=6.6.0; extra == "hologram"
38
38
  Provides-Extra: dev
39
39
  Requires-Dist: pytest>=8.0.0; extra == "dev"
@@ -51,11 +51,16 @@ Dynamic: license-file
51
51
 
52
52
  [![CI](https://github.com/ognistie/ai-virtual-mouse-controller/actions/workflows/ci.yml/badge.svg)](https://github.com/ognistie/ai-virtual-mouse-controller/actions/workflows/ci.yml)
53
53
  [![PyPI](https://img.shields.io/pypi/v/ai-virtual-mouse-controller?style=flat-square&color=22d3ee&label=pypi)](https://pypi.org/project/ai-virtual-mouse-controller/)
54
- [![Python](https://img.shields.io/badge/python-3.11_|_3.12-22d3ee?style=flat-square)](https://pypi.org/project/ai-virtual-mouse-controller/)
54
+ [![Python](https://img.shields.io/badge/python-3.10--3.14-22d3ee?style=flat-square)](https://pypi.org/project/ai-virtual-mouse-controller/)
55
55
  [![License](https://img.shields.io/badge/license-MIT-22d3ee?style=flat-square)](LICENSE)
56
56
 
57
57
  Webcam → 21 landmarks → cursor do sistema. Sem hardware extra. Sem GPU.
58
58
 
59
+ **AI-powered virtual mouse controller for Windows, macOS, and Linux.** Control the
60
+ mouse cursor, left and right clicks, drag-and-drop, and presentations with real-time
61
+ hand gestures captured by a standard webcam. Built with Python, OpenCV, MediaPipe
62
+ Hands, and PyAutoGUI; runs locally without sending camera images to the cloud.
63
+
59
64
  <br/>
60
65
 
61
66
  <table>
@@ -78,23 +83,34 @@ Webcam → 21 landmarks → cursor do sistema. Sem hardware extra. Sem GPU.
78
83
 
79
84
  ## O que é
80
85
 
81
- Sistema gestual de controle de cursor com qualidade comparável a periféricos físicos. O MediaPipe identifica 21 pontos da mão em tempo real, uma state machine traduz gestos em eventos do sistema operacional (move, click, drag, scroll), e um holograma 3D opcional renderiza a mão virtual sobre o desktop.
86
+ O **AI Virtual Mouse Controller** é um mouse virtual com reconhecimento de gestos pela webcam. O MediaPipe identifica 21 pontos da mão em tempo real, uma state machine traduz gestos em eventos do sistema operacional (move, click, drag, scroll), e um holograma 3D opcional renderiza a mão virtual sobre o desktop.
82
87
 
83
88
  100% local. Sem nuvem, sem telemetria, sem persistir nada da webcam.
84
89
 
85
- **Stack:** Python 3.11+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · ModernGL/PySide6 (opcional)
90
+ **Stack:** Python 3.10+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · PySide6 (holograma 3D via OpenGL do Qt)
86
91
 
87
92
  ---
88
93
 
89
94
  ## Instalar
90
95
 
91
- Requer **Python 3.11 ou 3.12** + webcam.
96
+ Requer **Python 3.10 ou mais novo** (testado de 3.10 a 3.14) + webcam.
92
97
 
93
98
  ```bash
94
99
  pip install ai-virtual-mouse-controller
95
100
  avmc
96
101
  ```
97
102
 
103
+ > **Windows — "avmc não é reconhecido"?** O instalador novo do Python (padrão
104
+ > no 3.14) não põe a pasta `Scripts` no PATH. Rode uma vez:
105
+ >
106
+ > ```powershell
107
+ > py -m avmc
108
+ > ```
109
+ >
110
+ > O AVMC abre e adiciona essa pasta ao PATH do seu usuário (sem admin). A partir
111
+ > daí, num terminal **novo**, `avmc` funciona. Pra não mexer no PATH, defina
112
+ > `AVMC_NO_PATH_SETUP=1`.
113
+
98
114
  Posicione a mão a ~50cm da câmera. Atalhos em runtime:
99
115
 
100
116
  | Tecla | Ação |
@@ -134,6 +150,15 @@ Conferir a versão instalada:
134
150
  pip show ai-virtual-mouse-controller
135
151
  ```
136
152
 
153
+ Vindo da 1.1.2 ou anterior? O projeto trocou `opencv-python` por
154
+ `opencv-contrib-python` (mesmo `cv2`, usado pelo MediaPipe). Remova o antigo
155
+ pra os dois não disputarem a mesma pasta:
156
+
157
+ ```bash
158
+ pip uninstall -y opencv-python
159
+ pip install --force-reinstall --no-deps "opencv-contrib-python>=4.10,<5"
160
+ ```
161
+
137
162
  Se quiser pular o cache do pip e baixar do PyPI direto:
138
163
 
139
164
  ```bash
@@ -175,12 +200,13 @@ Toda a calibração vive em [`config.py`](config.py) — constantes nomeadas com
175
200
  | Seção | O que controla |
176
201
  |---|---|
177
202
  | `CAMERA` | índice da câmera, resolução, FPS alvo |
203
+ | `PROFILE` | perfil inicial do painel: `smooth`, `precise`, `responsive`, `stable` |
178
204
  | `CURSOR_ANCHOR` | qual ponto da mão o cursor segue (`-2` = âncora robusta, default) |
179
- | `PINCH` | thresholds de detecção de clique (com escala adaptativa por tamanho da mão) |
205
+ | `PINCH` | thresholds de detecção de clique (escala adaptativa por tamanho da mão + histerese pra soltar) |
180
206
  | `DPI` / `SMOOTHING` | sensibilidade do cursor + filtro OneEuro |
181
207
  | `SCREEN_MARGIN_*` | margens assimétricas (top/bottom < lateral) pra alcançar cantos |
182
208
  | `CURSOR_FOLLOWTHROUGH_*` | cinematic prediction quando a mão sai do FOV |
183
- | `HOLOGRAM` | backend (GL/QPainter), cor, opacidade, FPS |
209
+ | `HOLOGRAM` | estilo (`quest`, `graphite`, `neon`), backend (OpenGL/QPainter), tamanho, opacidade, FPS |
184
210
 
185
211
  Ajustes em tempo de execução também ficam disponíveis no painel (tecla `S`) — perfis prontos: *smooth*, *precise*, *responsive*, *stable*.
186
212
 
@@ -191,11 +217,11 @@ Ajustes em tempo de execução também ficam disponíveis no painel (tecla `S`)
191
217
  | OS | Setup adicional |
192
218
  |---|---|
193
219
  | 🪟 **Windows 10/11** | Nada. Funciona out-of-the-box após `pip install`. |
194
- | 🍎 **macOS** | Após primeiro run, liberar **System Settings → Privacy & Security → Accessibility** (cursor) e **Camera** (webcam). Em Apple Silicon, se PyAutoGUI reclamar: `pip install pyobjc-core pyobjc`. |
195
- | 🐧 **Linux (X11)** | `sudo apt install scrot python3-tk python3-dev` (Ubuntu/Debian). PyAutoGUI precisa desses pra capturar a tela. |
220
+ | 🍎 **macOS** | Mac Intel: use Python ≤ 3.12 (o MediaPipe novo só publica wheel pra Apple Silicon). Após primeiro run, liberar **System Settings → Privacy & Security → Accessibility** (cursor) e **Camera** (webcam). Em Apple Silicon, se PyAutoGUI reclamar: `pip install pyobjc-core pyobjc`. |
221
+ | 🐧 **Linux (X11)** | `sudo apt install scrot python3-tk python3-dev libegl1` (Ubuntu/Debian). PyAutoGUI precisa dos três primeiros pra capturar a tela; o MediaPipe precisa do `libegl1`. |
196
222
  | 🐧 **Linux (Wayland)** | Suporte limitado de PyAutoGUI. Recomendado mudar pra sessão X11. |
197
223
 
198
- > **Mediapipe pin:** o projeto usa `mediapipe < 0.10.30`. Versões 0.10.30+ removeram o módulo `mp.solutions.hands` que sustenta o pipeline. O `pyproject.toml` já fixa o limite — não há nada manual pra fazer.
224
+ > **MediaPipe:** o rastreamento usa a Tasks API (`HandLandmarker`), disponível em `mediapipe >= 0.10.18`. O modelo (`core/models/hand_landmarker.task`) vem dentro do pacote — roda offline, sem download extra.
199
225
 
200
226
  ---
201
227
 
@@ -213,7 +239,7 @@ webcam → MediaPipe Hands (21 landmarks)
213
239
  CursorController ← PyAutoGUI move o cursor real
214
240
  ```
215
241
 
216
- Componentes auxiliares: `HologramOverlay` (renderização 3D opcional via ModernGL), `RuntimeSettings` (perfis e sliders), `PerfTelemetry` (timing p50/p99 por estágio).
242
+ 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).
217
243
 
218
244
  Estrutura de pastas:
219
245
 
@@ -222,7 +248,8 @@ core/ # camera, hand_tracker, gesture_detector, hand_anchor, smoothing
222
248
  services/ # orquestração do loop principal
223
249
  config.py # constantes de calibração documentadas
224
250
  main.py # entry point
225
- tests/ # cobertura dos módulos puros (sem cv2/mediapipe)
251
+ scripts/ # eval_motion.py: mede jitter/atraso/cliques com mãos sintéticas
252
+ tests/ # unitários + gate de qualidade de movimento
226
253
  docs/ # site estático + assets
227
254
  ```
228
255
 
@@ -242,7 +269,7 @@ make test-gpu # só testes que precisam de display/GPU real
242
269
  make test-cov # com coverage HTML
243
270
  ```
244
271
 
245
- 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.
272
+ 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.
246
273
 
247
274
  ---
248
275
 
@@ -6,11 +6,16 @@
6
6
 
7
7
  [![CI](https://github.com/ognistie/ai-virtual-mouse-controller/actions/workflows/ci.yml/badge.svg)](https://github.com/ognistie/ai-virtual-mouse-controller/actions/workflows/ci.yml)
8
8
  [![PyPI](https://img.shields.io/pypi/v/ai-virtual-mouse-controller?style=flat-square&color=22d3ee&label=pypi)](https://pypi.org/project/ai-virtual-mouse-controller/)
9
- [![Python](https://img.shields.io/badge/python-3.11_|_3.12-22d3ee?style=flat-square)](https://pypi.org/project/ai-virtual-mouse-controller/)
9
+ [![Python](https://img.shields.io/badge/python-3.10--3.14-22d3ee?style=flat-square)](https://pypi.org/project/ai-virtual-mouse-controller/)
10
10
  [![License](https://img.shields.io/badge/license-MIT-22d3ee?style=flat-square)](LICENSE)
11
11
 
12
12
  Webcam → 21 landmarks → cursor do sistema. Sem hardware extra. Sem GPU.
13
13
 
14
+ **AI-powered virtual mouse controller for Windows, macOS, and Linux.** Control the
15
+ mouse cursor, left and right clicks, drag-and-drop, and presentations with real-time
16
+ hand gestures captured by a standard webcam. Built with Python, OpenCV, MediaPipe
17
+ Hands, and PyAutoGUI; runs locally without sending camera images to the cloud.
18
+
14
19
  <br/>
15
20
 
16
21
  <table>
@@ -33,23 +38,34 @@ Webcam → 21 landmarks → cursor do sistema. Sem hardware extra. Sem GPU.
33
38
 
34
39
  ## O que é
35
40
 
36
- Sistema gestual de controle de cursor com qualidade comparável a periféricos físicos. O MediaPipe identifica 21 pontos da mão em tempo real, uma state machine traduz gestos em eventos do sistema operacional (move, click, drag, scroll), e um holograma 3D opcional renderiza a mão virtual sobre o desktop.
41
+ O **AI Virtual Mouse Controller** é um mouse virtual com reconhecimento de gestos pela webcam. O MediaPipe identifica 21 pontos da mão em tempo real, uma state machine traduz gestos em eventos do sistema operacional (move, click, drag, scroll), e um holograma 3D opcional renderiza a mão virtual sobre o desktop.
37
42
 
38
43
  100% local. Sem nuvem, sem telemetria, sem persistir nada da webcam.
39
44
 
40
- **Stack:** Python 3.11+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · ModernGL/PySide6 (opcional)
45
+ **Stack:** Python 3.10+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · PySide6 (holograma 3D via OpenGL do Qt)
41
46
 
42
47
  ---
43
48
 
44
49
  ## Instalar
45
50
 
46
- Requer **Python 3.11 ou 3.12** + webcam.
51
+ Requer **Python 3.10 ou mais novo** (testado de 3.10 a 3.14) + webcam.
47
52
 
48
53
  ```bash
49
54
  pip install ai-virtual-mouse-controller
50
55
  avmc
51
56
  ```
52
57
 
58
+ > **Windows — "avmc não é reconhecido"?** O instalador novo do Python (padrão
59
+ > no 3.14) não põe a pasta `Scripts` no PATH. Rode uma vez:
60
+ >
61
+ > ```powershell
62
+ > py -m avmc
63
+ > ```
64
+ >
65
+ > O AVMC abre e adiciona essa pasta ao PATH do seu usuário (sem admin). A partir
66
+ > daí, num terminal **novo**, `avmc` funciona. Pra não mexer no PATH, defina
67
+ > `AVMC_NO_PATH_SETUP=1`.
68
+
53
69
  Posicione a mão a ~50cm da câmera. Atalhos em runtime:
54
70
 
55
71
  | Tecla | Ação |
@@ -89,6 +105,15 @@ Conferir a versão instalada:
89
105
  pip show ai-virtual-mouse-controller
90
106
  ```
91
107
 
108
+ Vindo da 1.1.2 ou anterior? O projeto trocou `opencv-python` por
109
+ `opencv-contrib-python` (mesmo `cv2`, usado pelo MediaPipe). Remova o antigo
110
+ pra os dois não disputarem a mesma pasta:
111
+
112
+ ```bash
113
+ pip uninstall -y opencv-python
114
+ pip install --force-reinstall --no-deps "opencv-contrib-python>=4.10,<5"
115
+ ```
116
+
92
117
  Se quiser pular o cache do pip e baixar do PyPI direto:
93
118
 
94
119
  ```bash
@@ -130,12 +155,13 @@ Toda a calibração vive em [`config.py`](config.py) — constantes nomeadas com
130
155
  | Seção | O que controla |
131
156
  |---|---|
132
157
  | `CAMERA` | índice da câmera, resolução, FPS alvo |
158
+ | `PROFILE` | perfil inicial do painel: `smooth`, `precise`, `responsive`, `stable` |
133
159
  | `CURSOR_ANCHOR` | qual ponto da mão o cursor segue (`-2` = âncora robusta, default) |
134
- | `PINCH` | thresholds de detecção de clique (com escala adaptativa por tamanho da mão) |
160
+ | `PINCH` | thresholds de detecção de clique (escala adaptativa por tamanho da mão + histerese pra soltar) |
135
161
  | `DPI` / `SMOOTHING` | sensibilidade do cursor + filtro OneEuro |
136
162
  | `SCREEN_MARGIN_*` | margens assimétricas (top/bottom < lateral) pra alcançar cantos |
137
163
  | `CURSOR_FOLLOWTHROUGH_*` | cinematic prediction quando a mão sai do FOV |
138
- | `HOLOGRAM` | backend (GL/QPainter), cor, opacidade, FPS |
164
+ | `HOLOGRAM` | estilo (`quest`, `graphite`, `neon`), backend (OpenGL/QPainter), tamanho, opacidade, FPS |
139
165
 
140
166
  Ajustes em tempo de execução também ficam disponíveis no painel (tecla `S`) — perfis prontos: *smooth*, *precise*, *responsive*, *stable*.
141
167
 
@@ -146,11 +172,11 @@ Ajustes em tempo de execução também ficam disponíveis no painel (tecla `S`)
146
172
  | OS | Setup adicional |
147
173
  |---|---|
148
174
  | 🪟 **Windows 10/11** | Nada. Funciona out-of-the-box após `pip install`. |
149
- | 🍎 **macOS** | Após primeiro run, liberar **System Settings → Privacy & Security → Accessibility** (cursor) e **Camera** (webcam). Em Apple Silicon, se PyAutoGUI reclamar: `pip install pyobjc-core pyobjc`. |
150
- | 🐧 **Linux (X11)** | `sudo apt install scrot python3-tk python3-dev` (Ubuntu/Debian). PyAutoGUI precisa desses pra capturar a tela. |
175
+ | 🍎 **macOS** | Mac Intel: use Python ≤ 3.12 (o MediaPipe novo só publica wheel pra Apple Silicon). Após primeiro run, liberar **System Settings → Privacy & Security → Accessibility** (cursor) e **Camera** (webcam). Em Apple Silicon, se PyAutoGUI reclamar: `pip install pyobjc-core pyobjc`. |
176
+ | 🐧 **Linux (X11)** | `sudo apt install scrot python3-tk python3-dev libegl1` (Ubuntu/Debian). PyAutoGUI precisa dos três primeiros pra capturar a tela; o MediaPipe precisa do `libegl1`. |
151
177
  | 🐧 **Linux (Wayland)** | Suporte limitado de PyAutoGUI. Recomendado mudar pra sessão X11. |
152
178
 
153
- > **Mediapipe pin:** o projeto usa `mediapipe < 0.10.30`. Versões 0.10.30+ removeram o módulo `mp.solutions.hands` que sustenta o pipeline. O `pyproject.toml` já fixa o limite — não há nada manual pra fazer.
179
+ > **MediaPipe:** o rastreamento usa a Tasks API (`HandLandmarker`), disponível em `mediapipe >= 0.10.18`. O modelo (`core/models/hand_landmarker.task`) vem dentro do pacote — roda offline, sem download extra.
154
180
 
155
181
  ---
156
182
 
@@ -168,7 +194,7 @@ webcam → MediaPipe Hands (21 landmarks)
168
194
  CursorController ← PyAutoGUI move o cursor real
169
195
  ```
170
196
 
171
- Componentes auxiliares: `HologramOverlay` (renderização 3D opcional via ModernGL), `RuntimeSettings` (perfis e sliders), `PerfTelemetry` (timing p50/p99 por estágio).
197
+ 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).
172
198
 
173
199
  Estrutura de pastas:
174
200
 
@@ -177,7 +203,8 @@ core/ # camera, hand_tracker, gesture_detector, hand_anchor, smoothing
177
203
  services/ # orquestração do loop principal
178
204
  config.py # constantes de calibração documentadas
179
205
  main.py # entry point
180
- tests/ # cobertura dos módulos puros (sem cv2/mediapipe)
206
+ scripts/ # eval_motion.py: mede jitter/atraso/cliques com mãos sintéticas
207
+ tests/ # unitários + gate de qualidade de movimento
181
208
  docs/ # site estático + assets
182
209
  ```
183
210
 
@@ -197,7 +224,7 @@ make test-gpu # só testes que precisam de display/GPU real
197
224
  make test-cov # com coverage HTML
198
225
  ```
199
226
 
200
- 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.
227
+ 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.
201
228
 
202
229
  ---
203
230
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ai-virtual-mouse-controller
3
- Version: 1.1.2
3
+ Version: 1.3.0
4
4
  Summary: Controle de cursor por gestos da mao via webcam, com holograma 3D opcional.
5
5
  Author: Guilherme Moraes Franco
6
6
  License: MIT
@@ -18,22 +18,22 @@ Classifier: Operating System :: Microsoft :: Windows
18
18
  Classifier: Operating System :: POSIX :: Linux
19
19
  Classifier: Operating System :: MacOS :: MacOS X
20
20
  Classifier: Programming Language :: Python :: 3
21
+ Classifier: Programming Language :: Python :: 3.10
21
22
  Classifier: Programming Language :: Python :: 3.11
22
23
  Classifier: Programming Language :: Python :: 3.12
23
24
  Classifier: Programming Language :: Python :: 3.13
25
+ Classifier: Programming Language :: Python :: 3.14
24
26
  Classifier: Topic :: Multimedia :: Video :: Capture
25
27
  Classifier: Topic :: Scientific/Engineering :: Image Recognition
26
- Requires-Python: <3.14,>=3.11
28
+ Requires-Python: >=3.10
27
29
  Description-Content-Type: text/markdown
28
30
  License-File: LICENSE
29
- Requires-Dist: opencv-python<5.0.0,>=4.10.0
30
- Requires-Dist: mediapipe<0.10.30,>=0.10.18
31
+ Requires-Dist: opencv-contrib-python<5.0.0,>=4.10.0
32
+ Requires-Dist: mediapipe>=0.10.18
31
33
  Requires-Dist: pyautogui<1.0.0,>=0.9.54
32
- Requires-Dist: numpy<2.2.0,>=1.26.0
33
- Requires-Dist: moderngl>=5.10.0
34
+ Requires-Dist: numpy>=1.26.0
34
35
  Requires-Dist: PySide6>=6.6.0
35
36
  Provides-Extra: hologram
36
- Requires-Dist: moderngl>=5.10.0; extra == "hologram"
37
37
  Requires-Dist: PySide6>=6.6.0; extra == "hologram"
38
38
  Provides-Extra: dev
39
39
  Requires-Dist: pytest>=8.0.0; extra == "dev"
@@ -51,11 +51,16 @@ Dynamic: license-file
51
51
 
52
52
  [![CI](https://github.com/ognistie/ai-virtual-mouse-controller/actions/workflows/ci.yml/badge.svg)](https://github.com/ognistie/ai-virtual-mouse-controller/actions/workflows/ci.yml)
53
53
  [![PyPI](https://img.shields.io/pypi/v/ai-virtual-mouse-controller?style=flat-square&color=22d3ee&label=pypi)](https://pypi.org/project/ai-virtual-mouse-controller/)
54
- [![Python](https://img.shields.io/badge/python-3.11_|_3.12-22d3ee?style=flat-square)](https://pypi.org/project/ai-virtual-mouse-controller/)
54
+ [![Python](https://img.shields.io/badge/python-3.10--3.14-22d3ee?style=flat-square)](https://pypi.org/project/ai-virtual-mouse-controller/)
55
55
  [![License](https://img.shields.io/badge/license-MIT-22d3ee?style=flat-square)](LICENSE)
56
56
 
57
57
  Webcam → 21 landmarks → cursor do sistema. Sem hardware extra. Sem GPU.
58
58
 
59
+ **AI-powered virtual mouse controller for Windows, macOS, and Linux.** Control the
60
+ mouse cursor, left and right clicks, drag-and-drop, and presentations with real-time
61
+ hand gestures captured by a standard webcam. Built with Python, OpenCV, MediaPipe
62
+ Hands, and PyAutoGUI; runs locally without sending camera images to the cloud.
63
+
59
64
  <br/>
60
65
 
61
66
  <table>
@@ -78,23 +83,34 @@ Webcam → 21 landmarks → cursor do sistema. Sem hardware extra. Sem GPU.
78
83
 
79
84
  ## O que é
80
85
 
81
- Sistema gestual de controle de cursor com qualidade comparável a periféricos físicos. O MediaPipe identifica 21 pontos da mão em tempo real, uma state machine traduz gestos em eventos do sistema operacional (move, click, drag, scroll), e um holograma 3D opcional renderiza a mão virtual sobre o desktop.
86
+ O **AI Virtual Mouse Controller** é um mouse virtual com reconhecimento de gestos pela webcam. O MediaPipe identifica 21 pontos da mão em tempo real, uma state machine traduz gestos em eventos do sistema operacional (move, click, drag, scroll), e um holograma 3D opcional renderiza a mão virtual sobre o desktop.
82
87
 
83
88
  100% local. Sem nuvem, sem telemetria, sem persistir nada da webcam.
84
89
 
85
- **Stack:** Python 3.11+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · ModernGL/PySide6 (opcional)
90
+ **Stack:** Python 3.10+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · PySide6 (holograma 3D via OpenGL do Qt)
86
91
 
87
92
  ---
88
93
 
89
94
  ## Instalar
90
95
 
91
- Requer **Python 3.11 ou 3.12** + webcam.
96
+ Requer **Python 3.10 ou mais novo** (testado de 3.10 a 3.14) + webcam.
92
97
 
93
98
  ```bash
94
99
  pip install ai-virtual-mouse-controller
95
100
  avmc
96
101
  ```
97
102
 
103
+ > **Windows — "avmc não é reconhecido"?** O instalador novo do Python (padrão
104
+ > no 3.14) não põe a pasta `Scripts` no PATH. Rode uma vez:
105
+ >
106
+ > ```powershell
107
+ > py -m avmc
108
+ > ```
109
+ >
110
+ > O AVMC abre e adiciona essa pasta ao PATH do seu usuário (sem admin). A partir
111
+ > daí, num terminal **novo**, `avmc` funciona. Pra não mexer no PATH, defina
112
+ > `AVMC_NO_PATH_SETUP=1`.
113
+
98
114
  Posicione a mão a ~50cm da câmera. Atalhos em runtime:
99
115
 
100
116
  | Tecla | Ação |
@@ -134,6 +150,15 @@ Conferir a versão instalada:
134
150
  pip show ai-virtual-mouse-controller
135
151
  ```
136
152
 
153
+ Vindo da 1.1.2 ou anterior? O projeto trocou `opencv-python` por
154
+ `opencv-contrib-python` (mesmo `cv2`, usado pelo MediaPipe). Remova o antigo
155
+ pra os dois não disputarem a mesma pasta:
156
+
157
+ ```bash
158
+ pip uninstall -y opencv-python
159
+ pip install --force-reinstall --no-deps "opencv-contrib-python>=4.10,<5"
160
+ ```
161
+
137
162
  Se quiser pular o cache do pip e baixar do PyPI direto:
138
163
 
139
164
  ```bash
@@ -175,12 +200,13 @@ Toda a calibração vive em [`config.py`](config.py) — constantes nomeadas com
175
200
  | Seção | O que controla |
176
201
  |---|---|
177
202
  | `CAMERA` | índice da câmera, resolução, FPS alvo |
203
+ | `PROFILE` | perfil inicial do painel: `smooth`, `precise`, `responsive`, `stable` |
178
204
  | `CURSOR_ANCHOR` | qual ponto da mão o cursor segue (`-2` = âncora robusta, default) |
179
- | `PINCH` | thresholds de detecção de clique (com escala adaptativa por tamanho da mão) |
205
+ | `PINCH` | thresholds de detecção de clique (escala adaptativa por tamanho da mão + histerese pra soltar) |
180
206
  | `DPI` / `SMOOTHING` | sensibilidade do cursor + filtro OneEuro |
181
207
  | `SCREEN_MARGIN_*` | margens assimétricas (top/bottom < lateral) pra alcançar cantos |
182
208
  | `CURSOR_FOLLOWTHROUGH_*` | cinematic prediction quando a mão sai do FOV |
183
- | `HOLOGRAM` | backend (GL/QPainter), cor, opacidade, FPS |
209
+ | `HOLOGRAM` | estilo (`quest`, `graphite`, `neon`), backend (OpenGL/QPainter), tamanho, opacidade, FPS |
184
210
 
185
211
  Ajustes em tempo de execução também ficam disponíveis no painel (tecla `S`) — perfis prontos: *smooth*, *precise*, *responsive*, *stable*.
186
212
 
@@ -191,11 +217,11 @@ Ajustes em tempo de execução também ficam disponíveis no painel (tecla `S`)
191
217
  | OS | Setup adicional |
192
218
  |---|---|
193
219
  | 🪟 **Windows 10/11** | Nada. Funciona out-of-the-box após `pip install`. |
194
- | 🍎 **macOS** | Após primeiro run, liberar **System Settings → Privacy & Security → Accessibility** (cursor) e **Camera** (webcam). Em Apple Silicon, se PyAutoGUI reclamar: `pip install pyobjc-core pyobjc`. |
195
- | 🐧 **Linux (X11)** | `sudo apt install scrot python3-tk python3-dev` (Ubuntu/Debian). PyAutoGUI precisa desses pra capturar a tela. |
220
+ | 🍎 **macOS** | Mac Intel: use Python ≤ 3.12 (o MediaPipe novo só publica wheel pra Apple Silicon). Após primeiro run, liberar **System Settings → Privacy & Security → Accessibility** (cursor) e **Camera** (webcam). Em Apple Silicon, se PyAutoGUI reclamar: `pip install pyobjc-core pyobjc`. |
221
+ | 🐧 **Linux (X11)** | `sudo apt install scrot python3-tk python3-dev libegl1` (Ubuntu/Debian). PyAutoGUI precisa dos três primeiros pra capturar a tela; o MediaPipe precisa do `libegl1`. |
196
222
  | 🐧 **Linux (Wayland)** | Suporte limitado de PyAutoGUI. Recomendado mudar pra sessão X11. |
197
223
 
198
- > **Mediapipe pin:** o projeto usa `mediapipe < 0.10.30`. Versões 0.10.30+ removeram o módulo `mp.solutions.hands` que sustenta o pipeline. O `pyproject.toml` já fixa o limite — não há nada manual pra fazer.
224
+ > **MediaPipe:** o rastreamento usa a Tasks API (`HandLandmarker`), disponível em `mediapipe >= 0.10.18`. O modelo (`core/models/hand_landmarker.task`) vem dentro do pacote — roda offline, sem download extra.
199
225
 
200
226
  ---
201
227
 
@@ -213,7 +239,7 @@ webcam → MediaPipe Hands (21 landmarks)
213
239
  CursorController ← PyAutoGUI move o cursor real
214
240
  ```
215
241
 
216
- Componentes auxiliares: `HologramOverlay` (renderização 3D opcional via ModernGL), `RuntimeSettings` (perfis e sliders), `PerfTelemetry` (timing p50/p99 por estágio).
242
+ 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).
217
243
 
218
244
  Estrutura de pastas:
219
245
 
@@ -222,7 +248,8 @@ core/ # camera, hand_tracker, gesture_detector, hand_anchor, smoothing
222
248
  services/ # orquestração do loop principal
223
249
  config.py # constantes de calibração documentadas
224
250
  main.py # entry point
225
- tests/ # cobertura dos módulos puros (sem cv2/mediapipe)
251
+ scripts/ # eval_motion.py: mede jitter/atraso/cliques com mãos sintéticas
252
+ tests/ # unitários + gate de qualidade de movimento
226
253
  docs/ # site estático + assets
227
254
  ```
228
255
 
@@ -242,7 +269,7 @@ make test-gpu # só testes que precisam de display/GPU real
242
269
  make test-cov # com coverage HTML
243
270
  ```
244
271
 
245
- 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.
272
+ 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.
246
273
 
247
274
  ---
248
275
 
@@ -1,5 +1,6 @@
1
1
  LICENSE
2
2
  README.md
3
+ avmc.py
3
4
  config.py
4
5
  main.py
5
6
  pyproject.toml
@@ -16,8 +17,11 @@ core/cursor_controller.py
16
17
  core/finger_posture.py
17
18
  core/gesture_detector.py
18
19
  core/hand_anchor.py
20
+ core/hand_gl_renderer.py
19
21
  core/hand_mesh.py
22
+ core/hand_pose.py
20
23
  core/hand_renderer.py
24
+ core/hand_soft_renderer.py
21
25
  core/hand_tracker.py
22
26
  core/hologram_gl_backend.py
23
27
  core/hologram_overlay.py
@@ -28,17 +32,30 @@ core/settings_panel.py
28
32
  core/smoothing.py
29
33
  core/ui_overlay.py
30
34
  core/utils.py
35
+ core/windows_path.py
36
+ core/models/hand_landmarker.task
31
37
  services/__init__.py
32
38
  services/virtual_mouse_service.py
39
+ tests/test_camera.py
33
40
  tests/test_click_burst.py
34
41
  tests/test_cursor_bottom_reach.py
35
42
  tests/test_cursor_click_at.py
43
+ tests/test_cursor_feel.py
36
44
  tests/test_gesture_detector.py
45
+ tests/test_gesture_detector_behavior.py
37
46
  tests/test_hand_anchor_bottom.py
47
+ tests/test_hand_mesh.py
48
+ tests/test_hand_pose.py
38
49
  tests/test_hand_renderer.py
50
+ tests/test_hand_renderers.py
51
+ tests/test_hand_tracker.py
39
52
  tests/test_hologram_overlay.py
53
+ tests/test_motion_quality.py
40
54
  tests/test_overlay_smoke.py
41
55
  tests/test_perf_telemetry.py
42
56
  tests/test_presentation_controller.py
57
+ tests/test_runtime_settings.py
58
+ tests/test_service_camera_loss.py
43
59
  tests/test_settings_panel.py
44
- tests/test_smoothing.py
60
+ tests/test_smoothing.py
61
+ tests/test_windows_path.py
@@ -1,8 +1,7 @@
1
- opencv-python<5.0.0,>=4.10.0
2
- mediapipe<0.10.30,>=0.10.18
1
+ opencv-contrib-python<5.0.0,>=4.10.0
2
+ mediapipe>=0.10.18
3
3
  pyautogui<1.0.0,>=0.9.54
4
- numpy<2.2.0,>=1.26.0
5
- moderngl>=5.10.0
4
+ numpy>=1.26.0
6
5
  PySide6>=6.6.0
7
6
 
8
7
  [dev]
@@ -13,5 +12,4 @@ mypy>=1.10.0
13
12
  pre-commit>=3.7.0
14
13
 
15
14
  [hologram]
16
- moderngl>=5.10.0
17
15
  PySide6>=6.6.0
@@ -0,0 +1,15 @@
1
+ """
2
+ avmc
3
+ ====
4
+
5
+ Permite rodar o projeto como modulo: `py -m avmc` (Windows) ou
6
+ `python -m avmc`. Funciona mesmo quando a pasta Scripts do Python nao esta
7
+ no PATH e o comando `avmc` ainda nao e' reconhecido.
8
+ """
9
+
10
+ import sys
11
+
12
+ from main import main
13
+
14
+ if __name__ == "__main__":
15
+ sys.exit(main())