CompleteCaptureX

Captura de movimiento (motion capture) de escritorio, local y sin nube: graba tu cuerpo con una webcam o un video, y lleva la animación a 3ds Max, Blender o Unity.

El problema

Probar una idea de animación suele exigir equipo caro, trajes con sensores o servicios en la nube. Para un prototipo, un corto personal o una práctica de animación, esa barrera no tiene sentido: lo que hace falta es capturar un movimiento aceptable con el hardware que ya tienes y seguir trabajando en tu programa 3D de siempre.

Lo que propone este programa

CompleteCaptureX es una herramienta pequeña y concreta: detecta el cuerpo, las manos y la cara con la cámara, guarda la captura en un formato propio abierto (JSON v1) y la convierte a los formatos que los programas 3D sí entienden (BVH, FBX con rig). No pretende sustituir a un sistema profesional de mocap; pretende que puedas pasar de una idea a un personaje moviéndose en una tarde, y que cada paso intermedio quede en archivos que puedes inspeccionar.

Características

• Captura en vivo (webcam) o desde video (mp4/avi/mov/mkv), y reproducción de capturas JSON.
• Detección de Pose (33), Manos (21+21) y Cara (468) con MediaPipe Tasks.
• Grabación de landmarks con timestamp, grabación de video mp4 y procesado de video en segundo plano.
• Suavizado temporal (EMA) con perfiles (default, euroone, aggressive, none).
• Exportación: JSON v1, BVH (16 articulaciones, cm, Y-up) y FBX con rig vía Blender.
• Importadores incluidos para 3ds Max (huesos nativos o puntos, sin Blender) y Unity (preview + bake a AnimationClip).
• Sección Ayuda integrada en la aplicación con el flujo y las guías de exportación.
• Distribución Windows de una carpeta, sin necesidad de Python instalado.

Cómo funciona

webcam / video  →  OpenCV  →  MediaPipe Tasks  →  landmarks (0..1)
      →  suavizado EMA  →  vista previa + grabación  →  JSON v1
JSON v1  →  BVH / FBX con rig / scripts de Max / Unity  →  retarget al personaje

El mundo de exportación es centímetros centrado: X=(x-0.5)·S, Y_up=(0.5-y)·S, Z=-z·S. La pose de reposo se calcula por mediana para tolerar frames vacíos al inicio.

Compatibilidad

Destino	Formato	Cómo
3ds Max	Huesos CCX_* (sin Blender)	Scripting > Run Script > docs/guia_3dsmax_retarget/scripts_max/import_capture_json.py
3ds Max	BVH	Export BVH → importar en CAT / Biped (Motion Capture) → retarget
3ds Max / Blender / Unity	FBX con rig CCX_Rig	Prepare for 3ds Max + Blender --mode armature
Blender	BVH o empties	Importar BVH directo, o --mode empties para depurar
Unity	FBX Humanoid/Generic	Importar el FBX (Scale 0.01 si está en cm); Unity no lee BVH de serie
Unity	Puntos / AnimationClip	integrations/unity/CompleteCaptureXImporter.cs en Assets/Editor

Tecnologías

• Python 3.11–3.14, PyQt6 (interfaz), OpenCV (video), MediaPipe 0.10+ Tasks (detección), NumPy.
• Empaquetado Windows con PyInstaller (script build.ps1 reproducible: tests + build + ZIP).
• Calidad: suite pytest (esquema JSON, exportador BVH, matemática de los conversores, ayuda).

Uso rápido

# 1. Entorno y ejecución
.venv/Scripts/python -m pip install -r requirements.txt
.venv/Scripts/python main.py

# 2. Tests
python -m pytest tests -q        # (o .venv/Scripts/python -m pytest)

# 3. Compilar distribución Windows
pwsh -NoProfile -File build.ps1  # genera dist/CompleteCaptureX + CompleteCaptureX_dist.zip

Flujo típico: abre la cámara → Start Recording → actúa → Export Recording → Export BVH (o Prepare for 3ds Max) → importa en tu programa 3D y haz retarget. La ayuda integrada (menú Ayuda) detalla cada botón y cada exportación.

Estructura del proyecto

main.py                 Interfaz y lógica de la app (+ menú Ayuda)
video_processor.py      Hilo de captura/procesado MediaPipe
storage.py              Esquema JSON v1 (carga, guardado, migración)
bvh_export.py           Exportador BVH + plantilla Blender (FBX con rig)
help_content.py         Textos de la ayuda integrada
drawing_utils.py        Dibujado de landmarks
scripts/                Descarga de modelos .task
integrations/unity/     Importador C# para Unity + guía
docs/guia_3dsmax_retarget/  Script de 3ds Max (rig/puntos) + guías
tests/                  Suite pytest (21 tests)
build.ps1               Build reproducible (tests + PyInstaller + ZIP)

Estado y futuro

El programa es funcional para su objetivo (capturar, previsualizar y exportar), pero hay margen honesto de mejora, entre otros: retarget automático al personaje final (hoy es manual), seguimiento de pies/suelo, más formatos de salida directa, y validación en más versiones de Max/Unity/Blender. Las limitaciones conocidas están documentadas en la ayuda (Solución de problemas) y en docs/. Cualquier aporte en esa dirección es bienvenido.