F3D 命令系统完全指南交互式控制台、命令脚本与 libf3d 命令参考【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3dF3D 是一个快速且极简的 3D 查看器除了命令行参数外它还提供了一套内置的命令Commands系统用于触发那些无法通过命令行直接完成的行为。本文以 doc/user/07-COMMANDS.md 为主体结合application/F3DStarter.cxx、library/src/interactor_impl.cxx等源码与testing/scripts/下的真实脚本测试系统讲解命令的语法规则、libf3d 内置命令、F3D 应用层命令、选项域Domain机制以及命令脚本与交互式控制台两种执行方式帮助你从命令行、配置绑定、脚本自动化三个维度全面掌握 F3D 的命令能力。注意命令系统目前仍处于实验性阶段行为、动作可能在没有弃用通知的情况下被添加或移除动作名与参数也可能随时变化见 doc/user/07-COMMANDS.md。命令的三种访问入口F3D 命令可通过以下三种方式触发交互式控制台Interactive Console构建时启用F3D_MODULE_UI后按Esc打开控制台输入命令命令脚本Command Script通过--command-script命令行选项执行一个纯文本脚本文件例如f3d --command-script path/to/command_script.txt按键绑定配置Bindings在 配置文件 中将命令绑定到键盘按键交互时按对应键即可触发。所有命令采用统一的语法action [args]即“动作名 可选参数”。命令语法类 Bash 的 Token 解析规则命令的语法与 bash 类似会按 “token” 切分后再处理。具体规则如下均来自 doc/user/07-COMMANDS.mdToken 以空格分隔例如set scene.up.direction Z会被拆成set、scene.up.direction、Z三个 token。引号包裹以支持空格例如set render.hdri.file /path/to/file with spaces.png。支持多种引号、、均可例如set render.hdri.file /path/to/file with spaces.png。引号可嵌套例如set render.hdri.file /path/to/filewithquotes.png。引号与空格可转义例如set render.hdri.file /path/to/file\ with\ spaces\ and\ \quotes\.png。注释使用#其后的所有字符都会被忽略使用\#可以按字面量输出#。[!NOTE] 注释仅在命令脚本中有效在交互式控制台中#及其后的所有字符都会按普通字符处理。转义符本身可被转义例如 Windows 路径set render.hdri.file C:\\path\\to\\windows\\file.png。其他转义字符按原样处理例如set scene.up.direction \Z中的\Z等价于Z。未闭合的引号段无效例如set scene.up.direction Z是非法命令。结尾的转义符同样无效例如set scene.up.direction Z\是非法命令。选项值按其类型解析具体规则见 解析文档。从源码看命令的解析与执行位于library/src/interactor_impl.cxx中interactor_impl::interactor_impl构造函数内的大段addCommand注册逻辑而命令脚本的执行入口在application/F3DStarter.cxx约 L1756-L1785F3DStarter读取AppOptions.CommandScriptFile逐行读取脚本文件并调用interactor.triggerCommand(command)一旦某条命令执行失败会输出Error in command script, stopping script execution并中止脚本。libf3d 提供的命令libf3d 内置了一批命令其中很多与 libf3d 选项 的读写相关。以下逐一说明全部命令的注册与文档字符串可在 library/src/interactor_impl.cxx 中检索到。选项读写类命令命令说明示例set option.name values设置一个 libf3d 选项set scene.up.direction Z、set render.hdri.file /path/to/file with spaces.pngtoggle option.name切换布尔选项toggle ui.scalar_barreset option.name将选项重置为默认值reset render.background.blur.cocprint option.name打印选项当前值print scene.up.directionset_reader_option Reader.option_name value设置 reader 选项set_reader_option QuakeMDL.skin_index 1increase option.name按范围域range domain递增选项increase render.light.intensitydecrease option.name按范围域递减选项decrease render.light.intensitycycle option.name按枚举域enum domain循环选项cycle render.effect.blending.mode源码佐证library/src/interactor_impl.cxxset内部调用f3d::options::set系方法print使用Options.getAsString(args[0])输出set_reader_option内部调用f3d::engine::setReaderOption(args[0], args[1])见set_reader_option注册处并支持对 reader 选项名自动补全print命令带有complOptionNames补全器可在交互式控制台中按Tab补全选项名。场景与渲染信息类命令命令说明print_scene_info打印场景信息无参数print_coloring_info打印着色coloring设置信息无参数print_mesh_info打印网格导入器提供的信息无参数print_options_info打印当前有值的 libf3d 选项无参数print_config_info打印配置文件信息无参数对应的测试application/testing/tests.features.cmake验证了这些命令的输出例如TestCommandScriptPrintScene检查Camera position: 2.23745, 3.83305, 507.598TestCommandScriptPrintMesh检查Number of points: 13268TestCommandScriptPrintOptions检查interactor.invert_zoom: falseTestCommandScriptPrintColoring检查Not coloringTestCommandScriptPrintConfig检查Found available config path。这些断言可以直接用作脚本输出的期望值参考。相机操作类命令命令说明示例roll_camera value让相机绕自身轴滚动参数为角度度roll_camera 120elevation_camera value相机上下俯仰参数为角度度elevation_camera 120azimuth_camera value相机左右旋转方位角参数为角度度azimuth_camera 120set_camera front/top/right/back/bottom/left/isometric将相机定位到相对模型指定方位set_camera topreset_camera将相机重置到初始位置无参数—源码细节roll_camera在interactor_impl.cxx中实现为Window.getCamera().roll(options::parseint(args[0]))且当交互风格为2d时直接返回2D 模式下不生效执行后还会调用Style-SetTemporaryUp(...)同步临时上方向。按键绑定层中数字键4/6分别绑定了roll_camera -90/roll_camera 90见 library/src/interactor_impl.cxx 中addBinding部分。着色Scivis相关命令命令说明cycle_coloring field/array/component基于模型信息循环切换着色方式支持field、array、component三种参数详见 着色循环toggle_volume_rendering切换model.volume.enable并打印着色信息无参数源码细节cycle_coloring在 interactor_impl.cxx 中通过vtkF3DRenderer的CycleFieldForColoring()/CycleArrayForColoring()/CycleComponentForColoring()实现参数不合法时抛出invalid_args_exception执行后调用SynchronizeScivisOptions同步选项并以 DEBUG 级别打印着色描述。默认按键绑定中C/S/Y分别触发cycle_coloring field/cycle_coloring array/cycle_coloring component。动画控制类命令命令说明示例cycle_animation基于模型信息循环scene.animation.index选项无参数—toggle_animation开始/停止动画无参数—toggle_animation_backward开始/停止反向播放动画无参数—jump_to_frame跳到指定帧参数为帧索引jump_to_frame 0第 0 帧、jump_to_frame -1最后一帧、jump_to_frame -2倒数第二帧jump_to_frame_relative相对当前帧移动若干帧参数为帧偏移jump_to_frame_relative 1下一帧、jump_to_frame_relative -1上一帧jump_to_keyframe跳到指定关键帧参数为关键帧索引jump_to_keyframe 0动画起始帧、jump_to_keyframe 10第 10 个关键帧jump_to_keyframe_relative相对当前关键帧移动参数为关键帧偏移jump_to_keyframe_relative 0最近关键帧、jump_to_keyframe_relative 1下一关键帧、jump_to_keyframe_relative -1上一关键帧、jump_to_keyframe_relative 10前进 10 个关键帧jump_to_time跳到指定时间参数为秒jump_to_time 2.5jump_to_time_relative相对当前时间移动参数为秒偏移jump_to_time_relative 0.5前进 0.5 秒、jump_to_time_relative -0.5后退 0.5 秒jump_to_keyframe/jump_to_keyframe_relative在跳转时会把目标关键帧索引自动约束在可用关键帧总数范围内避免非法访问。目前这两条命令仅被以下 reader 支持vtkF3DGLTFImportervtkF3DQuakeMDLImporter其他 reader 的动画时间步支持进展可跟踪 F3D 项目的动画系统改进 IssueF3D Issue #2637。源码中jump_to_frame等命令经由AnimationManager-JumpToFrame(frame, relative)/JumpToTime(time, relative)实现见 library/src/interactor_impl.cxx 中jump_to_frame等注册处。关于帧号负数的约定负索引表示从末尾倒数例如-1是最后一帧、-2是倒数第二帧相对偏移中0表示跳到最近的关键帧。文件与状态管理类命令libf3d 层libf3d 提供以下命令但它们会被 F3D 应用层的同名命令覆盖见下文命令说明add_files [path/to/file1] [path/to/file2]向场景添加文件可接一个或多个文件save_statefile [path/to/file]将当前状态保存到指定 statefileload_statefile [path/to/file]从指定 statefile 恢复状态save_statefile_to_clipboard将当前状态保存到系统剪贴板需要启用clip模块构建load_statefile_from_clipboard从系统剪贴板恢复状态需要启用clip模块构建其他工具类命令命令说明示例clear清空控制台无参数—cycle_verbose_level在Debug、Info、Warning、Error、Quiet之间循环切换日志级别无参数—alias [alias_name] [command]为某条命令创建别名alias myrotate roll_camera 90help [command]打印指定命令的帮助信息help set_camerastop_interactor停止交互器并退出应用无参数—源码细节alias命令在interactor_impl.cxx中注册作用是把一个命令名映射到一串命令文本之后即可直接调用别名help会输出注册命令时的command_documentation_t描述。测试TestCommandScriptHelp检查help set输出包含set a libf3d optionTestCommandScriptAlias则直接执行alias myrotate roll_camera 90后调用myrotate见 testing/scripts/TestCommandScriptAlias.txt 与 application/testing/tests.features.cmake。F3D 应用层提供的专用命令F3D 应用application/F3DStarter.cxx在 libf3d 命令之上额外提供了以下命令主要涉及文件组管理、截图、状态文件与文件对话框文件组File Group管理命令说明load_previous_file_group [keep_camera]加载上一个文件或文件组keep_camera为true时保持相机状态默认falseload_next_file_group [keep_camera]加载下一个文件或文件组相机保持规则同上reload_current_file_group重新加载当前文件或文件组无参数add_current_directories将当前文件/文件组所在目录下的所有文件加入场景无参数add_files [path/to/file1] [path/to/file2]按当前分组逻辑向场景添加文件覆盖 libf3d 同名命令可接一个或多个文件remove_current_file_group移除当前文件组并加载下一个文件组如果有无参数remove_file_groups移除所有文件无参数注意load_previous_file_group的参数最多为 1 个TestCommandScriptParseOptionalBoolExtraArg测试验证了传入多余参数会报错Command: load_previous_file_group takes at most 1 argument, got 2 arguments instead.见 application/testing/tests.features.cmake。相关测试包括TestCommandScriptResetreset render.show_edges; load_next_file_group、TestCommandScriptRemoveCurrentFileGroup、TestCommandScriptRemoveFileGroups见 application/testing/tests.features.cmake。截图命令命令说明take_screenshot [filename]截图未指定文件名时使用--screenshot-filenameCLI 选项take_minimal_screenshot [filename]截取最小化截图未指定文件名时同样回退到--screenshot-filename截图方式详见 截图交互示例take_screenshot path/to/file.png。文件对话框与 HDRI命令说明open_file_dialog打开文件对话框选择要加载的文件无参数set_hdri [path/to/hdri]设置并使用 HDRI 图像参数为 HDRI 文件add_files_or_set_hdri [path/to/file1] [path/to/file2]逐个处理文件若文件扩展名是已识别的 HDR 扩展则执行set_hdri否则执行add_files示例set_hdri /path/to/file.hdr、add_files_or_set_hdri /path/to/dragon.vtu /path/to/file.hdr。状态文件Statefile管理F3D 层命令说明save_statefile [filename]保存当前状态到 statefile包含所有文件组包括未加载的未指定文件名时使用--statefile-filenameCLI 选项为空则使用默认文件名使用-输出到标准输出save_statefile_dialog通过文件对话框选择保存位置需要启用tinyfiledialogs模块构建load_statefile [filename]从 statefile 恢复状态恢复所有已保存的文件组并重新加载当前文件组未指定文件名时规则同上使用-从标准输入读取文件不存在时仅警告不报错load_statefile_dialog通过文件对话框选择 statefile 恢复需要启用tinyfiledialogs模块构建save_statefile_to_clipboard保存状态到系统剪贴板需要启用clip模块构建load_statefile_from_clipboard从系统剪贴板恢复状态并重新加载文件需要启用clip模块构建示例save_statefile path/to/state.json、load_statefile path/to/state.json。选项域Domainsincrease / decrease / cycle 的底层机制部分 libf3d 选项带有域domain命令系统据此提供了三种操作方式见 doc/user/07-COMMANDS.md 的 Domains 一节范围域Range domain通过increase/decrease操作。具有包含的最小值和最大值以及一个增量。increase/decrease按增量增减并在达到最大/最小值处截断。枚举域Enum domain通过cycle操作。只列出选项可能的取值cycle依次遍历并在到达末尾后循环回起点。索引域Index domaincycle与increase/decrease均可使用。对increase/decrease它等价于一个[0, max]范围域增量为 1对cycle它等价于一个包含 0 到 max 之间所有取值的枚举域。例如increase render.light.intensity会按域定义逐步提升光照强度cycle render.effect.blending.mode会在混合模式枚举间循环。域的定义与解析可以在 doc/libf3d/03-OPTIONS.md 与library/private/options_generated.h.in/library/src/options.cxx中追溯测试方面TestSDKOptionsDomains.cxxlibrary/testing/TestSDKOptionsDomains.cxx覆盖了域相关行为。命令脚本--command-scriptF3D 支持通过--command-scriptCLI 选项 从脚本文件执行命令序列便于自动化f3d --command-script path/to/command_script.txt。脚本规则命令之间以换行分隔支持注释。官方示例# A comment roll_camera 90 toggle ui.scalar_bar print_scene_info # Another comment increase_light_intensity仓库中真实的脚本示例testing/scripts/TestCommandScriptBasic.txt# A comment at the beginning of the script roll_camera 90 # A comment at the end of a command toggle ui.scalar_bar # A comment in the middle of the script print_scene_info脚本执行流程源码依据 application/F3DStarter.cxxF3D 启动时若指定了--command-script会打开脚本文件并逐行std::getline读取对非空行调用interactor.triggerCommand(command)任一条命令执行失败即输出错误日志并停止后续执行文件无法打开时输出Unable to open command script file并返回失败。对应测试见 application/testing/tests.features.cmakeTestCommandScriptMissingFile验证了文件打不开时的报错路径。交互式控制台Interactive Console当 F3D 以F3D_MODULE_UI构建时交互窗口中按Esc即可打开控制台在输入框中输入任意命令按Enter立即执行按Tab自动补全命令并显示建议选项名、reader 选项名等均支持补全按↑/↓在命令历史中上下浏览再次按Esc关闭控制台。结合前文可知控制台内的补全能力由interactor_impl.cxx中每个命令注册时挂载的补全器提供如complOptionNames、reader 选项名补全等。从测试与绑定看命令的实战组合命令系统不仅在脚本与控制台中直接使用还被按键绑定大量复用。interactor_impl.cxx中的addBinding把命令与默认按键关联例如C→cycle_coloring field、S→cycle_coloring array、Y→cycle_coloring component、4→roll_camera -90、6→roll_camera 90。也就是说你看到的交互层“快捷键”本质上就是命令这也解释了命令文档与 交互文档 之间的对应关系。仓库中大量TestCommandScript*.txt见 testing/scripts 目录展示了命令的典型组合例如TestCommandScriptJumpToPreviousKeyFrame.txt、TestCommandScriptJumpToClosestKeyFrame.txt等覆盖jump_to_keyframe*系列配合soldier_animations.mdl与--animation-indices2等参数TestCommandScriptCycleCameraIndex.txt、TestCommandScriptIncreaseDecreaseCameraIndex.txt覆盖相机索引切换TestCommandScriptAxesGridAnimation.txt结合--axes-grid使用。这些脚本直接位于testing/scripts/可作为自动化场景下的参考模板。小结F3D 的命令系统以action [args]为统一语法提供三大入口交互式控制台、命令脚本、按键绑定配置覆盖选项读写set/toggle/reset/print/increase/decrease/cycle、相机控制、着色循环、动画跳转、文件组管理、截图与状态文件等能力。掌握这套命令体系意味着你可以在交互窗口中即时探索并修改任意选项用--command-script将重复性操作固化为可复用的自动化脚本配合 CI/测试在 配置文件 中自定义按键绑定把常用命令映射到顺手的位置。由于命令系统仍处于实验阶段建议在实际使用中通过help command查询当前构建下的命令帮助并以本仓库当前版本的源码library/src/interactor_impl.cxx与测试脚本为准。【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3d创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
F3D 命令系统完全指南：交互式控制台、命令脚本与 libf3d 命令参考
F3D 命令系统完全指南交互式控制台、命令脚本与 libf3d 命令参考【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3dF3D 是一个快速且极简的 3D 查看器除了命令行参数外它还提供了一套内置的命令Commands系统用于触发那些无法通过命令行直接完成的行为。本文以 doc/user/07-COMMANDS.md 为主体结合application/F3DStarter.cxx、library/src/interactor_impl.cxx等源码与testing/scripts/下的真实脚本测试系统讲解命令的语法规则、libf3d 内置命令、F3D 应用层命令、选项域Domain机制以及命令脚本与交互式控制台两种执行方式帮助你从命令行、配置绑定、脚本自动化三个维度全面掌握 F3D 的命令能力。注意命令系统目前仍处于实验性阶段行为、动作可能在没有弃用通知的情况下被添加或移除动作名与参数也可能随时变化见 doc/user/07-COMMANDS.md。命令的三种访问入口F3D 命令可通过以下三种方式触发交互式控制台Interactive Console构建时启用F3D_MODULE_UI后按Esc打开控制台输入命令命令脚本Command Script通过--command-script命令行选项执行一个纯文本脚本文件例如f3d --command-script path/to/command_script.txt按键绑定配置Bindings在 配置文件 中将命令绑定到键盘按键交互时按对应键即可触发。所有命令采用统一的语法action [args]即“动作名 可选参数”。命令语法类 Bash 的 Token 解析规则命令的语法与 bash 类似会按 “token” 切分后再处理。具体规则如下均来自 doc/user/07-COMMANDS.mdToken 以空格分隔例如set scene.up.direction Z会被拆成set、scene.up.direction、Z三个 token。引号包裹以支持空格例如set render.hdri.file /path/to/file with spaces.png。支持多种引号、、均可例如set render.hdri.file /path/to/file with spaces.png。引号可嵌套例如set render.hdri.file /path/to/filewithquotes.png。引号与空格可转义例如set render.hdri.file /path/to/file\ with\ spaces\ and\ \quotes\.png。注释使用#其后的所有字符都会被忽略使用\#可以按字面量输出#。[!NOTE] 注释仅在命令脚本中有效在交互式控制台中#及其后的所有字符都会按普通字符处理。转义符本身可被转义例如 Windows 路径set render.hdri.file C:\\path\\to\\windows\\file.png。其他转义字符按原样处理例如set scene.up.direction \Z中的\Z等价于Z。未闭合的引号段无效例如set scene.up.direction Z是非法命令。结尾的转义符同样无效例如set scene.up.direction Z\是非法命令。选项值按其类型解析具体规则见 解析文档。从源码看命令的解析与执行位于library/src/interactor_impl.cxx中interactor_impl::interactor_impl构造函数内的大段addCommand注册逻辑而命令脚本的执行入口在application/F3DStarter.cxx约 L1756-L1785F3DStarter读取AppOptions.CommandScriptFile逐行读取脚本文件并调用interactor.triggerCommand(command)一旦某条命令执行失败会输出Error in command script, stopping script execution并中止脚本。libf3d 提供的命令libf3d 内置了一批命令其中很多与 libf3d 选项 的读写相关。以下逐一说明全部命令的注册与文档字符串可在 library/src/interactor_impl.cxx 中检索到。选项读写类命令命令说明示例set option.name values设置一个 libf3d 选项set scene.up.direction Z、set render.hdri.file /path/to/file with spaces.pngtoggle option.name切换布尔选项toggle ui.scalar_barreset option.name将选项重置为默认值reset render.background.blur.cocprint option.name打印选项当前值print scene.up.directionset_reader_option Reader.option_name value设置 reader 选项set_reader_option QuakeMDL.skin_index 1increase option.name按范围域range domain递增选项increase render.light.intensitydecrease option.name按范围域递减选项decrease render.light.intensitycycle option.name按枚举域enum domain循环选项cycle render.effect.blending.mode源码佐证library/src/interactor_impl.cxxset内部调用f3d::options::set系方法print使用Options.getAsString(args[0])输出set_reader_option内部调用f3d::engine::setReaderOption(args[0], args[1])见set_reader_option注册处并支持对 reader 选项名自动补全print命令带有complOptionNames补全器可在交互式控制台中按Tab补全选项名。场景与渲染信息类命令命令说明print_scene_info打印场景信息无参数print_coloring_info打印着色coloring设置信息无参数print_mesh_info打印网格导入器提供的信息无参数print_options_info打印当前有值的 libf3d 选项无参数print_config_info打印配置文件信息无参数对应的测试application/testing/tests.features.cmake验证了这些命令的输出例如TestCommandScriptPrintScene检查Camera position: 2.23745, 3.83305, 507.598TestCommandScriptPrintMesh检查Number of points: 13268TestCommandScriptPrintOptions检查interactor.invert_zoom: falseTestCommandScriptPrintColoring检查Not coloringTestCommandScriptPrintConfig检查Found available config path。这些断言可以直接用作脚本输出的期望值参考。相机操作类命令命令说明示例roll_camera value让相机绕自身轴滚动参数为角度度roll_camera 120elevation_camera value相机上下俯仰参数为角度度elevation_camera 120azimuth_camera value相机左右旋转方位角参数为角度度azimuth_camera 120set_camera front/top/right/back/bottom/left/isometric将相机定位到相对模型指定方位set_camera topreset_camera将相机重置到初始位置无参数—源码细节roll_camera在interactor_impl.cxx中实现为Window.getCamera().roll(options::parseint(args[0]))且当交互风格为2d时直接返回2D 模式下不生效执行后还会调用Style-SetTemporaryUp(...)同步临时上方向。按键绑定层中数字键4/6分别绑定了roll_camera -90/roll_camera 90见 library/src/interactor_impl.cxx 中addBinding部分。着色Scivis相关命令命令说明cycle_coloring field/array/component基于模型信息循环切换着色方式支持field、array、component三种参数详见 着色循环toggle_volume_rendering切换model.volume.enable并打印着色信息无参数源码细节cycle_coloring在 interactor_impl.cxx 中通过vtkF3DRenderer的CycleFieldForColoring()/CycleArrayForColoring()/CycleComponentForColoring()实现参数不合法时抛出invalid_args_exception执行后调用SynchronizeScivisOptions同步选项并以 DEBUG 级别打印着色描述。默认按键绑定中C/S/Y分别触发cycle_coloring field/cycle_coloring array/cycle_coloring component。动画控制类命令命令说明示例cycle_animation基于模型信息循环scene.animation.index选项无参数—toggle_animation开始/停止动画无参数—toggle_animation_backward开始/停止反向播放动画无参数—jump_to_frame跳到指定帧参数为帧索引jump_to_frame 0第 0 帧、jump_to_frame -1最后一帧、jump_to_frame -2倒数第二帧jump_to_frame_relative相对当前帧移动若干帧参数为帧偏移jump_to_frame_relative 1下一帧、jump_to_frame_relative -1上一帧jump_to_keyframe跳到指定关键帧参数为关键帧索引jump_to_keyframe 0动画起始帧、jump_to_keyframe 10第 10 个关键帧jump_to_keyframe_relative相对当前关键帧移动参数为关键帧偏移jump_to_keyframe_relative 0最近关键帧、jump_to_keyframe_relative 1下一关键帧、jump_to_keyframe_relative -1上一关键帧、jump_to_keyframe_relative 10前进 10 个关键帧jump_to_time跳到指定时间参数为秒jump_to_time 2.5jump_to_time_relative相对当前时间移动参数为秒偏移jump_to_time_relative 0.5前进 0.5 秒、jump_to_time_relative -0.5后退 0.5 秒jump_to_keyframe/jump_to_keyframe_relative在跳转时会把目标关键帧索引自动约束在可用关键帧总数范围内避免非法访问。目前这两条命令仅被以下 reader 支持vtkF3DGLTFImportervtkF3DQuakeMDLImporter其他 reader 的动画时间步支持进展可跟踪 F3D 项目的动画系统改进 IssueF3D Issue #2637。源码中jump_to_frame等命令经由AnimationManager-JumpToFrame(frame, relative)/JumpToTime(time, relative)实现见 library/src/interactor_impl.cxx 中jump_to_frame等注册处。关于帧号负数的约定负索引表示从末尾倒数例如-1是最后一帧、-2是倒数第二帧相对偏移中0表示跳到最近的关键帧。文件与状态管理类命令libf3d 层libf3d 提供以下命令但它们会被 F3D 应用层的同名命令覆盖见下文命令说明add_files [path/to/file1] [path/to/file2]向场景添加文件可接一个或多个文件save_statefile [path/to/file]将当前状态保存到指定 statefileload_statefile [path/to/file]从指定 statefile 恢复状态save_statefile_to_clipboard将当前状态保存到系统剪贴板需要启用clip模块构建load_statefile_from_clipboard从系统剪贴板恢复状态需要启用clip模块构建其他工具类命令命令说明示例clear清空控制台无参数—cycle_verbose_level在Debug、Info、Warning、Error、Quiet之间循环切换日志级别无参数—alias [alias_name] [command]为某条命令创建别名alias myrotate roll_camera 90help [command]打印指定命令的帮助信息help set_camerastop_interactor停止交互器并退出应用无参数—源码细节alias命令在interactor_impl.cxx中注册作用是把一个命令名映射到一串命令文本之后即可直接调用别名help会输出注册命令时的command_documentation_t描述。测试TestCommandScriptHelp检查help set输出包含set a libf3d optionTestCommandScriptAlias则直接执行alias myrotate roll_camera 90后调用myrotate见 testing/scripts/TestCommandScriptAlias.txt 与 application/testing/tests.features.cmake。F3D 应用层提供的专用命令F3D 应用application/F3DStarter.cxx在 libf3d 命令之上额外提供了以下命令主要涉及文件组管理、截图、状态文件与文件对话框文件组File Group管理命令说明load_previous_file_group [keep_camera]加载上一个文件或文件组keep_camera为true时保持相机状态默认falseload_next_file_group [keep_camera]加载下一个文件或文件组相机保持规则同上reload_current_file_group重新加载当前文件或文件组无参数add_current_directories将当前文件/文件组所在目录下的所有文件加入场景无参数add_files [path/to/file1] [path/to/file2]按当前分组逻辑向场景添加文件覆盖 libf3d 同名命令可接一个或多个文件remove_current_file_group移除当前文件组并加载下一个文件组如果有无参数remove_file_groups移除所有文件无参数注意load_previous_file_group的参数最多为 1 个TestCommandScriptParseOptionalBoolExtraArg测试验证了传入多余参数会报错Command: load_previous_file_group takes at most 1 argument, got 2 arguments instead.见 application/testing/tests.features.cmake。相关测试包括TestCommandScriptResetreset render.show_edges; load_next_file_group、TestCommandScriptRemoveCurrentFileGroup、TestCommandScriptRemoveFileGroups见 application/testing/tests.features.cmake。截图命令命令说明take_screenshot [filename]截图未指定文件名时使用--screenshot-filenameCLI 选项take_minimal_screenshot [filename]截取最小化截图未指定文件名时同样回退到--screenshot-filename截图方式详见 截图交互示例take_screenshot path/to/file.png。文件对话框与 HDRI命令说明open_file_dialog打开文件对话框选择要加载的文件无参数set_hdri [path/to/hdri]设置并使用 HDRI 图像参数为 HDRI 文件add_files_or_set_hdri [path/to/file1] [path/to/file2]逐个处理文件若文件扩展名是已识别的 HDR 扩展则执行set_hdri否则执行add_files示例set_hdri /path/to/file.hdr、add_files_or_set_hdri /path/to/dragon.vtu /path/to/file.hdr。状态文件Statefile管理F3D 层命令说明save_statefile [filename]保存当前状态到 statefile包含所有文件组包括未加载的未指定文件名时使用--statefile-filenameCLI 选项为空则使用默认文件名使用-输出到标准输出save_statefile_dialog通过文件对话框选择保存位置需要启用tinyfiledialogs模块构建load_statefile [filename]从 statefile 恢复状态恢复所有已保存的文件组并重新加载当前文件组未指定文件名时规则同上使用-从标准输入读取文件不存在时仅警告不报错load_statefile_dialog通过文件对话框选择 statefile 恢复需要启用tinyfiledialogs模块构建save_statefile_to_clipboard保存状态到系统剪贴板需要启用clip模块构建load_statefile_from_clipboard从系统剪贴板恢复状态并重新加载文件需要启用clip模块构建示例save_statefile path/to/state.json、load_statefile path/to/state.json。选项域Domainsincrease / decrease / cycle 的底层机制部分 libf3d 选项带有域domain命令系统据此提供了三种操作方式见 doc/user/07-COMMANDS.md 的 Domains 一节范围域Range domain通过increase/decrease操作。具有包含的最小值和最大值以及一个增量。increase/decrease按增量增减并在达到最大/最小值处截断。枚举域Enum domain通过cycle操作。只列出选项可能的取值cycle依次遍历并在到达末尾后循环回起点。索引域Index domaincycle与increase/decrease均可使用。对increase/decrease它等价于一个[0, max]范围域增量为 1对cycle它等价于一个包含 0 到 max 之间所有取值的枚举域。例如increase render.light.intensity会按域定义逐步提升光照强度cycle render.effect.blending.mode会在混合模式枚举间循环。域的定义与解析可以在 doc/libf3d/03-OPTIONS.md 与library/private/options_generated.h.in/library/src/options.cxx中追溯测试方面TestSDKOptionsDomains.cxxlibrary/testing/TestSDKOptionsDomains.cxx覆盖了域相关行为。命令脚本--command-scriptF3D 支持通过--command-scriptCLI 选项 从脚本文件执行命令序列便于自动化f3d --command-script path/to/command_script.txt。脚本规则命令之间以换行分隔支持注释。官方示例# A comment roll_camera 90 toggle ui.scalar_bar print_scene_info # Another comment increase_light_intensity仓库中真实的脚本示例testing/scripts/TestCommandScriptBasic.txt# A comment at the beginning of the script roll_camera 90 # A comment at the end of a command toggle ui.scalar_bar # A comment in the middle of the script print_scene_info脚本执行流程源码依据 application/F3DStarter.cxxF3D 启动时若指定了--command-script会打开脚本文件并逐行std::getline读取对非空行调用interactor.triggerCommand(command)任一条命令执行失败即输出错误日志并停止后续执行文件无法打开时输出Unable to open command script file并返回失败。对应测试见 application/testing/tests.features.cmakeTestCommandScriptMissingFile验证了文件打不开时的报错路径。交互式控制台Interactive Console当 F3D 以F3D_MODULE_UI构建时交互窗口中按Esc即可打开控制台在输入框中输入任意命令按Enter立即执行按Tab自动补全命令并显示建议选项名、reader 选项名等均支持补全按↑/↓在命令历史中上下浏览再次按Esc关闭控制台。结合前文可知控制台内的补全能力由interactor_impl.cxx中每个命令注册时挂载的补全器提供如complOptionNames、reader 选项名补全等。从测试与绑定看命令的实战组合命令系统不仅在脚本与控制台中直接使用还被按键绑定大量复用。interactor_impl.cxx中的addBinding把命令与默认按键关联例如C→cycle_coloring field、S→cycle_coloring array、Y→cycle_coloring component、4→roll_camera -90、6→roll_camera 90。也就是说你看到的交互层“快捷键”本质上就是命令这也解释了命令文档与 交互文档 之间的对应关系。仓库中大量TestCommandScript*.txt见 testing/scripts 目录展示了命令的典型组合例如TestCommandScriptJumpToPreviousKeyFrame.txt、TestCommandScriptJumpToClosestKeyFrame.txt等覆盖jump_to_keyframe*系列配合soldier_animations.mdl与--animation-indices2等参数TestCommandScriptCycleCameraIndex.txt、TestCommandScriptIncreaseDecreaseCameraIndex.txt覆盖相机索引切换TestCommandScriptAxesGridAnimation.txt结合--axes-grid使用。这些脚本直接位于testing/scripts/可作为自动化场景下的参考模板。小结F3D 的命令系统以action [args]为统一语法提供三大入口交互式控制台、命令脚本、按键绑定配置覆盖选项读写set/toggle/reset/print/increase/decrease/cycle、相机控制、着色循环、动画跳转、文件组管理、截图与状态文件等能力。掌握这套命令体系意味着你可以在交互窗口中即时探索并修改任意选项用--command-script将重复性操作固化为可复用的自动化脚本配合 CI/测试在 配置文件 中自定义按键绑定把常用命令映射到顺手的位置。由于命令系统仍处于实验阶段建议在实际使用中通过help command查询当前构建下的命令帮助并以本仓库当前版本的源码library/src/interactor_impl.cxx与测试脚本为准。【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3d创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考