Options

An option is a specific value stored in different struct in an options instance. They can be accessed directly through the structs, through a string API or through a std::variant API.

The possible option are listed below and are organized by categories and subcategories, here is a non-exhaustive explanation of the categories.

• scene options are related to how the scene is being displayed
• render options are related to the way the render is done
• render.effect options are related to specific techniques used that modify the render
• ui options are related to the screenspace UI element displayed
• model options are related to modifications on the model
• interactor options requires an interactor to be present to have any effect

Please note certain options are taken into account when rendering, others when loading a file. See the exhaustive list below.

Please note certain options are optional by default, which means they are not set initially, See the APIs details below for more info.

Scene Options

scene.animation.autoplay (bool, default: false, on load)

Automatically start animation.

CLI: --animation-autoplay.

scene.animation.indices (vector<int>, default: 0, on load)

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

CLI: --animation-indices.

scene.animation.speed_factor (ratio, default: 1)

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

CLI: --animation-speed-factor.

scene.animation.time (double, optional, on load)

Set the animation time to load.

CLI: --animation-time.

scene.camera.index (int, optional, on load)

Select the scene camera to use when available in the file. The default scene always uses automatic camera.

CLI: --camera-index.

scene.up_direction (direction, default: +Y, on load)

Define the Up direction. It impacts the grid, the axis, the HDRI and the camera. CLI: --up.

scene.force_reader (string, optional, on load)

Force a specific reader to be used, disregarding the file extension. See user documentation.

CLI: --force-reader.

scene.camera.orthographic (bool, optional, on load)

Set to true to force orthographic projection. Model-specified by default, which is false if not specified.

CLI: --camera-orthographic.

Interactor Options

interactor.trackball (bool, default: false)

Enable trackball interaction.

CLI: --trackball.

interactor.invert_zoom (bool, default: false)

Invert the zoom direction.

CLI: --invert-zoom.

Model Options

model.matcap.texture (path, optional)

Path to a texture file containing a material capture. All other model options for surfaces are ignored if this is set. Model-specified by default.

CLI: --texture-matcap.

model.color.opacity (double, optional)

Set opacity on the geometry. Usually used with Depth Peeling option. Multiplied with the model.color.texture when present. Model-specified by default.

CLI: --opacity.

model.color.rgb (color, optional)

Set a color on the geometry. Multiplied with the model.color.texture when present. Model-specified by default.

CLI: --color.

model.color.texture (path, optional)

Path to a texture file that sets the color of the object. Will be multiplied with rgb and opacity. Model-specified by default.

CLI: --texture-base-color.

model.emissive.factor (color, optional)

Multiply the emissive color when an emissive texture is present. Model-specified by default.

CLI: --emissive-factor.

model.emissive.texture (path, optional)

Path to a texture file that sets the emitted light of the object. Multiplied with the model.emissive.factor. Model-specified by default.

CLI: --texture-emissive.

model.material.metallic (double, optional)

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

CLI: --metallic.

model.material.roughness (double, optional)

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

CLI: --roughness.

model.material.base_ior (double, optional)

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

CLI: --base-ior.

model.material.texture (path, optional)

Path to a texture file that sets the Occlusion, Roughness and Metallic values of the object. Multiplied with the model.material.roughness and model.material.metallic, set both of them to 1.0 to get a true result. Model-specified by default.

CLI: --texture-material.

model.normal.scale (double, optional)

Normal scale affects the strength of the normal deviation from the normal texture. Model-specified by default.

CLI: --normal-scale.

model.normal.texture (path, optional)

Path to a texture file that sets the normal map of the object. Model-specified by default.

CLI: --texture-normal.

model.scivis.enable (bool, default: false)

Color by an array present in on the data. If model.scivis.array_name is not set, the first available array will be used.

CLI: --scalar-coloring.

model.scivis.cells (bool, default: false)

Color the data with value found on the cells instead of points

CLI: --cells.

model.scivis.discretization (int, optional)

Set how many distinct colors will be used from the colormap. Should be >=1.

CLI: --colormap-discretization.

model.scivis.colormap (colormap, default: \<inferno\>)

Set a custom colormap for the coloring.See colormap parsing for details.

CLI: --colormap.

model.scivis.component (int, default: -1)

Specify the component to color with. -1 means magnitude. -2 means direct values.

CLI: --comp.

model.scivis.array_name (string, optional)

Select the name of the array to color with.

CLI: --coloring-array.

model.scivis.range (vector<double>, optional)

Set the coloring range. Automatically computed by default.

CLI: --range.

model.point_sprites.enable (bool, default: false)

Show sphere points sprites instead of the geometry.

CLI: --point-sprites.

model.point_sprites.type (string, default: sphere)

Set the sprites type when showing point sprites (can be sphere or gaussian).

CLI: --point-sprites-type.

model.point_sprites.size (double, default: 10.0)

Set the size of point sprites.

CLI: --point-sprites-size.

model.volume.enable (bool, default: false)

Enable volume rendering. It is only available for 3D image data and will display nothing with incompatible data. It forces coloring.

CLI: --volume.

model.volume.inverse (bool, default: false)

Inverse the linear opacity function.

CLI: --inverse.

model.textures_transform (transform2d, optional)

Transform applied to textures on the model. If a default transform is set by the importer, the default value will be multiplied by this transform.

CLI: --textures-transform.

Render Options

render.effect.translucency_support (bool, default: false)

Enable translucency support. This is a technique used to correctly render translucent objects, implemented using depth peeling

CLI: --translucency-support.

render.effect.antialiasing.enable (string, default: false)

Enable anti-aliasing. This technique is used to reduce aliasing.

CLI: --anti-aliasing.

render.effect.antialiasing.mode (string, default: fxaa)

Set the anti-aliasing technique. Valid options are: fxaa (fast), ssaa (quality), taa (balanced)

CLI: --anti-aliasing-mode.

render.effect.ambient_occlusion (bool, default: false)

Enable ambient occlusion. This is a technique providing approximate shadows, used to improve the depth perception of the object. Implemented using SSAO

CLI: --ambient-occlusion.

render.effect.tone_mapping (bool, default: false)

Enable generic filmic Tone Mapping Pass. This technique is used to map colors properly to the monitor colors.

CLI: --tone-mapping.

render.effect.final_shader (string, optional)

Add a final shader to the output image. See user documentation.

CLI: --final-shader

render.line_width (double, optional)

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

CLI: --line-width.

render.show_edges (bool, optional)

Set to true to show the cell edges. Model-specified by default.

CLI: --edges.

render.point_size (double, optional)

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

CLI: --point-size.

render.backface_type (string, optional)

Set the Backface type, can be visible or hidden, Model-specified by default.

CLI: --backface-type.

render.grid.enable (bool, default: false)

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

CLI: --grid.

render.grid.absolute (bool, default: false)

Position the grid at the absolute origin of the model's coordinate system instead of below the model.

CLI: --grid-absolute.

render.grid.unit (double, optional)

Set the size of the unit square for the grid. Automatically computed by default.

CLI: --grid-unit.

render.grid.subdivisions (int, default: 10)

Set the number of subdivisions for the grid.

CLI: --grid-subdivisions.

render.grid.color (color, default: 0, 0, 0)

Set the color of grid lines.

CLI: --grid-color.

render.raytracing.enable (bool, default: false)

Enable raytracing. Requires the raytracing module to be enabled.

CLI: --raytracing.

render.raytracing.samples (int, default: 5)

The number of samples per pixel.

CLI: --samples.

render.raytracing.denoise (bool, default: false)

Denoise the raytracing rendering.

CLI: --denoise.

render.hdri.file (path, optional)

Set the HDRI image that can be used for ambient lighting and skybox. Valid file format are .hdr, .exr, .png, .jpg, .pnm, .tiff, .bmp. If not set, a default is provided.

CLI: --hdri-file.

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

CLI: --hdri-ambient.

render.background.color (color, default: 0.2,0.2,0.2)

Set the window background color. Ignored if a hdri skybox is used.

CLI: --background-color.

render.background.skybox (bool, default: false)

Show the HDRI image as a skybox Overrides the the background color if any

CLI: --hdri-skybox.

render.background.blur.enable (bool, default: false)

Blur background, useful with a skybox.

CLI: --blur-background.

render.background.blur.coc (double, default: 20.0)

Blur background circle of confusion radius.

CLI: --blur-coc.

render.light.intensity (double, default: 1.0)

Adjust the intensity of every light in the scene.

CLI: --light-intensity.

render.armature.enable (bool, default: false)

Display armatures if present in the scene (glTF only).

CLI: --armature.

UI Options

ui.axis (bool, default: false)

Show axes as a trihedron in the scene. Requires an interactor.

CLI: --axis.

ui.scalar_bar (bool, default: false)

Show scalar bar of the coloring by data array.

CLI: --bar.

ui.cheatsheet (bool, default: false)

Show a interaction cheatsheet

ui.console (bool, default: false)

Show the console

ui.minimal_console (bool, default: false)

Show the minimal console. Useful to execute a quick command and exit.

ui.filename (bool, default: false)

Display the filename info content on top of the window.

ui.filename_info (string, default: "")

Content of filename info to display.

ui.font_file (path, optional)

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

CLI: --font-file.

ui.scale (ratio, default: 1.0)

Scale fonts. Useful for HiDPI displays.

CLI: --font-scale.

ui.fps (bool, default: false)

Display a frame per second counter.

CLI: --fps.

ui.loader_progress (bool, default: false, on load)

Show a progress bar when loading the file.

CLI: --progress.

ui.animation_progress (bool, default: false, on load)

Show a progress bar when playing the animation. CLI: --animation-progress.

ui.metadata (bool, default: false)

Display the metadata.

CLI: --metadata.

ui.drop_zone.enable (bool, default: false)

Show a drop zone. Rendering is disabled when the viewport is smaller than 10×10 pixels.

ui.drop_zone.custom_binds (string, default: "")

Space separated custom key bindings to display in the drop zone.

ui.drop_zone.show_logo (bool, default: false)

Display the logo. Needs ui.drop_zone.enable to be true.

ui.backdrop.opacity (double, default: 0.9)

Set the opacity of the backdrop behind the UI elements. Value is between 0.0 (fully transparent) and 1.0 (fully opaque).

CLI: --backdrop-opacity.

APIs

There are three APIs to access the options

Struct API

The most straightforward and easy to use API, just access it through the structs available in the options instance, eg:

  f3d::engine eng = f3d::engine::create();
  f3d::options& opt = eng.getOptions();
  opt.render.show_edges = true;
  opt.render.grid.enable = true;
  opt.ui.metadata = true;
  opt.model.material.roughness = 0.6;

Please note that when accessing optional options, special care must be used, eg:

  f3d::engine eng = f3d::engine::create();
  f3d::options& opt = eng.getOptions();
  if (opt.render.line_width.has_value())
  {
    std::cout << "Line Width: " << opt.render.line_width.value() << "\n";
  }
  else
  {
    std::cout << "Line Width: unset\n";
  }

It's even more true with the few optional boolean options as std::optional has an implicit boolean cast operator.

String API

The most generic and flexible API, as it rely on parsing and string generation. See the parsing documentation for more details.

  f3d::engine eng = f3d::engine::create();
  f3d::options& opt = eng.getOptions();
  opt.setAsString("render.show_edges", "true");
  opt.setAsString("render.grid.enable", "true");
  opt.setAsString("ui.metadata", "true");
  opt.setAsString("model.material.roughness", "0.6");

When using this API make sure to catch exceptions has needed, eg:

  f3d::engine eng = f3d::engine::create();
  f3d::options& opt = eng.getOptions();

  try
  {
    std::cout << userProvidedName << ": " << opt.getAsString(userProvidedName) << "\n";
  }
  catch (const f3d::options::inexistent_exception&)
  {
    std::cout << userProvidedName << " does not exist.\n";
  }
  catch (const f3d::options::no_value_exception&)
  {
    std::cout << userProvidedName << " is not set.\n";
  }

Variant API

An API that is similar to the F3D 2.0 options API thanks to std::variant.

  f3d::engine eng = f3d::engine::create();
  f3d::options& opt = eng.getOptions();
  opt.set("render.show_edges", true);
  opt.set("render.grid.enable", true);
  opt.set("ui.metadata", true);
  opt.set("model.material.roughness", 0.6);

When using this API make sure to catch exception shown above with the string API.