# 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](#struct-api) 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`)

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 and file content. See [user documentation](../user/02-SUPPORTED_FORMATS.md).

CLI: `--force-reader`.

### `scene.camera.orthographic` (_bool_, optional)

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

CLI: `--camera-orthographic`.

## Interactor Options

### `interactor.style` (_string_, default: `default`)

Set the interaction style. `default` uses standard 3D interaction, `trackball` enables trackball interaction, `2d` enables 2D interaction mode (pan/zoom only, no rotation). In `2d` mode, camera commands (`set_camera`, `roll_camera`, `elevation_camera`, `azimuth_camera`) are disabled.

CLI: `--interaction-style`.

### `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_glyphs.enable` (_bool_, default: `false`)

Render vertex normals as arrows on top of the geometry.

### `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.checkerboard.enable` (_bool_, default: `false`, **on load**)

Override model's texture with a checkerboard texture.

CLI: `--checkerboard`.

### `model.unlit` (_bool_, optional)

Override model's lighting configuration.
If the value is true, no shading is applied and the model will be unlit.

CLI: `--unlit`.

### `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: `--coloring-by-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](../user/08-PARSING.md#colormap) for details.

CLI: `--colormap`.

### `model.scivis.opacity_map` (_opacity_map_, default: "0.0,0.0,1.0,1.0")

Set a _custom opacity map for the coloring_. The format of the opacity map should be `val, opacity, ...`.
It is only used for volume rendering currently.

CLI: `--volume-opacity-map`.

### `model.scivis.component` (_int_, default: `-1`)

Specify the component to color with. `-1` means _magnitude_. `-2` means _direct values_.

CLI: `--coloring-component`.

### `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: `--coloring-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`, `gaussian`, `circle`, `stddev`, `bound` or `cross`).

CLI: `--point-sprites`.

### `model.point_sprites.size` (_double_, default: `10.0`)

Set the _size_ of point sprites.

CLI: `--point-sprites-size`.

### `model.point_sprites.absolute_size` (_bool_, default: `false`)

Do not scale the point sprites size by the scene bounding box.

CLI: `--point-sprites-absolute-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: `--volume-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.blending.enable` (_bool_, default: `false`)

Enable _blending support_. This is a technique used to correctly render translucent objects.

CLI: `--blending`.

### `render.effect.blending.mode` (_string_, default: `ddp`)

Set the blending technique. Valid options are: `ddp` (dual depth peeling, quality), `sort` (only for gaussians), `sort_cpu` (only for gaussians, slow), `stochastic` (fast)

CLI: `--blending`.

### `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`.

### `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](../user/10-FINAL_SHADER.md).

CLI: `--final-shader`

### `render.effect.display_depth` (_bool_, default: `false`)

Display the depth buffer as a grayscale image or with a colormap if `model.scivis.enable` is specified.
Only opaque objects are displayed, the grid and translucent/volumetric objects are ignored.

CLI: `--display-depth`

### `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, **on load**)

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.axes_grid` (_bool_, default: `false`)

Show _axes grid_ in the scene.

CLI: `--axes-grid`.

### `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: `--raytracing-samples`.

### `render.raytracing.denoise` (_bool_, default: `false`)

_Denoise_ the raytracing rendering.

CLI: `--raytracing-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.x_color` (_color_, default: `#f94306`)

Set the X axis color in both widget and grid.

CLI: `--x-color`.

### `ui.y_color` (_color_, default: `#7aff7a`)

Set the Y axis color in both widget and grid.

CLI: `--y-color`.

### `ui.z_color` (_color_, default: `#788bff`)

Set the Z axis color in both widget and grid.

CLI: `--z-color`.

### `ui.scalar_bar` (_bool_, default: `false`)

Show _scalar bar_ of the coloring by data array.

CLI: `--coloring-scalar-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.hdri_filename` (_bool_, default: `false`)

Display the _HDRI filename info content_ on top of the window.

CLI: `--hdri-filename`.

### `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.font_color` (_color_, default: `0.957,0.957,0.957`)

Set font color.

CLI: `--font-color`.

### `ui.dpi_aware` (_bool_, default: `false`)

Scale the _font scale_ and _resolution_ by the display scaling factor.
Only supported on Windows platform.

CLI: `--dpi-aware`.

### `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: `--loading-progress`.

### `ui.loader_progress_color` (_color_, optional, **on load**)

Set loader progress bar color or use default one #FFFFFF if not set.

### `ui.animation_progress` (_bool_, default: `false`, **on load**)

Show a _progress bar_ when playing the animation.

CLI: `--animation-progress`.

### `ui.animation_progress_color` (_color_, optional, **on load**)

Set animation progress bar color or use default one #788BFF if not set.

### `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`.

### `ui.scene_hierarchy` (_bool_, default: `false`)

Display the _scene hierarchy_ as a tree representing the internal structure of the model, with checkboxes allowing to hide or show individual parts.
By default the tree is only expanded enough to show nodes that have meaningful names, but all nodes can be fully expanded manually.

CLI: `--scene-hierarchy`.

### `ui.notifications.enable` (_bool_, default: `false`)

Show notifications at the bottom left of the viewport.

CLI: `--notifications`.

### `ui.notifications.show_bindings` (_bool_, default: `false`)

Show corresponding keys when notifications are triggered by bindings key press events.

# 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:

```cpp
  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:

```cpp
  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](../user/08-PARSING.md) for more details.

```cpp
  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:

```cpp
  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.

```cpp
  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.
