Pixerate/pixerate-animation-editor

Pixerate 动画编辑器

一个场景由美术素材（解析为矢量路径和组、每个带有id的SVG）加上一个有序的镜头列表组成。一个镜头可以选择移动摄像机、播放其 run 中的指令，然后保持不动（默认 600 毫秒）。指令会一个接一个播放，除非指定了 "with": "previous"；每条指令的默认时长由内容决定（进入 600 毫秒、退出 450、移动 700、绘制跟随路径长度），因此除非你打算改变节奏，否则请省略 duration。每一帧都是时间的纯函数。

Id：元素id来自 get_animation (elements) 或 find_animation_elements；镜头id由你自行选择（例如 "intro"）；指令通过镜头id及其在run中的索引来引用。时间以毫秒为单位，位置是美术素材的文件单位。稍后才进入的元素在其 enter 之前是隐藏的；从不进入的元素从一开始就可见。

有关错误、带命名空间的工具名称和通用指令工具，请参见 pixerate-agent-tools。完整的指令词汇表（每种类型、选项和默认值）在 references/commands.md 中。

工作流技能

对于这些任务，请同时加载工作流技能：它包含了方法、步骤间的检查以及陷阱，并使用下面的工具。

• pixerate-animation-motion-graphics：镜头、交错进入、缓动、保持、匹配时长。
• pixerate-animation-logo-reveal：从徽标的各个部分开始的一个短展示，配合节拍，结束时保持。

工作方法

1. 读取。 get_animation 获取元素、带时间的镜头、片段、驱动器和问题。如果没有美术素材，则先使用 set_animation_artwork_svg（为你将动画化的每个元素赋予id），或者从 import_flair_effect / import_pptx_animation 开始。对于轮廓文本，get_text_layout 显示字母、单词和行单元。
2. 规划镜头，每个镜头一个想法。 写下观众在每个镜头中应该注意什么以及以什么顺序注意，然后将每个节拍映射到一条指令。隐藏的结束状态（变形/匹配目标、跟随路径）必须在引用它们之前存在于美术素材中。
3. 批量写入。 insert_shots 用于整个镜头；edit_animation 用于将几个相关编辑作为一个撤销步骤（如果不确定，先使用 dry_run: true；"$0.indexes[0]" 和 "$last.shot" 引用之前的操作）。使用 add_commands、update_command、move_command、delete_commands 进行细化。仅当需要替换所有镜头时才使用 write_animation。对于之前未编写过的指令类型，首先使用 describe_animation_command 返回其确切字段。对于应该感觉像表演而非关键帧的运动（手绘式挥动、抖动式拖拽、在移动中拾取的颜色），record_animation_take 使用计时样本将其录制为一个镜头，就像人在舞台上实时录制一样。
4. 适配和提示。 fit_animation 用于匹配一个时长（保留节奏重要的镜头）。对于音乐或配音，使用 set_animation_settings 设置 beat 或 narration，使用 get_timing_grid 读取提示，并为镜头指定 "at": { "beat": n } 或 { "word": i }。
5. 检查。 check_animation；修复每个错误和警告（代码如 too-fast、overlap、out-of-frame、enter-visible、cue-missed）。使用 get_motion_path 查看数值形式的间距和弧度。
6. 查看。 render_animation_frame 使用 shot + at: "end"，或 times 生成联系表，再加上 onion_skin / motion_paths 在一张图片中查看运动。在批量操作后渲染，而不是每次编辑后。seek_animation 向用户展示某个时刻。
7. 导出 当被要求时：export_flair_motion、export_flair_effect（在 set_animation_controls 之后）或 export_lottie；阅读返回的关于采样或丢弃内容的注释。

最佳实践

• 每个镜头一个想法，每次一个焦点运动。 分阶段安排动作，让眼睛知道看哪里；次要元素运动更少、更晚或完全不运动。使用摄像机（frame 一个节点）来引导注意力，而不是移动所有东西。
• 为每个变化添加缓动。 到达时缓出（减速到位；enter 的默认值），退出时缓入（exit 使用 ease: "ease-in"），移动时缓入-缓出（默认值）。仅对机械运动（恒定旋转、进度条）或循环使用 linear。
• 根据大小和距离确定时间。 小的 UI 变化 150-300 毫秒，元素进入 300-600 毫秒，大移动和摄像机移动 600-1200 毫秒。不要低于 120 毫秒（too-fast）。大的物体比小的物体移动得慢。
• 预期和后续动作。 在快速退出前使用 ease-in-back 进行预摆；使用 pop、rise、ease-out-back 或弹簧预设（spring-gentle、spring-quick）在到达时产生过头和稳定效果。谨慎使用 spring-bouncy；它看起来很有趣。
• 重叠动作。 将相关项目交错 40-120 毫秒（stagger，或为文本使用 split 配合 cascade），而不是同时移动它们；使用 "with": "previous" 加上一个小 delay 启动次要运动，使其跟随主导运动。
• 弧线。 自然运动曲线：使用带 via 航点的 move（一条平滑路径），而不是在每一点停止的链式移动，或者使用 follow 跟随一个路径节点。
• 录制片段。 以每秒 30-60 个样本的频率采样一个表演；记录器只保留重要的点（提高 tolerance 以获得更少、更干净的指令）。每个移动元素从其当前姿态（get_motion_path 的最后一点，或静止时的边界中心）开始采样，否则它会跳到其第一个样本的位置。一个片段是位于其他镜头之后（或在 at 处）的新镜头；它不能叠加在现有镜头上。像任何镜头一样细化它：它是普通的 move（带 via 和 times）、scale、rotate、fade 和 style 指令。
• 保持足够长的时间以便阅读。 将每个结果保留在屏幕上（镜头 hold，默认 600 毫秒）；对于必须阅读的文本，大约每个词 250 毫秒，对于最后一帧或徽标则更长。
• 克制的夸张。 强调效果（pulse、shake、teeter、color-pulse）只用于需要引起注意的一个东西，一次；它会自行恢复到静止状态。
• 运动模糊 仅用于真正快速的运动（motionBlur: { shutter: 180 }）；它影响舞台和渲染帧，但不影响 Flair 或 Lottie 导出。
• 无障碍。 避免闪烁：每秒不超过三次闪光（WCAG 2.3.1），因此对于大面积的 color-pulse 和淡入淡出要保持缓慢且少量。避免对基本 UI 运动使用大规模视差、缩放和旋转；提供一个减少运动效果的替代方案（宿主应在 prefers-reduced-motion 下替换为淡入或结束状态；此编辑器不会生成一个）。运行超过 5 秒的循环需要一种暂停方式（WCAG 2.2.2）。
• 交互式部件。 对于按钮或开关，设置 trigger（click、hover、press、scroll）；对于点击切换，使最后一个镜头恢复到起始状态。

工具参考

读取

工具	用途
get_animation	从这开始。返回名称、美术素材尺寸、时长(ms)、循环、元素(id、类型、名称、父元素、边界、实色、带数值参数的活动效果)、每个镜头及其每条指令的索引、开始、结束和flairPrimitive、片段、驱动器、控件和问题摘要，以及当编辑被拒绝时的readOnly。includeElements: false（默认为true）在大型美术素材上跳过元素列表。
get_shot	按存储方式读取一个镜头（shot id）及其开始/结束时间以及每条指令的开始/结束时间（毫秒）；在细化某个镜头时比get_animation更便宜。
describe_animation_command	在编写尚未使用过的指令类型之前，或当写入操作拒绝某个字段时：返回每个types的完整JSON Schema（例如["enter", "move"]），包含每个字段的类型、范围、默认值和含义，以及哪些是必需的。写入工具在一个简短的列表中列出每个指令字段，前缀为接受它的类型。
find_animation_elements	当美术素材较大时，查找其id或名称包含query的元素（不区分大小写；limit默认为20，最多200）。返回id、类型、名称、父元素、边界、颜料、效果。
get_text_layout	在使用split动画化轮廓文本之前：按阅读顺序返回group的行、单词和字母id。如果元素不是一个路径组（将文本转换为轮廓，每个字母一个路径，并分组），则会出错。
get_motion_path	以数值形式检查间距、弧线和着陆点：每step毫秒（默认33，最多400个样本）对from到to毫秒之间的节点中心（文档单位）进行采样，并显示每个移动变化的开始和结束位置。
get_timing_grid	列出from和to之间的节拍（编号、毫秒、小节、节拍内）和旁白词（索引、文本、开始、结束）（limit默认为200），以及每个时刻播放哪个镜头，以便选择at提示。当未设置节拍网格或旁白时，返回空值并附有提示。
check_animation	在每次批量写入之后使用。列出带有代码、严重性、镜头、指令索引、节点id、测量值与所需值以及修复方法的问题。修复错误和警告；备注仅供参考。
render_animation_frame	查看结果：time（毫秒）或shot + at（start、middle、end；默认为end）。times（2-16个时刻）生成带标签的联系表（columns 1-8）。onion_skin 添加幽灵帧（before默认为2，after为0，spacing毫秒或"commands"）；motion_paths（true或id列表）绘制移动路径。默认为SVG；仅当主机能够进行光栅化时format: "png"。
export_flair_motion	将场景作为Flair SvgMotion { svg, animate } 获取，包含保持时间、采样步数和备注。fps（默认为场景fps，否则30），curves 和 behaviors（默认为true），flair 目标版本（默认为0.39；旧版本对弹簧、步进、行为和曲线进行采样）。
export_flair_effect	获取Flair目录矢量效果（id短横线命名，name，description，category默认为icon，tags，加上如上所述的curves / behaviors / flair）。首先调用set_animation_controls，以便颜色成为{{name: color}}控件。
export_lottie	获取Lottie（Bodymovin v5）JSON，用于lottie-web和移动播放器，每个镜头有一个标记，fps（默认为场景fps，否则30）、采样关键帧数以及关于未传递内容的备注（渐变、虚线、显示剪辑、更改点数的变形）。

写入

工具	用途
seek_animation	向用户展示某个时刻：time（毫秒）或shot的开始，带play true或false。不会改变场景。
set_animation_artwork_svg	将美术素材替换为一个独立的svg（带有viewBox）作为一个撤销步骤。为你将动画化的每个元素赋予id；如果现有镜头命名了新美术素材中缺少的id，则会被拒绝。返回元素。
import_pptx_animation	用PowerPoint幻灯片的形状和动画窗格替换整个场景（data base64 .pptx，slide默认为1）：每次点击一个镜头、延迟、重复和加速均保留；文本、图片和图表被省略并附有提示。首先使用dry_run: true运行。
set_animation_drivers	替换所有驱动器（空列表清除）：目标的 x、y、rotation、scaleX、scaleY 或 opacity 跟随源节点的属性变化，乘以factor + offset，可选择进行clamp。用于视差、滚动时转动的轮子、随着某物上升而淡出的阴影。
set_animation_clip	定义、替换或（使用 clip: null）删除一个命名的可复用片段，其 run 以 "$" 为目标；在任何节点上使用 play 指令播放。优先使用片段而不是重复的相同指令。
copy_animation	将所有动画化 from 的指令（所有镜头或 shots）赋予 to 中的节点，每个副本从其原始指令开始，可选地 stagger（毫秒）处理。适用于一次性快速复制；对于要重复使用的运动，请使用片段。
record_animation_take	将表演的运动录制为一个新镜头（一个撤销步骤）：samples 包括 { node, t (进入镜头后的毫秒数), x, y (中心), scaleX, scaleY, rotation, opacity, fill, stroke, strokeWidth }，生成一个通过具有记录 times 的航点的 move，以及一些缓动的 scale / rotate / fade / style 指令，每条指令从发生的时间开始。可选的 length、id、label、at、tolerance；dry_run: true 首先返回运行序列。返回镜头id、其开始时间以及每条指令的索引、类型、开始和结束；之后使用 check_animation 和 render_animation_frame。
fit_animation	通过设置镜头的 speed，保持比例，使场景持续 seconds 秒；keep 中的镜头按原样播放。dry_run: true 首先报告新的时长和速度。
import_flair_effect	用Flair矢量 effect 或 SvgMotion motion 替换整个场景（只提供一个；可选的 name）。占位符成为颜色控件；每个Flair步骤成为一个镜头。首先使用 dry_run: true。
insert_shots	在位置 at（默认为结尾）添加一个或多个完整镜头（id、run、可选的 label、camera、hold、speed、at）。返回每个镜头的时序和问题。
update_shot	通过 set 更改一个镜头的 label、camera、run、hold、speed、at 或 id，并通过 remove 清除 label、camera、hold、speed 或 at。
delete_shots	按id删除镜头（一个撤销步骤）。
move_shot	将一个镜头重新排序到索引 to（0 = 第一个）。
add_commands	在索引 at（默认为结尾）处向镜头的run中添加指令。返回它们获得的索引及其时序；使用这些索引进行后续更新。
update_command	更改一条指令（通过 shot 和 command 索引）：set 中的字段替换，remove 中的名称清除（例如 "delay"）。返回指令及其时序。
delete_commands	按索引从镜头中删除指令；之后的指令会向上移动，因此之后重新读取索引。
move_command	将一条指令移动到其run中的索引 to 处；然后，一条 "with": "previous" 指令将与其新邻居同时开始。
set_animation_settings	设置 name、description、loop（none、loop、ping-pong）、trigger（click、hover、press、scroll 或 null）、导出 fps（默认 30）、场景 steps（12 = 隔帧；null 平滑...）