Commands

F3D provides access to commands through interactive console, command script and bindings configuration. Commands let you trigger specific behavior that may not be available otherwise. Please note commands are currently experimental and the behaviors, actions may be added or removed without deprecation. Action names and arguments may also change without deprecation.

Commands have the following syntax:

action [args]

libf3d provided commands

The libf3d provides a few commands, many related to manipulating libf3d (options)[../libf3d/03-OPTIONS.md].

set option.name values: A command to set a libf3d option, eg: set scene.up.direction +Z or set render.hdri.file "/path/to/file with spaces.png"

toggle option.name: A command to toggle a boolean libf3d option, eg: toggle ui.scalar_bar.

reset option.name: A command to reset a libf3d option to its default values, eg: reset render.background.blur.coc.

clear: A command to clear console. No argument.

print option.name: A command to print the value of an libf3d option, eg: print scene.up.direction.

set_reader_option Reader.option_name value: A specific command to set a reader option, eg: set_reader_option QuakeMDL.skin_index 1

increase option.name: A command to increase a libf3d option according to its range domain, if it has one, eg: increase render.light.intensity.

decrease option.name: A command to decrease a libf3d option according to its range domain, if it has one, eg: decrease render.light.intensity.

cycle option.name: A command to cycle a libf3d option according to its enumeration domain, if it has one, eg: cycle render.effect.blending.mode.

cycle_animation: A specific command to cycle scene.animation.index option using model information. No argument.

cycle_coloring field/array/component: A specific command to manipulate scivis options using model information. Supports field, array or component arguments, see documentation. eg: cycle_coloring array.

roll_camera value: A specific command to roll the camera on its side, takes an angle in degrees as an argument. eg: roll_camera 120.

elevation_camera value: A specific command to tilt the camera up or down, takes an angle in degrees as an argument. eg: elevation_camera 120.

azimuth_camera value: A specific command to tilt the camera right or left, takes an angle in degrees as an argument. eg: azimuth_camera 120.

print_scene_info: A specific command to print information about the scene. No argument.

print_coloring_info: A specific command to print information about coloring settings. No argument.

print_mesh_info: A specific command to print information from the mesh importer. No argument.

print_options_info: A specific command to print libf3d options that have a value. No argument.

print_config_info: A specific command to print config file information. No argument.

set_camera front/top/right/back/bottom/left/isometric: A specific command to position the camera in the specified location relative to the model. Supports front, top, right, back, bottom, left, isometric arguments. eg: set_camera top.

toggle_volume_rendering: A specific command to toggle model.volume.enable and print coloring information. No argument.

stop_interactor: A specific command to stop the interactor hence quitting the application. No argument.

reset_camera: A specific command to reset the camera to its original location. No argument.

toggle_animation: A specific command to start/stop the animation. No argument.

toggle_animation_backward: A specific command to start/stop the animation backward. No argument.

jump_to_frame: A specific command to load an animation at a specific frame, takes a frame index as argument. eg:

• jump_to_frame 0 jump to frame 0.
• jump_to_frame 1 jump to frame 1.
• jump_to_frame 10 jump to frame 10.
• jump_to_frame -1 jump to last frame.
• jump_to_frame -2 jump to second last frame.

jump_to_frame_relative: A specific command to move the animation by a number of frames relative to the current frame, takes a frame offset as argument. eg:

• jump_to_frame_relative 1 jump to next frame.
• jump_to_frame_relative -1 jump to previous frame.

jump_to_keyframe: A specific command to load an animation at a specific keyframe, takes a keyframe index as argument. When jumping to a keyframe, the target keyframe index is adjusted to stay within the total number of available keyframes, avoiding invalid keyframe access. eg:

• jump_to_keyframe 0 jump to animation start frame.
• jump_to_keyframe 1 jump to keyframe 1.
• jump_to_keyframe 10 jump to keyframe 10.

jump_to_keyframe_relative: A specific command to move the animation by a number of keyframes relative to the current keyframe, takes a keyframe offset as argument. When jumping between keyframes, the target keyframe index is adjusted to stay within the total number of available keyframes, avoiding invalid keyframe access. eg:

• jump_to_keyframe_relative 0 jump to closest keyframe.
• jump_to_keyframe_relative 1 jump to next keyframe.
• jump_to_keyframe_relative -1 jump to previous keyframe.
• jump_to_keyframe_relative 10 jump 10 keyframes ahead.

The jump_to_keyframe* commands are currently supported only by the following readers :

• vtkF3DGLTFImporter
• vtkF3DQuakeMDLImporter

You can follow the issue below to track the progress of animation support for other readers: F3D Issue – Improve Animation System #2637

jump_to_time: A specific command to load an animation at a specific time, takes a time in seconds as argument. eg:

• jump_to_time 2.5 jump to time 2.5 seconds.

jump_to_time_relative: A specific command to move the animation by a number of seconds relative to the current time, takes a time offset as argument. eg:

• jump_to_time_relative 0.5 jump 0.5 seconds forward.
• jump_to_time_relative -0.5 jump 0.5 seconds backward.

cycle_verbose_level : A specific command to cycle between the verbose levels (Debug, Info, Warning, Error, Quiet).

add_files [path/to/file1] [path/to/file2]: A specific command to add files to the scene (overridden by a F3D specific command, see below). Take one or more files as arguments. eg: add_files /path/to/dragon.vtu.

save_statefile [path/to/file]: A specific command to save the current state into the provided statefile (overridden by a F3D specific command, see below). Take a file as argument. eg: save_statefile /path/to/state.json.

load_statefile [path/to/file]: A specific command to restore the state from the provided statefile (overridden by a F3D specific command, see below). Take a file as argument. eg: load_statefile /path/to/state.json.

save_statefile_to_clipboard: A specific command to save the current state into the system clipboard (overridden by a F3D specific command, see below). Requires a build with the clip module. No argument.

load_statefile_from_clipboard: A specific command to restore the state from the system clipboard (overridden by a F3D specific command, see below). Requires a build with the clip module. No argument.

alias [alias_name] [command]: A specific command to create an alias for a command. Take an alias name and a command as arguments. eg: alias myrotate roll_camera 90.

help [command]: A specific command to print help about a specific command. eg: help set_camera`.

F3D provided specific commands

The F3D application provides a few more commands.

exit: A specific command to quit the application. No argument.

load_previous_file_group [keep_camera]: A specific command to load the previous file or file group. Camera state is kept if keep_camera is true (default: false).

load_next_file_group [keep_camera]: A specific command to load the next file or file group. No argument. Camera state is kept if keep_camera is true (default: false).

reload_current_file_group: A specific command to reload the current file or file group. No argument.

add_current_directories: A specific command to add all files from the current file or file group directories. No argument.

take_screenshot [filename]: A specific command to take a screenshot. If filename is not specified, rely on the --screenshot-filename CLI option. eg: take_screenshot path/to/file.png.

take_minimal_screenshot [filename]: A specific command to take a minimal screenshot. If filename is not specified, rely on the --screenshot-filename CLI option. eg: take_screenshot path/to/file.png.

add_files [path/to/file1] [path/to/file2]: A specific command to add files to the scene according to the current grouping logic. Take one or more files as arguments. eg: add_files /path/to/dragon.vtu.

set_hdri [path/to/hdri]: A specific command to set and use an HDRI image. Take a HDRI file as an argument. eg: set_hdri /path/to/file.hdr.

add_files_or_set_hdri [path/to/file1] [path/to/file2]: A specific command that will process each files and either, set_hdri if the provided file uses a recognised HDR extension or add_files otherwise. Take one or more files as arguments. eg: add_files_or_set_hdri /path/to/dragon.vtu /path/to/file.hdr.

remove_current_file_group: A specific command to remove current file group and load the next file group if any. No argument.

remove_file_groups: A specific command to remove all files. No argument.

open_file_dialog: A specific command to open a file dialog to selected a file to load. No argument.

save_statefile [filename]: A specific command to save the current state into a statefile, including all file groups (also the ones not currently loaded). If filename is not specified, rely on the --statefile-filename CLI option, or a default filename when it is empty too. Use - for the standard output. eg: save_statefile path/to/state.json.

save_statefile_dialog: A specific command to save the current state into a statefile picked with a file dialog. Requires a build with the tinyfiledialogs module. No argument.

load_statefile [filename]: A specific command to restore the state from a statefile, restoring all saved file groups and reloading the current one. If filename is not specified, rely on the --statefile-filename CLI option, or a default filename when it is empty too. Use - for the standard input. Does nothing but warn if the file does not exist. eg: load_statefile path/to/state.json.

load_statefile_dialog: A specific command to restore the state from a statefile picked with a file dialog. Requires a build with the tinyfiledialogs module. No argument.

save_statefile_to_clipboard: A specific command to save the current state into the system clipboard. Requires a build with the clip module. No argument.

load_statefile_from_clipboard: A specific command to restore the state from the system clipboard, reloading the saved files. Requires a build with the clip module. No argument.

Domains

Certain libf3d (options)[../libf3d/03-OPTIONS.md] have domains which can be interacted with using commands.

A range domain is used through increase and decrease commands, it has inclusive minimum and maximum, as well as an increment. increase and decrease use increment to increase/decrease and cap at maximum/minimum respectively.

An enum domain is used through cycle command, it just list possible values of the option. cycle just iterate over the different possible values and loops when reaching the end.

An index domain can be used through both cycle and increase/decrease commands. For increase/decrease, it behaves like a range domain [0, max] with an increment of 1. For cycle, it behave like an enum domain containing all possible values between o and max.

Command Script (--command-script)

F3D provides a feature to execute commands from a script file using the --command-script CLI option. This allows users to automate a sequence of commands by listing them in a plain text file, eg: f3d --command-script path/to/command_script.txt.

Example Command Script, commands are separated by new lines, comments are supported:

# A comment
roll_camera 90
toggle ui.scalar_bar
print_scene_info # Another comment
increase_light_intensity

Interactive Console

If F3D is built with F3D_MODULE_UI support, pressing Esc will open the console. It's possible to type any command in the input field and pressing Enter will trigger the command instantly.

Press Tab to autocomplete the command and display suggestions.

Press ↑ and ↓ to navigate through the command history.

Press Esc to close the console.

Command syntax

Command syntax is similar to bash, as in they will be split by "token" to be processed.

• Tokens are spaces separated, eg: set scene.up.direction +Z.
• Tokens can also be quoted to support spaces inside, eg: set render.hdri.file "/path/to/file with spaces.png".
• Supported quotes are `'", eg: set render.hdri.file '/path/to/file with spaces.png'.
• Quotes inside quotes are supported as well, eg: set render.hdri.file "/path/to/file'with'quotes.png".
• Quotes and spaces can be escaped, eg: set render.hdri.file /path/to/file\ with\ spaces\ and\ \'quotes\".png.
• Comment are supported using #, Any character after will be ignored. Use \# to add it verbatim.

note

Comments are only supported in command script, in interactive console # and all characters after will be handled as standard character.

• Escapes can be escaped too: eg: set render.hdri.file C:\\path\\to\\windows\\file.png.
• Other escaped character will be processed as if the escape was not present, eg: set scene.up.direction +\Z
• Unfinished quoted section is invalid, eg: set scene.up.direction "+Z
• A escape at the end is also invalid, eg: set scene.up.direction +Z\
• Options values are parsed according to their types.