Configuration File

Options

Almost all the command-line options can be controlled using configuration files. Configuration files uses the “long” version of the command-line options in a JSON formatted file to provide values for these options. It is also possible to use the libf3d options syntax.

These options can be organized by block using a regular expression for each block in order to provide different default values for the different filetypes.

Using a command-line option will override similar option set in any config files.

Some options are only taken into account on the first load and not on subsequent loads, when switching between files.

A typical config file with options may look like this:

[
{
  "options":
  {
     "background-color": "0.7,0.7,0.7",
     "color": "0.5,0.1,0.1",
     "anti-aliasing": true,
     "timer": true,
     "progress": true,
     "axis": true,
     "bar": true,
     "roughness": 0.2,
     "grid": true,
     "scalar-coloring": true
  }
},
{
  "match": ".*vt.",
  "options":
  {
    "edges": true
  }
},
{
  "match": ".*gl(tf|b)",
  "options":
  {
    "raytracing": true,
    "denoise": true,
    "samples": 3
  }
},
{
  "match": ".*mhd",
  "options":
  {
    "volume": true
  }
}
]

Here, the first block defines a basic configuration with many desired options for all files. The second block specifies that all files ending with vt., eg: vtk, vtp, vtu, … will be shown with edges visibility turned on. The third block specifies raytracing usage for .gltf and .glb files. The last block specifies that volume rendering should be used with .mhd files.

The following options cannot be set via config file: help, version, readers-list, config, dry-run and input.

The following options are only taken on the first load: no-render, output, position, resolution, frame-rate and all testing options.

Boolean options that have been turned on in the configuration file can be turned off on the command line if needed, eg: --point-sprites=false.

Bindings

All interaction bindings can be configured using configuration files. The logic is the same as with options, where configuration blocks are used depending on the filename being loaded using regular expression. A bindings block can be added to specify associations between binds (eg : Ctrl+O) and one or multiple commands.

A typical config file with bindings may look like this:

[
{
  "bindings":
  {
    "Ctrl+Shift+O": "toggle ui.filename",
    "Any+3": "roll_camera -90",
    "O": "set_camera isometric"
  }
},
{
  "match": ".*vtu",
  "bindings":
  {
    "Any+3": "roll_camera 90",
    "Shift+O": "toggle model.point_sprites.enable",
    "Ctrl+O": ["toggle render.grid.enable", "toggle scene.camera.orthographic"],
    "None+I": "toggle ui.axis"
  }
}
]

Here, the first block define new bindings for all and any files. It even replace an existing default interaction on the O key with its own. Each bind is associated to the command to execute when it is pressed.

In the second block, new bindings are defined for files ending in .vtu, and there bindings will only be available when loading such a file. In the first config block, we define bindings for all and any files. It also replace an existing default interaction on the Any+3 bind and even define a bindings that have multiple commands using a json array on the Ctrl+O bind.

Please note this configuration feature is only available through config file and not through the command line. However, it is possible to check your current binding configuration by using the --bindings-list CLI options.

Bind

A bind is the association of a modifier and an interaction.

Supported modifiers are:

None : No modifiers is pressed, can be omitted completely. Ctrl : Control key is pressed, no distinction between left and right. Shift : Shift key is pressed, no distinction between left and right. Ctrl+Shift : Control and Shift keys are pressed, no distinction between left and right. Any : A special modifier that does not consider modifiers keys but can only be reached if there is no bind with the same interaction.

Supported interactions are legion, eg:

  • Keyboard letter keys, eg:
    • O
    • P
  • Keyboard number keys, eg:
    • 2
    • 5
  • Keyboard special keys, eg:
    • Enter
    • Delete
  • Other interactions, eg:
    • Drop when files or folders are dropped on F3D window

To identify the interaction to use, just use f3d --verbose and perform the interaction, F3D will log it like this:

Interaction: KeyPress Ctrl+Shift+Insert

Please note that the interaction itself can be modified by the modifiers, hence some binds may be unreachable depending on your keyboard layout, eg. on a QWERTY layout, the bind Exclam is unreachable while Shift+Exclam is reachable. We tried to make the default bindings of F3D to be a keyboard layout independent as possible, but feel free to redefined them for your needs.

Locations

Single .json file for configuration is supported, as well a config directory containing multiple .json config files. In the case of config directory, .json file are read in alphabetical order and an option or binding in a block can be overridden by the same option or bind being set in another block in another .json file read after.

F3D provides a default config directory for generic usage (config.d) and a thumbnail specific config directory (thumbnail.d). You can edit the file contained in these directory or add your own in specific directories (see below).

F3D looks for configuration files in different locations depending on your operating system. Existing configuration files are read in order and combined with later entries, potentially overriding previously read entry with the same names.

  • Linux: /etc/f3d/config(.json,.d), /usr/share/f3d/configs/config(.json,.d), [install_dir]/share/f3d/configs/config(.json,.d), ${XDG_CONFIG_HOME}/f3d/config(.json,.d)
  • Windows: [install_dir]\share\f3d\configs\(config.json,.d), %APPDATA%\f3d\(config.json,.d)
  • macOS: /usr/local/etc/f3d/config(.json,.d), f3d.app/Contents/Resources/configs/config(.json,.d), ${XDG_CONFIG_HOME}/f3d/config(.json,.d)

Please note XDG_CONFIG_HOME rely on environment variables as specified here.

The binary release will install the default config directory. On Linux, they will be installed in [install_dir]/share/f3d/configs/, on Windows, they will be installed in [install_dir]\share\f3d\configs\, on macOS, it will be installed in the bundle.

Please note there is a command line option to control the configuration file to read. Using it, one can specify an absolute/relative path for the configuration path, but also only the filename or filestem (.json and .d will be added) to look for in the locations listed above, , eg: f3d --config=custom_config will look for custom_config.json and custom_config.d in locations listed above. When specifying an absolute/relative path for the configuration file, a single file is read. If not, all files from locations listed above, with the overriding logic specified above.