ai-virtual-mouse-controller 1.1.2__tar.gz → 1.2.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 (52) hide show
  1. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/PKG-INFO +39 -12
  2. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/README.md +32 -7
  3. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/ai_virtual_mouse_controller.egg-info/PKG-INFO +39 -12
  4. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/ai_virtual_mouse_controller.egg-info/SOURCES.txt +6 -1
  5. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/ai_virtual_mouse_controller.egg-info/requires.txt +3 -3
  6. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/ai_virtual_mouse_controller.egg-info/top_level.txt +1 -0
  7. ai_virtual_mouse_controller-1.2.0/avmc.py +15 -0
  8. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/config.py +3 -3
  9. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/__init__.py +1 -1
  10. ai_virtual_mouse_controller-1.2.0/core/hand_tracker.py +292 -0
  11. ai_virtual_mouse_controller-1.2.0/core/models/hand_landmarker.task +0 -0
  12. ai_virtual_mouse_controller-1.2.0/core/windows_path.py +161 -0
  13. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/main.py +34 -13
  14. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/pyproject.toml +20 -11
  15. ai_virtual_mouse_controller-1.2.0/tests/test_hand_tracker.py +139 -0
  16. ai_virtual_mouse_controller-1.2.0/tests/test_windows_path.py +131 -0
  17. ai_virtual_mouse_controller-1.1.2/core/hand_tracker.py +0 -238
  18. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/LICENSE +0 -0
  19. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/ai_virtual_mouse_controller.egg-info/dependency_links.txt +0 -0
  20. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/ai_virtual_mouse_controller.egg-info/entry_points.txt +0 -0
  21. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/camera.py +0 -0
  22. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/click_burst.py +0 -0
  23. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/cursor_controller.py +0 -0
  24. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/finger_posture.py +0 -0
  25. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/gesture_detector.py +0 -0
  26. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/hand_anchor.py +0 -0
  27. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/hand_mesh.py +0 -0
  28. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/hand_renderer.py +0 -0
  29. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/hologram_gl_backend.py +0 -0
  30. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/hologram_overlay.py +0 -0
  31. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/perf_telemetry.py +0 -0
  32. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/presentation_controller.py +0 -0
  33. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/runtime_settings.py +0 -0
  34. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/settings_panel.py +0 -0
  35. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/smoothing.py +0 -0
  36. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/ui_overlay.py +0 -0
  37. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/core/utils.py +0 -0
  38. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/services/__init__.py +0 -0
  39. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/services/virtual_mouse_service.py +0 -0
  40. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/setup.cfg +0 -0
  41. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/tests/test_click_burst.py +0 -0
  42. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/tests/test_cursor_bottom_reach.py +0 -0
  43. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/tests/test_cursor_click_at.py +0 -0
  44. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/tests/test_gesture_detector.py +0 -0
  45. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/tests/test_hand_anchor_bottom.py +0 -0
  46. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/tests/test_hand_renderer.py +0 -0
  47. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/tests/test_hologram_overlay.py +0 -0
  48. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/tests/test_overlay_smoke.py +0 -0
  49. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/tests/test_perf_telemetry.py +0 -0
  50. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/tests/test_presentation_controller.py +0 -0
  51. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.0}/tests/test_settings_panel.py +0 -0
  52. {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.2.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.2.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,18 +18,20 @@ 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
34
+ Requires-Dist: numpy>=1.26.0
33
35
  Requires-Dist: moderngl>=5.10.0
34
36
  Requires-Dist: PySide6>=6.6.0
35
37
  Provides-Extra: hologram
@@ -51,11 +53,16 @@ Dynamic: license-file
51
53
 
52
54
  [![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
55
  [![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/)
56
+ [![Python](https://img.shields.io/badge/python-3.10--3.14-22d3ee?style=flat-square)](https://pypi.org/project/ai-virtual-mouse-controller/)
55
57
  [![License](https://img.shields.io/badge/license-MIT-22d3ee?style=flat-square)](LICENSE)
56
58
 
57
59
  Webcam → 21 landmarks → cursor do sistema. Sem hardware extra. Sem GPU.
58
60
 
61
+ **AI-powered virtual mouse controller for Windows, macOS, and Linux.** Control the
62
+ mouse cursor, left and right clicks, drag-and-drop, and presentations with real-time
63
+ hand gestures captured by a standard webcam. Built with Python, OpenCV, MediaPipe
64
+ Hands, and PyAutoGUI; runs locally without sending camera images to the cloud.
65
+
59
66
  <br/>
60
67
 
61
68
  <table>
@@ -78,23 +85,34 @@ Webcam → 21 landmarks → cursor do sistema. Sem hardware extra. Sem GPU.
78
85
 
79
86
  ## O que é
80
87
 
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.
88
+ 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
89
 
83
90
  100% local. Sem nuvem, sem telemetria, sem persistir nada da webcam.
84
91
 
85
- **Stack:** Python 3.11+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · ModernGL/PySide6 (opcional)
92
+ **Stack:** Python 3.10+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · ModernGL/PySide6 (opcional)
86
93
 
87
94
  ---
88
95
 
89
96
  ## Instalar
90
97
 
91
- Requer **Python 3.11 ou 3.12** + webcam.
98
+ Requer **Python 3.10 ou mais novo** (testado de 3.10 a 3.14) + webcam.
92
99
 
93
100
  ```bash
94
101
  pip install ai-virtual-mouse-controller
95
102
  avmc
96
103
  ```
97
104
 
105
+ > **Windows — "avmc não é reconhecido"?** O instalador novo do Python (padrão
106
+ > no 3.14) não põe a pasta `Scripts` no PATH. Rode uma vez:
107
+ >
108
+ > ```powershell
109
+ > py -m avmc
110
+ > ```
111
+ >
112
+ > O AVMC abre e adiciona essa pasta ao PATH do seu usuário (sem admin). A partir
113
+ > daí, num terminal **novo**, `avmc` funciona. Pra não mexer no PATH, defina
114
+ > `AVMC_NO_PATH_SETUP=1`.
115
+
98
116
  Posicione a mão a ~50cm da câmera. Atalhos em runtime:
99
117
 
100
118
  | Tecla | Ação |
@@ -134,6 +152,15 @@ Conferir a versão instalada:
134
152
  pip show ai-virtual-mouse-controller
135
153
  ```
136
154
 
155
+ Vindo da 1.1.2 ou anterior? O projeto trocou `opencv-python` por
156
+ `opencv-contrib-python` (mesmo `cv2`, usado pelo MediaPipe). Remova o antigo
157
+ pra os dois não disputarem a mesma pasta:
158
+
159
+ ```bash
160
+ pip uninstall -y opencv-python
161
+ pip install --force-reinstall --no-deps "opencv-contrib-python>=4.10,<5"
162
+ ```
163
+
137
164
  Se quiser pular o cache do pip e baixar do PyPI direto:
138
165
 
139
166
  ```bash
@@ -191,11 +218,11 @@ Ajustes em tempo de execução também ficam disponíveis no painel (tecla `S`)
191
218
  | OS | Setup adicional |
192
219
  |---|---|
193
220
  | 🪟 **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. |
221
+ | 🍎 **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`. |
222
+ | 🐧 **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
223
  | 🐧 **Linux (Wayland)** | Suporte limitado de PyAutoGUI. Recomendado mudar pra sessão X11. |
197
224
 
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.
225
+ > **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
226
 
200
227
  ---
201
228
 
@@ -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 · ModernGL/PySide6 (opcional)
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
@@ -146,11 +171,11 @@ Ajustes em tempo de execução também ficam disponíveis no painel (tecla `S`)
146
171
  | OS | Setup adicional |
147
172
  |---|---|
148
173
  | 🪟 **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. |
174
+ | 🍎 **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`. |
175
+ | 🐧 **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
176
  | 🐧 **Linux (Wayland)** | Suporte limitado de PyAutoGUI. Recomendado mudar pra sessão X11. |
152
177
 
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.
178
+ > **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
179
 
155
180
  ---
156
181
 
@@ -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.2.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,18 +18,20 @@ 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
34
+ Requires-Dist: numpy>=1.26.0
33
35
  Requires-Dist: moderngl>=5.10.0
34
36
  Requires-Dist: PySide6>=6.6.0
35
37
  Provides-Extra: hologram
@@ -51,11 +53,16 @@ Dynamic: license-file
51
53
 
52
54
  [![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
55
  [![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/)
56
+ [![Python](https://img.shields.io/badge/python-3.10--3.14-22d3ee?style=flat-square)](https://pypi.org/project/ai-virtual-mouse-controller/)
55
57
  [![License](https://img.shields.io/badge/license-MIT-22d3ee?style=flat-square)](LICENSE)
56
58
 
57
59
  Webcam → 21 landmarks → cursor do sistema. Sem hardware extra. Sem GPU.
58
60
 
61
+ **AI-powered virtual mouse controller for Windows, macOS, and Linux.** Control the
62
+ mouse cursor, left and right clicks, drag-and-drop, and presentations with real-time
63
+ hand gestures captured by a standard webcam. Built with Python, OpenCV, MediaPipe
64
+ Hands, and PyAutoGUI; runs locally without sending camera images to the cloud.
65
+
59
66
  <br/>
60
67
 
61
68
  <table>
@@ -78,23 +85,34 @@ Webcam → 21 landmarks → cursor do sistema. Sem hardware extra. Sem GPU.
78
85
 
79
86
  ## O que é
80
87
 
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.
88
+ 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
89
 
83
90
  100% local. Sem nuvem, sem telemetria, sem persistir nada da webcam.
84
91
 
85
- **Stack:** Python 3.11+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · ModernGL/PySide6 (opcional)
92
+ **Stack:** Python 3.10+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · ModernGL/PySide6 (opcional)
86
93
 
87
94
  ---
88
95
 
89
96
  ## Instalar
90
97
 
91
- Requer **Python 3.11 ou 3.12** + webcam.
98
+ Requer **Python 3.10 ou mais novo** (testado de 3.10 a 3.14) + webcam.
92
99
 
93
100
  ```bash
94
101
  pip install ai-virtual-mouse-controller
95
102
  avmc
96
103
  ```
97
104
 
105
+ > **Windows — "avmc não é reconhecido"?** O instalador novo do Python (padrão
106
+ > no 3.14) não põe a pasta `Scripts` no PATH. Rode uma vez:
107
+ >
108
+ > ```powershell
109
+ > py -m avmc
110
+ > ```
111
+ >
112
+ > O AVMC abre e adiciona essa pasta ao PATH do seu usuário (sem admin). A partir
113
+ > daí, num terminal **novo**, `avmc` funciona. Pra não mexer no PATH, defina
114
+ > `AVMC_NO_PATH_SETUP=1`.
115
+
98
116
  Posicione a mão a ~50cm da câmera. Atalhos em runtime:
99
117
 
100
118
  | Tecla | Ação |
@@ -134,6 +152,15 @@ Conferir a versão instalada:
134
152
  pip show ai-virtual-mouse-controller
135
153
  ```
136
154
 
155
+ Vindo da 1.1.2 ou anterior? O projeto trocou `opencv-python` por
156
+ `opencv-contrib-python` (mesmo `cv2`, usado pelo MediaPipe). Remova o antigo
157
+ pra os dois não disputarem a mesma pasta:
158
+
159
+ ```bash
160
+ pip uninstall -y opencv-python
161
+ pip install --force-reinstall --no-deps "opencv-contrib-python>=4.10,<5"
162
+ ```
163
+
137
164
  Se quiser pular o cache do pip e baixar do PyPI direto:
138
165
 
139
166
  ```bash
@@ -191,11 +218,11 @@ Ajustes em tempo de execução também ficam disponíveis no painel (tecla `S`)
191
218
  | OS | Setup adicional |
192
219
  |---|---|
193
220
  | 🪟 **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. |
221
+ | 🍎 **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`. |
222
+ | 🐧 **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
223
  | 🐧 **Linux (Wayland)** | Suporte limitado de PyAutoGUI. Recomendado mudar pra sessão X11. |
197
224
 
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.
225
+ > **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
226
 
200
227
  ---
201
228
 
@@ -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
@@ -28,6 +29,8 @@ core/settings_panel.py
28
29
  core/smoothing.py
29
30
  core/ui_overlay.py
30
31
  core/utils.py
32
+ core/windows_path.py
33
+ core/models/hand_landmarker.task
31
34
  services/__init__.py
32
35
  services/virtual_mouse_service.py
33
36
  tests/test_click_burst.py
@@ -36,9 +39,11 @@ tests/test_cursor_click_at.py
36
39
  tests/test_gesture_detector.py
37
40
  tests/test_hand_anchor_bottom.py
38
41
  tests/test_hand_renderer.py
42
+ tests/test_hand_tracker.py
39
43
  tests/test_hologram_overlay.py
40
44
  tests/test_overlay_smoke.py
41
45
  tests/test_perf_telemetry.py
42
46
  tests/test_presentation_controller.py
43
47
  tests/test_settings_panel.py
44
- tests/test_smoothing.py
48
+ tests/test_smoothing.py
49
+ tests/test_windows_path.py
@@ -1,7 +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
4
+ numpy>=1.26.0
5
5
  moderngl>=5.10.0
6
6
  PySide6>=6.6.0
7
7
 
@@ -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())
@@ -33,10 +33,10 @@ MAX_NUM_HANDS: int = 1
33
33
  MIN_DETECTION_CONFIDENCE: float = 0.6
34
34
  MIN_TRACKING_CONFIDENCE: float = 0.4
35
35
  MODEL_COMPLEXITY: int = 0
36
- """0=lite, 1=full.
36
+ """Sem efeito desde a migracao pra Tasks API do MediaPipe.
37
37
 
38
- Lite reduz inference em ~40-50% vs full sem perda perceptivel no pinch.
39
- Volta pra 1 se notar drop na deteccao em iluminacao ruim ou mao longe.
38
+ O HandLandmarker tem um unico modelo (equivalente ao antigo 1=full).
39
+ Mantido so pra nao quebrar configs existentes.
40
40
  """
41
41
 
42
42
  INFERENCE_PRE_RESIZE_ENABLED: bool = False
@@ -10,5 +10,5 @@ Versao do pacote vive em `__version__` e e' a fonte unica de verdade
10
10
 
11
11
  from __future__ import annotations
12
12
 
13
- __version__ = "1.1.2"
13
+ __version__ = "1.2.0"
14
14
  __all__ = ["__version__"]