Rastreamento de mãos SCS0009 (Demo oficial dora)

Esta página apresenta a cadeia oficial de rastreamento de mãos da versão com servos de barramento SCS0009: câmera → MediaPipe → MuJoCo IK → AHControl (Rust) → SCS0009. Para o rastreamento na versão PWM, veja Rastreamento de mãos PWM.

Os scripts 1 → 4 abaixo usam como exemplo os scripts de um clique para Windows, localizados em AmazingHand-main/Demo/Windows_Deploy_Scripts/; para a localização dos scripts e as diferenças no Linux e macOS, veja o final. Basta executar na ordem numérica.

---

Preparação do hardware

Hardware	Requisito
Corpo da mão dexterosa	Direita / Esquerda / Ambas
Placa driver de servos	Externa, USB para o PC
Alimentação	Fonte externa de pelo menos 5 V 4 A (ou entrada de 7–12 V conforme a placa driver); a alimentação pela USB não é suficiente
Câmera	Integrada ou webcam USB

Os arquivos de modelo podem ser visualizados ou baixados no Onshape (inclui URDF).

Modelo MuJoCo da mão dexterosa

---

Instalação do ambiente (script 1)

Dê um duplo clique em 1-Install_Env.bat; ele faz automaticamente:

1. Verifica as ferramentas de build do MSVC (cl.exe) — necessárias para compilar o Rust. Se faltarem, pede para instalar as Visual Studio 2022 Build Tools, marcar "Desenvolvimento para desktop com C++" e reabrir o terminal após a instalação.

2. Instala o Rust (rustup + toolchain stable-msvc)

3. Configura a mirror tuna do cargo (C:\Users\<seu usuário>\.cargo\config.toml) para acelerar o download de crates

4. Instala o uv (gerenciador de pacotes Python)

5. Instala o dora-cli 0.5.0 (cargo install; a primeira compilação leva cerca de 10~20 minutos, tenha paciência)

6. Instala o pacote pip dora-rs (opcional; também é instalado no ambiente virtual)

Importante: Feche e reabra o terminal após o script para que as variáveis de ambiente tenham efeito. Os downloads podem ser lentos dependendo da sua rede — aguarde, não interrompa.

Instalação manual (se o script não for utilizável)

• Rust: https://www.rust-lang.org/tools/install

  • No Windows, use o rustup-init.exe e o toolchain MSVC padrão

  • Variável de ambiente: adicione %USERPROFILE%\.cargo\bin ao PATH

• uv: no PowerShell, execute irm https://astral.sh/uv/install.ps1 | iex.

  • Variável de ambiente: adicione %USERPROFILE%\.local\bin ao PATH

• dora-cli: cargo install dora-cli --version 0.5.0

Configuração da mirror tuna do cargo (~/.cargo/config.toml)

[source.crates-io]
replace-with = "tuna"

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

[registries.tuna]
index = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

[http]
check-revoke = false

Use o índice sparse (acima), NÃO a mirror do repositório git — a mirror git primeiro baixa ~1 GB de índice e costuma travar em Updating 'tuna' index.

---

Ligação

• Conecte a placa driver de servos ao PC por USB, com fonte externa (pelo menos 5 V 4 A, ou entrada de 7–12 V conforme a placa driver)

• No PC, localize a porta: Gerenciador de Dispositivos → Portas (COM e LPT), por exemplo COM11

---

Configuração da porta serial (script 2)

Dê um duplo clique em 2-Setup_Serial.bat (a lógica está em 2-Setup_Serial.ps1):

1. Pede para conectar a placa driver de servos ao PC → pressione Enter para iniciar a detecção

2. Lista automaticamente as portas COM detectadas (com o nome do dispositivo)

3. Com uma única porta, pressione Enter para confirmar; com várias, digite o número

4. Grava automaticamente o --serialport nos 3 arquivos yml de dataflow e a porta padrão em AHControl\src\main.rs

5. Os arquivos originais são salvos automaticamente como backup em .bak

Se você reconectar o cabo USB, o número da porta pode mudar — execute este script novamente.

---

Implantação do código (script 3)

Dê um duplo clique em 3-Deploy_Demo.bat; ele faz automaticamente:

1. Inicia o daemon do dora (dora up)

2. Cria um ambiente virtual do Python 3.12 (uv venv --python 3.12)

3. Ativa o ambiente virtual

4. Compila o nó Rust AHControl (cargo build --release, cerca de 10 minutos na primeira vez)

5. Sincroniza as dependências de AHSimulation e HandTracking (uv sync)

6. Instala à força o mediapipe==0.10.14

Faça a implantação uma vez. Executar novamente pergunta se você quer reconstruir o ambiente virtual.

---

Executar o código (script 4)

Dê um duplo clique em 4-Run_Demo.bat; aparece um menu interativo:

============================================
   Selecione o modo de execução:
============================================
    1 - Simulação (rastreamento de mãos pela câmera)
    2 - Hardware real
    q - Sair
============================================
  Digite o número [1/2/q]:

• 1: ambiente de simulação, gestos da câmera acionam duas mãos simuladas

• 2: abre o submenu para escolher mão direita / esquerda / ambas

============================================
   Hardware real - selecione a mão dexterosa:
============================================
    1 - Mão direita
    2 - Mão esquerda
    3 - Ambas as mãos
    b - Voltar ao menu anterior
============================================

Depois da escolha, ele executa dora build + dora run. Uma janela da câmera se abre; faça gestos para a câmera e a mão dexterosa acompanha em tempo real. Ctrl+C para parar; após o fim do dataflow, pressione Enter para voltar ao menu principal e escolher outro modo, ou q para sair.

Na primeira execução, o Windows pode pedir permissão de câmera — clique em "Permitir".

---

Limpeza do projeto (script 0)

Dê um duplo clique em 0-Cleanup_Project.bat e digite Y para confirmar; ele limpa automaticamente:

1. Para o daemon do dora

2. Exclui os 3 ambientes virtuais (.venv)

3. Exclui a saída de compilação do Rust (AmazingHand-main/Demo/target)

4. Exclui pycache, os backups .bak, os logs e AmazingHand-main/Demo/out (diretório de logs do dora)

5. Restaura a porta padrão (--serialport /dev/ttyACM0), removendo resíduos de porta serial desta máquina

Após a limpeza, você pode copiar a pasta AmazingHand-main inteira para outra máquina — limpa e portátil. Na nova máquina, basta executar 1 → 2 → 3 → 4 na ordem.

---

Diferenças entre Linux e macOS

Os scripts de um clique também têm versões para Linux e macOS, nos diretórios AmazingHand-main/Demo/Linux_Deploy_Scripts/ e AmazingHand-main/Demo/Mac_Deploy_Scripts/. O fluxo dos passos 1–4 é o mesmo do Windows; abaixo listamos apenas as diferenças de cada sistema.

Permissão de execução dos scripts (Linux / macOS)

Ao copiar do Windows ou de um arquivo compactado, o bit de execução +x dos scripts se perde; antes da primeira execução, rode:

cd "AmazingHand-main/Demo/Linux_Deploy_Scripts"   # no macOS, troque para Mac_Deploy_Scripts
chmod +x *.sh

Depois, execute com ./nome_do_script; não use bash nome_do_script, pois isso pula os avisos interativos dentro do script.

Linux (Ubuntu)

• Permissões da porta serial: sudo usermod -aG dialout $USER, faça logout e login novamente; temporariamente, use sudo chmod 666 /dev/ttyACM*.
• Nome do dispositivo: /dev/ttyUSB* (CH340 / CP2102) ou /dev/ttyACM* (USB serial embutida).
• Câmera: Configurações → Privacidade → Câmera, permita o acesso de aplicativos; confirme que nenhum outro programa está usando a câmera.
• Máquina virtual: conecte primeiro a câmera USB à VM; se o OpenCV reportar can't open camera by index ou select() timeout, troque o controlador USB para 2.0 / 3.1 nas configurações da VM e reinicie; se necessário, sudo usermod -aG video $USER.
• Caminhos em chinês: use caminhos em inglês no projeto sempre que possível, para evitar falhas do MuJoCo / MediaPipe ao carregar modelos.

macOS

• Porta serial: use /dev/cu.*, não /dev/tty.*; veja o nome do dispositivo com ls /dev/cu.*.
• Permissões da porta serial: sudo chmod 666 /dev/cu.usbmodem*, ou permita o terminal em «Ajustes do Sistema → Privacidade e Segurança → Monitoramento de entrada».
• Câmera: na primeira execução, permita que o terminal acesse a câmera; também é possível alterar em «Ajustes do Sistema → Privacidade e Segurança → Câmera».
• Apple Silicon: é normal que a primeira compilação das dependências do dora com cargo build seja lenta; se aparecer «não foi possível verificar o desenvolvedor», clique em «Abrir mesmo assim» em «Privacidade e Segurança».

Instalação manual (sem os scripts de um clique)

Se os scripts não estiverem disponíveis, faça a implantação manual seguindo a Demo oficial:

1. Obter o código: clone o repositório ou baixe AmazingHand.zip e entre em AmazingHand-main/Demo/.

   

2. Instalar o ambiente: Rust (rustup), uv, dora-cli; reabra o PowerShell/Bash para que o PATH tenha efeito. Detalhes em Instalação do ambiente (script 1).

3. Criar o ambiente e instalar as dependências:

   uv venv --python 3.12
   # Windows: .venv\Scripts\activate
   # Linux/macOS: source .venv/bin/activate
   
   cd AHControl
   cargo build --release
   cd ..
   cd AHSimulation
   uv sync
   cd ..
   cd HandTracking
   uv sync
   cd ..

   

4. Configurar a porta serial: edite o --serialport em dataflow_tracking_real_right.yml / _left.yml / _2hands.yml, trocando pela porta COM real ou por /dev/ttyUSB0, /dev/cu.usbserial-*.

   

   

5. Compilar e executar:

   # simulação
   dora build dataflow_tracking_simu.yml --uv
   dora run dataflow_tracking_simu.yml --uv
   
   # hardware real (mão direita; troque o nome do arquivo para esquerda/ambas)
   dora build dataflow_tracking_real_right.yml --uv
   dora run dataflow_tracking_real_right.yml --uv
   
   # exemplo simples de ângulo
   dora build dataflow_angle_simu.yml --uv
   dora run dataflow_angle_simu.yml --uv

   

   

6. Problemas comuns: o mediapipe precisa da versão 0.10.14 (Python 3.12); se a versão do dora for incompatível, alinhe conforme o pyproject.toml/logs; se faltar o OpenCV, instale opencv-contrib-python; permissões de câmera, passthrough USB na máquina virtual e caminhos em chinês afetam o carregamento dos modelos. Para o diagnóstico detalhado, veja Perguntas frequentes e observações.

Para a documentação mais detalhada da Demo oficial, veja AmazingHand-main/Demo/README.md; os passos de implantação em um clique de cada sistema já foram incorporados a esta página.

Descrição da estrutura do código

Diretório Demo

AmazingHand-main/Demo/
├── AHControl/                nó Rust: controla os servos pela serial; em config/ ficam IDs e deslocamentos dos servos
├── AHSimulation/             nó Python: simulação MuJoCo e cinemática inversa
├── HandTracking/             nó Python: reconhecimento de landmarks da mão com MediaPipe
├── dataflow_*.yml            orquestração de dataflow do dora
├── Windows_Deploy_Scripts/   scripts de implantação em um clique para Windows
├── Linux_Deploy_Scripts/     scripts de implantação em um clique para Linux
├── Mac_Deploy_Scripts/       scripts de implantação em um clique para macOS
└── docs/                     tutoriais oficiais de implantação em vários idiomas

Correspondência dos dataflows

Arquivo de dataflow	Finalidade
dataflow_tracking_simu.yml	rastreamento de gestos pela câmera, aciona apenas as mãos simuladas no MuJoCo
dataflow_tracking_real_right.yml	rastreamento de gestos pela câmera, aciona a mão direita real
dataflow_tracking_real_left.yml	rastreamento de gestos pela câmera, aciona a mão esquerda real
dataflow_tracking_real_2hands.yml	rastreamento de gestos pela câmera, aciona as duas mãos ao mesmo tempo
dataflow_angle_simu.yml	envia ângulos de junta diretamente, para validar a simulação e a cinemática inversa

Princípio do dataflow

câmera → HandTracking (detecção de gestos com MediaPipe)
              ↓ coordenadas dos landmarks da mão
         AHSimulation (simulação MuJoCo + cinemática inversa)
              ↓ ângulos-alvo das juntas
         AHControl (serial → placa driver de servos → mão dexterosa)

Locais de configuração da porta

• A linha args: dos 3 arquivos dataflow_tracking_real_*.yml: --serialport COMxx

• default_value = "COMxx" em AHControl\src\main.rs (valor padrão do parâmetro serial)

• AHControl\config\*.toml: modelo do servo, IDs, deslocamentos (normalmente não precisa alterar)

---

Perguntas frequentes e observações

1. cargo travado em Updating 'tuna' index

• Causa: a mirror foi configurada no modo repositório git (.../git/crates.io-index.git), e a primeira execução baixa um índice de 1 GB+

• Solução: defina C:\Users\<seu usuário>\.cargo\config.toml com o índice sparse (veja «Configuração da mirror tuna do cargo» acima), ou execute 1-Install_Env.bat novamente

2. mediapipe sem o submódulo solutions / instalação quebrada

uv pip uninstall mediapipe

uv pip install mediapipe==0.10.14

• Execute com o ambiente virtual ativado (no diretório Demo)

• O 3-Deploy_Demo.bat já faz isso automaticamente como fallback

3. Incompatibilidade de versão do dora (message v0.8.0 vs v0.7.0)

• Sintoma: version mismatch: message format v0.8.0 is not compatible with expected message format v0.7.0

• Causa: a versão do dora-cli difere da do dora-node-api. Ambas devem ser 0.5.0

  • Verificação: dora --version deve imprimir dora-cli 0.5.0 e dora-message: 0.8.0

  • Correção: cargo install dora-cli --version 0.5.0 --force

  • Se houver vários dora no PATH (por exemplo, uma versão antiga em C:\Users\<seu usuário>\.dora\bin), garanta que .cargo\bin venha primeiro ou exclua a versão antiga

  

  

4. Falha ao carregar modelos do MuJoCo / mediapipe (caminhos em chinês)

• Sintoma: ParseXML: Error opening file '...\scene.xml' ou Can't find file: ....tflite

• Causa: os carregadores C++ do MuJoCo 3.x / mediapipe não abrem caminhos absolutos com caracteres chineses no Windows (por exemplo, D:\中文目录...)

• Este projeto já inclui correções:

  • AHSimulation\AHSimulation\mj_mink_*.py muda o diretório de trabalho antes de carregar

  • HandTracking\mediapipe_patch.py usa caminhos curtos 8.3 + caminhos relativos

• Não exclua esse código de correção

5. Permissão da câmera

• Na primeira execução, escolha "Permitir" na janela

• Configurações → Privacidade → Câmera → permitir aplicativos de desktop

  

  

  

6. O número da porta muda a cada vez

• Após reconectar o USB, o número da COM pode mudar — execute 2-Setup_Serial.bat novamente

7. OpenCV ausente

python -m pip install opencv-contrib-python numpy mediapipe -i https://mirrors.aliyun.com/pypi/simple/

(no diretório HandTracking, com o ambiente virtual ativado)

---

Páginas relacionadas

• Início rápido com SCS0009
• Controle web SCS0009
• Depuração e calibração de servos SCS0009
• Rastreamento de mãos PWM