Skip to main content
Version: 🚧 Nightly

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.

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.