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.
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/PKG-INFO +46 -19
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/README.md +39 -12
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/ai_virtual_mouse_controller.egg-info/PKG-INFO +46 -19
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/ai_virtual_mouse_controller.egg-info/SOURCES.txt +18 -1
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/ai_virtual_mouse_controller.egg-info/requires.txt +3 -5
- {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
- ai_virtual_mouse_controller-1.3.0/avmc.py +15 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/config.py +74 -17
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/__init__.py +1 -1
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/camera.py +122 -25
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/cursor_controller.py +32 -16
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/gesture_detector.py +65 -40
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/hand_anchor.py +89 -5
- ai_virtual_mouse_controller-1.3.0/core/hand_gl_renderer.py +347 -0
- ai_virtual_mouse_controller-1.3.0/core/hand_mesh.py +501 -0
- ai_virtual_mouse_controller-1.3.0/core/hand_pose.py +217 -0
- ai_virtual_mouse_controller-1.3.0/core/hand_soft_renderer.py +262 -0
- ai_virtual_mouse_controller-1.3.0/core/hand_tracker.py +292 -0
- ai_virtual_mouse_controller-1.3.0/core/hologram_gl_backend.py +334 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/hologram_overlay.py +53 -4
- ai_virtual_mouse_controller-1.3.0/core/models/hand_landmarker.task +0 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/presentation_controller.py +3 -2
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/runtime_settings.py +24 -16
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/settings_panel.py +1 -1
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/smoothing.py +37 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/ui_overlay.py +2 -2
- ai_virtual_mouse_controller-1.3.0/core/windows_path.py +161 -0
- ai_virtual_mouse_controller-1.3.0/main.py +115 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/pyproject.toml +25 -18
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/services/virtual_mouse_service.py +212 -127
- ai_virtual_mouse_controller-1.3.0/tests/test_camera.py +118 -0
- ai_virtual_mouse_controller-1.3.0/tests/test_cursor_feel.py +92 -0
- ai_virtual_mouse_controller-1.3.0/tests/test_gesture_detector_behavior.py +200 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_hand_anchor_bottom.py +33 -0
- ai_virtual_mouse_controller-1.3.0/tests/test_hand_mesh.py +75 -0
- ai_virtual_mouse_controller-1.3.0/tests/test_hand_pose.py +111 -0
- ai_virtual_mouse_controller-1.3.0/tests/test_hand_renderers.py +98 -0
- ai_virtual_mouse_controller-1.3.0/tests/test_hand_tracker.py +139 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_hologram_overlay.py +3 -3
- ai_virtual_mouse_controller-1.3.0/tests/test_motion_quality.py +87 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_overlay_smoke.py +4 -2
- ai_virtual_mouse_controller-1.3.0/tests/test_runtime_settings.py +50 -0
- ai_virtual_mouse_controller-1.3.0/tests/test_service_camera_loss.py +59 -0
- ai_virtual_mouse_controller-1.3.0/tests/test_windows_path.py +131 -0
- ai_virtual_mouse_controller-1.1.2/core/hand_mesh.py +0 -794
- ai_virtual_mouse_controller-1.1.2/core/hand_tracker.py +0 -238
- ai_virtual_mouse_controller-1.1.2/core/hologram_gl_backend.py +0 -964
- ai_virtual_mouse_controller-1.1.2/main.py +0 -80
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/LICENSE +0 -0
- {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
- {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
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/click_burst.py +0 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/finger_posture.py +0 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/hand_renderer.py +0 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/perf_telemetry.py +0 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/core/utils.py +0 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/services/__init__.py +0 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/setup.cfg +0 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_click_burst.py +0 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_cursor_bottom_reach.py +0 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_cursor_click_at.py +0 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_gesture_detector.py +0 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_hand_renderer.py +0 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_perf_telemetry.py +0 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_presentation_controller.py +0 -0
- {ai_virtual_mouse_controller-1.1.2 → ai_virtual_mouse_controller-1.3.0}/tests/test_settings_panel.py +0 -0
- {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.
|
|
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:
|
|
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
|
|
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
|
|
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
|
[](https://github.com/ognistie/ai-virtual-mouse-controller/actions/workflows/ci.yml)
|
|
53
53
|
[](https://pypi.org/project/ai-virtual-mouse-controller/)
|
|
54
|
-
[](https://pypi.org/project/ai-virtual-mouse-controller/)
|
|
55
55
|
[](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
|
-
|
|
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.
|
|
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.
|
|
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 (
|
|
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 (
|
|
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
|
|
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
|
-
> **
|
|
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` (
|
|
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
|
-
|
|
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/
|
|
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
|
[](https://github.com/ognistie/ai-virtual-mouse-controller/actions/workflows/ci.yml)
|
|
8
8
|
[](https://pypi.org/project/ai-virtual-mouse-controller/)
|
|
9
|
-
[](https://pypi.org/project/ai-virtual-mouse-controller/)
|
|
10
10
|
[](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
|
-
|
|
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.
|
|
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.
|
|
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 (
|
|
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 (
|
|
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
|
|
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
|
-
> **
|
|
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` (
|
|
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
|
-
|
|
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/
|
|
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.
|
|
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:
|
|
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
|
|
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
|
|
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
|
[](https://github.com/ognistie/ai-virtual-mouse-controller/actions/workflows/ci.yml)
|
|
53
53
|
[](https://pypi.org/project/ai-virtual-mouse-controller/)
|
|
54
|
-
[](https://pypi.org/project/ai-virtual-mouse-controller/)
|
|
55
55
|
[](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
|
-
|
|
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.
|
|
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.
|
|
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 (
|
|
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 (
|
|
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
|
|
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
|
-
> **
|
|
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` (
|
|
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
|
-
|
|
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/
|
|
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
|
|
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
|
|
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())
|