humanoidMotion-predictiveControl

Simulações de caminhada bípede para robôs humanoides, feitas para estudo: Pêndulo Invertido Linear (LIPM), ZMP, controle preditivo (MPC) e cinemática inversa analítica, em código curto e comentado.

Simulação	Robô	Gerador de caminhada	Simulador
mujoco_sim/	Robotis OP3 (modelo oficial)	Analítico (LIPM em forma fechada)	MuJoCo

📖 Teoria: docs/theory.md explica cada modelo e aponta onde ele está no código.

English summary

Bipedal walking simulations built for learning: Linear Inverted Pendulum (LIPM), ZMP, model predictive control (MPC) and analytical inverse kinematics, in short, commented Python.

• mujoco_sim/: Robotis OP3 in MuJoCo with an analytical LIPM walking pattern generator and 6-DoF analytical leg IK. Run python -m mujoco_sim and drive it with the arrow keys.
• docs/theory.md (Portuguese) derives every model and links each equation to the code. Code and comments are in English.

---

Instalação

Requer Python 3.10+:

git clone https://github.com/PedroH-Peres/humanoidMotion-predictiveControl.git
cd humanoidMotion-predictiveControl
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install -e ".[mujoco]"      # simulação MuJoCo
pip install -e ".[tools,dev]"   # gráficos e testes

---

mujoco_sim: OP3 com caminhada analítica

Física completa (contato, gravidade, atuadores PD) com o modelo oficial do Robotis OP3. O robot_descriptions baixa o MJCF automaticamente na primeira execução.

python -m mujoco_sim          # da raiz do repositório

No macOS, o viewer passivo do MuJoCo precisa ser iniciado com mjpython -m mujoco_sim.

Com a janela do viewer em foco:

Tecla	Comando
↑ / ↓	Andar para frente / para trás
← / →	Passo lateral para a esquerda / direita
PgUp / PgDn	Girar para a esquerda / direita
Home	Marchar no lugar
Delete	Parar (termina o passo atual)

Todas as letras já são atalhos do viewer do MuJoCo (wireframe, sombras, contatos…), por isso os comandos ficam nas setas e nas teclas de navegação. Para sair, feche a janela.

Configuração

Tudo em mujoco_sim/config.py:

Parâmetro	Efeito
FIELD_SIZE	Campo da RoboCup Humanoid League: "kid" (9 × 6 m) ou "adult" (14 × 9 m); None para chão liso sem campo e gols
BALL_SIZE, BALL_POSITION	Bola de futebol: tamanho FIFA 1 a 5 (raio de 7 a 11,25 cm, massa de 205 a 430 g) e posição inicial (x, y) no referencial do campo; BALL_SIZE = None remove a bola
RENDER_FPS	Taxa de atualização do viewer; vários passos de física rodam por quadro
PHYSICS	True: mj_step com física real. False: só cinemática (útil para depurar o gerador e o IK)
USE_TORSO_CTRL, TORSO_CTRL_PARAMS	Liga e ajusta o controlador PD que corrige o quadril a partir da inclinação do torso (IMU simulada)
WALK_PARAMS	Período do passo T, altura do torso z_com, altura do pé z_step, fração de apoio duplo ds_ratio, separação dos pés y_sep
KEY_COMMANDS	Velocidades associadas às teclas
ACTUATOR_KP/KV/FORCE_RANGE	Ganhos e limite de torque dos atuadores

Código

mujoco_sim/
├── sim.py                        # modelo MuJoCo, laço de simulação, teclado
├── config.py                     # todos os parâmetros
├── field.py                      # campo e gols da RoboCup (dimensões oficiais)
├── ball.py                       # bola de futebol (corpo livre com massa e amortecimento)
├── analytical_walking/
│   ├── trajectory_generator.py   # LIPM em forma fechada, pé em balanço, planejamento de passos
│   └── walking_engine.py         # máquina de estados da caminhada
├── kinematics/
│   └── ik_solver.py              # IK analítica 6-DoF da perna do OP3
└── control/
    └── torso_controller.py       # IMU simulada + PD de orientação do torso

---

Ferramentas e testes

python tools/plot_trajectories.py --vx 0.05      # CoM, ZMP e pés do gerador analítico
python tools/plot_trajectories.py --vy 0.03 --vx 0 --save lateral.png

pytest                    # todos os testes
pytest -m "not slow"      # pula as simulações físicas completas

Os testes conferem propriedades da trajetória (continuidade, pé nunca abaixo do chão, condições de contorno do LIPM), o IK contra a cinemática direta do MuJoCo e uma caminhada completa sem queda. Eles rodam no GitHub Actions a cada push.

---

Créditos

• O gerador de trajetória analítico é um port em Python do trajectory_generator.cpp do pacote ROS2 aurea_walk, com duas correções no perfil de pouso do pé (veja os comentários no código).
• O campo e os gols (mujoco_sim/field.py) são um port do RobocupSoccerField.proto e do RobocupGoal.proto do Webots (R2025a, Apache License 2.0). As linhas são caixas planas em vez da malha de triângulos do original, e a física do gramado (turfPhysics) não foi reproduzida.
• A bola (mujoco_sim/ball.py) usa só os parâmetros físicos do RobocupSoccerBall.proto do Webots (raio, massa e amortecimento). A malha 3D dele tem licença própria da Cyberbotics, restrita ao uso com o Webots, e por isso não foi copiada: a bola aqui é uma esfera com textura xadrez.
• Modelo do OP3: MuJoCo Menagerie, via robot_descriptions.

Licença

MIT. Use, modifique e redistribua à vontade, mantendo o aviso de copyright.