A mirror for F3D
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 
Michael MIGLIORE 3b302a3ea2
Fix filesystem linking (#430)
11 hours ago
.github Add Java bindings (#390) 1 week ago
application Fix filesystem linking (#430) 11 hours ago
cmake Remove libf3d installation when not needed (#436) 14 hours ago
documentation Using minimalist everywhere (#406) 3 weeks ago
java Add Java bindings (#390) 1 week ago
library Fix filesystem linking (#430) 11 hours ago
python Addin options getNames, isSame, copy 7 days ago
resources Using max-size 5 days ago
testing Updating cheatsheet test image 3 days ago
winshellext Adding a thumbnail specific config 5 days ago
.clang-format Improve CMake file to include packaging 3 years ago
.gitattributes moving data around 9 months ago
.gitignore Clean up vscode 3 years ago
.lsan.supp Adding simple sdk test architecture (#246) 6 months ago
.tsan.supp Stricter cmake build (#317) 4 months ago
CMakeLists.txt Add Java bindings (#390) 1 week ago
GENERATE.md Copyright update (#93) 10 months ago
LICENSE Clarify and fixup license 5 months ago
README.md Fix filesystem linking (#430) 11 hours ago
README_libf3d.md Removing fullscreen option entirely 3 days ago
THIRD_PARTY_LICENSES.md Adding json.hpp license (#369) 1 month ago
codecov.yml Rework CI (#198) 9 months ago

README.md

CI codecov Downloads Downloads

F3D Logo

F3D - Fast and minimalist 3D viewer

By Michael Migliore and Mathieu Westphal.

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 on 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, FBX), 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

Acknowledgments

F3D was initially created by Kitware SAS and is relying on many awesome open source projects, including VTK, OCCT, Assimp and Alembic.

How to use

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 automatically in the file manager when opening file.
  • As a thumbnailer for all supported file formats with certain file managers.

Installation

You can find the release binary packages for Windows, Linux and macOS on the Release page. See the desktop integration section in order actually integrate the binary release in your desktop. Alternatively, you can build it yourself following the build guide below.

You can also find packages for the following operating systems:

OpenSuse

Available in OpenSuse.

Arch Linux

Available in the AUR.

FreeBSD

Avaiable in FreshPORTS.

DragonFly BSD

Available in DPorts.

MacOS Brew

Available in Homebrew.

NixOS

Available in nixpkgs.

Ubuntu/Debian/Fedora

Available on OpenSuse OBS.

Flathub

Available in Flathub.

Spack

Available in Spack.

Build

Dependencies

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

Configuration and building

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).
  • F3D_PYTHON_BINDINGS: Generate python bindings (needs python and pybind11)

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.
  • F3D_MODULE_ASSIMP: Support for FBX, DAE, OFF and DXF file formats. Requires Assimp. Disabled by default.
  • F3D_MODULE_ALEMBIC: Support for ABC file format. Requires Alembic. Disabled by default.

Then build the software using your build system.

File formats

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
  • .abc : Alembic 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)
  • .fbx : Autodesk Filmbox (full scene)
  • .dae : COLLADA (full scene)
  • .off : Object File Format (full scene)
  • .dxf : Drawing Exchange Format (full scene)

Scene construction

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.

Options

Applicative Options

Options Description
--input=<file> The input file or files to read, can also be provided as a positional argument.
--output=<png file> Instead of showing a render view and render into it, render directly into a png file. When used with ref option, only outputs on failure.
--no-background Output file is saved with a transparent background.
-h, --help Print help.
--version Show version information.
--readers-list List available readers.
--config Specify the configuration file to use. Supports absolute/relative path but also filename/filestem to search for in configuration file locations.
--dry-run Do not read any configuration file but consider only the command line options.
--no-render Verbose mode without any rendering for the first provided file, useful to recover information about a file.
--max-size Maximum size in Mib of a file to load, -1 means unlimited, useful for thumbnails.

General Options

Options Description
--verbose Enable verbose mode, providing more information about the loaded data in the console output.
--quiet Enable quiet mode, which superseed any verbose options. No console output will be generated at all.
--progress Show a progress bar when loading the file.
--geometry-only For certain full scene file formats (gltf/glb and obj),
reads only the geometry from the file and use default scene construction instead.
--up Define the Up direction (default: +Y).
-x, --axis Show axes as a trihedron in the scene.
-g, --grid Show a grid aligned with the XZ plane.
-e, --edges Show the cell edges.
--camera-index Select the scene camera to use when available in the file.
Any negative value means automatic camera.
The default scene always uses automatic camera.
-k, --trackball Enable trackball interaction.
--animation-index Select the animation to show.
Any negative value means all animations.
The default scene always has at most one animation.
If the option is not specified, the first animation is enabled.
--font-file Use the provided FreeType compatible font file to display text.
Can be useful to display non-ASCII filenames.

Material options

Options Default Description
-o, --point-sprites Show sphere points sprites instead of the geometry.
--point-size 10.0 Set the size of points when showing vertices and point sprites.
--line-width 1.0 Set the width of lines when showing edges.
--color=<R,G,B> 1.0, 1.0, 1.0 Set a color on the geometry. Multiplied with the base color texture when present.
This only makes sense when using the default scene.
--opacity=<opacity> 1.0 Set opacity on the geometry. Multiplied with the base color texture when present.
This only makes sense when using the default scene. Usually used with Depth Peeling option.
--roughness=<roughness> 0.3 Set the roughness coefficient on the geometry (0.0-1.0). Multiplied with the material texture when present.
This only makes sense when using the default scene.
--metallic=<metallic> 0.0 Set the metallic coefficient on the geometry (0.0-1.0). Multiplied with the material texture when present.
This only makes sense when using the default scene.
--hrdi=<file path> Set the HDRI image used to create the environment.
The environment act as a light source and is reflected on the material.
Valid file format are hdr, png, jpg, pnm, tiff, bmp.
--texture-base-color=<file path> Path to a texture file that sets the color of the object. Please note this will be multiplied with the color and opacity options.
--texture-material=<file path> Path to a texture file that sets the Occlusion, Roughness and Metallic values of the object. Please note this will be multiplied with the roughness and metallic options, which have impactful default values. To obtain true results, use --roughness=1 --metallic=1.
--texture-emissive=<file path> Path to a texture file that sets the emitted light of the object. Please note this will be multiplied with the emissive factor.
--emissive-factor=<R,G,B> 1.0, 1.0, 1.0 Emissive factor. This value is multiplied with the emissive color when an emissive texture is present.
--texture-normal=<file path> Path to a texture file that sets the normal map of the object.
--normal-scale=<normal_scale> 1.0 Normal scale affects the strength of the normal deviation from the normal texture.

Window options

Options Default Description
--bg-color=<R,G,B> 0.2, 0.2, 0.2 Set the window background color.
Ignored if hdri is set.
--resolution=<width,height> 1000, 600 Set the window resolution.
-z, --fps Display a frame per second counter.
-n, --filename Display the name of the file.
-m, --metadata Display the metadata.
This only makes sense when using the default scene.
-u, --blur-background Blur background.
This only makes sense when using a HDRI.

Scientific visualization options

Options Default Description
-s, --scalars=<array_name> Color by a specific scalar array present in the file. If no array_name is provided, one will be picked if any are available.
This only makes sense when using the default scene.
Use verbose to recover the usable array names.
-y, --comp=<comp_index> -1 Specify the component from the scalar array to color with.
Use with the scalar option. -1 means magnitude. -2 or the short option, -y, means direct values.
When using direct values, components are used as L, LA, RGB, RGBA values depending on the number of components.
-c, --cells Specify that the scalar array is to be found on the cells instead of on the points.
Use with the scalar option.
--range=<min,max> Set a custom range for the coloring by the array.
Use with the scalar option.
-b, --bar Show scalar bar of the coloring by array.
Use with the scalar option.
--colormap=<color_list> Set a custom colormap for the coloring.
This is a list of colors in the format val1,red1,green1,blue1,...,valN,redN,greenN,blueN
where all values are in the range (0,1).
Use with the scalar option.
-v, --volume Enable volume rendering. It is only available for 3D image data (vti, dcm, nrrd, mhd files) and will display nothing with other default scene formats.
-i, --inverse Inverse the linear opacity function. Only makes sense with volume rendering.

Camera configuration options

Options Description
--camera-position=<X,Y,Z> The position of the camera.
--camera-focal-point=<X,Y,Z> The focal point of the camera.
--camera-view-up=<X,Y,Z> The view up vector of the camera. Will be orthogonalized even when provided.
--camera-view-angle=<angle> The view angle of the camera, non-zero value in degrees.
--camera-azimuth-angle=<angle> Apply an azimuth transformation to the camera, in degrees (default: 0.0).
--camera-elevation-angle=<angle> Apply an elevation transformation to the camera, in degrees (default: 0.0).

Raytracing options

Options Default Description
-r, --raytracing Enable OSPRay raytracing. Requires OSPRay raytracing to be enabled in the linked VTK dependency.
--samples=<samples> 5 The number of samples per pixel. It only makes sense with raytracing enabled.
-d, --denoise Denoise the image. It only makes sense with raytracing enabled.

PostFX (OpenGL) options

Options Description
-p, --depth-peeling Enable depth peeling. This is a technique used to correctly render translucent objects.
-q, --ssao Enable Screen-Space Ambient Occlusion. This is a technique used to improve the depth perception of the object.
-a, --fxaa Enable Fast Approximate Anti-Aliasing. This technique is used to reduce aliasing.
-t, --tone-mapping Enable generic filmic Tone Mapping Pass. This technique is used to map colors properly to the monitor colors.

Testing options

Options Description
--ref=<png file> Reference image to compare with for testing purposes. Use with output option to generate new baselines and diff images.
--ref-threshold=<threshold> Testing threshold to trigger a test failure or success.
--interaction-test-record=<log file> Path to an interaction log file to record interaction events to.
--interaction-test-play=<log file> Path to an interaction log file to play interactions events from when loading a file.

Rendering 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)

Interaction

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 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.
  • 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 print scene description 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 loading another file or reloading, options that have been changed before are kept but can be overridden by a dedicated regular expression block in the configuration file if any, see configuration file for more info.

Cycling Coloring

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.

Configuration file

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.

A special block, named global, will apply to all files. Using a command-line option will override the corresponding value in the config file.

The global block and command-line options are only taken into account on the first load and not on subsequent loads. The regular expression blocks are always taken into account, even when loading further files.

A typical config file may look like this:

{
   "global": {
       "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,
       "roughness": 0.2,
       "grid": true,
       "scalars": true,
   },
   ".*vt.": {
       "edges": true
   },
   ".*gl(tf|b)": {
       "raytracing": true,
       "denoise": true,
       "samples": 3
   },
   ".*mhd": {
       "volume": true
   }
}

Here, the first block defines a basic global 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, readers-list, config, dry-run.

The following command-line options
can only
be set in the global block of the config file: no-render, inputs, output, quiet, verbose, resolution 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.

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: ${XDG_CONFIG_HOME}/.config/f3d/config.json, ~/.config/f3d/config.json, /etc/f3d/config.json, /usr/share/f3d/config.json, [install_dir]/share/f3d/config.json
  • Windows: %APPDATA%\f3d\config.json, [install_dir]\config.json
  • macOS: ${XDG_CONFIG_HOME}/.config/f3d/config.json, ~/.config/f3d/config.json, /usr/local/etc/f3d/config.json, f3d.app/Contents/Resources/config.json

When installing F3D default configuration files can be installed, one for generic usage (config.json) and one for thumbnails (thumbnail.json). When installing the binary release, On Linux, they will be installed in [install_dir]/share/f3d/, on Windows, it will be installed in the install directory, 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 will be added) to look for in the locations listed above, instead of looking for config.json.

libf3d

F3D contains not only the F3D executable but also the libf3d, a library to render 3D meshes, which can be used in C++ or Python. The libf3d is documented here.

Desktop Integration

F3D can be integrated in the desktop experience.

Linux

For Linux desktop integration, F3D rely on mime types files as defined by the XDG standard, .thumbnailer file as specified here and .desktop file as specified here. Many file managers use this mechanism, including nautilus, thunar, pcmanfm and caja.

The simplest way to obtain desktop integration on linux is to use a package for your distribution, or the .deb binary package we provide if compatible with your distribution. In other cases, the binary archive can be used like this:

  1. Make sure ~/.local/bin is part of your PATH
  2. Extract F3D archive in ~/.local/
  3. Update your mime database pointing to ~/.local/share/mime
  4. Update your desktop database pointing to ~/.local/share/application
export PATH=$PATH:~/.local/bin
tar -xzvf f3d-1.3.0-Linux.tar.gz -C ~/.local/
sudo update-mime-database ~/.local/share/mime/
sudo update-desktop-database ~/.local/share/applications

If you have any issues, read the troubleshooting section.

Windows

For Windows desktop integration, F3D rely on a registered shell extension.

Using the F3D NSIS installer (.exe) is the simplest way to enable thumbnails and integrate F3D on windows.

It is also possible to do it manually when using the zipped binary release, on installation, just run:

cd C:\path\to\f3d\bin\
regsvr32 F3DShellExtension.dll

To remove the shell extension, run:

cd C:\path\to\f3d\bin\
regsvr32 /u F3DShellExtension.dll

MacOS

There is no support for thumbnails on MacOS, the .dmg binary release should provide automatic file openings.

Known limitations

  • 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.
  • Volume rendering and HDRI support requires a decent GPU

Assimp

FBX, DAE, OFF, and DXF file formats rely on Assimp library. It comes with some known limitations:

  • PBR materials are not supported for FBX file format
  • Animations are not working very well with Assimp 5.1, it's recommended to use Assimp 5.0
  • Some files can be empty, crash, or show artifacts
  • DXF support is very limited: only files with polylines and 3D faces are displayed.

Alembic

ABC file formats rely on Alembic library. It comes with some known limitations:

  • Supports Alembic 1.7 or later
  • Supports only simple polygonal geometry
  • Does not support ArbGeomParam feature in Alembic
  • Does not support Subdivision Meshes
  • Does not support Materials

Troubleshooting

General

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).

Linux

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 (see below for a potential work around).
  • 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
  • If only big file do not have thumbnails, this is intended, you can modify this behavior in the thumbnail.json configuration file using the max-size option.

Sandboxing

Some file managers (eg: Nautilus) are using sandboxing for thumbnails, which the F3D binary release does not support as it needs access to the Xorg server for rendering anything. A work around to this issue is to use a virtual Xorg server like Xephyr or Xvfb in the f3d.thumbnailer file. Here is how your Exec line should look to use xvfb-run. Keep in mind running xvfb can be very slow.

Exec=xvfb-run f3d --dry-run -sta --no-background --output=%o --resolution=%s,%s %i

Another workaround is to build VTK with EGL or osmesa support and then build f3d yourself against this custom VTK build.

I have a link error related to stdc++fs not found.

With some C++ STD library version, explicit linking to stdc++fs is not supported. We provide a CMake option F3D_APPLICATION_LINK_FILESYSTEM that you can set to OFF to workaround this issue.

Windows

After installing F3D or registering the shell extension, my explorer is broken

Unregister the shell extension by running:

cd C:\path\to\f3d\bin\
regsvr32 /u F3DShellExtension.dll

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.

License

F3D can be used and distributed under the 3-Clause BSD License, see LICENSE. F3D rely on other libraries and tools, all under permissive licenses, see THIRD_PARTY_LICENSES.md.