F3D Documentation

F3D is a fast and minimalist 3D viewer desktop application designed for viewing various file formats, including digital content and scientific datasets (e.g., glTF, USD, STL, STEP, PLY, OBJ, FBX, Alembic). It supports animations, thumbnails, real-time physically based rendering, and raytracing.

Key features include:

• Full command-line control.
• Support for configuration files.
• Interactive hotkeys and drag-and-drop support.
• Integration into file managers.
• A library component called libf3d for rendering meshes via C++17, C, Python, Java, and JavaScript bindings.

The application directory contains the code for the F3D standalone viewer. Key components include:

• F3DStarter: The primary class containing the core application logic.
• F3DOptionsTools: A utility class responsible for handling command-line options logic.

F3D defines several roles for community members and stakeholders:

• Maintainers: Responsible for organizing development, upholding the Code of Conduct, and determining consensus for technical or community matters. They hold 'owner' roles in the f3d-app GitHub organization.
• Moderators: Responsible for upholding the Code of Conduct and determining consensus for community matters.
• Returning Contributors: Individuals who have merged at least two pull requests over multiple releases. They are recognized as 'members' in the f3d-app GitHub organization and may mentor Mentees.
• Contributors: Anyone making or intending to make contributions to the project.
• Mentees: Contributors enrolled in the F3D mentoring program to learn open-source contribution.
• Sponsors / Industry Sponsors: Individuals or companies providing financial support to the project.

F3D uses a plugin-based architecture to handle file reading.

• Functionality: Each plugin provides access to specific readers for specific file formats. Without plugins, neither the F3D application nor libf3d can open files.
• Loading: Plugins can be loaded either statically or dynamically.
• Optionality: Because plugins can be loaded dynamically, their specific dependencies are truly optional, allowing for a modular installation.

The libf3d library is a C++ library with a split architecture designed to maintain a limited public API surface while providing a robust implementation:

• public: Contains the public API header files that are installed for consumers.
• private: Contains implementation class headers and the src directory containing source files for both public and private classes.
• Implementation Pattern: Most classes are split into a public part and a private part (suffixed with _impl). The _impl classes handle the actual logic and facilitate communication between classes, particularly regarding VTK symbols.
• Options: The library uses an options.json file to automatically generate all available options code.

F3D handles files in two ways depending on their format:

1. Full scene formats: Formats like .gltf/.glb, .3ds, .wrl, .obj, .fbx, .dae, .off, .x, .3mf, and .usd contain geometry, lights, cameras, actors, and texture properties. F3D loads and displays all this information by default.

2. Default scene formats: For formats that are not full scenes, F3D creates a default scene using these automatic values:

   • texture-*: ""
   • line-width: 1.0
   • point-size: 10.0
   • opacity: 1.0
   • color: 0.65, 0.65, 0.65
   • emissive-factor: 1.0, 1.0, 1.0
   • normal-scale: 1.0
   • metallic: 0.0
   • roughness: 0.3
   • base-ior: 1.5
   • camera-orthographic: false
   • unlit: false

These defaults can be overridden via command-line options or a configuration file.

F3D follows a predictable release cycle consisting of one minor release every three months. Minor releases are scheduled for:

• January
• April
• July
• October

Note that a minor release may be skipped in anticipation of a major release (e.g., version 4.0.0).

To render a 3D file and start an interactive session, initialize the engine, load the file into the scene, and start the interactor. It is recommended to call f3d::engine::autoloadPlugins() to ensure VTK native readers are available.

#include <f3d/engine.h>
#include <f3d/interactor.h>
#include <f3d/scene.h>

// Load VTK native readers
f3d::engine::autoloadPlugins();

// Create a f3d::engine
f3d::engine eng = f3d::engine::create();

// Add a file into a scene
eng.getScene().add("path/to/file.ext");

// Start rendering and interacting
eng.getInteractor().start();

Interaction tests simulate human input like mouse movements, scrolls, and keypresses.

1. Record the interaction: Run F3D with the --interaction-test-record flag. Perform the minimum necessary actions, then exit F3D using your window manager or Ctrl+C (do not use the internal quit command).

f3d --interaction-test-record ./TestName.log

2. Verify the recording: Play back the log to ensure it behaves as expected:

f3d --interaction-test-play ./TestName.log

3. Integrate into the test suite: Clean up unnecessary interactions in the log, move the file to ./testing/recordings, and add the test to application/testing/CMakeLists.txt using the INTERACTION keyword:

f3d_test(NAME TestName DATA datafile.ext INTERACTION)

F3D allows you to save and restore the application state (options, camera, window size, and file groups) using statefiles.

• Save state: Use --save-statefile=<file path> to save the current state immediately after loading. Use - to write to stdout.
• Load state: Use --load-statefile=<file path> to restore state immediately after starting. Use - to read from stdin. Note that restored window size is overridden by an explicit --resolution.
• Default filename: The --statefile-filename=<file path> option sets the default filename used by the save_statefile and load_statefile commands if none is provided. Use - for stdin/stdout behavior.

When rendering STEP files, the --color option may be ignored because scalar coloring is enabled by default. To use a specific color, you must explicitly disable scalar coloring.

CLI approach: Use --color=<COLOR> --scalar-coloring=no.

Configuration file approach: Add a match rule to your config file to disable scalar coloring for these extensions:

{
  "match-type": "glob",
  "match": "*.{step,stp,iges,igs,brep,xbf}",
  "options": {
    "scalar-coloring": false
  }
}