Motor Geométrico C++ + WebAssembly

Motor híbrido para procesar geometría 3D pesada con C++ y visualizarla en el navegador con Three.js.

🎯 Características

• ✅ Parser STL binario en C++ (archivos de 50+ MB)
• ✅ Cálculo de normales suaves para rendering profesional
• ✅ WebAssembly para near-native performance
• ✅ Visualización 3D con Three.js y smooth shading
• ✅ Arquitectura modular y escalable
• ✅ Compilación con Docker (sin ensuciar tu sistema)

🚀 Inicio Rápido

1. Prerrequisitos

• Docker Desktop (para compilar C++)
• Python 3 (para servidor local) o Live Server (extensión VS Code)

2. Ejecutar

# Modo todo-en-uno
.\start.bat

# Opción 1: Desarrollo (compila + servidor)
# Opción 4: Verificar que todo esté instalado

3. Usar

1. Abre http://localhost:8000/web
2. Presiona F12 para ver la consola
3. Arrastra un archivo STL o haz click en "Seleccionar archivo"
4. ¡Ver tu modelo 3D con smooth shading!

📁 Estructura del Proyecto

visor/
├── core/                      # Backend C++
│   ├── engine.cpp            # Punto de entrada WASM
│   ├── stl_parser.h          # Parser de formato STL
│   └── mesh_processor.h      # Cálculo de normales suaves
│
├── web/                      # Frontend JavaScript
│   ├── index.html           # Interfaz de usuario
│   ├── app.js               # Orquestación principal
│   ├── geometry_loader.js   # Comunicación con WASM
│   └── renderer.js          # Renderizado Three.js
│
├── build/                    # Generados por compilación
│   ├── engine.js            # Wrapper JavaScript
│   └── engine.wasm          # Código C++ compilado
│
├── Dockerfile               # Imagen Emscripten
├── Makefile                 # Configuración de compilación
├── start.bat               # Script principal (Windows)
└── README.md               # Este archivo

🔄 Flujo de Datos

Archivo STL (ej: 58 MB)
    ↓
JavaScript: FileReader → ArrayBuffer
    ↓
WASM: Transferencia de datos
    ↓
C++: STL Parser → Extrae triángulos
    ↓
C++: Mesh Processor → Calcula normales suaves
    ↓
WASM: Exporta arrays (vertices + normals)
    ↓
JavaScript: Lee HEAPF32
    ↓
Three.js: BufferGeometry + MeshPhongMaterial
    ↓
WebGL: Renderizado con smooth shading
    ↓
🎨 Modelo 3D profesional en el navegador

🛠️ Comandos Disponibles

Usando start.bat (Recomendado)

.\start.bat

# Menú interactivo:
# 1. Desarrollo (compila + servidor)
# 2. Solo compilar
# 3. Solo servidor
# 4. Verificar setup
# 5. Limpiar y recompilar

Comandos Directos

# Compilar C++ a WebAssembly
docker run --rm -v "%cd%":/src emscripten/emsdk make

# Iniciar servidor
python -m http.server 8000

# Limpiar build
make clean

🎨 Smooth Shading

El motor calcula normales suaves por vértice en C++ para lograr renderizado profesional:

Algoritmo

1. Parse STL: Extrae triángulos del archivo binario
2. Calcula normales de triángulos: Producto cruz de edges
3. Agrupa por vértices compartidos: Mapa de coordenadas → normales
4. Promedia normales: Suma y normaliza por vértice
5. Exporta a JavaScript: Arrays de vertices + normals
6. Renderiza con Three.js: MeshPhongMaterial + flatShading:false

Resultado: Superficie orgánica y profesional vs aspecto facetado.

Ver SMOOTH_SHADING.md para detalles técnicos.

📊 Rendimiento

Example File (TestModel.stl)

• Size: 58.38 MB
• Triangles: 1,224,222
• Vertices: 3,672,666
• Load time: < 1 second
• Parsing + normals: ~200ms
• FPS: stable 60fps

🐛 Troubleshooting

"Docker no está corriendo"

• Abre Docker Desktop y espera a que inicie
• Ejecuta .\start.bat → Opción 4 para verificar

"HEAPF32 no está disponible"

• Ejecuta .\start.bat → Opción 5 (Limpiar y recompilar)
• En el navegador: Ctrl + Shift + R (hard refresh)

"El modelo no se ve"

• Verifica la consola (F12) en busca de errores
• Asegúrate de que engine.js y engine.wasm existen en build/
• Prueba con un archivo STL pequeño primero

"Compilación muy lenta la primera vez"

• Normal: Docker descarga la imagen de Emscripten (~1.5 GB)
• Solo sucede una vez
• Siguientes compilaciones: ~10-15 segundos

🧪 Generar STL de Prueba

cd tools
python generate_test_stl.py
# Crea test_cube.stl (cubo simple)

O descarga archivos STL de:

• https://www.thingiverse.com/
• https://www.cgtrader.com/free-3d-models/stl

📚 Documentación

• SMOOTH_SHADING.md - Algoritmo de normales suaves
• build/README.md - Archivos generados por compilación

🔧 Tecnologías

Componente	Tecnología	Propósito
Parser STL	C++	Procesamiento rápido
Normales	C++	Cálculos matemáticos pesados
Compilador	Emscripten	C++ → WebAssembly
Containerización	Docker	Entorno reproducible
Visualización	Three.js	Renderizado 3D
Interfaz	HTML5 + ES6 Modules	UI moderna

🚧 Próximos Pasos Posibles

• OrbitControls (rotar con mouse)
• Materiales PBR (Physically Based Rendering)
• Ambient Occlusion
• Simplificación de malla (LOD)
• Operaciones booleanas
• Exportar STL procesado
• Cálculo de volumen
• Detección de errores en geometría

📝 Licencia

MIT

🤝 Contribuir

Este es un proyecto de aprendizaje demostrando integración C++/WASM/JavaScript.

---

Desarrollado con: C++17, WebAssembly, Three.js, Emscripten, Docker