timeqsz/motion-atoms

Motion Atoms

Permite al agente generar animaciones según una descripción, así como desglosar acciones y composiciones reutilizables a partir de videos de referencia. El agente observa, comprende el propósito y orquesta las animaciones; los átomos, validadores y herramientas de renderizado del paquete se encargan de la ejecución. El usuario no necesita elegir efectos de antemano ni recordar nombres de átomos. El paquete incluye 53 átomos bidimensionales organizados en 8 familias, con implementación compartida con el sitio web. Utiliza rutas relativas para acceder a los recursos del paquete, sin depender del sitio web en línea, del repositorio de código fuente ni de la instalación de npm. Para la instalación inicial, consulta Instalación y entorno; el archivo manifest.json registra la versión del paquete, los archivos y sus valores de verificación.

Lee según la tarea, no cargues todo el directorio de una vez

Tarea	Lee primero	Luego utiliza
Generar según descripción, o modificar un efecto existente	Ciclo de generación y modificación	Mapeo de intenciones
Desglosar un video de referencia, o analizar cómo se implementa una acción	Desglose de animaciones de video	Según las observaciones, consulta la lista de átomos y su uso; utiliza breakdown para extraer fragmentos del video original; separa las pistas por tipo de animación, con separación clara entre pistas, y resalta de forma independiente los bloques de acción sin texto en la misma pista
Animaciones 2D de texto, gráficos y propiedades	Catálogo 2D, filtrar solo las familias necesarias	atoms/<ID>.md y el correspondiente .mjs; Convenciones de entrada y salida
Exportar archivos de素材 2D	Orquestación de escenas	scripts/motion.mjs; para campos precisos, consulta MotionSpec
Reparar bloqueos, desplazamientos, occlusiones o ilegibilidad	Verificación de tiempo e imagen	Repara los problemas reales y luego verifica los fotogramas y la reproducción afectados

Al crear, primero define el anfitrión, el formato, la frecuencia de cuadros, el sujeto objetivo y el entregable; al desglosar, primero confirma el video visible, el alcance y el propósito del análisis, conservando los códigos de tiempo originales. Respeta las decisiones ya tomadas por el usuario. Los nombres, parámetros y comportamientos de las animaciones se rigen por la documentación del paquete.

Entrega los resultados que el usuario solicita, no solo recomiendes átomos candidatos; para modificaciones de resultados existentes, conserva el archivo original y verifica los cambios reales. El comando deliver en 2D puede empaquetar una vista previa independiente, una escena editable, recursos y un informe de verificación; el informe no debe confundir la validación numérica con la inspección visual. Cuando una capacidad esté más allá de lo implementado, indica la brecha y luego utiliza la implementación del anfitrión que realiza la llamada; no se debe presentar un efecto similar como si ya cumpliera con los requisitos.

Núcleo de la creación

• Primero el propósito, luego la acción. La combinación debe mostrar un producto, evento o cambio de estado claro; cada átomo debe poder explicar su función. Toma como referencia el sujeto, el ritmo y la transición de PV reales; después de verlos realmente, refina el método, sin copiar las imágenes ni usar iconos irrelevantes, controles falsos o movimientos decorativos para aumentar la cantidad. Los clips cortos del sitio web duran aproximadamente 5 segundos y usan 2–3 átomos; esto no es una limitación de duración ni cantidad para todos los videos.
• Orquesta cambios, no decore pósters con efectos. Primero organiza lo principal y lo secundario, luego describe claramente la entrada, los cambios, el asentamiento y la salida; las acciones deben tener una relación causal o visual de continuación, y los cambios clave deben ser visibles de un vistazo. Cada grupo debe usar un método de entrada y salida adecuado para el sujeto; después de que el texto se detenga, deja suficiente tiempo para leer; elimina el texto pequeño e inútil en los bordes.
• El movimiento debe ser completo y continuo. No lo cortes prematuramente ni lo reproduzcas en reversa de manera uniforme; al cambiar de plano, considera la posición, la dirección, la velocidad y el brillo. Diseña por separado las acciones finitas y los bucles continuos; verifica el principio y el final reales del bucle; no uses interpolación de fotogramas ni aumentes la frecuencia de cuadros nominal para ocultar pausas.
• El sujeto como un todo. Imágenes, logotipos y marcas comparten las coordenadas y los ejes de pivote correctos; las máscaras reales y el orden de dibujo determinan la oclusión. Al entrar y salir, verifica el grupo completo de texto y detalles; no dejes que solo el fondo se mueva; verifica la alineación, la nitidez y el recorte en el formato y tamaño de visualización reales.
• Los materiales sirven a la acción. Elige materiales gratuitos para uso comercial que coincidan con el propósito y tengan licencia rastreable; maneja las atribuciones y la distribución de archivos fuente según la licencia; no uses el mismo material para llenar diferentes casos. Controla el tamaño de carga de los materiales; cuando el sitio web y el video promocional hagan referencia a la misma escena, sincroniza los materiales y el movimiento.
• Acepta con la salida real. Para páginas web, verifica la reproducción real y el tamaño objetivo; para videos, primero haz un storyboard, luego renderiza fotograma por fotograma, compón el video, verifica la entrada/estado estable/salida/unión después de la codificación y reproduce completamente. No afirmes que una parte no vista ha sido verificada; entrega los resultados reproducibles junto con el alcance de la verificación. Para verificaciones técnicas específicas, consulta Verificación de tiempo e imagen.

2D: Integración en el anfitrión de renderizado

Copia solo los archivos .mjs necesarios; cuando necesites dibujar, copia también atoms/draw.mjs. Los átomos se evalúan según fotogramas explícitos y no tienen reproductor propio. El anfitrión controla el orden de dibujo, las coordenadas y el tiempo. Las ocho familias responden a una pregunta cada una: propiedades (qué cambia), ritmo (cómo cambia), bucle (se mueve constantemente), orquestación (quién va primero), transición (aparece/desaparece), texto (cómo se mueve el texto), textura (se superpone), generación (aparece de la nada).

import move from './atoms/prop.move.mjs';
import spring from './atoms/timing.spring.mjs';
import breathe from './atoms/loop.breathe.mjs';
import { drawAtom } from './atoms/draw.mjs';

const subject = { points: [[-50,-50],[50,-50],[50,50],[-50,50]], closed: true, fill: true };
const curve = (t) => spring({ frame: t, durationFrames: 1 }).value;   // ritmo: solo la curva
function renderFrame(ctx, frame) {
  const shape = move({ frame, durationFrames: 30, subject, params: { fromPx: -200, toPx: 0 }, ease: curve });
  const breath = breathe({ frame, startFrame: 30, durationFrames: 90 });   // bucle: se superpone
  drawAtom(ctx, { ...shape, scale: shape.scale * breath.scale }, { x: 320, y: 200, color: '#f4f1ea' });
}

• En las funciones independientes, params puede incluir solo los cambios; en MotionSpec clips, los parámetros deben estar completos. No mezcles estas dos convenciones.
• Al combinar, primero verifica el rol y writes: desplazamiento y ángulo se suman, escala, opacidad y estiramiento se multiplican, los filtros se concatenan; los átomos de orquestación devuelven copies, y el anfitrión dibuja cada copia según el desplazamiento y el retardo. La salida de un contorno de sujeto no puede superponer dos layers mediante la extensión de objetos.
• En MotionSpec, las animaciones de la misma propiedad no pueden superponerse en el tiempo, pueden encadenarse; el valor final de la primera debe coincidir con el valor inicial de la siguiente. El ritmo, el bucle, la orquestación y la textura se superponen. La exportación de archivos no utiliza automáticamente la estrategia de reproducción en bucle del sitio web.
• Las coordenadas gráficas son relativas al origen del sujeto; la posición del texto es la línea base izquierda de la primera línea. Las fuentes del dispositivo (system, mono) se pueden usar directamente; solo se necesitan fuentes fijas para una precisión exacta entre máquinas.
• Ejemplo mínimo ejecutable: atoms/example.html, con arreglo × desplazamiento × desplazamiento × muelle.

2D: Entrega de archivos de materiales

Los siguientes comandos se ejecutan dentro del directorio motion-atoms/ descomprimido; la salida se escribe en el directorio de trabajo del usuario. Antes de exportar, verifica si el navegador/FFmpeg local están disponibles según sea necesario; no solicites estas herramientas durante una búsqueda básica.

node scripts/motion.mjs describe transition.slices
node scripts/motion.mjs scaffold transition.slices --out work/slices.scene.json --width 1920 --height 1080 --fps 30 --duration 60
node scripts/motion.mjs validate work/slices.scene.json
node scripts/motion.mjs frames work/slices.scene.json --out work/check --frames 0,20,40,59 --transparent
node scripts/motion.mjs render work/slices.scene.json --out work/slices.mov --transparent

Se puede usar directamente para escenas con múltiples átomos, por ejemplo:

node scripts/motion.mjs preview assets/examples/showcase.scene.json --out work/showcase.html
node scripts/motion.mjs breakdown assets/examples/showcase.scene.json --out work/showcase-breakdown.gif --title "Cabecera · Desglose de átomos"

preview genera HTML, no video. render puede generar MP4 (sin transparencia), MOV / WebM (con transparencia); frames genera PNG; breakdown añade una línea de tiempo de átomos debajo de la imagen, generando GIF, MP4 o WebM: cuando la entrada es una escena, explica las animaciones realizadas; cuando la entrada es un archivo de desglose, extrae fragmentos del video de referencia para el desglose (consulta Desglose de animaciones de video). verified: true solo prueba la verificación de archivos como dimensiones, número de fotogramas y duración; no prueba la corrección de la composición, el ritmo o la oclusión. Antes de la entrega, verifica el resultado de la codificación y la reproducción real según Verificación de imagen, e indica el alcance real de la verificación. Devuelve la ruta del archivo, la ruta de la escena, la frecuencia de cuadros, la duración y el canal alfa; estos materiales no tienen pista de audio.

Límites de capacidad

• El desglose de videos lo realiza el agente utilizando las herramientas de reproducción, extracción de fotogramas y audio del anfitrión; el CLI del paquete no tiene comandos de reconocimiento de video. breakdown extrae fragmentos del video original según el archivo de desglose escrito por el agente, y dibuja la línea de tiempo de átomos debajo. Se pueden analizar acciones que van más allá del paquete, pero se debe distinguir entre directamente usable, parcialmente aproximado y que requiere implementación separada del anfitrión; no se debe afirmar el proyecto original, el complemento o los parámetros precisos a partir del video terminado; los fragmentos extraídos del video original solo se utilizan para el análisis, no se redistribuyen como materials.
• Las escenas 2D solo tienen nodos text / path, sin campos de imagen, video, audio, grupo padre-hijo ni z-index. La salida de propiedades, curvas y copias puede ser aplicada por el anfitrión a imágenes o videos; los átomos geométricos solo manejan gráficos de polilíneas. El anfitrión es responsable de la composición de imágenes y videos.
• Las transiciones y texturas se pueden aplicar a texto y gráficos; el cuadro delimitador del texto se mide según la forma real de la fuente al renderizar. Los bucles y el ritmo no leen audio.
• Los ejemplos predeterminados y el comando scaffold utilizan fuentes del sistema; el paquete no incluye bibliotecas de fuentes. Cuando se necesita consistencia entre máquinas, el anfitrión debe proporcionar fuentes fijas con licencia, declarando la ruta y el hash, y verificando la forma de los caracteres.
• Actualmente no hay átomos 3D; las escenas 3D deben ser implementadas por el anfitrión.
• La producción de videos completos continúa utilizando el storyboard, el sonido, la edición y el flujo de entrega de la parte que realiza la llamada; esta habilidad no impone ningún anfitrión, estilo visual o transición uniforme.

Referencias y agradecimientos

El concepto inicial de indexación de animaciones del proyecto MotionFlux, al que pertenece este paquete, se inspiró en la Tabla Periódica de Movimiento de Kazuki Akamine. Agradecemos su inspiración para la organización y presentación de animaciones básicas. MotionFlux es un proyecto independiente.