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.
sceneoptions are related to how the scene is being displayedrenderoptions are related to the way the render is donerender.effectoptions are related to specific techniques used that modify the renderuioptions are related to the screenspace UI element displayedmodeloptions are related to modifications on the modelinteractoroptions 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, but note that this may change in the future.
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
| Option | Type Default Trigger | Description | F3D option |
|---|---|---|---|
| scene.animation.autoplay | bool false load | Automatically start animation. | --animation-autoplay |
| scene.animation.indices | vector<int> 0 load | Select the animations to load. Any negative value means all animations. The default scene always has at most one animation. | --animation-indices |
| scene.animation.speed_factor | ratio 1 render | Set the animation speed factor to slow, speed up or even invert animation. | --animation-speed-factor |
| scene.animation.time | double optional load | Set the animation time to load. | --animation-time |
| scene.camera.index | int optional load | Select the scene camera to use when available in the file. The default scene always uses automatic camera. | --camera-index |
| scene.up_direction | direction +Y load | Define the Up direction. It impacts the grid, the axis, the HDRI and the camera. | --up |
| scene.force_reader | string optional load | Force a specific reader to be used, disregarding the file extension. See user documentation | --force-reader |
| scene.camera.orthographic | bool optional load | Set to true to force orthographic projection. Model specified by default, which is false if not specified. | --camera-orthographic |
Interactor Options
| Option | Type Default Trigger | Description | F3D option |
|---|---|---|---|
| interactor.trackball | bool false render | Enable trackball interaction. | --trackball |
| interactor.invert_zoom | bool false render | Invert the zoom direction. | --invert-zoom |
Model Options
| Option | Type Default Trigger | Description | F3D option |
|---|---|---|---|
| model.matcap.texture | path optional render | 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. | --texture-matcap |
| model.color.opacity | double optional render | Set opacity on the geometry. Usually used with Depth Peeling option. Multiplied with the model.color.texture when present. Model specified by default. | --opacity |
| model.color.rgb | color optional render | Set a color on the geometry. Multiplied with the model.color.texture when present. Model specified by default. | --color |
| model.color.texture | path optional render | Path to a texture file that sets the color of the object. Will be multiplied with rgb and opacity. Model specified by default. | --texture-base-color |
| model.emissive.factor | color optional render | Multiply the emissive color when an emissive texture is present. Model specified by default. | --emissive-factor |
| model.emissive.texture | path render | Path to a texture file that sets the emitted light of the object. Multiplied with the model.emissive.factor. Model specified by default. | --texture-emissive |
| model.material.metallic | double optional render | Set the metallic coefficient on the geometry (0.0-1.0). Multiplied with the model.material.texture when present. Model specified by default. | --metallic |
| model.material.roughness | double optional render | Set the roughness coefficient on the geometry (0.0-1.0). Multiplied with the model.material.texture when present. Model specified by default. | --roughness |
| model.material.base_ior | double optional render | Set the index of refraction of the base layer (1.0-2.5). Model specified by default. | --base-ior |
| model.material.texture | path optional render | 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. | --texture-material |
| model.normal.scale | double optional render | Normal scale affects the strength of the normal deviation from the normal texture. Model specified by default. | --normal-scale |
| model.normal.texture | path optional render | Path to a texture file that sets the normal map of the object. Model specified by default. | --texture-normal |
| model.scivis.enable | bool false render | Color by an array present in on the data. If model.scivis.array_name is not set, the first available array will be used. | --scalar-coloring |
| model.scivis.cells | bool false render | Color the data with value found on the cells instead of points | --cells |
| model.scivis.discretization | int optional render | Set how many distinct colors will be used from the colormap. [1, N] will discretize, values outside that range will result in smooth shading. | --colormap-discretization |
| model.scivis.colormap | colormap <inferno> render | Set a custom colormap for the coloring.See colormap parsing for details. | --colormap |
| model.scivis.component | int -1 render | Specify the component to color with. -1 means magnitude. -2 means direct values. | --comp |
| model.scivis.array_name | string render | Select the name of the array to color with. | --coloring-array |
| model.scivis.range | vector<double> optional render | Set the coloring range. Automatically computed by default. | --range |
| model.point_sprites.enable | bool false render | Show sphere points sprites instead of the geometry. | --point-sprites |
| model.point_sprites.type | string sphere render | Set the sprites type when showing point sprites (can be sphere or gaussian). | --point-stripes-type |
| model.point_sprites.size | double 10.0 render | Set the size of point sprites. | --point-stripes-size |
| model.volume.enable | bool false render | Enable volume rendering. It is only available for 3D image data (vti, dcm, nrrd, mhd files) and will display nothing with other formats. It forces coloring. | --volume |
| model.volume.inverse | bool false render | Inverse the linear opacity function. | --inverse |
| model.textures_transform | transform2d optional render | 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. | --textures-transform |
Render Options
| Option | Type Default Trigger | Description | F3D option |
|---|---|---|---|
| render.effect.translucency_support | bool false render | Enable translucency support. This is a technique used to correctly render translucent objects, implemented using depth peeling | --translucency-support |
| render.effect.antialiasing.enable | string false render | Enable anti-aliasing. This technique is used to reduce aliasing. | --anti-aliasing |
| render.effect.antialiasing.mode | string fxaa render | Set the anti-aliasing technique. Valid options are: FXAA (fast), SSAA (quality) | --anti-aliasing-mode |
| render.effect.ambient_occlusion | bool false render | Enable ambient occlusion. This is a technique providing approximate shadows, used to improve the depth perception of the object. Implemented using SSAO | --ambient_occlusion |
| render.effect.tone_mapping | bool false render | Enable generic filmic Tone Mapping Pass. This technique is used to map colors properly to the monitor colors. | --tone-mapping |
| render.effect.final_shader | string optional render | Add a final shader to the output image | --final-shader. See user documentation. |
| render.line_width | double optional render | Set the width of lines when showing edges. Model specified by default. | --line-width |
| render.show_edges | bool optional render | Set to true to show the cell edges. Model specified by default. | --edges |
| render.point_size | double optional render | Set the size of points when showing vertices. Model specified by default. | --point-size |
| render.backface_type | string optional render | Set the Backface type, can be visible or hidden, model specified by default. | --backface-type |
| render.grid.enable | bool false render | Show a grid aligned with the horizontal (orthogonal to the Up direction) plane. | --grid |
| render.grid.absolute | bool false render | Position the grid at the absolute origin of the model's coordinate system instead of below the model. | --grid |
| render.grid.unit | double optional render | Set the size of the unit square for the grid. Automatically computed by default. | --grid-unit |
| render.grid.subdivisions | int 10 render | Set the number of subdivisions for the grid. | --grid-subdivisions |
| render.grid.color | color 0, 0, 0 render | Set the color of grid lines. | --grid-color |
| render.raytracing.enable | bool false render | Enable raytracing. Requires the raytracing module to be enabled. | --raytracing |
| render.raytracing.samples | int 5 render | The number of samples per pixel. | --samples |
| render.raytracing.denoise | bool false render | Denoise the raytracing rendering. | --denoise |
| render.hdri.file | path optional render | 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. | --hdri-file |
| render.hdri.ambient | bool false render | Light the scene using the HDRI image as ambient lighting The environment act as a light source and is reflected on the material. | --hdri-ambient |
| render.background.color | color 0.2,0.2,0.2 render | Set the window background color. Ignored if a hdri skybox is used. | --background-color |
| render.background.skybox | bool false render | Show the HDRI image as a skybox Overrides the the background color if any | --hdri-skybox |
| render.background.blur.enable | bool false render | Blur background, useful with a skybox. | --blur-background |
| render.background.blur.coc | double 20.0 render | Blur background circle of confusion radius. | --blur-coc |
| render.light.intensity | double 1.0 render | Adjust the intensity of every light in the scene. | --light-intensity |
| render.armature.enable | bool false render | Display armatures if present in the scene (glTF only). | --armature |
UI Options
| Option | Type Default Trigger | Description | F3D option |
|---|---|---|---|
| ui.axis | bool false render | Show axes as a trihedron in the scene. Requires an interactor. | --axis |
| ui.scalar_bar | bool false render | Show scalar bar of the coloring by data array. | --bar |
| ui.cheatsheet | bool false render | Show a interaction cheatsheet | - |
| ui.console | bool false render | Show the console | - |
| ui.minimal_console | bool false render | Show the minimal console. Useful to execute a quick command and exit. | - |
| ui.filename | bool false render | Display the filename info content on top of the window. | --filename |
| ui.filename_info | string - render | Content of filename info to display. | - |
| ui.font_file | path optional render | Use the provided FreeType compatible font file to display text. Can be useful to display non-ASCII filenames. | --font-file |
| ui.scale | ratio 1.0 render | Scale fonts. | --font-scale |
| ui.fps | bool false render | Display a frame per second counter. | --fps |
| ui.loader_progress | bool false load | Show a progress bar when loading the file. | --progress |
| ui.animation_progress | bool false load | Show a progress bar when playing the animation. | --animation-progress |
| ui.metadata | bool false render | Display the metadata. | --metadata |
| ui.drop_zone.enable | bool false render | Show a drop zone. Rendering is disabled when the viewport is smaller than 10×10 pixels. | - |
| ui.drop_zone.custom_binds | string - render | Space separated custom key bindings to display in the drop zone. | - |
| ui.drop_zone.show_logo | bool false render | Display the logo. Needs ui.drop_zone.enable to be true. | - |
| ui.backdrop.opacity | double 0.9 render | Set the opacity of the backdrop behind the UI elements. Value is between 0.0 (fully transparent) and 1.0 (fully opaque). | --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.