F3D 动画系统完全指南播放、切换、导出与命令控制【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3dF3D 是一款快速且极简的 3D 查看器其内置的动画系统允许对任何包含动画数据的文件进行播放、时间跳转与帧导出。本文以 doc/user/05-ANIMATIONS.md 为核心骨架结合 animationManager 源码实现与相关命令行选项系统讲解 F3D 动画的交互操作、命令行参数、帧导出、动画循环规则、时间单位、着色范围与各读取器的动画支持级别帮助你在实际工作流中完整掌控 F3D 的动画能力。快速上手播放一个动画文件F3D 可以为任何包含动画的文件播放动画既可以交互式播放也可以直接指定一个时间点进行显示对于包含多个动画的文件既可以逐个播放也可以同时选择多个动画一起播放。官方文档演示所用的示例动画文件InterpolationTest.glb位于仓库 testing/data 目录下GLB 格式由 native 插件的 GLB 读取器加载支持 MULTI 级别动画。在命令行中执行f3d InterpolationTest.glb加载后即可通过以下交互键位控制动画按键功能H打开作弊速查表cheatsheet菜单查看当前动画名称等信息W循环切换可用的动画Space播放 / 暂停当前动画CtrlShiftSpace反向播放 / 暂停动画当--animation-progress设置为default或advanced时屏幕底部会有一条蓝色进度条用于指示动画序列当前所处的时间区间。其中advanced模式还会额外显示时间范围、动画名称与当前时间并在进度条上用竖线标记每个关键帧两种模式下都可以点击或拖动进度条直接跳转到指定时间鼠标悬停在advanced进度条的关键帧标记附近时工具提示会报告该关键帧的时间。按下W循环动画时All Animations全部动画会在文件格式支持的前提下将全部动画同时播放。说明原文档配图演示了按 H 查看速查表、按 W 循环动画、空格播放/暂停以及全部动画同时播放等界面效果这些截图位于上游 f3d-website 仓库本文档仓库中无对应本地图片故不重复插图以上文字描述即为完整操作指引。命令行选项F3D 的动画行为可以通过命令行完全控制相关选项定义在 library/options.json 的scene.animation与ui.animation_progress等配置节中选项默认值说明--animation-indices0选择要播放的动画索引对应scene.animation.indices类型为int_vector--animation-indices-1—一次性播放全部动画仅在文件格式支持时有效任何负值都表示选择全部动画--animation-speed-factor1.0时间单位换算因子对应scene.animation.speed_factor类型为ratio合法区间0.0~2.0步进0.1用于放慢、加快甚至反转动画时间--frame-rate60FPS调整动画以及其他组件如 watch、UI的刷新帧率不影响渲染帧率--animation-time—启动时加载一个指定的时间值对应scene.animation.time类型为double单位为秒--animation-autoplayfalse自动开始播放动画对应scene.animation.autoplay布尔值从源码看animationManager::Initialize 在初始化时会先读取 importer 中可用的动画数量GetNumberOfAnimations随后调用PrepareForAnimationIndices()依据选项中的索引集合启用/禁用动画并在Autoplay为真时直接StartAnimation()。而 animationManager::Tick 则按DeltaTime * SpeedFactor * AnimationDirection累积当前时间并对时间范围做取模回绕保证播放循环不越界——这就是--animation-speed-factor能够调速的底层机制。旧选项兼容说明scene.animation.index--animation-index已被标记为 deprecated官方建议改用scene.animation.indices。源码在 animationManager::CycleAnimation 与PrepareForAnimationIndices中均做了兼容处理当检测到indices仍为默认的{0}而index非 0 时会打印警告并把index值迁移到indices。导出动画帧F3D 可以将动画的多帧导出为图片文件。只要在输出文件名模板中包含{frame}占位符即可f3d example.file --outputframe_{frame:04}.png这会依次保存为frame_0000.png、frame_0001.png等文件{frame:04}表示 4 位零填充{frame:4}、{frame:5}等数字越大填充位数越多参见 doc/user/03-OPTIONS.md 的 Filename templating 一节。导出帧数由--frame-rate决定f3d example.file --outputframe_{frame}.png --frame-rate30使用--animation-time可以从指定时间点开始导出而不是从开头开始f3d example.file --outputframe_{frame}.png --frame-rate10 --animation-time1.5其余模板变量如{camera_index}、{user}等详见 Filename templating。需要提醒的是--output在配合--ref使用时仅在对比失败时输出文件若把文件名指定为-则会将 PNG 流式写入标准输出详见 doc/user/03-OPTIONS.md。动画交互与命令除了键盘快捷键F3D 还提供了一整套动画控制命令可通过命令行、脚本或配置文件中的命令机制触发完整定义见 doc/user/07-COMMANDS.md命令参数说明cycle_animation无基于模型信息循环scene.animation.index选项toggle_animation无开始 / 停止动画toggle_animation_backward无开始 / 停止反向动画jump_to_frame帧索引跳到指定帧jump_to_frame 0跳第 0 帧jump_to_frame -1跳最后一帧-2跳倒数第二帧jump_to_frame_relative帧偏移相对当前帧移动1下一帧-1上一帧jump_to_keyframe关键帧索引跳到指定关键帧0为动画起始帧1/10为第 1/10 个关键帧jump_to_keyframe_relative关键帧偏移相对当前关键帧移动0跳到最近的关键帧1/-1下一个/上一个关键帧jump_to_time秒跳到指定时间jump_to_time 2.5跳到 2.5 秒处jump_to_time_relative秒偏移相对当前时间移动0.5前进 0.5 秒-0.5后退 0.5 秒这些命令的底层实现在 animationManager 中均有对应方法JumpToFrame通过帧时长DeltaTime * SpeedFactor换算时间JumpToKeyFrame使用std::lower_bound在AnimationTimeSteps中查找当前时间最接近的关键帧并对相对跳转做取模回绕animationManager.cxxJumpToTime则直接以目标时间调用LoadAtTime并触发重渲染。所有时间跳转都会经过LoadAtTime的范围钳制——超出[TimeRange[0], TimeRange[1]]的时间会被警告并钳制到边界animationManager.cxx。循环切换动画的顺序按下W循环动画时F3D 遵循如下顺序对应 animationManager::CycleAnimation 的实现逻辑多个动画或全部动画若当前正处于该状态动画索引 0动画索引 1……依次递增……动画索引 N全部动画仅当文件支持多个动画且可用动画多于一个时无动画两点注意事项如果你手动指定了多个动画索引循环时永远不会再回到这一组合状态因为索引集合大小大于 1 时会被判为多动画分支而清空全部动画仅在当前加载文件支持多动画MULTI 级别时才会进入循环序列。在实现上CycleAnimation会先检查索引中是否含负值任何负值 全部动画或集合大小大于 1是则清空选择无动画为空则选中索引 0否则递增索引越界后若 importer 支持 MULTI 且动画多于一个则改为选中全部动画否则清空选择。每次切换后都会调用PrepareForAnimationIndices与LoadAtTime(TimeRange[0])并刷新进度条 UI。时间单位与着色范围时间单位F3D 播放动画时默认假设时间单位为秒以保证动画速度显示准确。--animation-speed-factor本质上是这个秒单位的换算因子大于 1 加快播放、小于 1 放慢播放负值可反转时间方向该值在 options.json 中被限定在0.0~2.0区间。着色范围当在加载时间值或播放动画的过程中进行着色时着色范围会自动从先前加载的时间值扩展这包括--animation-time先加载初始时间、再加载用户提供时间值的情形。也就是说动画播放过程中颜色映射范围会随时间的推进而动态扩展避免把后续时间步的着色信息截断。各读取器的动画支持级别F3D 为每个读取器reader都标注了动画支持级别完整表格见 doc/user/02-SUPPORTED_FORMATS.mdNONE不支持动画文件格式或实现层面均不支持如 VTK 旧格式.vtk、VTK XML.vtp/.vtu等、PLY、STL、DICOM、图片类格式.png/.jpg/.exr等、Draco、3DS、OFF、DXF、3MF 等UNIQUE文件永远最多只有一个动画如 VTKHDF.vtkhdf、EXODUS II.e/.ex2等、NetCDF.nc等、Alembic.abcSINGLE可能存在多个动画但同一时刻只能选择一个播放如 QuakeMDL.mdl、USD.usd/.usda/.usdc/.usdzMULTI可以同时选择多个动画播放如 GLTF/GLB.gltf/.glb、FBX、COLLADA.dae、DirectX.x。当使用--multi-file-mode同时打开多个文件并选择多个动画时如果混合了 SINGLE 与非 SINGLE 级别的文件F3D 可能会发出警告但仍会尽量尊重所指定的动画索引。这一行为在 animationManager::PrepareForAnimationIndices 中有对应实现它会依据 importer 上报的AnimationSupportLevelUNIQUE / SINGLE / MULTI检查索引合法性并打印相应警告随后逐个DisableAnimation再EnableAnimation选中的索引最后汇总所有已启用动画的时间范围与关键帧时间步animationManager.cxx。关键帧跳转的支持范围jump_to_keyframe命令允许将动画加载到特定关键帧用法示例见 doc/user/07-COMMANDS.md目前仅以下读取器支持vtkF3DGLTFImporterGLTF/GLBnative 插件vtkF3DQuakeMDLImporterQuakeMDLnative 插件其他读取器的关键帧级动画访问正在推进中上游跟踪问题编号为 #2637主题为Improve Animation System / Access to timesteps。此外jump_to_frame与jump_to_time系列命令对时间步的访问也依赖 importer 提供的GetTemporalInformation时间步信息支持程度同样以各读取器实现为准。小结F3D 的动画系统由 animationManager 统一管理它负责动画索引的启用/禁用、时间推进Tick、时间跳转JumpToFrame/KeyFrame/Time、动画循环CycleAnimation以及进度条 UI 的推送PushAnimationProgress。配合命令行选项、交互键位与命令系统你可以实现从加载即播放到按帧/按关键帧/按秒精确跳转再到批量导出动画帧的完整动画工作流。实际使用前建议先查阅 doc/user/02-SUPPORTED_FORMATS.md 确认目标文件格式的动画支持级别再据此选择 SINGLE 或 MULTI 级别的索引策略。【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3d创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考