luo-cccc/hyperframes-previs

Adaptador de previsualización descendente para storyboards HyperFrames

Versión de adaptación 0.4.0. Entrada STORYBOARD_PREVIS_ADAPTER_V1, validación de estado JSON SCOPED_STATE_V2; identidad de imagen PREVIS_RENDER_CONTENT_V2. Compila el guion formal entregado por script-to-storyboard-prompts en una previsualización 3D editable y revisable, sin cambiar el número de segmento original, el guion formal ni la versión de presupuesto. Three.js gestiona la escena y las acciones; HyperFrames exporta fotograma a fotograma.

Comenzar a trabajar

Primero lee references/upstream-adapter.md, localiza el proyecto upstream explícito del usuario, el segmento formal, la versión del guion formal válida y la versión de presupuesto; lee el texto real, el análisis de escenas, los activos de personajes/escenarios/utilería y los estados inicial y final del texto. La entrada puede ser un archivo de proyecto o una entrega de sesión localizable; no se puede exigir al upstream que produzca una tabla de diseño de storyboard independiente adicional.

Hereda la relación de aspecto confirmada, el estilo completo, el límite de duración del segmento, el tiempo real calculado, el orden de tomas, la altura en centímetros, la versión del diseño, la dirección espacial, el diálogo original, las responsabilidades de sonido y el momento de la revelación; no vuelve a preguntar por elementos ya confirmados, ni adopta el 16:9/12 segundos de demostraciones antiguas como valor predeterminado del proyecto. Si no se especifica la resolución de renderizado ni los fps, se puede elegir un tamaño par adecuado para esa relación de aspecto y 24 fps, registrándolos como parámetros técnicos de la previsualización; esto no puede cambiar el presupuesto ni añadir trama. Solo se preguntan de forma concentrada las carencias que afectan a esta adaptación.

Los siete pasos upstream y la cobertura de segmentos formales continúan siendo gestionados por el upstream. Este adaptador lee el estado autorizado, escribe sus propios archivos en <proyecto>/previs/<formal_id>/<prompt_version>/, y no modifica next_required, el cursor, la cobertura, el guion formal ni el presupuesto upstream. Cuando el usuario solo dice "continuar", se ejecuta según el objetivo actual del upstream; solo se activa cuando la solicitud actual incluye previsualización o ya se ha seleccionado explícitamente la entrega de previsualización. Dentro de una solicitud de previsualización autorizada, la lectura, construcción, verificación y exportación se pueden realizar de forma continua.

Soporta entregas de texto existentes del estado 1.8/V3 y proyectos JSON del 1.9/V4. El JSON se extrae de solo lectura con scripts/intake_storyboard.py; el texto libre/sesión es leído y organizado por el agente, usando scripts/finalize_manual_intake.py para sellar la evidencia real, sin migración automática ni adivinación de estados antiguos. La progresión normal de otros segmentos no invalida automáticamente el segmento objetivo; se readapta cuando cambia la versión de este segmento, los activos relacionados, los estados inicial/final o el texto original seleccionado. La ingesta del STATE_JSON antiguo, si carece de datos de alcance, se vuelve a extraer explícitamente, sin actualización silenciosa.

Utiliza la geometría más simple suficiente para verificar la composición, el bloqueo, la oclusión y el tiempo. La codificación de colores estable corresponde a los personajes upstream; el entorno solo conserva el espacio y los puntos de referencia relevantes; si se necesita una acción detallada, se conectan modelos con derechos de uso. Las responsabilidades de imagen, acción y cámara se separan; no se promete que una previsualización simplificada pueda forzar un seguimiento píxel a píxel del modelo descendente.

Creación y modificación

1. Recibir y mapear. Se heredan formal_id, prompt_version, budget_version, ID de activo, ID de toma e intervalo de tiempo del upstream. Los elementos "plano, posición de cámara", "movimiento de cámara y sujeto de grabación", "composición" y "contenido de la imagen" se convierten en escala geométrica, cámara, punto de mira y muestreo de tiempo absoluto; las coordenadas no especificadas se marcan como complemento ejecutado, sin redirigir la escena. Todas las tomas y tiempos de acción son relativos al segundo 0 del segmento formal actual; las fases de una sola toma no se dividen en cortes.
2. Construir un espacio unificado. Se usa sistema métrico, Y hacia arriba, indicando la orientación. Se establecen la escena, ID de personajes estables, pertenencia de utilería, puertas/ventanas como estructuras dinámicas. La apariencia de los personajes se diferencia con una codificación de colores clara; se proporciona escala geométrica para evitar adivinar proporciones solo por la imagen.
3. Crear animaciones deterministas. La pose, posición, cámara y estado de la puerta en cualquier fotograma deben estar determinados únicamente por t. No se permite usar desplazamiento acumulativo, números aleatorios no fijados ni el estado del fotograma anterior para impulsar la exportación. Los materiales de animación usan AnimationMixer.setTime(t) o un muestreo absoluto similar. El temporizador de reproducción del navegador solo puede llamar al mismo renderAt(t).
4. Verificar y ajustar. Se coteja el guion formal, los puntos de corte y los estados inicial/final toma por toma; se usa selección de imagen, línea de tiempo, observación libre, edición de cámara/FOV y puntos clave de trayectoria. La plantilla solo previsualiza la trayectoria de la toma actual, sin cambiar el número de tomas ni el presupuesto. Las tomas/bloqueos confirmados se pueden bloquear explícitamente; la deshacer local solo revierte la modificación conservada más reciente del objetivo correspondiente. Los cambios que afectan a hechos fotográficos formales, historia, duración, diálogo o revelación se devuelven al upstream para revisión; no se puede usar una plantilla para reemplazar la intención del director existente. Ver Edición y retroalimentación de imagen.
5. Verificar y exportar. Se realizan verificaciones de datos y fuentes, muestreo espacial del proxy, exportación real fotograma a fotograma, y se verifican las especificaciones del video, los estados inicial/final y los puntos de corte. Solo se verifica la entrada en cuadro para framing.requiredActors explícitamente indicado; las advertencias espaciales deben confirmarse con la imagen; no se reemplaza la aceptación del medio con un programa sin advertencias. Las anotaciones contienen el PNG real, el código de tiempo dentro del segmento, el ID del objeto, las coordenadas y la fuente; si la fuente cambia, se marca como caducada; lo procesado y lo aceptado se mantienen separados.
6. Devolver el producto adaptado. Se entrega un video limpio, el proyecto fuente, el mapeo fuente, una copia textual del guion formal original, notas adicionales de materiales de referencia y un comprobante de verificación real. El guion formal upstream o la adaptación de modelo existente continúa siendo la fuente de las indicaciones; no se reemplaza con indicaciones cortas generadas automáticamente por una plantilla. El comprobante solo representa la verificación local de previsualización; el envío final del modelo y la capacidad de generación siguen siendo gestionados por la adaptación del modelo correspondiente.

Punto de partida reutilizable

assets/starter/ es un ejemplo de ejecución que contiene una página de revisión, muestreo de tiempo absoluto, guardado y exportación. El pasillo, los personajes, la utilería, las tres tomas y el evento de apertura de puerta son contenido de demostración; al recibir datos del upstream, se reemplazan la geometría y las acciones según la entrada real; no se puede heredar automáticamente estos elementos de la trama. Si no hay imágenes, se pueden usar marcadores de color según el archivo de texto válido, verificando explícitamente solo el espacio y la secuencia.

node <skill-dir>/scripts/create_project.mjs <project-dir>
python -X utf8 <skill-dir>/scripts/intake_storyboard.py --state <estado_upstream_JSON> --budget <presupuesto_upstream_JSON> --formal-id FORMAL_1 --out <project-dir>/upstream-intake.json
cd <project-dir>
npm install
npm run prepare-libs

Después de leer el guion formal completo, se convierten los activos reales, las tomas y las acciones en scene.json y código de escena, escribiendo assetBindings, sourceAssetIds y adaptationMap. Luego se ejecutan los siguientes comandos de enlace y verificación; no se puede omitir el enlace para que el proyecto retroceda a la rama de demostración:

npm run bind-upstream
npm run validate
npm run studio

sourceAssetIds.scenes/props lista explícitamente los ID de activos realmente utilizados en este segmento; si no se usa ninguno, escribe []. Los personajes especifican la versión LOOK/STATE y la altura a través de assetBindings. Los valores numéricos, las versiones y las comprobaciones de dependencias no reemplazan la verificación semántica de la trama, el diálogo y la fotografía.

studio.html es para revisar, index.html para exportación limpia. Al hacer clic en un personaje se selecciona el objeto; al hacer clic en un espacio vacío se selecciona el punto de imagen. El guardado de una sola toma/punto clave no incluye otros borradores; los conflictos se señalan explícitamente. El bloqueo es forzado por el servidor; la deshacer local conserva 100 entradas de historial; los cambios externos en conflicto rechazan la sobrescritura. La captura primero guarda o descarta el borrador de la cámara, cambia a la cámara formal, oculta el marco de selección y alinea con el fotograma del video.

npm run lint
npm run spatial-check
npm run snapshot
npm run render
npm run handoff
npm run feedback
node scripts/bundle.mjs --project . --out <directorio_del_nuevo_paquete_fuera_del_proyecto>

Estos comandos están definidos en el package.json de la plantilla. Las dependencias están fijadas en HyperFrames 0.9.10 y Three.js 0.187.0 verificados; en entornos nuevos se pueden actualizar, pero primero se debe consultar la API oficial actual y luego repetir la exportación de verificación; no se puede solo cambiar el número de versión.

Los campos se detallan en Contrato de escena, las fuentes/revisiones en Adaptador upstream, y el bloqueo/deshacer/anotaciones/verificación espacial en Edición y retroalimentación de imagen. Consultar según sea necesario Entorno de ejecución de renderizado, Paquete de devolución y Paquete portátil. Los diseños externos adoptados y pospuestos se detallan en Fundamento de diseño; no es necesario tratar los repositorios externos como precursores de la producción.

Criterios de entrega

• Las acciones narrativas son reconocibles; los personajes/cámaras/utilería tienen una base de continuidad entre tomas. Se debe verificar realmente el eje, la oclusión y las penetraciones; si se cruza el eje intencionadamente, se explica con qué toma se establece la dirección.
• El mismo instante produce el mismo estado después de reproducción secuencial, salto directo y salto inverso; se verifica al menos un muestreo no secuencial, por ejemplo 8 → 2 → 8.
• El diálogo original y el tiempo de sonido se conservan completamente en el mapeo y el comprobante; cuando el sonido no está mezclado, los labios no están sincronizados o las acciones complejas no están implementadas, se escribe claramente como elementos no verificados. La entrega de indicaciones de activos, la existencia de imágenes, la lectura de imágenes y el enlace de modelos se registran por separado.
• El mismo segmento formal se exporta de forma independiente por defecto; la combinación de escenas o el empalme entre segmentos requiere una solicitud correspondiente, guardando un mapeo de desplazamiento. Los límites de archivo no se convierten automáticamente en cortes; no se repiten eventos del segmento anterior; no se alarga ni redondea el presupuesto; el material sobrante de fotogramas no enteros debe registrar explícitamente el mapeo entre el reloj fuente y el reloj de la película.
• La exportación utiliza los datos de la toma después de guardar. El primer fotograma está cargado completamente, sin fotogramas negros, recursos faltantes, interfaces de revisión intrusivas o residuos de puntos de corte.
• La exportación primero se almacena temporalmente y se verifica antes de publicar; si falla, se conserva el video exitoso anterior. El bloqueo, la escritura de historial y las anotaciones no cambian la identidad de la imagen; solo los cambios sustanciales en la cámara/trayectoria/modelo/código hacen que expire la evidencia de la imagen anterior. La revisión aún requiere cuatro elementos relacionados consistentes. VERIFIED en una anotación solo indica que el usuario ha registrado evidencia separada; no reemplaza la aceptación del medio del modelo final.
• La generación del modelo reinterpreta los materiales, las extremidades y los detalles. Se escribe claramente "la intención de composición y acción que debe conservarse" y "la actuación y textura permitidas para naturalizar", sin prometer control a nivel de píxel o esqueleto.
• El informe final indica claramente el alcance real de la ejecución y la verificación. Cuando no se proporciona referencia de personaje o no se ejecuta el modelo descendente, los personajes de bloque de color no se describen como verificación de consistencia de personaje, ni la salida de previsualización se describe como película final generada.