video2threejs — Video → escena procedural Three.js
Reconstruye un video de referencia (salida de Seedance / Sora / Veo, o grabación) como una escena de Three.js exclusivamente con código y sin activos. El estándar es 1:1: cámara, la posición y proporciones de cada objeto, paleta, luz, apariencia de los personajes y la línea temporal de movimiento que siguen los personajes.
Reconstrucción mediante código — no NeRF, no video a malla, no paquetes de activos descargados. Habilidad hermana de img2threejs (un objeto o personaje a partir de una imagen); esta habilidad abarca una habitación completa con personas y tiempo.
Este archivo es el enrutador siempre cargado. Contiene el orden de las operaciones, las reglas estrictas con su fundamento, la definición de finalización y los antipatrones. El contrato completo para cada etapa reside en el archivo grimoire/ que las reglas nombran — léelo cuando llegues a esa etapa, no antes.
Cuándo usarlo
- El usuario comparte un video o un tuit con un video y pide reconstruir / replicar / "hacer esto en three.js".
- El usuario pregunta cómo modelar un objeto blando u orgánico específico de forma procedural (un edredón, almohadas, un peluche, pelo de anime, un gato).
- Una habitación o interior necesita ser reconstruido 1:1 a partir de grabaciones para un juego, un diorama, un homenaje interactivo.
No para: un solo objeto principal a partir de una sola imagen (usa img2threejs), o proyectos donde sea aceptable descargar activos GLB.
Entradas requeridas
- El video (URL mp4 / URL de tuit / archivo). Si es un tuit, obtén las variantes multimedia y descarga el mp4 720p.
- La tolerancia del usuario: "1:1" (predeterminado para esta habilidad) o "en el espíritu de".
- Un lugar para ejecutar un servidor de desarrollo que el usuario pueda abrir en un navegador.
Reglas estrictas
Cada regla a continuación se pagó con una repetición del trabajo en el caso práctico de la Habitación Azul. No son preferencias estilísticas.
1. Vista previa en vivo durante el esculpido
Inicia el servidor de desarrollo y abre la página para el usuario antes de modelar cualquier cosa. Escribe la escena en etapas que se recarguen en caliente (paredes → muebles → luz → personajes → movimiento → cámara de introducción). Coloca una etiqueta de etapa en una esquina de la página; enruta window.onerror a ella para que los errores en tiempo de ejecución sean visibles en la página.
Por qué: la retroalimentación es más barata en el momento en que aparece la pared incorrecta, no después de que toda la habitación esté amueblada alrededor de ella.
→ grimoire/build/live_preview.md
2. Analiza el video primero, desde varios ángulos
Extrae al menos 8 fotogramas de todo el clip. Para hechos espaciales (qué pared, qué esquina, qué se apoya sobre qué) lee un fotograma cuadriculado celda por celda; confirma cada hecho en un segundo fotograma; si la perspectiva aún no se resuelve, pide al usuario que dibuje las líneas de la esquina y el suelo en una captura de pantalla. Produce la hoja de hechos espaciales, el inventario de objetos, la paleta, las fichas de los personajes y la tabla de escenas de movimiento antes de escribir código.
Decide explícitamente, por toma, qué se mueve — el sujeto o la cámara. Equivocarse en esto es costoso: una toma animada como un lento avance resultó ser una cámara estática observando un brazo levantarse, y el brazo no tenía esqueleto.
Por qué: tres reconstrucciones seguras colocaron la ventana en el lugar equivocado; un boceto con lápiz rojo lo arregló.
→ grimoire/intake/multi_view_analysis.md, grimoire/intake/frame_extraction.md
3. Espacio antes que objetos; resuelve la cámara
Decide las paredes visibles y la esquina, establece el marco de coordenadas (pared izquierda x = LW, pared derecha z = RW), luego resuelve la cámara a partir de fracciones de puntos de referencia con forge/solve_camera.py. Solo entonces coloca los muebles.
Resuelve a partir de mediciones — posición en pantalla de los puntos de referencia y tamaño aparente — con forge/solve_camera.mjs, y restringe la elevación para que el solucionador no pueda elegir la rama incorrecta. Antes de perseguir un encuadre, comprueba si es posible en absoluto: dos tomas de una referencia compuesta a menudo no pueden coexistir a una escala (prueba de desigualdad triangular en el grimorio). Dilo, toma el encuadre coherente más cercano y sigue adelante.
Por qué: una cámara colocada por intuición hace que cada comparación posterior mienta; una imposible hace que mienta para siempre.
→ grimoire/space/perspective_solving.md
4. Mantén un contrato de diseño por escrito
Una línea por objeto: pared, posición, tamaño, relación, marco de referencia. Cada corrección del usuario edita primero el contrato, luego el código. El contrato es la única fuente de verdad para las posiciones utilizadas por los muebles, las poses y el solucionador de cámara.
→ grimoire/space/layout_contract.md
5. Los colores provienen de los píxeles
Muestrea parches iluminados y sombreados de cada objeto en el fotograma cuadriculado; elige colores base entre ellos, inclinándote hacia lo brillante. Nunca escribas un color de memoria.
→ grimoire/intake/frame_extraction.md
6. Luz real, diagnosticada, nunca pintada
Paredes sólidas con una abertura de ventana real; un techo que cubre exactamente el interior de la habitación; una rampa de dibujos animados cuyo escalón inferior es cero; un sol cálido con una cámara de sombra que cubre la habitación. Nunca finjas luz con parches de suelo pintados, planos volumétricos o partículas flotantes. Diagnostica con una renderización solo de sol directo (?diag=sun): las paredes y el techo deben ser negros, los parches deben caer donde dice la geometría.
→ grimoire/build/lighting.md
7. Esculpe objeto por objeto hasta 8/10
Antes de construir un objeto, enumera sus características de referencia (forma, posición, color, accesorios). Después de construirlo, toma una captura de pantalla desde una cámara de primer plano y puntúalo. No continúes por debajo de 8. Geometría sobre textura: un edredón es una sábana drapada, una estantería está abierta con libros reales, una almohada es gruesa y se inclina.
→ grimoire/build/procedural_recipes.md
8. Una malla, esculpida — nunca ensamblada
Una forma orgánica (una cabeza, una oreja, un torso, un miembro, una mano, una túnica) es una superficie cerrada moldeada moviendo sus propios vértices: abúlzala, húndela, extruye un miembro de una de sus caras, desplázala con un campo suave. No la construyas a partir de una esfera más un cono más una cápsula juntadas. Los orgánicos ensamblados producen, cada vez: una costura brillante que se mueve con la luz, un anillo de contorno alrededor de la parte enterrada, una pieza que se desprende cuando una articulación rota, un centelleo por z-fighting, un aspecto "transparente" de una sub-malla mal orientada, y una ruptura de sombreado que ningún ajuste de material puede eliminar.
Cuándo se aplica: cualquier cosa que comparta piel en la referencia debe compartir una malla en la construcción — una nariz es la cara empujada hacia adelante, una oreja es el cráneo elevado. Los objetos genuinamente separados (una lámpara, un libro, un poste, un marco de ventana) permanecen como primitivas separadas; los sólidos rígidos pequeños que se apoyan sobre una superficie y nunca se deforman (rizos de pelo, remaches, flores) son joyas instanciadas sobre la piel esculpida; las tiradas largas y delgadas son un solo tubo barrido, no una cadena de cápsulas.
Dos sustratos: un campo de desplazamiento sobre una primitiva subdividida densa (cabezas, formas casi esféricas), o una jaula de modelado de caja + Catmull-Clark, luego desplazamiento para el detalle (cuerpos, miembros, manos, ropa). Ambos dejan una sola piel, que es a lo que se vincula el esqueleto.
Por qué: cada orgánico ensamblado en la historia de este proyecto fue reconstruido como una malla al final, después de que las costuras se hubieran comido una ronda de revisión cada una.
→ grimoire/build/one_mesh_sculpting.md, grimoire/build/box_modelling.md
9. Razona primero, luego esculpe paso a paso, cada paso terminado
Antes de tocar la geometría, escribe la forma: el volumen base, qué características están elevadas, cuáles hundidas, cuáles son un cambio de pendiente, y en qué orden deben aplicarse — cada paso se construye sobre la superficie que dejó el anterior. Luego divide el trabajo en pasos que cada uno deje una superficie válida y comprobable (base en blanco → planos grandes → características primarias → secundarias → detalle fino), y termina cada paso antes de comenzar el siguiente: captura la pantalla, vuelca su perfil numérico, muéstralo, haz que sea aceptado. Una oscilación dejada en el paso 2 es irreparable en el paso 5 porque cinco campos ahora se asientan sobre ella. Nunca un paso cuyo resultado solo pueda juzgarse después de que llegue un paso posterior.
Por qué: la cabeza que fue esculpida borrón por borrón fue desechada dos veces; la misma cabeza esculpida como cara en blanco → hueco → ojos → boca → nariz, un visto bueno por flecha, fue aceptada.
→ grimoire/build/one_mesh_sculpting.md
10. Verifica la superficie con números, no con tus ojos
Vuelca un perfil a través de la superficie — la línea central de una cara, un carril a través de una palma, un anillo alrededor de una articulación — y comprueba que es monótono donde debería ser. Una meseta entre dos elevaciones se lee al ojo como una abolladura, y un brillo especular oculta ambas. Después de cualquier operación de jaula, cuenta también los bordes utilizados por ≠ 2 caras: distinto de cero significa una unión en T, y la subdivisión la representará como un pliegue duro.
→ grimoire/build/box_modelling.md, grimoire/build/one_mesh_sculpting.md
11. Sólidos cerrados, orientación correcta, una superficie cuando sea posible
Un tubo barrido a mano tiene dos órdenes de triángulos posibles y solo uno mira hacia afuera; el equivocado hace que FrontSide elimine la capa exterior, por lo que ves el interior del objeto — la figura se ve transparente y "mal cosida", y culparás al material. LatheGeometry es un tubo abierto. Las bolas de las articulaciones deben ser más grandes que los extremos del tubo que cubren. Prefiere un perfil continuo (cuello y torso en un solo barrido) a dos primitivas juntadas: "lo suficientemente dentro para que no pueda mostrarse" deja de ser cierto tan pronto como sus secciones transversales difieren o una articulación rota. Diagnostica con ?diag=flat (material opaco — todavía transparente significa geometría), ?diag=norm, luego ?off=<parte>.
Por qué: varias rondas de revisión se dedicaron al ajuste de materiales para un error de orden de índice de una línea.
→ grimoire/build/solid_geometry.md
12. Los shaders fallan en silencio — conecta el enlace de error primero
renderer.debug.onShaderError en la página, antes de escribir cualquier material personalizado. Un ShaderMaterial que falla al compilar no renderiza nada y registra solo en la consola. Luego conoce los silenciosos: modelMatrix existe solo en la etapa de vértice; pow(negative, 2.0) y smoothstep(hi, lo, x) son indefinidos en GLSL y producen NaN; un hash entero que se desborda a double antes de sus operaciones de bits está sesgado y aplana cada textura en la escena; un fresnel no puede hacer una atmósfera cuando la cámara roza el miembro.
→ grimoire/build/shader_traps.md
13. Investiga cuando no estés seguro
Si una construcción es desconocida (tela, pelo, un arco de lámpara), busca en los ejemplos de three.js, el foro y las habilidades hermanas, enumera hasta tres enfoques, elige el más controlable, cita la fuente y registra el hallazgo en grimoire/research/when_unsure.md. Verifica las matemáticas con node (orden de Euler, orígenes de geometría φ) en lugar de razonar sobre ello.
→ grimoire/research/when_unsure.md
14. El movimiento debe parecer humano
Orden de Euler raíz YZX; muslo negativo = hacia adelante, pantorrilla positiva = se pliega hacia atrás; en la espalda rx=-π/2, boca abajo añade rz=π, de lado añade rz=±π/2. La rotation.x de una cabeza está invertida respecto a la intuición — Rx(+t) mira hacia abajo. Especifica los gestos dramáticos como palma aquí, mirando hacia allá, dedos en esa dirección y resuélvelos con forge/solve_ik_arm.mjs, keyframéalos en secuencia con un término de continuidad para que las poses permanezcan en una rama e interpolen como un solo movimiento. Los puntos de ruta (via) dirigen a los personajes alrededor de los muebles. Las alturas al sentarse y acostarse se miden desde la parte superior del edredón. Registra las articulaciones y las cajas delimitadoras de cualquier personaje que "desaparezca". Captura la pantalla de cada escena.
Vincula la piel con segmentos rígidos y una bisagra corta (un diámetro de miembro de mezcla, un hueso de media rotación en la articulación, bucles de jaula abanicados en la articulación), y deriva cada eje de articulación en lugar de asumirlo — el eje de flexión de una muñeca es antebrazo × normalPalma, y construirlo sobre el eje de la bisagra del codo hace que la clave no haga literalmente nada. Los efectos que causa el personaje pertenecen al reloj del clip, no al de una toma.
→ grimoire/build/characters.md, grimoire/build/motion_timeline.md, grimoire/build/skinning_rig.md
15. Captura todo con pantallazos, luego auto-revísate
Chrome sin cabeza en la ruta de la GPU (segundos), viewport en la relación de aspecto del video, hstack contra el fotograma de referencia. Antes de entregar, escribe una tabla de auto-revisión puntuada con una lista de brechas y deja que el usuario elija el siguiente lote. "Mejorado" no es "terminado".
→ grimoire/review/verification.md, grimoire/review/self_review.md
16. La lista de "no" del usuario es permanente
Todo lo que el usuario rechaza va a grimoire/feedback/user_signals.md y nunca se reintroduce (partículas flotantes, luz pintada, ropa de cama de Lego, pelo fibroso, patas de perro, luz en las paredes…).
→ grimoire/feedback/user_signals.md
17. Despliega desde la raíz del proyecto
vercel --prod (o cualquier despliegue) solo desde el directorio del proyecto. Escribe el CLAUDE.md del proyecto con el marco de coordenadas, cámara, paleta, luz, hechos de objetos, parámetros de depuración y las listas del usuario.
→ grimoire/review/handoff.md
Pipeline
| Etapa | Hacer | Salida | Leer |
|---|---|---|---|
| 0 | Obtener el video, extraer fotogramas y una imagen cuadriculada | frame_*.jpg, grid_01.jpg | intake/frame_extraction.md |
| 1 | Análisis multiángulo | hoja de hechos, inventario, paleta, fichas de personajes, tabla de escenas | intake/multi_view_analysis.md |
| 2 | Espacio: paredes → marco → resolución de cámara → contrato de diseño | landmarks.json, CAM/LOOK/fov, contrato | space/* |
| 3 | Andamio con vista previa en vivo; esqueleto por etapas desde la plantilla | página en ejecución que el usuario observa | build/live_preview.md |
| 4 | Luz | agujero de ventana, techo, rampa, sol; ?diag=sun limpio | build/lighting.md |
| 5 | Objetos uno por uno; formas orgánicas como una malla esculpida, paso a paso | primeros planos por objeto ≥8/10, volcados de perfil | build/one_mesh_sculpting.md, build/box_modelling.md, build/procedural_recipes.md, build/solid_geometry.md, build/shader_traps.md |
| 6 | Personajes: esculpir → esqueleto → pesos → claves de gestos → línea temporal de movimiento | capturas de pantalla por escena, mapa de pesos, registro de IK | build/characters.md, build/skinning_rig.md, build/motion_timeline.md |
| 6b | Efectos volumétricos (fuego, tormenta, explosión), sincronizados con el clip | capturas de pantalla en órbita + dentro de la toma | build/volumetrics.md |
| 7 | UX de cámara: órbita, copiar/persistir, introducción | C/R, tomas de introducción verificadas | build/camera_ux.md |
| 8 | Verificar y auto-revisar; iterar con el usuario | comparaciones lado a lado, tabla puntuada | review/* |
| 9 | Desplegar y entregar | URL, proyecto CLAUDE.md | review/handoff.md |
Definición de terminado
- Comparación lado a lado con el fotograma de referencia: paredes, co…
…
[truncado para traducción]