rellytechgame/reverse3d-tool

---

Tabla de contenidos

• ⚡ Instalación en 1 minuto
• 🗣️ Úsalo con tu agente
• 🚀 GPU o CPU
• 💰 Ahorro de tokens
• 🔌 Sin internet (modo offline)
• 🤖 Piloto automático
• Capacidades
• Herramientas externas opcionales
• Referencia de la CLI
• Configuración
• Integración avanzada
• Stack tecnológico
• Arquitectura
• Seguridad
• 🔏 Autenticidad y autoría
• Solución de problemas
• Estructura del repositorio
• Desarrollo
• Hoja de ruta
• Sobre Voxel Enterprise
• Licencia

---

⚡ Instalación en 1 minuto

No necesitas instalar nada antes: ni Python, ni Git, ni permisos de administrador. Solo conexión a internet y unos 4 GB libres.

Opción 1 — Pídeselo a tu agente (recomendado)

Copia y pega esta frase en tu agente de IA (Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Copilot, Windsurf…):

Instala reverse3d desde https://github.com/rellytechgame/Reverse3D-tool siguiendo su AGENTS.md. Tienes mi permiso para ejecutar el instalador; no me hagas preguntas.

Eso es todo. Tu agente te pedirá permiso una sola vez, para ejecutar el instalador; acéptalo, por ejemplo con “Sí” o “Permitir siempre”. A partir de ahí no te preguntará nada más:

• instala Python, todos los módulos, Blender (renders fotorrealistas) y COLMAP (fotos → 3D);
• detecta tu tarjeta gráfica (GPU) y la usa si existe;
• conecta reverse3d con todos tus agentes de IA y deja sus herramientas aprobadas, para que no te pidan permiso en cada uso;
• comprueba que todo funciona.

Tarda entre 10 y 20 minutos según tu conexión. Al terminar, cierra y vuelve a abrir tu agente.

¿Quieres algo concreto? Dilo en la misma frase:

Instala reverse3d desde https://github.com/rellytechgame/Reverse3D-tool siguiendo su AGENTS.md, en modo ligero y usando solo CPU. Tienes mi permiso; no me hagas preguntas.

Opción 2 — Un comando en la terminal

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/rellytechgame/Reverse3D-tool/main/scripts/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/rellytechgame/Reverse3D-tool/main/scripts/install.ps1 | iex

Con opciones:

# Linux/macOS: GPU + calidad máxima
curl -fsSL https://raw.githubusercontent.com/rellytechgame/Reverse3D-tool/main/scripts/install.sh | bash -s -- --device gpu --profile quality

# Windows: GPU + calidad máxima
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/rellytechgame/Reverse3D-tool/main/scripts/install.ps1))) -Device gpu -Performance quality

¿Prefieres revisar el script antes de ejecutarlo? Descárgalo, léelo y ejecútalo: curl -fsSLO …/install.sh && less install.sh && bash install.sh.

Qué hace el instalador

Nunca hace preguntas y no necesita administrador. Si se interrumpe, por ejemplo porque el agente lo corta por tiempo, basta con volver a ejecutarlo: continúa donde se quedó.

1. Python: descarga uv y con él un Python 3.12 privado en ~/.reverse3d. No toca el Python de tu sistema; si uv no está disponible, usa un Python ≥ 3.10 que ya tengas.

2. Entorno aislado en ~/.reverse3d/venv.

3. reverse3d con todos los módulos:

   • mallado (Open3D);
   • render (PyVista);
   • IA de profundidad (PyTorch): con CUDA si hay GPU NVIDIA y, si no, la versión CPU, mucho más ligera.

   Si un módulo opcional falla, la instalación sigue y lo indica al final.

4. Blender 5.2 y COLMAP 4.2 portables en ~/.reverse3d/tools. Las versiones están fijadas y cada descarga se verifica con su huella SHA-256 oficial.

   • En Linux no existe un COLMAP portable: se instala con apt o brew solo si no hace falta contraseña. Si no se puede, el instalador lo indica y todo lo demás funciona.

5. Deja el comando reverse3d disponible: ~/.local/bin en Linux/macOS, PATH de usuario en Windows.

6. Ejecuta reverse3d setup, que registra el servidor MCP en todos los agentes que encuentre:

Cada archivo modificado se respalda antes (*.reverse3d-backup-). Solo se toca la entrada reverse3d y, si un archivo no se puede leer con seguridad (por ejemplo, JSON con comentarios), no se modifica y se muestra el bloque para pegarlo a mano.

Herramientas aprobadas de antemano, para que el agente no te pregunte en cada uso:

Solo se aprueban las herramientas de reverse3d, que trabajan únicamente dentro del workspace (ver Seguridad). Para desactivarlo usa --no-auto-approve.

7. Verifica todo con reverse3d doctor y guarda el resultado en ~/.reverse3d/install-status.json. El registro completo queda en ~/.reverse3d/install.log. Reinicia tu agente y listo.

Opciones del instalador

Opción 3 — Sin instalar nada (con uv)

Si tienes uv, cualquier cliente MCP puede ejecutar reverse3d directamente desde GitHub:

{
  "mcpServers": {
    "reverse3d": {
      "command": "uvx",
      "args": ["--from", "reverse3d[mcp,render] @ git+https://github.com/rellytechgame/Reverse3D-tool",
               "reverse3d", "agent", "mcp"],
      "env": { "REVERSE3D_WORKSPACE": "/ruta/a/mi-workspace" }
    }
  }
}

Opción 4 — Manual (desarrolladores)

git clone https://github.com/rellytechgame/Reverse3D-tool.git && cd Reverse3D-tool
python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\Activate.ps1
pip install -e ".[mcp,render]"                          # o ".[all]" / ".[dev]"
reverse3d setup                                         # registra en tus agentes
reverse3d doctor

---

🗣️ Úsalo con tu agente

Coloca tus archivos en el workspace (~/reverse3d-workspace) y habla normal:

“Convierte las fotos de taza/ en un modelo 3D y dime sus medidas.” “Este plano soporte.png mide 120 mm de ancho; sácame la pieza con 4 mm de espesor.” “Repara escaneo.stl, alinéalo y genérame el código OpenSCAD.” “Hazme un render de pieza.glb en azul metálico.” “Usa la GPU de ahora en adelante.” · “Cambia a modo rápido.”

Comandos / (prompts MCP)

En los clientes que muestran prompts MCP como comandos (Claude Code: /mcp__reverse3d__; Claude Desktop: menú + → reverse3d; también VS Code y otros):

Recetas: un flujo completo en una sola llamada

Desde la terminal: reverse3d run plan_to_part plano.png salida/ --thickness 4 --units-per-pixel 0.5.

---

🚀 GPU o CPU

reverse3d detecta tu GPU automáticamente: NVIDIA CUDA mediante nvidia-smi y Apple Silicon (MPS). Si pides GPU y no está disponible, pasa a CPU solo, sin fallar: por ejemplo, con un COLMAP compilado sin CUDA.

Los cambios desde el agente se aplican al instante, sin reiniciar: el servidor relee la configuración en cada llamada.

Perfiles de rendimiento

Cambia el perfil con “modo rápido”, rendimiento quality, reverse3d config set profile fast o --profile. Los argumentos explícitos de una herramienta siempre tienen prioridad sobre el perfil. Hilos de CPU: reverse3d config set threads 8.

---

💰 Ahorro de tokens

reverse3d está diseñado para gastar poco contexto del modelo:

*Flujo plano → pieza con 5 pasos medido en la v0.2.0, a ~4 caracteres por token. Cada ida y vuelta evitada ahorra además reenviar todo el historial de la conversación.

reverse3d config set toolset lean       # menos herramientas = menos tokens (reinicia el agente)
reverse3d config set verbosity full     # si alguna vez necesitas el detalle completo

---

🔌 Sin internet (modo offline)

reverse3d funciona sin conexión. Todo el cálculo es local (OpenCV, COLMAP, Open3D, trimesh, Blender). Lo único que se descarga es el modelo de IA de profundidad, y el instalador lo deja descargado.

• Cambio automático: si el equipo no detecta internet, reverse3d pasa solo a modo offline. No tienes que hacer nada.
• Comprobar: reverse3d offline status dice si hay conexión y qué funciona sin ella. reverse3d doctor lo incluye en su informe.
• Preparar a mano: reverse3d offline prepare descarga los modelos (solo safetensors, en una revisión fijada y revisada) en ~/.reverse3d/models. Usa --all para incluir también los modelos grandes CC-BY-NC.
• Forzarlo: reverse3d config set offline on, para no usar nunca la red. Con off reverse3d asume que hay conexión y no la comprueba; el valor por defecto es auto.

Tu agente de IA (Claude, Cursor, Copilot…) sí necesita internet. Sin agente, usa el piloto automático o la CLI.

🤖 Piloto automático

No hace falta elegir receta ni tener un agente. reverse3d detecta qué le das y lo procesa:

reverse3d auto bandeja/taza          # carpeta de fotos → modelo 3D medido
reverse3d auto plano.png             # plano o silueta → pieza extruida
reverse3d auto pieza.stl             # malla → reparación + cotas + CAD

O déjalo trabajando solo con la carpeta vigilada:

reverse3d watch

1. Suelta en ~/reverse3d-workspace/bandeja una carpeta de fotos, un plano, una foto o un STL/OBJ/PLY/GLB.
2. Cuando termina de copiarse, se procesa solo. El resultado aparece en resultados//, con un RESUMEN.md que explica qué detectó, las medidas, los archivos y el siguiente paso.
3. El original se mueve a bandeja/_procesado/. Si algo falla, va a bandeja/_revisar/ con un LEEME.txt que dice qué corregir.

Qué decide solo:

Si las fotos están borrosas o falta una herramienta, no reintenta en vano: te explica qué cambiar. Funciona sin internet y sin modelo de IA, porque son reglas, no adivinanzas.

---

Capacidades

Formatos: imágenes png jpg jpeg tif tiff bmp webp, y fotos de iPhone heic heif (se convierten a JPEG conservando el EXIF) · mallas stl obj ply glb gltf off · nubes ply xyz pcd.

Perfiles de escena: reverse3d predice si las fotos son de un objeto, un personaje, arquitectura o un paisaje (reverse3d scene detect ) y ajusta la reconstrucción; también puedes elegirlo con reverse3d auto --scene architecture.

¿Cómo tomar las fotos? Mínimo 20, recomendadas 40-60, en 4 perfiles (anillos a 10-20°, 35-45° y 60-70°, y 4 desde arriba), sin mover el objeto, con luz pareja y sin reflejos. Guía completa: docs/captura.md.

---

Herramientas externas opcionales

El instalador las instala solo (salvo --no-tools/--minimal). reverse3d funciona sin ellas, pero desbloquean más potencia. Comprueba en cualquier momento con reverse3d doctor o con el comando estado.

Si quieres usar un Blender o COLMAP propio: reverse3d config set blender "C:\Program Files\Blender Foundation\Blender 4.2\blender.exe" (igual con colmap).

---

Referencia de la CLI

reverse3d [--json] [--device auto|cpu|gpu] [--profile fast|balanced|quality] [--workspace DIR] 

Códigos de salida: 0 OK · 1 error · 2 entrada inválida o seguridad · 3 falta una dependencia · 4 falló COLMAP o Blender.

---

Configuración

Prioridad: valores por defecto ← ~/.reverse3d/config.json (reverse3d config set) ← variables de entorno.

reverse3d no necesita credenciales de ningún tipo.

---

Integración avanzada

• Function calling propio (SDK de Anthropic, OpenAI o Gemini): tool_definitions("anthropic" | "openai" | "gemini", toolset) + execute_tool(name, args, settings). Ver docs/agent-integration.md y el agente de ejemplo examples/claude_agent.py.
• Configuración MCP manual para cualquier cliente: reverse3d setup --snippets imprime el JSON o TOML exacto. Ver docs/mcp.md.
• Esquemas estáticos: docs/tools/.
• Agentes con terminal sin MCP: reverse3d --json agent call --args '{…}' (mismo sandbox).

---

Stack tecnológico

Arquitectura

flowchart LR
    U[Tú] -->|"lenguaje natural / comandos /"| AG[Agente de IA]
    AG -->|MCP stdio| MCP[mcp_server.pyherramientas + prompts]
    AG -->|shell| CLI[cli.py]
    MCP --> T[agent/tools.pyvalidación · sandbox · compactación]
    CLI --> T
    T --> R[recipes.pyflujos de 1 llamada]
    T --> D[vision · reconstruction · reverse_eng · rendering]
    R --> D
    D --> HW[hardware.pyGPU/CPU · perfiles]
    D --> SEC[security.py]
    SEC -->|sin shell| C[(COLMAP)]
    SEC -->|sin shell| B[(Blender)]

Detalle en docs/architecture.md.

Seguridad

• Sandbox de workspace: los agentes solo leen y escriben dentro de su carpeta; se resuelven symlinks y referencias internas de glTF/OBJ.
• Configuración por agente limitada: con reverse3d_configure el agente solo puede cambiar device, profile, verbosity y threads. Nunca el workspace, los límites ni la ruta de Blender o COLMAP, porque eso equivaldría a ejecutar código arbitrario.
• setup respetuoso: respalda cada archivo, solo toca la entrada reverse3d y nunca reescribe archivos que no puede leer con seguridad.
• Instaladores sin privilegios: sin sudo ni administrador, en un venv aislado y con validación de argumentos. Se puede fijar la versión con --ref.
• Procesos sin shell, con timeout y entorno sin secretos. Blender endurecido (--factory-startup --disable-autoexec, script estático).
• Modelos de IA: lista blanca, solo safetensors y trust_remote_code=False.
• CI: bandit, CodeQL, pip-audit, gitleaks, SBOM y actions fijadas por SHA.

Detalle en docs/security-model.md. Para reportar vulnerabilidades, consulta SECURITY.md.

🔏 Autenticidad y autoría

reverse3d fue creado por y es propiedad de Voxel Enterprise. El código es open source (Apache-2.0); la autoría y el nombre no se ceden.

• Repo oficial blindado: un guardián de autoría (scripts/check_authorship.py) bloquea en CI, en pre-commit y en los tests cualquier cambio de autor, licencia o copyright. CODEOWNERS exige la aprobación del propietario, y los agentes de IA tienen la regla explícita de no tocar la autoría (AGENTS.md §4).
• Releases verificables: solo se publican desde tags firmados, cada archivo lleva una atestación de procedencia (Sigstore) y PyPI usa Trusted Publishing. Para comprobar que tu copia es la oficial:

  gh attestation verify  --repo rellytechgame/Reverse3D-tool
  

• Copias y forks: están permitidos, pero deben conservar la atribución (Apache-2.0 §4, NOTICE) y usar otro nombre (TRADEMARKS.md). Presentarse como autor o dueño de reverse3d no está permitido.

Más detalles, cómo reportar suplantaciones y la lista de blindaje del propietario: docs/authenticity.md · Autores: AUTHORS.md

Solución de problemas

Estructura del repositorio

reverse3d/
├── AGENTS.md · CLAUDE.md · GEMINI.md   # Protocolo de instalación y uso para agentes de IA
├── scripts/install.sh · install.ps1   # Instaladores de 1 comando (Linux/macOS · Windows)
├── pyproject.toml · requirements.txt · policy.yaml
├── docs/                               # Arquitectura, MCP, agentes, seguridad, esquemas de tools
├── examples/                           # Agente Claude y demo de punta a punta
├── reverse3d/
│   ├── cli.py · recipes.py · autopilot.py · watch.py · offline.py · setup_agents.py · userconfig.py
│   ├── config.py · security.py · mesh_io.py · imaging.py · errors.py · doctor.py
│   ├── vision/ · reconstruction/ · reverse_eng/ · rendering/
│   └── agent/                          # tools.py · mcp_server.py · prompts.py · compact.py · skill/
└── tests/                              # 170+ tests (unitarios, seguridad, CLI, MCP, setup)

Desarrollo

pip install -e ".[dev]" && pre-commit install
pytest --cov=reverse3d
ruff format --check reverse3d tests && ruff check reverse3d tests && mypy reverse3d
bandit -c pyproject.toml -r reverse3d && pip-audit --skip-editable

Las normas y reglas de seguridad obligatorias están en CONTRIBUTING.md y AGENTS.md.

Hoja de ruta

• [ ] Visual hull multivista desde siluetas
• [ ] Reconstrucción feed-forward multivista (DUSt3R / VGGT) como alternativa a COLMAP
• [ ] Exportación STEP directa y ajuste de conos y toroides
• [ ] Comparación escaneo vs CAD (mapa de desviaciones)
• [ ] Publicación en PyPI (pipx install reverse3d) con Trusted Publishing
• [ ] Imagen Docker con CUDA para el servidor MCP

Sobre Voxel Enterprise

Voxel Enterprise es una empresa de desarrollo de software y soluciones tecnológicas con sede en Panamá, que da servicio a toda Latinoamérica:

• Desarrollo web a medida, orientado a conversión.
• Aplicaciones móviles para iOS, Android y multiplataforma.
• Diseño UI/UX, SEO y publicidad digital.
• VX Business: plataforma todo en uno para PYMES (CRM, contabilidad, RR. HH., nómina, reclutamiento, sucursales).
• IT outsourcing y staff augmentation: desde un especialista hasta un departamento de TI completo.

reverse3d es una contribución open source de Voxel Enterprise a la comunidad de ingeniería, manufactura e IA.

¿Integraciones a medida o soporte comercial? Contáctanos.

Licencia

Apache 2.0 © Voxel Enterprise. Ver LICENSE, NOTICE, AUTHORS.md y TRADEMARKS.md. Las redistribuciones deben conservar la atribución. Blender, COLMAP y los pesos de los modelos conservan sus propias licencias. Depth Anything V2 Base y Large son CC-BY-NC-4.0 (uso no comercial); el modelo por defecto, Small, es Apache-2.0.