By Kitware SAS, 2019-2021

F3D (pronounced /fɛd/) is a VTK-based 3D viewer following the KISS principle, so it is minimalist, efficient, has no GUI, has simple interaction mechanisms and is fully controllable using arguments in the command line.

F3D is open-source and cross-platform (tested on Windows, Linux and macOS). It supports a range of file formats (including animated glTF, stl, step, ply, obj), and provides numerous rendering and texturing options.

A typical render by F3D

Animation of a glTF file within F3D

A direct scalars render by F3D

There are 4 main ways to use F3D:

• By running F3D from a terminal with a set of command-line options.
• By running F3D directly and then dragging and dropping files into it to open them.
• By using F3D as an "Open with" program with specific file types.
• As a thumbnailer for all supported file formats with certain file managers.

You can find the release binary packages for Windows, Linux and macOS on the Release page. Alternatively, you can build it yourself following the build guide below.

You can also find packages for the following operating systems:

Available on OpenSuse OBS.

Available on OpenSuse OBS.

Available in the AUR.

Avaiable in FreshPORTS.

Available in DPorts.

Available in Homebrew.

Available in nixpkgs.

• CMake >= 3.1.
• VTK >= 9.0.0 (optionally with raytracing capabilities to enable OSPray rendering).
• A C++11 compiler.
• A CMake-compatible build system (Visual Studio, XCode, Ninja, Make, etc.).

Configure and generate the project with CMake by providing the following CMake options:

• VTK_DIR: Path to a build or install directory of VTK.
• BUILD_TESTING: Enable the tests.
• F3D_MACOS_BUNDLE: On macOS, build a .app bundle.
• F3D_WINDOWS_GUI: On Windows, build a Win32 application (without console).

Some modules depending on external libraries can be optionally enabled with the following CMake variables:

• F3D_MODULE_EXODUS: Support for ExodusII (.ex2) file format. Requires that VTK has been built with IOExodus module (and hdf5). Enabled by default.
• F3D_MODULE_RAYTRACING: Support for raytracing rendering. Requires that VTK has been built with OSPRay. Disabled by default.
• F3D_MODULE_OCCT: Support for STEP and IGES file formats. Requires OpenCASCADE. Disabled by default.

Then build the software using your build system.

Here is the list of supported file formats:

• .vtk : the legacy VTK format
• .vt[p|u|r|i|s|m] : XML based VTK formats
• .ply : Polygon File format
• .stl : Standard Triangle Language format
• .dcm : DICOM file format
• .nrrd/.nhrd : "nearly raw raster data" file format
• .mhd/.mha : MetaHeader MetaIO file format
• .tif/.tiff : TIFF 2D/3D file format
• .ex2/.e/.exo/.g : Exodus 2 file format
• .gml : CityGML file format
• .pts : Point Cloud file format
• .step/.stp : CAD STEP exchange ISO format
• .iges/.igs : CAD Initial Graphics Exchange Specification format
• .obj : Wavefront OBJ file format (full scene)
• .gltf/.glb : GL Transmission Format (full scene)
• .3ds : Autodesk 3D Studio file format (full scene)
• .wrl : VRML file format (full scene)

The full scene formats (gltf/glb, 3ds, wrl, obj) contain not only geometry, but also some scene information like lights, cameras, actors in the scene, as well as texture properties. By default, all this information will be loaded from the file and displayed. For file formats that do not support it, a default scene will be created.

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

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

Simple interaction with the displayed data is possible directly within the window. It is as follows:

• Click and drag with the left mouse button to rotate around the focal point of the camera.
• Hold Shift then Click and drag horizontally with the right mouse button to rotate the HDRI.
• Click and drag vertically with the right mouse button to zoom in/out.
• Move the mouse wheel to zoom in/out.
• Click and drag with the middle mouse button to translate the camera.
• Drag and drop a file or directory into the F3D window to load it

Note: When playing an animation with a scene camera, camera interactions are locked.

The coloring can be controlled directly by pressing the following hotkeys:

• C: cycle between coloring with array from point data and from cell data.
• S: cycle the array to color with.
• Y: cycle the component of the array to color with.

See the [coloring cycle](#Cycling Coloring) section for more info.

Other options can be toggled directly by pressing the following hotkeys:

• B: display of the scalar bar, only when coloring and not using direct scalars.
• V: volume rendering.
• I: opacity function inversion during volume rendering.
• O: point sprites rendering.
• P: depth peeling.
• Q: Screen-Space Ambient Occlusion.
• A: Fast Approximate Anti-Aliasing.
• T: tone mapping.
• E: the display of cell edges.
• X: the trihedral axes display.
• G: the XZ grid display.
• N: the display of the file name.
• M: the display of the metadata if exists.
• Z: the display of the FPS counter.
• R: raytracing.
• D: the denoiser when raytracing.
• F: full screen.
• U: background blur.
• K: trackball interaction mode.

Note that some hotkeys can be available or not depending on the file being loaded and the F3D configuration.

Other hotkeys are available:

• H: key to toggle the display of a cheat sheet showing all these hotkeys and their statuses.
• ?: key to dump camera state to the terminal.
• ESC: close the window and quit F3D.
• ENTER: reset the camera to its initial parameters.
• SPACE: play the animation if any.
• LEFT: load the previous file if any.
• RIGHT: load the next file if any.
• UP: reload the current file.

When using the default scene, the following hotkeys let you cycle the coloring of the data:

• C: cycle between point data and cell data - field data is not supported.
• S: cycle the array available on the currently selected data, skipping array not containing numeric data. It will loop back to not coloring unless using volume rendering.
• Y: cycle the component available on the currently selected array, looping to -2 for direct scalars rendering if the array contains 4 or less components, -1 otherwise.

When changing the array, the component in use will be kept if valid with the new array, if not it will be reset to 0 when coloring with an invalid higher than zero component, and to -1 when using direct scalars rendering with an array having more than 4 components.

When changing the type of data to color with, the index of the array within the data will be kept if valid with the new data. If not, it will cycle until a valid array is found. After that, the component will be checked as well.

Almost all the command-line options can be controlled using a configuration file. This configuration file uses the "long" version of the options in a JSON formatted file to provide default values for these options.

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 the corresponding value in the config file. A typical config file may look like this:

{
   ".*": {
       "resolution": "1200,800",
       "bg-color": "0.7,0.7,0.7",
       "color": "0.5,0.1,0.1",
       "fxaa": true,
       "timer": true,
       "progress": true,
       "axis": true,
       "bar": true,
       "verbose": true,
       "roughness": 0.2,
       "grid": true
   },
   ".*vt.": {
       "edges": true
   },
   ".*gl(tf|b)": {
       "raytracing": true,
       "denoise": true,
       "samples": 3
   },
   ".*mhd": {
       "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 command-line options
cannot
be set via config file: help, version, config, dry-run, no-render, inputs, output and all testing options.

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

The configuration file possible locations depends on your operating system. They are considered in the below order and only the first found will be used.

• Linux: /etc/f3d/config.json, [install_dir]/config.json, ${XDG_CONFIG_HOME}/.config/f3d/config.json, ~/.config/f3d/config.json
• Windows: [install_dir]\config.json, %APPDATA%\f3d\config.json
• macOS: /etc/f3d/config.json, f3d.app/Contents/Resources/config.json, [install_dir]/config.json, ~/.config/f3d/config.json

If you are using the releases, a default configuration file is provided when installing F3D. On Linux, it will be installed in /etc/f3d/, on Windows, it will be installed in the install directory, on macOS, it will be installed in the bundle.

F3D can be used as a thumbnailer in certain cases

During instalation, F3D will install mime types files as defined by the XDG standard and a thumbnailer file as specified here. Many file managers use this mechanism, including nautilus, thunar, pcmanfm and caja. Make sure to update the mime types database using update-mime-database.

• No categorical generic field data rendering support.
• No string array categorical rendering support.
• No support for specifying manual lighting in the default scene.
• Pressing the z hotkey to display the FPS timer triggers a double render.
• Multiblock (.vtm, .gml) support is partial, non-surfacic data will be converted into surfaces.
• Animation support with full scene data format require VTK >= 9.0.20201016.
• Full drag and drop support require VTK >= 9.0.20210620
• Escape interaction events cannot be recorded.
• Drag and drop interaction cannot be recorded nor played back.

I have built F3D with raytracing support but the denoiser is not working.

Be sure that VTK has been built with OpenImageDenoise support (VTKOSPRAY_ENABLE_DENOISER option).

Thumbnails are not working in my file manager.

• Check that your file manager supports the thumbnailer mechanism.
• Check that you have updated your mime type database.
• If all fails, remove your .cache user dir and check that pcmanfm thumbnails are working.
• If they are working, then it is an issue specific to your file manager.
• If only a few format have working thumbnails, then it is an issue with mime types
• If no formats have working thumbnails, then it is an issue with the f3d.thumbnailer file

I use F3D in a VM, the application fails to launch.

OpenGL applications like F3D can have issues when launched from a guest Windows because the access to the GPU is restricted. You can try to use a software implementation of OpenGL, called Mesa.

• Download the latest release-msvc.
• copy x64/OpenGL32.dll and x64/libglapi.dll in the same folder as f3d.exe.
• set the environment variable MESA_GL_VERSION_OVERRIDE to 4.5.
• run f3d.exe.

I run f3d from the command prompt and my Unicode characters are not displayed properly.

Set the codepage to UTF-8, run chcp 65001.