Options exhaustive list
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 last one require C++17. If your compiler does not support C++17, you can disable this API by defining F3D_DISABLE_CXX17_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 model, they are only meaningful when using the default sceneinteractoroptions 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.
Scene Options
| Option | Type Default Trigger | Description | F3D option |
|---|---|---|---|
| scene.animation.autoplay | bool false load | Automatically start animation. | --animation-autoplay |
| scene.animation.index | int 0 load | Select the animation to load. Any negative value means all animations (glTF only). The default scene always has at most one animation. | --animation-index |
| scene.animation.speed_factor | double 1 render | Set the animation speed factor to slow, speed up or even invert animation. | --animation-speed-factor |
| scene.animation.frame_rate | double 60 render | Set the animation frame rate used to play the animation interactively. | --animation-frame-rate |
| scene.camera.index | int -1 load | Select the scene camera to use when available in the file. Any negative value means automatic camera. The default scene always uses automatic camera. | --camera-index |
| scene.up_direction | string +Y load | Define the Up direction | --up |
| scene.camera.orthographic | bool false load | Toggles between orthographic projection and parallel mode. | --camera-orthographic |
Interactor Options
| Option | Type Default Trigger | Description | F3D option |
|---|---|---|---|
| interactor.axis | bool false render | Show axes as a trihedron in the scene. | --axis |
| interactor.trackball | bool false render | Enable trackball interaction. | --trackball |
Model Options
| Option | Type Default Trigger | Description | F3D option |
|---|---|---|---|
| model.matcap.texture | string - render | Path to a texture file containing a material capture. All other model options for surfaces are ignored if this is set. | --texture-matcap |
| model.color.opacity | double 1.0 render | Set opacity on the geometry. Usually used with Depth Peeling option. Multiplied with the model.color.texture when present. | --opacity |
| model.color.rgb | vector<double> 1.0,1.0,1.0 render | Set a color on the geometry. Multiplied with the model.color.texture when present. | --color |
| model.color.texture | string - render | Path to a texture file that sets the color of the object. Will be multiplied with rgb and opacity. | --texture-base-color |
| model.emissive.factor | vector<double> 1.0,1.0,1.0 render | Multiply the emissive color when an emissive texture is present. | --emissive-factor |
| model.emissive.texture | string - render | Path to a texture file that sets the emitted light of the object. Multiplied with the model.emissive.factor. | --texture-emissive |
| model.material.metallic | double 0.0 render | Set the metallic coefficient on the geometry (0.0-1.0). Multiplied with the model.material.texture when present. | --metallic |
| model.material.roughness | double 0.3 render | Set the roughness coefficient on the geometry (0.0-1.0). Multiplied with the model.material.texture when present. | --roughness |
| model.material.texture | string - 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. | --texture-material |
| model.normal.scale | double 1.0 render | Normal scale affects the strength of the normal deviation from the normal texture. | --normal-scale |
| model.normal.texture | string - render | Path to a texture file that sets the normal map of the object. | --texture-normal |
| model.scivis.cells | bool false render | Color the data with value found on the cells instead of points | --cells |
| model.scivis.colormap | vector<double> <inferno> render | Set a custom colormap for the coloring. This is a list of colors in the format val1,red1,green1,blue1,...,valN,redN,greenN,blueNwhere all values are in the range (0,1). | --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 <reserved> render | Color by a specific data array present in on the data. Set to | --scalars |
| model.scivis.range | vector<double> - render | Set a custom range for the coloring. | --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-type |
| 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 default scene formats. | --volume |
| model.volume.inverse | bool false render | Inverse the linear opacity function. | --inverse |
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.anti_aliasing | bool false render | Enable anti-aliasing. This technique is used to reduce aliasing, implemented using FXAA. | --anti-aliasing |
| 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 ”“ render | Add a final shader to the output image | --final-shader. See user documentation. |
| render.line_width | double 1.0 render | Set the width of lines when showing edges. | --line-width |
| render.show_edges | bool false render | Show the cell edges | --edges |
| render.point_size | double 10.0 render | Set the size of points when showing vertices and point sprites. | --point-size |
| 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 0 render | Set the size of the unit square for the grid. If set to non-positive (the default) a suitable value will be automatically computed. | --grid-unit |
| render.grid.subdivisions | int 10 render | Set the number of subdivisions for the grid. | --grid-subdivisions |
| render.grid.color | int (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 | string - 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 | vector<double> 0.2,0.2,0.2 render | Set the window background color. Ignored if a hdri skybox is used. | --bg-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 | 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 |
UI Options
| Option | Type Default Trigger | Description | F3D option |
|---|---|---|---|
| ui.scalar_bar | bool false render | Show scalar bar of the coloring by data array. | --bar |
| ui.cheatsheet | bool false render | Show a interactor cheatsheet | |
| 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 | string - render | Use the provided FreeType compatible font file to display text. Can be useful to display non-ASCII filenames. | --font-file |
| 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.dropzone | bool false render | Show a drop zone. | |
| ui.dropzone_info | string - render | Content of the drop zone text to display. |
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::window::Type::NATIVE);
+ Options | F3D Skip to main content Options exhaustive list
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 last one require C++17. If your compiler does not support C++17, you can disable this API by defining F3D_DISABLE_CXX17_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 displayedrender options are related to the way the render is donerender.effect options are related to specific techniques used that modify the renderui options are related to the screenspace UI element displayedmodel options are related to modifications on the model, they are only meaningful when using the default sceneinteractor 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, but note that this may change in the future.
Scene Options
Option Type
Default
Trigger Description F3D option scene.animation.autoplay bool
false
load Automatically start animation. --animation-autoplay scene.animation.index int
0
load Select the animation to load.
Any negative value means all animations (glTF only).
The default scene always has at most one animation. --animation-index scene.animation.speed_factor double
1
render Set the animation speed factor to slow, speed up or even invert animation. --animation-speed-factor scene.animation.frame_rate double
60
render Set the animation frame rate used to play the animation interactively. --animation-frame-rate scene.camera.index int
-1
load Select the scene camera to use when available in the file.
Any negative value means automatic camera.
The default scene always uses automatic camera. --camera-index scene.up_direction string
+Y
load Define the Up direction --up scene.camera.orthographic bool
false
load Toggles between orthographic projection and parallel mode. --camera-orthographic
Interactor Options
Option Type
Default
Trigger Description F3D option interactor.axis bool
false
render Show axes as a trihedron in the scene. --axis interactor.trackball bool
false
render Enable trackball interaction. --trackball
Model Options
Option Type
Default
Trigger Description F3D option model.matcap.texture string
-
render Path to a texture file containing a material capture. All other model options for surfaces are ignored if this is set. --texture-matcap model.color.opacity double
1.0
render Set opacity on the geometry. Usually used with Depth Peeling option. Multiplied with the model.color.texture when present. --opacity model.color.rgb vector<double>
1.0,1.0,1.0
render Set a color on the geometry. Multiplied with the model.color.texture when present. --color model.color.texture string
-
render Path to a texture file that sets the color of the object. Will be multiplied with rgb and opacity. --texture-base-color model.emissive.factor vector<double>
1.0,1.0,1.0
render Multiply the emissive color when an emissive texture is present. --emissive-factor model.emissive.texture string
-
render Path to a texture file that sets the emitted light of the object. Multiplied with the model.emissive.factor. --texture-emissive model.material.metallic double
0.0
render Set the metallic coefficient on the geometry (0.0-1.0). Multiplied with the model.material.texture when present. --metallic model.material.roughness double
0.3
render Set the roughness coefficient on the geometry (0.0-1.0). Multiplied with the model.material.texture when present. --roughness model.material.texture string
-
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. --texture-material model.normal.scale double
1.0
render Normal scale affects the strength of the normal deviation from the normal texture. --normal-scale model.normal.texture string
-
render Path to a texture file that sets the normal map of the object. --texture-normal model.scivis.enable bool
false
render Color by an array present in on the data. If model.scivis.array_name is set to , 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.colormap vector<double>
<inferno>
render Set a custom colormap for the coloring.
This is a list of colors in the format val1,red1,green1,blue1,...,valN,redN,greenN,blueN
where all values are in the range (0,1). --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>
-
render Set a custom range for the coloring. --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-type 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 default scene formats. --volume model.volume.inverse bool
false
render Inverse the linear opacity function. --inverse
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.anti_aliasing bool
false
render Enable anti-aliasing. This technique is used to reduce aliasing, implemented using FXAA. --anti-aliasing 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
”“
render Add a final shader to the output image --final-shader. See user documentation. render.line_width double
1.0
render Set the width of lines when showing edges. --line-width render.show_edges bool
false
render Show the cell edges --edges render.point_size double
10.0
render Set the size of points when showing vertices and point sprites. --point-size 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
0
render Set the size of the unit square for the grid. If set to non-positive (the default) a suitable value will be automatically computed. --grid-unit render.grid.subdivisions int
10
render Set the number of subdivisions for the grid. --grid-subdivisions render.grid.color int
(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 string
-
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 vector<double>
0.2,0.2,0.2
render Set the window background color.
Ignored if a hdri skybox is used. --bg-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 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
UI Options
Option Type
Default
Trigger Description F3D option ui.scalar_bar bool
false
render Show scalar bar of the coloring by data array. --bar ui.cheatsheet bool
false
render Show a interactor cheatsheet 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 string
-
render Use the provided FreeType compatible font file to display text.
Can be useful to display non-ASCII filenames. --font-file 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.dropzone bool
false
render Show a drop zone. ui.dropzone_info string
-
render Content of the drop zone text to display.
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::window::Type::NATIVE);
f3d::options& opt = eng.getOptions();
opt.render.show_edges = true;
opt.render.grid.enable = true;
diff --git a/doc/libf3d/OPTIONS.md b/doc/libf3d/OPTIONS.md
index ec2cfca05f..8302adee48 100644
--- a/doc/libf3d/OPTIONS.md
+++ b/doc/libf3d/OPTIONS.md
@@ -50,10 +50,11 @@ model.material.roughness|double
0.3
render|Set the *roughness coefficient*
model.material.texture|string
-
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.|\-\-texture-material
model.normal.scale|double
1.0
render|Normal scale affects the strength of the normal deviation from the normal texture.|\-\-normal-scale
model.normal.texture|string
-
render|Path to a texture file that sets the normal map of the object.|\-\-texture-normal
+model.scivis.enable|bool
false
render|*Color by an array* present in on the data. If `model.scivis.array_name` is set to , 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.colormap|vector\
\
render|Set a *custom colormap for the coloring*.
This is a list of colors in the format `val1,red1,green1,blue1,...,valN,redN,greenN,blueN`
where all values are in the range (0,1).|\-\-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|*Color by a specific data array* present in on the data. Set to to let libf3d find the first available array.|\-\-scalars
+model.scivis.array_name|string
-
render|Select the name of the array to color with.|\-\-coloring-array
model.scivis.range|vector\
-
render|Set a *custom range for the coloring*.|\-\-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-type
diff --git a/doc/user/CONFIGURATION_FILE.html b/doc/user/CONFIGURATION_FILE.html
index b4e08729ca..f8556f4a64 100644
--- a/doc/user/CONFIGURATION_FILE.html
+++ b/doc/user/CONFIGURATION_FILE.html
@@ -1,5 +1,5 @@
- Configuration File | F3D Skip to main content Configuration File
Almost all the command-line options can be controlled using configuration files. Configuration files uses the “long” version of the command-line options in a JSON formatted file to provide values for these options.
These options can be organized by block using a regular expression for each block in order to provide different default values for the different filetypes.
A special block, named global, will apply to all files. Using a command-line option will override the corresponding value in the config file.
The global block and command-line options are only taken into account on the first load and not on subsequent loads, when switching between files. The regular expression blocks are always taken into account, even when loading further files. Please note the regular expressions are not case-sensitive.
A typical config file may look like this:
{
- "global": {
+ Configuration File | F3D Skip to main content Configuration File
Almost all the command-line options can be controlled using configuration files. Configuration files uses the “long” version of the command-line options in a JSON formatted file to provide values for these options. It is also possible to use the libf3d options syntax.
These options can be organized by block using a regular expression for each block in order to provide different default values for the different filetypes.
Using a command-line option will override similar option set in any config files.
Some options are only taken into account on the first load and not on subsequent loads, when switching between files.
A typical config file may look like this:
{
+ ".*": {
"bg-color": "0.7,0.7,0.7",
"color": "0.5,0.1,0.1",
"anti-aliasing": true,
@@ -9,7 +9,7 @@
"bar": true,
"roughness": 0.2,
"grid": true,
- "scalars": true
+ "scalar-coloring": true
},
".*vt.": {
"edges": true
@@ -23,4 +23,4 @@
"volume": true
}
}
-
Here, the first block defines a basic global configuration with many desired options for all files. The second block specifies that all files ending with vt., eg: vtk, vtp, vtu, … will be shown with edges visibility turned on. The third block specifies raytracing usage for .gltf and .glb files. The last block specifies that volume rendering should be used with .mhd files.
Single .json file for configuration is supported, as well a config directory containing multiple .json config files. In the case of config directory, .json file are read in alphabetical order and an option in a block can be overridden by the same option being set in the same block in another .json file read after.
F3D provides a default config directory for generic usage (config.d) and a thumbnail specific config directory (thumbnail.d). You can edit the file contained in these directory or copy then into specific locations (see below) in order to customize F3D behavior.
The following command-line options cannot be set via config file: help, version, readers-list, config, dry-run.
The following command-line options can only be set in the global block of the config file: no-render, inputs, output, verbose, resolution, position and all testing options.
Boolean options that have been turned on in the configuration file can be turned off on the command line if needed, eg: --point-sprites=false.
F3D looks for configuration files in different locations depending on your operating system. Existing configuration files are read in order and combined with later entries, potentially overriding previously read entry with the same names.
- Linux:
/etc/f3d/config(.json,.d), /usr/share/f3d/configs/config(.json,.d), [install_dir]/share/f3d/configs/config(.json,.d), ${XDG_CONFIG_HOME}/f3d/config(.json,.d) - Windows:
[install_dir]\share\f3d\configs\(config.json,.d), %APPDATA%\f3d\(config.json,.d) - macOS:
/usr/local/etc/f3d/config(.json,.d), f3d.app/Contents/Resources/configs/config(.json,.d), ${XDG_CONFIG_HOME}/f3d/config(.json,.d)
Please note XDG_CONFIG_HOME rely on environment variables as specified here.
The binary release will install the default config directory. On Linux, they will be installed in [install_dir]/share/f3d/configs/, on Windows, they will be installed in [install_dir]\share\f3d\configs\, on macOS, it will be installed in the bundle.
Please note there is a command line option to control the configuration file to read. Using it, one can specify an absolute/relative path for the configuration path, but also only the filename or filestem (.json and .d will be added) to look for in the locations listed above, , eg: f3d --config=custom_config will look for custom_config.json and custom_config.d in locations listed above.
Please note only one config file or directory will be found and parsed.
+
Here, the first block defines a basic configuration with many desired options for all files. The second block specifies that all files ending with vt., eg: vtk, vtp, vtu, … will be shown with edges visibility turned on. The third block specifies raytracing usage for .gltf and .glb files. The last block specifies that volume rendering should be used with .mhd files.
Single .json file for configuration is supported, as well a config directory containing multiple .json config files. In the case of config directory, .json file are read in alphabetical order and an option in a block can be overridden by the same option being set in another block in another .json file read after.
F3D provides a default config directory for generic usage (config.d) and a thumbnail specific config directory (thumbnail.d). You can edit the file contained in these directory or add your own in specific directories (see below).
The following command-line options cannot be set via config file: help, version, readers-list, config, dry-run and input.
The following command-line options are only taken on the first load: no-render, output, and all testing options.
Boolean options that have been turned on in the configuration file can be turned off on the command line if needed, eg: --point-sprites=false.
F3D looks for configuration files in different locations depending on your operating system. Existing configuration files are read in order and combined with later entries, potentially overriding previously read entry with the same names.
- Linux:
/etc/f3d/config(.json,.d), /usr/share/f3d/configs/config(.json,.d), [install_dir]/share/f3d/configs/config(.json,.d), ${XDG_CONFIG_HOME}/f3d/config(.json,.d) - Windows:
[install_dir]\share\f3d\configs\(config.json,.d), %APPDATA%\f3d\(config.json,.d) - macOS:
/usr/local/etc/f3d/config(.json,.d), f3d.app/Contents/Resources/configs/config(.json,.d), ${XDG_CONFIG_HOME}/f3d/config(.json,.d)
Please note XDG_CONFIG_HOME rely on environment variables as specified here.
The binary release will install the default config directory. On Linux, they will be installed in [install_dir]/share/f3d/configs/, on Windows, they will be installed in [install_dir]\share\f3d\configs\, on macOS, it will be installed in the bundle.
Please note there is a command line option to control the configuration file to read. Using it, one can specify an absolute/relative path for the configuration path, but also only the filename or filestem (.json and .d will be added) to look for in the locations listed above, , eg: f3d --config=custom_config will look for custom_config.json and custom_config.d in locations listed above. When specifying an absolute/relative path for the configuration file, a single file is read. If not, all files from locations listed above, with the overriding logic specified above.
diff --git a/doc/user/CONFIGURATION_FILE.md b/doc/user/CONFIGURATION_FILE.md
index bb64ca57c7..072efab115 100644
--- a/doc/user/CONFIGURATION_FILE.md
+++ b/doc/user/CONFIGURATION_FILE.md
@@ -1,25 +1,23 @@
# Configuration File
-Almost all the command-line options can be controlled using configuration files.
+Almost all the command-line [options](OPTIONS.md) can be controlled using configuration files.
Configuration files uses the "long" version of the command-line options in a JSON
-formatted file to provide values for these options.
+formatted file to provide values for these options. It is also possible to use
+the [libf3d options](../libf3d/OPTIONS.md) syntax.
These options can be organized by block using a regular expression for each block
in order to provide different default values for the different filetypes.
-A special block, named `global`, will apply to all files.
-Using a command-line option will override the corresponding value in the config file.
+Using a command-line option will override similar option set in any config files.
-The `global` block and command-line options are only taken into account on the first load
-and not on subsequent loads, when switching between files.
-The regular expression blocks are always taken into account, even when loading further files.
-Please note the regular expressions are not case-sensitive.
+Some options are only taken into account on the first load and not on subsequent loads,
+when switching between files.
A typical config file may look like this:
```javascript
{
- "global": {
+ ".*": {
"bg-color": "0.7,0.7,0.7",
"color": "0.5,0.1,0.1",
"anti-aliasing": true,
@@ -29,7 +27,7 @@ A typical config file may look like this:
"bar": true,
"roughness": 0.2,
"grid": true,
- "scalars": true
+ "scalar-coloring": true
},
".*vt.": {
"edges": true
@@ -44,23 +42,23 @@ A typical config file may look like this:
}
}
```
-Here, the first block defines a basic global configuration with many desired options for all files.
+Here, the first block defines a basic configuration with many desired options for all files.
The second block specifies that all files ending with vt., eg: vtk, vtp, vtu, ... will be shown with edges visibility turned on.
The third block specifies raytracing usage for .gltf and .glb files.
The last block specifies that volume rendering should be used with .mhd files.
Single .json file for configuration is supported, as well a config directory containing multiple .json config files.
In the case of config directory, .json file are read in alphabetical order and an option in a block can be overridden
-by the same option being set in the same block in another .json file read after.
+by the same option being set in another block in another .json file read after.
F3D provides a default config directory for generic usage (`config.d`) and a thumbnail specific config directory (`thumbnail.d`).
-You can edit the file contained in these directory or copy then into specific locations (see below) in order to customize F3D behavior.
+You can edit the file contained in these directory or add your own in specific directories (see below).
The following command-line options cannot be set via config file:
-`help`, `version`, `readers-list`, `config`, `dry-run`.
+`help`, `version`, `readers-list`, `config`, `dry-run` and `input`.
-The following command-line options can only be set in the global block of the config file:
-`no-render`, `inputs`, `output`, `verbose`, `resolution`, `position` and all testing options.
+The following command-line options are only taken on the first load:
+`no-render`, `output`, and all testing options.
Boolean options that have been turned on in the configuration file can be turned
off on the command line if needed, eg: `--point-sprites=false`.
@@ -80,5 +78,4 @@ On Linux, they will be installed in `[install_dir]/share/f3d/configs/`, on Windo
Please note there is a command line option to control the configuration file to read. Using it, one can specify an absolute/relative path for the configuration path, but also
only the filename or filestem (`.json` and `.d` will be added) to look for in the locations listed above, , eg: `f3d --config=custom_config` will look
for `custom_config.json` and `custom_config.d` in locations listed above.
-
-Please note only one config file or directory will be found and parsed.
+When specifying an absolute/relative path for the configuration file, a single file is read. If not, all files from locations listed above, with the overriding logic specified above.
diff --git a/doc/user/INTERACTIONS.html b/doc/user/INTERACTIONS.html
index 7120c1741b..e69216528c 100644
--- a/doc/user/INTERACTIONS.html
+++ b/doc/user/INTERACTIONS.html
@@ -1 +1 @@
- Interactions | F3D Skip to main content Interactions
Mouse Interactions
Simple interaction with the displayed data is possible directly within the window. It is as follows:
- Click and drag with the left mouse button to rotate around the focal point of the camera.
- Hold Shift then Click and drag horizontally with the right mouse button to rotate the HDRI.
- Click and drag vertically with the right mouse button to zoom in/out.
- Move the mouse wheel to zoom in/out.
- Hold Ctrl, then Click and drag vertically with the right mouse button to zoom in/out to mouse position.
- Hold Ctrl, then Move the mouse wheel to zoom in/out to mouse position.
- Click and drag with the middle mouse button to translate the camera.
- Click with the middle mouse button to center the camera on the point under the cursor (hold Shift to allow forward or backward movement).
- Drag and drop a file, directory or HDRI into the F3D window to load it. F3D relies on the extension (
.hdr or .exr) to detect if the dropped file is an HDRI.
Note: When playing an animation with a scene camera, camera interactions are locked.
Hotkeys
The coloring can be controlled directly by pressing the following hotkeys:
- C: cycle between coloring with array from point data and from cell data.
- S: cycle the array to color with.
- Y: cycle the component of the array to color with.
See the coloring cycle section for more info.
Other options can be toggled directly by pressing the following hotkeys:
- W: cycle animations.
- B: display of the scalar bar, only when coloring and not using direct scalars.
- V: volume rendering.
- I: opacity function inversion during volume rendering.
- O: point sprites rendering.
- P: translucency support.
- Q: ambient occlusion.
- A: anti-aliasing.
- T: tone mapping.
- E: the display of cell edges.
- X: the trihedral axes display.
- G: the horizontal grid display.
- N: the display of the file name.
- M: the display of the metadata if exists.
- Z: the display of the FPS counter.
- R: raytracing.
- D: the denoiser when raytracing.
- U: background blur, useful with an HDRI skybox.
- K: trackball interaction mode.
- F: HDRI ambient lighting.
- J: the display of the HDRI skybox.
- L: increase lights intensity.
- Shift+L: decrease lights intensity.
Note that some hotkeys can be available or not depending on the file being loaded and the F3D configuration.
Camera Hotkeys:
- 1: front view camera.
- 3: right view camera.
- 5: toggle orthographic projection.
- 7: top view camera.
- 9: isometric view camera.
- Enter: reset the camera to its initial parameters.
Other hotkeys are available:
- H: key to toggle the display of a cheat sheet showing all these hotkeys and their statuses.
- ?: key to print scene description to the terminal.
- Esc: close the window and quit F3D.
- Space: play the animation if any.
- ←: load the previous file if any and reset the camera.
- →: load the next file if any and reset the camera.
- ↑: reload the current file.
- ↓: add current file parent directory to the list of files, reload the current file and reset the camera.
- F12: take a screenshot, ie. render the current view to an image file.
- F11: take a “minimal” screenshot, ie. render the current view with no grid and no overlays to an image file with a transparent background.
When loading another file or reloading, options that have been changed interactively are kept but can be overridden if a dedicated regular expression block in the configuration file is present, see the configuration file documentation for more info.
Cycling Coloring
When using the default scene, the following hotkeys let you cycle the coloring of the data:
- C: cycle between point data and cell data - field data is not supported.
- S: cycle the array available on the currently selected data in alphabetical order, skipping array not containing numeric data. It will loop back to not coloring unless using volume rendering.
- Y: cycle the component available on the currently selected array, looping to -2 for direct scalars rendering.
When changing the array, the component in use will be kept if valid with the new array, if not it will be cycled until a valid component is found. When changing the type of data to color with, the index of the array within the data will be kept if valid with the new data. If not, it will cycle until a valid array is found. After that, the component will be checked as specified above.
Taking Screenshots
The destination filename used to save the screenshots (created by pressing F12 or F11) is configurable (using the screenshot-filename option) and can use template variables as described on the options page.
Unless the configured filename template is an absolute path, images will be saved into the user’s home directory (using the following environment variables, if defined and pointing to an existing directory, in that order: XDG_PICTURES_DIR, HOME, or USERPROFILE).
+ Interactions | F3D Skip to main content Interactions
Mouse Interactions
Simple interaction with the displayed data is possible directly within the window. It is as follows:
- Click and drag with the left mouse button to rotate around the focal point of the camera.
- Hold Shift then Click and drag horizontally with the right mouse button to rotate the HDRI.
- Click and drag vertically with the right mouse button to zoom in/out.
- Move the mouse wheel to zoom in/out.
- Hold Ctrl, then Click and drag vertically with the right mouse button to zoom in/out to mouse position.
- Hold Ctrl, then Move the mouse wheel to zoom in/out to mouse position.
- Click and drag with the middle mouse button to translate the camera.
- Click with the middle mouse button to center the camera on the point under the cursor (hold Shift to allow forward or backward movement).
- Drag and drop a file, directory or HDRI into the F3D window to load it. F3D relies on the extension (
.hdr or .exr) to detect if the dropped file is an HDRI.
Note: When playing an animation with a scene camera, camera interactions are locked.
Hotkeys
The coloring can be controlled directly by pressing the following hotkeys:
- C: cycle between coloring with array from point data and from cell data.
- S: cycle the array to color with.
- Y: cycle the component of the array to color with.
See the coloring cycle section for more info.
Other options can be toggled directly by pressing the following hotkeys:
- W: cycle animations.
- B: display of the scalar bar, only when coloring and not using direct scalars.
- V: volume rendering.
- I: opacity function inversion during volume rendering.
- O: point sprites rendering.
- P: translucency support.
- Q: ambient occlusion.
- A: anti-aliasing.
- T: tone mapping.
- E: the display of cell edges.
- X: the trihedral axes display.
- G: the horizontal grid display.
- N: the display of the file name.
- M: the display of the metadata if exists.
- Z: the display of the FPS counter.
- R: raytracing.
- D: the denoiser when raytracing.
- U: background blur, useful with an HDRI skybox.
- K: trackball interaction mode.
- F: HDRI ambient lighting.
- J: the display of the HDRI skybox.
- L: increase lights intensity.
- Shift+L: decrease lights intensity.
Note that some hotkeys can be available or not depending on the file being loaded and the F3D configuration.
Camera Hotkeys:
- 1: front view camera.
- 3: right view camera.
- 5: toggle orthographic projection.
- 7: top view camera.
- 9: isometric view camera.
- Enter: reset the camera to its initial parameters.
Other hotkeys are available:
- H: key to toggle the display of a cheat sheet showing all these hotkeys and their statuses.
- ?: key to print scene description to the terminal.
- Esc: close the window and quit F3D.
- Space: play the animation if any.
- ←: load the previous file if any and reset the camera.
- →: load the next file if any and reset the camera.
- ↑: reload the current file.
- ↓: add current file parent directory to the list of files, reload the current file and reset the camera.
- F12: take a screenshot, ie. render the current view to an image file.
- F11: take a “minimal” screenshot, ie. render the current view with no grid and no overlays to an image file with a transparent background.
When loading another file or reloading, options that have been changed interactively are kept as is.
Cycling Coloring
When using the default scene, the following hotkeys let you cycle the coloring of the data:
- C: cycle between point data and cell data - field data is not supported.
- S: cycle the array available on the currently selected data in alphabetical order, skipping array not containing numeric data. It will loop back to not coloring unless using volume rendering.
- Y: cycle the component available on the currently selected array, looping to -2 for direct scalars rendering.
When changing the array, the component in use will be kept if valid with the new array, if not it will be cycled until a valid component is found. When changing the type of data to color with, the index of the array within the data will be kept if valid with the new data. If not, it will cycle until a valid array is found. After that, the component will be checked as specified above.
Taking Screenshots
The destination filename used to save the screenshots (created by pressing F12 or F11) is configurable (using the screenshot-filename option) and can use template variables as described on the options page.
Unless the configured filename template is an absolute path, images will be saved into the user’s home directory (using the following environment variables, if defined and pointing to an existing directory, in that order: XDG_PICTURES_DIR, HOME, or USERPROFILE).
diff --git a/doc/user/INTERACTIONS.md b/doc/user/INTERACTIONS.md
index 53778edbe0..4634b623b7 100644
--- a/doc/user/INTERACTIONS.md
+++ b/doc/user/INTERACTIONS.md
@@ -75,9 +75,7 @@ Other hotkeys are available:
* F12: take a screenshot, ie. render the current view to an image file.
* F11: take a "minimal" screenshot, ie. render the current view with no grid and no overlays to an image file with a transparent background.
-When loading another file or reloading, options that have been changed interactively are kept but can be overridden
-if a dedicated regular expression block in the configuration file is present, see the [configuration file](CONFIGURATION_FILE.md)
-documentation for more info.
+When loading another file or reloading, options that have been changed interactively are kept as is.
## Cycling Coloring
diff --git a/doc/user/OPTIONS.html b/doc/user/OPTIONS.html
index d0247940f6..6507d5d5ca 100644
--- a/doc/user/OPTIONS.html
+++ b/doc/user/OPTIONS.html
@@ -1 +1 @@
- Options | F3D Skip to main content Command line options
F3D behavior can be fully controlled from the command line using the following options.
Application Options
Options Default Description --output=<png file> Instead of showing a render view and render into it, render directly into a png file. When used with --ref option, only outputs on failure. If - is specified instead of a filename, the PNG file is streamed to the stdout. Can use template variables. --no-background Use with --output to output a png file with a transparent background. -h, --help Print help and exit. Ignore --verbose. --version Show version information and exit. Ignore --verbose. --readers-list List available readers and exit. Ignore --verbose. --config=<config file path/name/stem> config Specify the configuration file to use. Supports absolute/relative path but also filename/filestem to search for in standard configuration file locations. --dry-run Do not read any configuration file and consider only the command line options. --no-render Do not render anything and quit just after loading the first file, use with --verbose to recover information about a file. --max-size=<size in MiB> -1 Prevent F3D to load a file bigger than the provided size in Mib, negative value means unlimited, useful for thumbnails. --watch Watch current file and automatically reload it whenever it is modified on disk. --load-plugins=<paths or names> List of plugins to load separated with a comma. Official plugins are alembic, assimp, draco, exodus, occt, usd, vdb. See usage for more info. --scan-plugins Scan standard directories for plugins and display their names, results may be incomplete. See usage for more info. --screenshot-filename=<png file> {app}/{model}_{n}.pngFilename to save screenshots to. Can use template variables.
General Options
Options Default Description --verbose=<[debug|info|warning|error|quiet]> info Set verbose level, in order to provide more information about the loaded data in the console output. If no level is provided, assume debug. Option parsing may ignore this flag. --progress Show a progress bar when loading the file. --animation-progress Show a progress bar when playing the animation. --geometry-only For certain full scene file formats (gltf/glb and obj),
reads only the geometry from the file and use default scene construction instead. --group-geometries When opening multiple files, show them all in the same scene.
Force geometry-only. The configuration file for the first file will be loaded. --up=<[+|-][X|Y|Z]> +Y Define the Up direction. -x, --axis Show axes as a trihedron in the scene. -g, --grid Show a grid aligned with the horizontal (orthogonal to the Up direction) plane. --grid-unit=<length> Set the size of the unit square for the grid. If set to non-positive (the default) a suitable value will be automatically computed. --grid-subdivisions=<count> Set the number of subdivisions for the grid. --grid-color=<color> (0,0,0) Set the color grid lines. -e, --edges Show the cell edges. --camera-index=<idx> -1 Select the scene camera to use when available in the file.
Any negative value means automatic camera.
The default scene always uses automatic camera. -k, --trackball Enable trackball interaction. --animation-autoplay Automatically start animation. --animation-index=<idx> 0 Select the animation to show.
Any negative value means all animations (glTF only).
The default scene always has at most one animation. --animation-speed-factor=<factor> 1 Set the animation speed factor to slow, speed up or even invert animation time. --animation-frame-rate=<factor> 60 Set the animation frame rate used when playing animation interactively. --font-file=<font file> Use the provided FreeType compatible font file to display text.
Can be useful to display non-ASCII filenames.
Material options
Options Default Description -o, --point-sprites Show sphere points sprites instead of the geometry. --point-size=<size> 10.0 Set the size of points when showing vertices and point sprites. --point-type=<sphere gaussian> sphere Set the splat type when showing point sprites. --line-width=<size> 1.0 Set the width of lines when showing edges. --color=<R,G,B> 1.0, 1.0, 1.0 Set a color on the geometry. Multiplied with the base color texture when present.
Requires a default scene. --opacity=<opacity> 1.0 Set opacity on the geometry. Multiplied with the base color texture when present.
Requires a default scene. Usually used with Depth Peeling option. --roughness=<roughness> 0.3 Set the roughness coefficient on the geometry (0.0-1.0). Multiplied with the material texture when present.
Requires a default scene. --metallic=<metallic> 0.0 Set the metallic coefficient on the geometry (0.0-1.0). Multiplied with the material texture when present.
Requires a default scene. --hdri-file=<HDRI file> Set the HDRI image that can be used as ambient lighting and skybox.
Valid file format are hdr, exr, png, jpg, pnm, tiff, bmp.
If not set, a default is provided. --hdri-ambient Light the scene using the HDRI image as ambient lighting.
The environment act as a light source and is reflected on the material. --texture-matcap=<texture file> Set the texture file to control the material capture of the object. All other model options for surfaces are ignored if this is set. Must be in linear color space. --texture-base-color=<texture file> Set the texture file to control the color of the object. Please note this will be multiplied with the color and opacity options. Must be in sRGB color space. --texture-material=<texture file> Set the texture file to control the occlusion, roughness and metallic values of the object. Please note this will be multiplied with the roughness and metallic options, which have impactful default values. To obtain true results, use --roughness=1 --metallic=1. Must be in linear color space. --texture-emissive=<texture file> Set the texture file to control the emitted light of the object. Please note this will be multiplied with the emissive factor. Must be in sRGB color space. --emissive-factor=<R,G,B> 1.0, 1.0, 1.0 Set the emissive factor. This value is multiplied with the emissive color when an emissive texture is present.
Window options
Options Default Description --bg-color=<R,G,B> 0.2, 0.2, 0.2 Set the window background color.
Ignored if hdri is set. --resolution=<width,height> 1000, 600 Set the window resolution. --position=<x,y> Set the window position (top left corner) , in pixels, starting from the top left of your screens. -z, --fps Display a frame per second counter. -n, --filename Display the name of the file on top of the window. -m, --metadata Display the metadata.
Empty without a default scene. --hdri-skybox Show the HDRI as a skybox. Overrides --bg-color and --no-background. -u, --blur-background Blur background.
Useful with a HDRI skybox. --blur-coc 20 Blur circle of confusion radius. --light-intensity 1.0 Adjust the intensity of every light in the scene.
Scientific visualization options
Options Default Description -s, --scalars=<array_name> Specify an array to Color with if present in the file. If no array_name is provided, the first in alphabetical order will be picked if any are available.
Requires a default scene.
Use --verbose to recover the usable array names. -y, --comp=<comp_index> -1 Specify the component from the scalar array to color with.
Use with the scalar option. -1 means magnitude. -2 or the short option, -y, means direct values.
When using direct values, components are used as L, LA, RGB, RGBA values depending on the number of components. -c, --cells Specify that the scalar array is to be found on the cells instead of on the points.
Use with the scalar option. --range=<min,max> Set a custom range for the coloring by the array.
Use with the scalar option. -b, --bar Show scalar bar of the coloring by array.
Use with the scalar option. --colormap-file=<name> Set a colormap file for the coloring.
See color maps.
Use with the scalar option. --colormap=<color_list> Set a custom colormap for the coloring.
This is a list of colors in the format val1,red1,green1,blue1,...,valN,redN,greenN,blueN
where all values are in the range (0,1).
Ignored if --colormap-file option is specified.
Use with the scalar option. -v, --volume Enable volume rendering. It is only available for 3D image data (vti, dcm, nrrd, mhd files) and will display nothing with other formats. -i, --inverse Inverse the linear opacity function used for volume rendering.
Camera configuration options
Options Default Description --camera-position=<X,Y,Z> Set the camera position, overrides –camera-direction and camera-zoom-factor. --camera-focal-point=<X,Y,Z> Set the camera focal point. --camera-view-up=<X,Y,Z> Set the camera view up vector. Will be orthogonalized. --camera-view-angle=<angle> Set the camera view angle, a strictly positive value in degrees. --camera-direction=<X,Y,Z> Set the camera direction, looking at the focal point. --camera-zoom-factor=<factor> Set the camera zoom factor relative to the autozoom on data, a strictly positive value. --camera-azimuth-angle=<angle> 0.0 Apply an azimuth transformation to the camera, in degrees, added after other camera options. --camera-elevation-angle=<angle> 0.0 Apply an elevation transformation to the camera, in degrees, added after other camera options. --camera-orthographic Set the camera to use the orthographic projection.
Raytracing options
Options Default Description -r, --raytracing Enable OSPRay raytracing. Requires OSPRay raytracing to be enabled in the linked VTK dependency. --samples=<samples> 5 Set the number of samples per pixel when using raytracing. -d, --denoise Denoise the image when using raytracing.
PostFX (OpenGL) options
Options Description -p, --translucency-support Enable translucency support. This is a technique used to correctly render translucent objects. -q, --ambient-occlusion Enable ambient occlusion. This is a technique used to improve the depth perception of the object. -a, --anti-aliasing Enable anti-aliasing. This technique is used to reduce aliasing. -t, --tone-mapping Enable generic filmic Tone Mapping Pass. This technique is used to map colors properly to the monitor colors. --final-shader Add a final shader to the output image. See dedicated documentation for more details.
Testing options
Options Default Description --ref=<png file> Render and compare with the provided reference image, for testing purposes. Use with output option to generate new baselines and diff images. --ref-threshold=<threshold> 0.05 Set the comparison threshold to trigger a test failure or success. The default (0.05) correspond to almost visually identical images. --interaction-test-record=<log file> Path to an interaction log file to record interaction events to. --interaction-test-play=<log file> Path to an interaction log file to play interactions events from when loading a file.
Rendering options precedence
Some rendering options are not compatible between them, here is the precedence order if several are provided:
- Raytracing (
-r) - Volume (
-v) - Point Sprites (
-o)
Options syntax
The --options=value syntax is used everywhere in this documentation, however, the syntax --options value can also be used, with the exception of options that have implicit values, --verbose, --comp and --scalars.
Filename templating
The destination filename used by --output or to save screenshots can use the following template variables:
{app}: application name (ie. F3D){version}: application version (eg. 2.4.0){version_full}: full application version (eg. 2.4.0-abcdefgh){model}: current model filename without extension (eg. foo for /home/user/foo.glb){model.ext}: current model filename with extension (eg. foo.glb for /home/user/foo.glb){model_ext}: current model filename extension (eg. glb for /home/user/foo.glb){date}: current date in YYYYMMDD format{date:format}: current date as per C++’s std::put_time format{n}: auto-incremented number to make filename unique (up to 1000000){n:2}, {n:3}, …: zero-padded auto-incremented number to make filename unique (up to 1000000)- variable names can be escaped by doubling the braces (eg. use
{{model}}.png to output {model}.png without the model name being substituted)
For example the screenshot filename is configured as {app}/{model}_{n}.png by default, meaning that, assuming the model hello.glb is being viewed, consecutive screenshots are going to be saved as F3D/hello_1.png, F3D/hello_2.png, F3D/hello_3.png, …
+ Options | F3D Skip to main content Command line options
F3D behavior can be fully controlled from the command line using the following options.
Application Options
Options Default Description --input=<input file> The input file or files to read, can also be provided as a positional argument. --output=<png file> Instead of showing a render view and render into it, render directly into a png file. When used with --ref option, only outputs on failure. If - is specified instead of a filename, the PNG file is streamed to the stdout. Can use template variables. --no-background Use with --output to output a png file with a transparent background. -h, --help Print help and exit. Ignore --verbose. --version Show version information and exit. Ignore --verbose. --readers-list List available readers and exit. Ignore --verbose. --config=<config file path/name/stem> config Specify the configuration file to use. Supports absolute/relative path but also filename/filestem to search for in standard configuration file locations. --dry-run Do not read any configuration file and consider only the command line options. --no-render Do not render anything and quit just after loading the first file, use with --verbose to recover information about a file. --max-size=<size in MiB> -1 Prevent F3D to load a file bigger than the provided size in Mib, negative value means unlimited, useful for thumbnails. --watch Watch current file and automatically reload it whenever it is modified on disk. --load-plugins=<paths or names> List of plugins to load separated with a comma. Official plugins are alembic, assimp, draco, exodus, occt, usd, vdb. See usage for more info. --scan-plugins Scan standard directories for plugins and display their names, results may be incomplete. See usage for more info. --screenshot-filename=<png file> {app}/{model}_{n}.pngFilename to save screenshots to. Can use template variables.
General Options
Options Default Description --verbose=<[debug|info|warning|error|quiet]> info Set verbose level, in order to provide more information about the loaded data in the console output. If no level is provided, assume debug. Option parsing may ignore this flag. --progress Show a progress bar when loading the file. --animation-progress Show a progress bar when playing the animation. --geometry-only For certain full scene file formats (gltf/glb and obj),
reads only the geometry from the file and use default scene construction instead. --group-geometries When opening multiple files, show them all in the same scene.
Force geometry-only. The configuration file for the first file will be loaded. --up=<[+|-][X|Y|Z]> +Y Define the Up direction. -x, --axis Show axes as a trihedron in the scene. -g, --grid Show a grid aligned with the horizontal (orthogonal to the Up direction) plane. --grid-unit=<length> Set the size of the unit square for the grid. If set to non-positive (the default) a suitable value will be automatically computed. --grid-subdivisions=<count> Set the number of subdivisions for the grid. --grid-color=<color> (0,0,0) Set the color grid lines. -e, --edges Show the cell edges. --camera-index=<idx> -1 Select the scene camera to use when available in the file.
Any negative value means automatic camera.
The default scene always uses automatic camera. -k, --trackball Enable trackball interaction. --animation-autoplay Automatically start animation. --animation-index=<idx> 0 Select the animation to show.
Any negative value means all animations (glTF only).
The default scene always has at most one animation. --animation-speed-factor=<factor> 1 Set the animation speed factor to slow, speed up or even invert animation time. --animation-frame-rate=<factor> 60 Set the animation frame rate used when playing animation interactively. --font-file=<font file> Use the provided FreeType compatible font file to display text.
Can be useful to display non-ASCII filenames.
Material options
Options Default Description -o, --point-sprites Show sphere points sprites instead of the geometry. --point-size=<size> 10.0 Set the size of points when showing vertices and point sprites. --point-type=<sphere gaussian> sphere Set the splat type when showing point sprites. --line-width=<size> 1.0 Set the width of lines when showing edges. --color=<R,G,B> 1.0, 1.0, 1.0 Set a color on the geometry. Multiplied with the base color texture when present.
Requires a default scene. --opacity=<opacity> 1.0 Set opacity on the geometry. Multiplied with the base color texture when present.
Requires a default scene. Usually used with Depth Peeling option. --roughness=<roughness> 0.3 Set the roughness coefficient on the geometry (0.0-1.0). Multiplied with the material texture when present.
Requires a default scene. --metallic=<metallic> 0.0 Set the metallic coefficient on the geometry (0.0-1.0). Multiplied with the material texture when present.
Requires a default scene. --hdri-file=<HDRI file> Set the HDRI image that can be used as ambient lighting and skybox.
Valid file format are hdr, exr, png, jpg, pnm, tiff, bmp.
If not set, a default is provided. --hdri-ambient Light the scene using the HDRI image as ambient lighting.
The environment act as a light source and is reflected on the material. --texture-matcap=<texture file> Set the texture file to control the material capture of the object. All other model options for surfaces are ignored if this is set. Must be in linear color space. --texture-base-color=<texture file> Set the texture file to control the color of the object. Please note this will be multiplied with the color and opacity options. Must be in sRGB color space. --texture-material=<texture file> Set the texture file to control the occlusion, roughness and metallic values of the object. Please note this will be multiplied with the roughness and metallic options, which have impactful default values. To obtain true results, use --roughness=1 --metallic=1. Must be in linear color space. --texture-emissive=<texture file> Set the texture file to control the emitted light of the object. Please note this will be multiplied with the emissive factor. Must be in sRGB color space. --emissive-factor=<R,G,B> 1.0, 1.0, 1.0 Set the emissive factor. This value is multiplied with the emissive color when an emissive texture is present.
Window options
Options Default Description --bg-color=<R,G,B> 0.2, 0.2, 0.2 Set the window background color.
Ignored if hdri is set. --resolution=<width,height> 1000, 600 Set the window resolution. --position=<x,y> Set the window position (top left corner) , in pixels, starting from the top left of your screens. -z, --fps Display a frame per second counter. -n, --filename Display the name of the file on top of the window. -m, --metadata Display the metadata.
Empty without a default scene. --hdri-skybox Show the HDRI as a skybox. Overrides --bg-color and --no-background. -u, --blur-background Blur background.
Useful with a HDRI skybox. --blur-coc 20 Blur circle of confusion radius. --light-intensity 1.0 Adjust the intensity of every light in the scene.
Scientific visualization options
Options Default Description -s, --scalar-coloring Enable scalar coloring if present in the file. If no --coloring-array is provided, the first in alphabetical order will be picked if any are available.
Requires a default scene. --coloring-array=<array_name> The coloring array name to use when coloring.
Use --verbose to recover the usable array names. -y, --comp=<comp_index> -1 Specify the component from the scalar array to color with.
Use with the scalar option. -1 means magnitude. -2 or the short option, -y, means direct values.
When using direct values, components are used as L, LA, RGB, RGBA values depending on the number of components. -c, --cells Specify that the scalar array is to be found on the cells instead of on the points.
Use with the scalar option. --range=<min,max> Set a custom range for the coloring by the array.
Use with the scalar option. -b, --bar Show scalar bar of the coloring by array.
Use with the scalar option. --colormap-file=<name> Set a colormap file for the coloring.
See color maps.
Use with the scalar option. --colormap=<color_list> Set a custom colormap for the coloring.
This is a list of colors in the format val1,red1,green1,blue1,...,valN,redN,greenN,blueN
where all values are in the range (0,1).
Ignored if --colormap-file option is specified.
Use with the scalar option. -v, --volume Enable volume rendering. It is only available for 3D image data (vti, dcm, nrrd, mhd files) and will display nothing with other formats. -i, --inverse Inverse the linear opacity function used for volume rendering.
Camera configuration options
Options Default Description --camera-position=<X,Y,Z> Set the camera position, overrides –camera-direction and camera-zoom-factor. --camera-focal-point=<X,Y,Z> Set the camera focal point. --camera-view-up=<X,Y,Z> Set the camera view up vector. Will be orthogonalized. --camera-view-angle=<angle> Set the camera view angle, a strictly positive value in degrees. --camera-direction=<X,Y,Z> Set the camera direction, looking at the focal point. --camera-zoom-factor=<factor> Set the camera zoom factor relative to the autozoom on data, a strictly positive value. --camera-azimuth-angle=<angle> 0.0 Apply an azimuth transformation to the camera, in degrees, added after other camera options. --camera-elevation-angle=<angle> 0.0 Apply an elevation transformation to the camera, in degrees, added after other camera options. --camera-orthographic Set the camera to use the orthographic projection.
Raytracing options
Options Default Description -r, --raytracing Enable OSPRay raytracing. Requires OSPRay raytracing to be enabled in the linked VTK dependency. --samples=<samples> 5 Set the number of samples per pixel when using raytracing. -d, --denoise Denoise the image when using raytracing.
PostFX (OpenGL) options
Options Description -p, --translucency-support Enable translucency support. This is a technique used to correctly render translucent objects. -q, --ambient-occlusion Enable ambient occlusion. This is a technique used to improve the depth perception of the object. -a, --anti-aliasing Enable anti-aliasing. This technique is used to reduce aliasing. -t, --tone-mapping Enable generic filmic Tone Mapping Pass. This technique is used to map colors properly to the monitor colors. --final-shader Add a final shader to the output image. See dedicated documentation for more details.
Testing options
Options Default Description --ref=<png file> Render and compare with the provided reference image, for testing purposes. Use with output option to generate new baselines and diff images. --ref-threshold=<threshold> 0.05 Set the comparison threshold to trigger a test failure or success. The default (0.05) correspond to almost visually identical images. --interaction-test-record=<log file> Path to an interaction log file to record interaction events to. --interaction-test-play=<log file> Path to an interaction log file to play interactions events from when loading a file.
Rendering options precedence
Some rendering options are not compatible between them, here is the precedence order if several are provided:
- Raytracing (
-r) - Volume (
-v) - Point Sprites (
-o)
Options syntax
As documented, only the --options=value syntax is supported. The syntax --options value is not supported.
Filename templating
The destination filename used by --output or to save screenshots can use the following template variables:
{app}: application name (ie. F3D){version}: application version (eg. 2.4.0){version_full}: full application version (eg. 2.4.0-abcdefgh){model}: current model filename without extension (eg. foo for /home/user/foo.glb){model.ext}: current model filename with extension (eg. foo.glb for /home/user/foo.glb){model_ext}: current model filename extension (eg. glb for /home/user/foo.glb){date}: current date in YYYYMMDD format{date:format}: current date as per C++’s std::put_time format{n}: auto-incremented number to make filename unique (up to 1000000){n:2}, {n:3}, …: zero-padded auto-incremented number to make filename unique (up to 1000000)- variable names can be escaped by doubling the braces (eg. use
{{model}}.png to output {model}.png without the model name being substituted)
For example the screenshot filename is configured as {app}/{model}_{n}.png by default, meaning that, assuming the model hello.glb is being viewed, consecutive screenshots are going to be saved as F3D/hello_1.png, F3D/hello_2.png, F3D/hello_3.png, …
diff --git a/doc/user/OPTIONS.md b/doc/user/OPTIONS.md
index 1e82b44632..e43f39dd30 100644
--- a/doc/user/OPTIONS.md
+++ b/doc/user/OPTIONS.md
@@ -8,6 +8,7 @@ F3D behavior can be fully controlled from the command line using the following o
Options|Default|Description
------|------|------
+\-\-input=\||The input file or files to read, can also be provided as a positional argument.
\-\-output=\||Instead of showing a render view and render into it, *render directly into a png file*. When used with \-\-ref option, only outputs on failure. If `-` is specified instead of a filename, the PNG file is streamed to the stdout. Can use [template variables](#filename-templating).
\-\-no-background||Use with \-\-output to output a png file with a transparent background.
-h, \-\-help||Print *help* and exit. Ignore `--verbose`.
@@ -85,7 +86,8 @@ Options|Default|Description
Options|Default|Description
------|------|------
--s, \-\-scalars=\||Specify an array to *Color* with if present in the file. If no array_name is provided, the first in alphabetical order will be picked if any are available.
Requires a default scene.
Use \-\-verbose to recover the usable array names.
+-s, \-\-scalar-coloring||Enable scalar coloring if present in the file. If no `--coloring-array` is provided, the first in alphabetical order will be picked if any are available.
Requires a default scene.
+\-\-coloring-array=\||The coloring array name to use when coloring.
Use \-\-verbose to recover the usable array names.
-y, \-\-comp=\|-1|Specify the *component from the scalar* array to color with.
Use with the scalar option. -1 means *magnitude*. -2 or the short option, -y, means *direct values*.
When using *direct values*, components are used as L, LA, RGB, RGBA values depending on the number of components.
-c, \-\-cells||Specify that the scalar array is to be found *on the cells* instead of on the points.
Use with the scalar option.
\-\-range=\||Set a *custom range for the coloring* by the array.
Use with the scalar option.
@@ -146,8 +148,7 @@ Some rendering options are not compatible between them, here is the precedence o
## Options syntax
-The `--options=value` syntax is used everywhere in this documentation, however, the syntax `--options value` can also be used, with the exception of options that have implicit values,
-`--verbose`, `--comp` and `--scalars`.
+As documented, only the `--options=value` syntax is supported. The syntax `--options value` is not supported.
## Filename templating
@@ -167,4 +168,3 @@ The destination filename used by `--output` or to save screenshots can use the f
For example the screenshot filename is configured as `{app}/{model}_{n}.png` by default, meaning that, assuming the model `hello.glb` is being viewed,
consecutive screenshots are going to be saved as `F3D/hello_1.png`, `F3D/hello_2.png`, `F3D/hello_3.png`, ...
-
diff --git a/resources/configs/config.d/10_global.json b/resources/configs/config.d/05_all.json
similarity index 88%
rename from resources/configs/config.d/10_global.json
rename to resources/configs/config.d/05_all.json
index b579820c98..5a3c4bbc75 100644
--- a/resources/configs/config.d/10_global.json
+++ b/resources/configs/config.d/05_all.json
@@ -1,5 +1,5 @@
{
- "global":
+ ".*":
{
"axis": true,
"tone-mapping": true,
@@ -7,7 +7,7 @@
"progress": true,
"anti-aliasing": true,
"filename": true,
- "scalars": "",
+ "scalar-coloring": true,
"camera-direction": "-1,-0.5,-1",
"hdri-ambient": true,
"translucency-support": true,
diff --git a/resources/configs/thumbnail.d/10_global.json b/resources/configs/thumbnail.d/05_all.json
similarity index 86%
rename from resources/configs/thumbnail.d/10_global.json
rename to resources/configs/thumbnail.d/05_all.json
index 3a8353461c..7c337897e7 100644
--- a/resources/configs/thumbnail.d/10_global.json
+++ b/resources/configs/thumbnail.d/05_all.json
@@ -1,5 +1,5 @@
{
- "global":
+ ".*":
{
"anti-aliasing": true,
"camera-direction": "-1,-0.5,-1",
@@ -7,7 +7,7 @@
"max-size":100,
"no-background": true,
"verbose": "quiet",
- "scalars": "",
+ "scalar-coloring": true,
"tone-mapping": true,
"translucency-support": true
}
diff --git a/vtkext/private/module/Testing/TestF3DRendererWithColoring.cxx b/vtkext/private/module/Testing/TestF3DRendererWithColoring.cxx
index 7fc999dac5..fcb9fc6a5e 100644
--- a/vtkext/private/module/Testing/TestF3DRendererWithColoring.cxx
+++ b/vtkext/private/module/Testing/TestF3DRendererWithColoring.cxx
@@ -14,7 +14,7 @@ int TestF3DRendererWithColoring(int argc, char* argv[])
renderer->ShowGrid(true);
// Check error paths
- if (renderer->GetColoringArrayName() != F3D_RESERVED_STRING)
+ if (!renderer->GetColoringArrayName().empty())
{
std::cerr << "Unexpected coloring information without an importer" << std::endl;
return EXIT_FAILURE;
@@ -37,7 +37,7 @@ int TestF3DRendererWithColoring(int argc, char* argv[])
importer->Update();
// Check invalid array code path
- renderer->SetColoring(false, "Invalid", 0);
+ renderer->SetColoring(true, false, "Invalid", 0);
renderer->SetUseVolume(false);
renderer->UpdateActors();
renderer->CycleScalars(vtkF3DRendererWithColoring::CycleType::COMPONENT);
@@ -51,7 +51,7 @@ int TestF3DRendererWithColoring(int argc, char* argv[])
}
// Check invalid component code path
- renderer->SetColoring(false, "Momentum", 5);
+ renderer->SetColoring(true, false, "Momentum", 5);
renderer->UpdateActors();
renderer->SetUseVolume(true);
renderer->UpdateActors();
diff --git a/vtkext/private/module/vtkF3DConfigure.h.in b/vtkext/private/module/vtkF3DConfigure.h.in
index cb221b6557..441a94c64f 100644
--- a/vtkext/private/module/vtkF3DConfigure.h.in
+++ b/vtkext/private/module/vtkF3DConfigure.h.in
@@ -3,7 +3,6 @@
#include
-static const std::string F3D_RESERVED_STRING = "f3d_reserved";
static const std::string F3D_EXIT_HOTKEY_SYM = "Escape";
// TODO: Use CMake definitions and get rid of these
diff --git a/vtkext/private/module/vtkF3DRendererWithColoring.cxx b/vtkext/private/module/vtkF3DRendererWithColoring.cxx
index aeb8ffe807..fd40d8ee98 100644
--- a/vtkext/private/module/vtkF3DRendererWithColoring.cxx
+++ b/vtkext/private/module/vtkF3DRendererWithColoring.cxx
@@ -473,7 +473,7 @@ vtkF3DRendererWithColoring::CycleType vtkF3DRendererWithColoring::CheckColoring(
assert(this->Importer);
// Never force change of anything if we are currently not coloring
- if (this->ArrayIndexForColoring == -1)
+ if (this->ArrayIndexForColoring < 0)
{
return CycleType::NONE;
}
@@ -501,7 +501,7 @@ vtkF3DRendererWithColoring::CycleType vtkF3DRendererWithColoring::CheckColoring(
}
//----------------------------------------------------------------------------
-void vtkF3DRendererWithColoring::SetColoring(
+void vtkF3DRendererWithColoring::SetColoring(bool enable,
bool useCellData, const std::string& arrayName, int component)
{
if (!this->Importer)
@@ -511,13 +511,16 @@ void vtkF3DRendererWithColoring::SetColoring(
// XXX This should be reworked to avoid handling multiple information in one parameters
// while still being future-proof and flexible enough.
- if (this->GetColoringUseCell() != useCellData || this->GetColoringArrayName() != arrayName ||
- this->GetColoringComponent() != component)
+ if (enable != (this->ArrayIndexForColoring >= 0)
+ || useCellData != this->UseCellColoring
+ || component != this->ComponentForColoring
+ || arrayName != this->GetColoringArrayName())
{
this->UseCellColoring = useCellData;
+ this->ComponentForColoring = component;
int nIndexes = this->Importer->GetNumberOfIndexesForColoring(this->UseCellColoring);
- if (arrayName == F3D_RESERVED_STRING)
+ if (!enable)
{
// Not coloring
this->ArrayIndexForColoring = -1;
@@ -544,8 +547,6 @@ void vtkF3DRendererWithColoring::SetColoring(
}
}
- this->ComponentForColoring = component;
-
this->ColorTransferFunctionConfigured = false;
this->GeometryMappersConfigured = false;
this->PointSpritesMappersConfigured = false;
@@ -555,6 +556,12 @@ void vtkF3DRendererWithColoring::SetColoring(
}
}
+//----------------------------------------------------------------------------
+bool vtkF3DRendererWithColoring::GetColoringEnabled()
+{
+ return this->ArrayIndexForColoring >= 0;
+}
+
//----------------------------------------------------------------------------
bool vtkF3DRendererWithColoring::GetColoringUseCell()
{
@@ -566,7 +573,7 @@ std::string vtkF3DRendererWithColoring::GetColoringArrayName()
{
if (!this->Importer)
{
- return F3D_RESERVED_STRING;
+ return "";
}
vtkF3DGenericImporter::ColoringInfo info;
@@ -576,7 +583,7 @@ std::string vtkF3DRendererWithColoring::GetColoringArrayName()
}
else
{
- return F3D_RESERVED_STRING;
+ return "";
}
}
diff --git a/vtkext/private/module/vtkF3DRendererWithColoring.h b/vtkext/private/module/vtkF3DRendererWithColoring.h
index 9bbdbd2412..ff4459f9e9 100644
--- a/vtkext/private/module/vtkF3DRendererWithColoring.h
+++ b/vtkext/private/module/vtkF3DRendererWithColoring.h
@@ -157,17 +157,18 @@ class vtkF3DRendererWithColoring : public vtkF3DRenderer
void SetImporter(vtkF3DGenericImporter* importer);
/**
- * Set the coloring, call after SetColoringAttributes.
+ * Set coloring information.
* This method will try to find the corresponding array in the coloring attributes and will
* position ArrayIndexForColoring and DataForColoring accordingly.
*/
- void SetColoring(bool useCellData, const std::string& arrayName, int component);
+ void SetColoring(bool enable, bool useCellData, const std::string& arrayName, int component);
///@{
/**
* Get current coloring information,
* Useful after using Cycle methods
*/
+ bool GetColoringEnabled();
bool GetColoringUseCell();
std::string GetColoringArrayName();
int GetColoringComponent();
diff --git a/web/f3d.wasm b/web/f3d.wasm
index 20b08d097b..aee196f51f 100644
Binary files a/web/f3d.wasm and b/web/f3d.wasm differ
diff --git a/web/index.html b/web/index.html
index c7d3edd713..9b5c6dad6d 100644
--- a/web/index.html
+++ b/web/index.html
@@ -94,6 +94,7 @@ F3D Web
options.set_color('render.background.color', 0, 0, 0);
// setup coloring
+ options.toggle('model.scivis.enable');
options.set_string('model.scivis.array_name', 'Colors');
options.set_integer('model.scivis.component', -2);
options.toggle('model.scivis.cells');
diff --git a/webassembly/app.html b/webassembly/app.html
index c7d3edd713..9b5c6dad6d 100644
--- a/webassembly/app.html
+++ b/webassembly/app.html
@@ -94,6 +94,7 @@ F3D Web
options.set_color('render.background.color', 0, 0, 0);
// setup coloring
+ options.toggle('model.scivis.enable');
options.set_string('model.scivis.array_name', 'Colors');
options.set_integer('model.scivis.component', -2);
options.toggle('model.scivis.cells');