# CaptureX

**Repository Path**: titd/CaptureX

## Basic Information

- **Project Name**: CaptureX
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-04
- **Last Updated**: 2026-10-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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.

![Ventana principal](docs/img/captura_ventana.png)

## 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.

![Reproducción de una captura JSON](docs/img/captura_reproduccion.png)
![Sección de ayuda integrada](docs/img/captura_ayuda.png)

## 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

```powershell
# 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.