From d5a184efc53d351f4c244f1472ea265d9e1210c3 Mon Sep 17 00:00:00 2001 From: Mathieu Westphal Date: Sun, 1 Sep 2024 13:55:09 +0200 Subject: [PATCH] Doc: Update for all devs --- doc/libf3d/OPTIONS.md | 3 ++- doc/user/CONFIGURATION_FILE.md | 33 +++++++++++++++------------------ doc/user/INTERACTIONS.md | 4 +--- doc/user/OPTIONS.md | 8 ++++---- 4 files changed, 22 insertions(+), 26 deletions(-) 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.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.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.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`, ... -