Version: 🚧 Nightly

Command-line options

Control F3D behavior from the command-line using the following options. Option headings use command-line spelling and show the accepted value type, default value, and implicit value when those exist. In the configuration files, use command-line option names without the leading --, or use the libf3d option names documented in the libf3d options reference.

Application options

`--input``=<input file>` (string)

The input file or files to read, can also be provided as a positional argument. Support directories as well. If - is specified instead of a filename, F3D streams the file from stdin and waits until a stream is provided.

`--output``=<png file>` (string)

Instead of showing a render view and render into it, render directly into a png file. When used with the --reference option, only outputs on failure. If - is specified instead of a filename, F3D streams the PNG file to stdout. You can also use template variables. When using the {frame} variable, F3D exports multiple animation frames (see Export animation frames).

`--output-video``=<video file>` (string)

Instead of showing a render view and render to it, render directly into a video file. If - is specified instead of a filename, the video file is streamed to the stdout. The resulting file contains raw video frames and can be converted to a video container (e.g. MP4) using FFmpeg for example.

`--no-background` (bool, default: `false`)

Use with --output to output a png file with a transparent background.

`--no-cache` (bool, default: `false`)

No cache is used (both reading and writing). Cache is currently used to save and restore last window size and position. It's also used to save and restore HDRI related information.

`-h`, `--help`

Print help and exit. Ignore --verbose.

`--version`

Show version information and exit. Ignore --verbose.

`--list-readers`

List available readers and exit. Ignore --verbose.

`--force-reader``=<reader>` (string)

Force a specific reader to be used, disregarding the file extension and file content.

`--skip-content-check` (bool, default: `false`)

Select reader to read file without checking its header content, but only based on the file extension.

`--list-bindings`

List available bindings and exit. Ignore --verbose.

`--list-rendering-backends`

List available rendering backends and exit. Ignore --verbose.

`--list-video-encoders`

List available video encoders and exit. Ignore --verbose.

`--video-encoder` (string)

Specify the encoder to use when using --output-video. Use --list-video-encoders to list encoders available on your system.

`--video-bitrate` (double, default: `5.0`)

Specify the video encoder bitrate in Mbps. Higher means better quality but larger video stream.

`--video-low-latency` (bool, default: `false`)

Specify if the video encoder should reduce latency by emitting packets as soon as possible. Set this to true in case of real time streaming, otherwise leave it to false to have the best quality possible.

`--config``=<config file path/name/stem>` (string, default: `config`)

Specify the configuration file to use. Supports absolute/relative path but also filename/filestem to search for in standard configuration file locations.

`--no-config` (bool, default: `false`)

Do not read any configuration file and consider only the command-line options.

`--no-render` (bool, default: `false`)

Do not render anything and quit just after loading the first file, use with --verbose to recover information about a file.

`--load-statefile``=<file path>` (string)

Restore the F3D state from a statefile right after starting, then continue running. F3D applies the statefile above configuration files but below command-line options. An explicit --resolution overrides the restored window size, and an explicit --position overrides the restored window position. If - is specified instead of a filename, F3D reads the statefile from the standard input. If the file does not exist, F3D skips it with a warning.

`--save-statefile``=<file path>` (string)

Save the F3D state to a statefile right after loading, then continue running. The saved state includes the options, camera, window size and all file groups, including the ones not currently loaded. Supports the same template variables as --output. If - is specified instead of a filename, F3D writes the statefile to the standard output.

`--statefile-filename``=<file path>` (string, default: empty)

Default filename used by the save_statefile and load_statefile commands when none is provided, resolved relative to the current working directory. Supports the same template variables as --output. If - is specified instead of a filename, F3D writes the statefile to the standard output (save) or reads from the standard input (load). When left empty, the save_statefile and load_statefile commands fall back to a default filename; picking a file through a dialog is instead available with the dedicated save_statefile_dialog and load_statefile_dialog commands (requires a build with the tinyfiledialogs module).

`--max-size``=<size in MiB>` (int, default: `-1`)

Prevent F3D to load a file bigger than the provided size in Mib, leave empty for unlimited, useful for thumbnails.

`--watch` (bool, default: `false`)

Watch current file and automatically reload it whenever it is modified on disk. Consider ensuring --remove-empty-file-groups is not enabled when using this option.

`--frame-rate``=<fps>` (double, default: `30.0`)

Frame rate used to refresh animation and other repeated tasks (watch, UI). Does not impact rendering frame rate.

`--load-plugins``=<paths or names>` (string)

List of plugins to load separated with a comma. Official plugins are alembic, assimp, draco, hdf, occt, pdal, usd, vdb, webifc. See the plugin documentation for more info.

`--plugins-path``=<path>` (string)

Supplementary path to specify where to load plugins from, on top of default paths.

`--scan-plugins`

Scan standard directories for plugins and display their names. Results may be incomplete. See the plugin documentation for more info.

`--screenshot-filename``=<png file>` (string, default: `{app}/{model}_{n}.png`)

Filename to save screenshots to. Can use template variables. Supports relative screenshot paths.

`--rendering-backend``=<auto|egl|osmesa|glx|xr|wgl>` (string, default: `auto`)

Rendering backend to load, auto means to let F3D pick the correct one for you depending on your system capabilities. Use egl or osmesa to force headless rendering. Use rendering-backend=xr to specify F3D should use the xr rendering backend, referred in this doc as "XR mode". See rendering backends.

`-D`, `--define``=<libf3d.option=value>` (special)

A repeatable option to set libf3d and reader option manually. May trigger unexpected behavior.

`-R`, `--reset``=<libf3d.option>` (special)

A repeatable option to reset libf3d options manually. Useful when overidding option set in configuration files.

General options

`--verbose``=<[debug|info|warning|error|quiet]>` (string, default: `info`, implicit: `debug`)

Set verbose level to provide more information about the loaded data in the output. Error reporting during option parsing may ignore this flag.

`--loading-progress` (bool, default: `false`)

Show a progress bar when loading the file.

`--animation-progress``=<none|default|advanced>` (string, default: `none`, implicit: `default`)

Control the progress bar shown when playing the animation. Use none (hidden), default (only the progress bar, which can be clicked or dragged to jump to a time) or advanced (the progress bar plus time range, animation name and current time labels, with a marker for each key frame).

`--multi-file-mode``=<single|all| dir>` (string, default: `single`)

When opening multiple files, select if F3D shows them all at once (all), one by one (single), or by directory (dir). F3D uses configuration files for all loaded files in the order they are provided.

`--multi-file-regex``=<regex>` (string)

Regular expression pattern to group files. Captured groups are replaced with * so that, for example, the pattern part(\d+) would group files foo-part1.xyz and foo-part2.xyz together as foo-part*.xyz.

`--recursive-dir-add` (bool, default: `false`)

When opening a directory, choose if F3D adds files recursively. If not, F3D adds only the files in the provided directory.

`--remove-empty-file-groups` (bool, default: `false`)

When loading a file group, if they results in an empty scene, remove the file group and load the next file group.

`--up``=<direction>` (direction, default: `+Y`)

Define the Up direction.

+Y	+Z

`-x`, `--axis` (bool, default: `false`)

Show axes as a trihedron in the scene.

`--x-color` (color, default: `f3d_red`)

Set the X axis color in both widget and grid.

`--y-color` (color, default: `f3d_green`)

Set the Y axis color in both widget and grid.

`--z-color` (color, default: `f3d_blue`)

Set the Z axis color in both widget and grid.

`-g`, `--grid` (bool, default: `false`)

Show a grid aligned with the horizontal (orthogonal to the Up direction) plane.

`--grid-unit``=<length>` (double)

Set the size of the unit square for the grid. If not set (the default), F3D automatically computes a suitable value.

`--grid-subdivisions``=<count>` (int, default: `10`)

Set the number of subdivisions for the grid.

`--grid-color``=<color>` (color, default: `0,0,0`)

Set the color grid lines.

`--grid-opacity``=<opacity>` (double, default: `1`)

Set the opacity for grid lines. Can be set to 0 to show reflection only.

`--grid-reflection``=<strength>` (double, default: `0`)

Set the reflection strength on the grid.

`--grid-absolute` (bool, default: `false`)

Position the grid at absolute origin instead of below the model. Forced to true if XR mode is enabled.

`--axes-grid` (bool, default: `false`)

Show axes grid in the scene.

`-e`, `--edges` (bool, default: `false`)

Show the cell edges.

`--armature` (bool, default: `false`)

Show armature if present.

`--camera-index``=<idx>` (int)

Select the scene camera to use when available in the file. Automatically computed by default.

`-k`, `--interaction-style``=<default|trackball|2d>` (string, default: `default`)

Set the interaction style. default uses standard 3D interaction, trackball enables trackball interaction, 2d enables 2D interaction mode (pan/zoom only, no rotation). In 2d mode, the default camera zoom factor is 1.0 (no padding) instead of 0.9.

`--invert-zoom` (bool, default: `false`)

Invert zoom direction with right mouse click.

`--animation-autoplay` (bool, default: `false`)

Automatically start animation.

`--animation-indices``=<idx1,idx2>` (vector<int>, default: `0`)

Select the animations to show. Any negative value all animations. The default scene always has at most one animation.

`--animation-speed-factor``=<ratio>` (ratio, default: `1`)

Set the animation speed factor to slow, speed up or even invert animation time.

`--animation-time``=<time>` (double)

Set the animation time to load.

`--font-file``=<font file>` (path)

Use the provided FreeType compatible font file to display text. Can be useful to display non-ASCII filenames.

`--font-scale``=<ratio>` (ratio, default: `1.0`)

Scale fonts. Useful for HiDPI displays.

`--font-color``=<color>` (color, default: `0.957,0.957,0.957`)

Set font color. Defaults to #F4F4F4(F3DWhite).

`--dpi-aware` (bool, default: `false`)

Scale the font scale and resolution by the display scaling factor.

`--command-script``=<command script>` (script)

Provide a script file containing a list of commands to be executed sequentially. Allows automation of multiple commands or pre-defined tasks. Run before --interaction-test-play.

`--backdrop-color``=<color>` (color, default: `f3d_black`)

Set the color of the backdrop behind text information such as FPS Counter, Filename, Metadata, or Cheatsheet.

`--backdrop-opacity``=<opacity>` (double, default: `0.9`)

Set the opacity of the backdrop behind text information such as FPS Counter, Filename, Metadata, or Cheatsheet.

Material options

`--normal-glyphs` (bool, default: `false`)

Display arrows that show vertex normals.

`--normal-glyphs-scale` (ratio, default: `1.0`)

Adjusts the scales of normal glyphs.

`-o`, `--point-sprites``=<none|sphere|gaussian|circle|stddev|bound|cross>` (string, default: `none`, implicit: `sphere`)

Select points sprites types to show instead of the geometry.

`--point-sprites-size``=<size>` (double, default: `10.0`)

Set the size of point sprites.

`--point-sprites-absolute-size` (bool, default: `false`)

Do not scale the point sprites size by the scene bounding box.

`--point-size``=<size>` (double)

Set the size of points when showing vertices. Model-specified by default.

`--line-width``=<size>` (double)

Set the width of lines when showing edges. Model-specified by default.

`--backface-type``=<visible|hidden>` (string)

Set the Backface type. Model-specified by default.

The quad on the right is pointing away from the camera.

`--color``=<color>` (color)

Set a color on the geometry. Multiplied with the base color texture when present. Model-specified by default. Ignored if --coloring-mode is not material.

`--opacity``=<opacity>` (double)

Set opacity on the geometry. Multiplied with the base color texture when present. Model-specified by default. Usually used with --blending.

`--roughness``=<roughness>` (double)

Set the roughness coefficient on the geometry (0.0-1.0). Multiplied with the material texture when present. Model-specified by default.

`--metallic``=<metallic>` (double)

Set the metallic coefficient on the geometry (0.0-1.0). Multiplied with the material texture when present. Model-specified by default.

`--base-ior``=<base-ior>` (double)

Set the index of refraction of the base layer (1.0-2.5). Model-specified by default.

`--hdri-file``=<HDRI file>` (path)

Set the HDRI image to use as ambient lighting and skybox. Valid file format are .hdr, .exr, .png, .jpg, .pnm, .tiff, .bmp. If not set, a default is provided.

`-f`, `--hdri-ambient` (bool, default: `false`)

Light the scene using the HDRI image as ambient lighting. The environment act as a light source and is reflected on the material.

`--texture-matcap``=<texture file>` (path)

Set the texture file to control the material capture of the object. All other model options for surfaces are ignored if this is set. Must be in linear color space. Model-specified by default.

`--texture-base-color``=<texture file>` (path)

Set the texture file to control the color of the object. F3D multiplies this texture with the color and opacity options. Must be in sRGB color space. Model-specified by default. Set an empty path to remove the model-specified texture.

`--texture-material``=<texture file>` (path)

Set the texture file to control the occlusion, roughness and metallic values of the object. F3D multiplies this texture with the roughness and metallic options, which have impactful default values. To obtain true results, use --roughness=1 and --metallic=1. Must be in linear color space. Model-specified by default. Set an empty path to remove the model-specified texture.

`--texture-emissive``=<texture file>` (path)

Set the texture file to control the emitted light of the object. F3D multiplies this texture with the emissive factor. Must be in sRGB color space. Model-specified by default. Set an empty path to remove the model-specified texture.

`--emissive-factor``=<color>` (color)

Set the emissive factor. This value is multiplied with the emissive color when an emissive texture is present. Model-specified by default.

`--texture-normal``=<texture file>` (path)

Set the texture file to control the normal map of the object. Must be in sRGB color space. Model-specified by default. Set an empty path to remove the model-specified texture.

`--normal-scale``=<factor>` (double)

Set the normal scale. This value affects the strength of the normal deviation from the normal texture. Model-specified by default.

`--textures-transform``=<transform2d>` (transform2d)

Set the 2d transform to use for all textures applied to the model. The reader may set a default value depending on the file format. If a default value exists, F3D multiplies it by the provided transform.

`--checkerboard` (bool, default: `false`)

Override model's texture with a checkerboard texture. Anti-aliasing is recommended.

`--unlit` (bool)

Override model's lighting configuration. If the value is true, F3D applies no shading and the model is unlit.

Window options

`--background-color``=<color>` (color, default: `0.2, 0.2, 0.2`)

Set the window background color. Ignored if --hdri-skybox is enabled.

`--resolution``=<width,height>` (vector<double>, default: `1000, 600`)

Set the window resolution. When closing an interactive window, its resolution is remembered in a cache file, and restored on the next start, unless it is set in a configuration file, a statefile or on the command-line. Rendering to a file with --output or --reference is unaffected. Ignored in XR mode. To always start with the same window size, set it in a configuration file, eg: "resolution": "1280,720". It is only applied on the first load.

`--position``=<x,y>` (vector<double>)

Set the window position (top left corner), in pixels, starting from the top left of your screens. When closing an interactive window, its position is remembered in a cache file, and restored on the next start, unless it is set in a configuration file, a statefile or on the command-line. Rendering to a file with --output or --reference is unaffected. To always start with the same window position, set it in a configuration file, eg: "position": "100,50". It is only applied on the first load. To save and restore a whole session, including loaded files and the camera, use statefiles.

`-z`, `--fps` (bool, default: `false`)

Display the FPS Counter.

`-n`, `--filename` (bool, default: `false`)

Display the Filename on top of the window.

`-m`, `--metadata` (bool, default: `false`)

Display the Metadata.

`--scene-hierarchy` (bool, default: `false`)

Display the Scene hierarchy as a tree representing the internal structure of the model, with checkboxes allowing to hide or show individual parts. By default the tree expands only enough to show nodes that have meaningful names, but you can fully expand all nodes manually.

`--notifications` (bool, default: `false`)

Display the Notifications at the bottom left of the window.

`--hdri-filename` (bool, default: `false`)

Display the HDRI filename.

`-j`, `--hdri-skybox` (string, default: `disabled`, implicit: `enabled`)

Define the HDRI skybox display mode. If value is disabled, --background-color and --no-background are used. If value is enabled, the skybox is visible. If value is blurred, the skybox is visible and blurred.

`--blur-coc` (double, default: `20`)

Blur circle of confusion radius.

`--light-intensity` (double, default: `1.0`)

Adjust the intensity of every light in the scene, including HDRI image-based lighting.

Scientific visualization options

`-s`, `--coloring-mode` (string, default: `material`)

Specify the coloring mode. material means default file materials (textured or solid color) scivis and direct mean the array specified with option --coloring-array will be used for coloring (or the first available if not set) In the case of scivis, the array is mapped to a color using the colormap defined in --colormap In the case of direct, it is assumed that the array defines colors directly as L, LA, RGB, RGBA values depending on the number of components. Use S to cycle at runtime.

`--coloring-array``=<array_name>` (string)

The coloring array name to use when coloring. Use with --coloring-mode=scivis or Use with --coloring-mode=direct. Use Y to cycle at runtime. Use --verbose to recover the usable array names.

`-y`, `--coloring-component``=<comp_index>` (int, implicit: `0`)

Specify the component from the scalar array to color with. If the option is not specified, uses the magnitude of the array. Use with --coloring-mode=scivis. Use Shift+Y to cycle at runtime.

`--coloring-field` (string, default: `any`)

Specify that the scalar array field to color with (any, points, or cells). Use with --coloring-mode=scivis or --coloring-mode=direct. Use if a point array and a cell array have the same name or if you want to skip a field when cycling with Y at runtime.

`--coloring-range``=<min,max>` (vector<double>)

Set the coloring range. Automatically computed by default. When automatically computed and minimum and maximum values are nearly equal, the object is colored with the mid value. Use with --coloring-mode=scivis.

`-b`, `--coloring-scalar-bar` (bool, default: `false`)

Show Scalar bar of the coloring by array. Use with --coloring-mode=scivis.

`--colormap-file``=<name>` (string)

Set a colormap file for the coloring. See color maps. Use with --coloring-mode=scivis.

`--colormap``=<colormap>` (colormap)

Set a custom colormap for the coloring.See colormap parsing for details. Ignored if --colormap-file option is specified. Use with --coloring-mode=scivis.

`--colormap-discretization``=<colors>` (int)

Set the number of distinct colors from [1, N] used in the colormap. Any values outside the valid range result in smooth shading. Use with --coloring-mode=scivis.

`-v`, `--volume` (bool, default: `false`)

Enable volume rendering. It is only functional for 3D image data (VTKXMLVTI, DICOM, NRRD, MetaImage files) and displays nothing with other formats. It forces coloring. Warn if not used with --coloring-mode=scivis or --coloring-mode=scivis.

`--volume-opacity-file``=<name>` (string)

Set an opacity map file for the coloring.

`--volume-opacity-map``=<value, opacity>` (vector<double>, default: `0.0,0.0,1.0,1.0`)

Set a custom opacity map for the coloring. Only used with volume rendering for now. Ignored if --volume-opacity-file option is specified.

`-i`, `--volume-inverse` (bool, default: `false`)

Inverse the linear opacity function used for volume rendering.

Camera configuration options

`--camera-position``=<X,Y,Z>` (vector<double>)

Set the camera position, overrides --camera-direction and --camera-zoom-factor.

`--camera-focal-point``=<X,Y,Z>` (vector<double>)

Set the camera focal point.

`--camera-view-up``=<direction>` (direction)

Set the camera view up vector. Will be orthogonalized.

`--camera-view-angle``=<angle>` (double)

Set the camera view angle, a strictly positive value in degrees.

`--camera-direction``=<direction>` (direction)

Set the camera direction, looking at the focal point.

`--camera-zoom-factor``=<factor>` (double)

Set the camera zoom factor relative to the autozoom on data, a strictly positive value.

`--camera-azimuth-angle``=<angle>` (double, default: `0.0`)

Apply an azimuth transformation to the camera, in degrees, added after other camera options.

`--camera-elevation-angle``=<angle>` (double, default: `0.0`)

Apply an elevation transformation to the camera, in degrees, added after other camera options.

`--camera-orthographic` (bool)

Set the camera to use the orthographic projection. Model-specified by default.

Raytracing options

`-r`, `--raytracing` (bool, default: `false`)

Enable OSPRay raytracing. Requires OSPRay raytracing to be enabled in the linked VTK dependency.

`--raytracing-samples``=<samples>` (int, default: `5`)

Set the number of samples per pixel when using raytracing.

`-d`, `--raytracing-denoise` (bool, default: `false`)

Denoise the image when using raytracing.

PostFX (OpenGL) options

`-p`, `--blending` (string, default: `none`, implicit: `ddp`)

Enable translucency blending support. This is a technique used to correctly render translucent objects (ddp: dual depth peeling for quality, sort: for gaussians, sort_cpu: for gaussians, stochastic: fast).

warning

stochastic is introducing a lot of noise with strong translucency. It works better when combined with temporal anti-aliasing (when using the --anti-aliasing=taa option) sort is only working for 3D gaussians and requires compute shaders support. Alternatively, sort_cpu gives the same result and works everywhere but it's much slower.

`-q`, `--ambient-occlusion` (bool, default: `false`)

Enable ambient occlusion. This is a technique used to improve the depth perception of the object.

`-a`, `--anti-aliasing` (string, default: `none`, implicit: `fxaa`)

Anti-aliasing method (fxaa: fast, ssaa: quality, taa: balanced, none: no anti aliasing)

warning

taa forces rendering of the scene at regular interval and introduces ghosting artifacts on animated scenes. It also doesn't work with offscreen rendering (when using the --output option)

Notice how edges are smoother with SSAA.

`-t`, `--tone-mapping` (bool, default: `false`)

Enable neutral Tone Mapping. This technique maps colors properly to the monitor colors.

`--final-shader` (string)

Add a final shader to the output image. See the final shader documentation for more details.

`--display-depth` (bool, default: `false`)

Display the depth buffer as a grayscale image or with a colormap if --coloring-mode is scivis. Only opaque objects are displayed, the grid and translucent/volumetric objects are ignored.

Testing options

`--reference``=<png file>` (string)

Render and compare with the provided reference image, for testing purposes. Use with output option to generate new baselines and diff images.

`--reference-threshold``=<threshold>` (double, default: `0.04`)

Set the comparison threshold to trigger a test failure or success. The default (0.04) correspond to almost visually identical images.

`--interaction-test-record``=<log file>` (string)

Path to an interaction log file to record interaction events to.

`--interaction-test-play``=<log file>` (string)

Path to an interaction log file to play interactions events from when loading a file. Run after --command-script.

Rendering options precedence

Some rendering options are not compatible between them, here is the precedence order if several are provided:

Raytracing (-r)
Volume (-v)
Point Sprites (-o)

Color space

All options of type color must be expressed in sRGB color space. They are converted internally in linear color space for physically correct rendering.

Options syntax

To turn on/off boolean options, write --option=true and --option=false, eg --point-sprites=false.

If an option has an "implicit" value, use the option without specifying the value to use the implicit value.

The default corresponds to the value without any configuration file.

Prefer the --option=value syntax. The syntax --option value can have unintended effect with positional arguments.

The -R short option has a special syntax: -Rlibf3d.option but can also be used with --reset=libf3d.option

The -D/--define option has a special syntax: -Dlibf3d.option=value or --define=libf3d.option=value.

F3D parses all options according to their type, see the parsing documentation for more details.

Piping

F3D supports piping in and out for most formats, using the - char, eg:

f3d - --output=- < path/to/file.glb > path/to/img.png

or, using display:

cat path/to/file.glb | f3d - --output=- | display

and even, using build123d:

script.py:

import sys

from build123d import Box, Cylinder, export_brep

obj = Box(2, 2, 1) - Cylinder(0.5, 2)
export_brep(obj, sys.stdout.buffer)

python script.py | f3d - --output=- | display

F3D can also output animations to a video using piping with FFmpeg:

f3d path/to/file.glb --output-video=- | ffmpeg -f h264 -i - path/to/video.mp4

While piping is more common on Linux, F3D supports it perfectly on Windows and macOS as well.

With versions of VTK < v9.6.20260128, specifying the reader to use is required, like this:

cat path/to/file.glb | f3d - --force-reader=GLB --output=- | display

Filename templating

The destination filename used by --output, to save screenshots using --screenshot-filename, or to save statefiles using --save-statefile/--statefile-filename can use the following template variables:

{app}: application name (ie. F3D)
{version}: application version (eg. 2.4.0)
{version_full}: full application version (eg. 2.4.0-abcdefgh)
{model}: current model filename without extension (eg. foo for /home/user/foo.glb)
{model.ext}: current model filename with extension (eg. foo.glb for /home/user/foo.glb)
{model_ext}: current model filename extension (eg. glb for /home/user/foo.glb)
{date}: current date in YYYYMMDD format
{date:format}: current date as per C++'s std::put_time format
{n}: auto-incremented number to make filename unique (up to 1000000)
{n:2}, {n:3}, ...: zero-padded auto-incremented number to make filename unique (up to 1000000)
{frame}: frame number when outputting animation frames (see Animations)
{frame:4}, {frame:5}, ...: zero-padded frame number when outputting animation frames
escape variable names by doubling the braces (eg. use {{model}}.png to output {model}.png without the model name being substituted)

For example the screenshot filename is configured as {app}/{model}_{n}.png by default, meaning that, assuming the model hello.glb is being viewed, consecutive screenshots are going to be saved as F3D/hello_1.png, F3D/hello_2.png, F3D/hello_3.png, ...

F3D replaces model related variables by no_file if no file is loaded and multi_file if multiple files are loaded using the multi-file-mode option.

When loading a statefile (--load-statefile/load_statefile), the {n} variable resolves to the most recent existing file, instead of the next available one used when saving. This means that, with the default {n} template, saving then loading a statefile round-trips to the same file.

Caches

When using HDRI related options, F3D creates and uses a cache directory to store related data to speed up rendering.

F3D also stores the geometry of the last closed interactive window in a cache.json file, in the same directory, so it can restore that geometry on the next start, see --resolution and --position. Its window entry uses the same layout as in statefiles:

{
  "window": {
    "width": 1000,
    "height": 600,
    "left": 100,
    "top": 50
  }
}

You can safely remove these cache files, at the cost of recomputing the HDRI data on next use and losing the cached window geometry.

The cache directory location is as follows, in order, using the first defined environment variables:

Windows: %LOCALAPPDATA%\f3d
Linux: ${XDG_CACHE_HOME}/f3d,${HOME}/.cache/f3d
macOS: ${HOME}/Library/Caches/f3d

Statefiles

A statefile is a JSON file that captures a session to restore later, using --save-statefile/--load-statefile or the save_statefile/load_statefile commands.

A libf3d statefile (engine::dump/engine::load) contains the added files, the camera and the options. F3D stores file paths relatively to the statefile directory when possible, and resolves them on load. Content added from memory (meshes, buffers) is not captured.

F3D adds a file_groups entry storing all file groups, including the ones not currently loaded, so it can restore the whole navigation state. The library ignores this entry when loading a libf3d statefile.

Application options
General options
Material options
Window options
Scientific visualization options
Camera configuration options
Raytracing options
PostFX (OpenGL) options
Testing options
Rendering options precedence
Color space
Options syntax
Piping
Filename templating
Caches
Statefiles

Application options​

--input=<input file> (string)​

--output=<png file> (string)​

--output-video=<video file> (string)​

--no-background (bool, default: false)​

--no-cache (bool, default: false)​

-h, --help​

--version​

--list-readers​

--force-reader=<reader> (string)​

--skip-content-check (bool, default: false)​

--list-bindings​

--list-rendering-backends​

--list-video-encoders​

--video-encoder (string)​

--video-bitrate (double, default: 5.0)​

--video-low-latency (bool, default: false)​

--config=<config file path/name/stem> (string, default: config)​

--no-config (bool, default: false)​

--no-render (bool, default: false)​

--load-statefile=<file path> (string)​

--save-statefile=<file path> (string)​

--statefile-filename=<file path> (string, default: empty)​

--max-size=<size in MiB> (int, default: -1)​

--watch (bool, default: false)​

--frame-rate=<fps> (double, default: 30.0)​

--load-plugins=<paths or names> (string)​

--plugins-path=<path> (string)​

--scan-plugins​

--screenshot-filename=<png file> (string, default: {app}/{model}_{n}.png)​

--rendering-backend=<auto|egl|osmesa|glx|xr|wgl> (string, default: auto)​

-D, --define=<libf3d.option=value> (special)​

-R, --reset=<libf3d.option> (special)​

General options​

--verbose=<[debug|info|warning|error|quiet]> (string, default: info, implicit: debug)​

--loading-progress (bool, default: false)​

--animation-progress=<none|default|advanced> (string, default: none, implicit: default)​

--multi-file-mode=<single|all| dir> (string, default: single)​

--multi-file-regex=<regex> (string)​

--recursive-dir-add (bool, default: false)​

--remove-empty-file-groups (bool, default: false)​

--up=<direction> (direction, default: +Y)​

-x, --axis (bool, default: false)​

--x-color (color, default: f3d_red)​

--y-color (color, default: f3d_green)​

--z-color (color, default: f3d_blue)​

-g, --grid (bool, default: false)​

--grid-unit=<length> (double)​

--grid-subdivisions=<count> (int, default: 10)​

--grid-color=<color> (color, default: 0,0,0)​

--grid-opacity=<opacity> (double, default: 1)​

--grid-reflection=<strength> (double, default: 0)​

--grid-absolute (bool, default: false)​

--axes-grid (bool, default: false)​

-e, --edges (bool, default: false)​

--armature (bool, default: false)​

--camera-index=<idx> (int)​

-k, --interaction-style=<default|trackball|2d> (string, default: default)​

--invert-zoom (bool, default: false)​

--animation-autoplay (bool, default: false)​

--animation-indices=<idx1,idx2> (vector<int>, default: 0)​

--animation-speed-factor=<ratio> (ratio, default: 1)​

--animation-time=<time> (double)​

--font-file=<font file> (path)​

--font-scale=<ratio> (ratio, default: 1.0)​

--font-color=<color> (color, default: 0.957,0.957,0.957)​

--dpi-aware (bool, default: false)​

--command-script=<command script> (script)​

--backdrop-color=<color> (color, default: f3d_black)​

--backdrop-opacity=<opacity> (double, default: 0.9)​

Material options​

--normal-glyphs (bool, default: false)​

--normal-glyphs-scale (ratio, default: 1.0)​

-o, --point-sprites=<none|sphere|gaussian|circle|stddev|bound|cross> (string, default: none, implicit: sphere)​

--point-sprites-size=<size> (double, default: 10.0)​

--point-sprites-absolute-size (bool, default: false)​

--point-size=<size> (double)​

--line-width=<size> (double)​

--backface-type=<visible|hidden> (string)​

--color=<color> (color)​