Improve quickstart guide (#1563)

Fixes issue #1259 

Changes:
* Renamed page title from "Usage" to "Quickstart Guide".
* Added short introduction.
* Added "Prerequisites" section.
* Added "Run F3D" section and added quickstart section from README file.
* Reformatted supported file formats into table including scene and animation support.
* Improved style in "Animations" and "Plugins" sections.
* Added "Further Reading" section with links to other user documentation pages.
* Rename the "Usage" page to "Quickstart"

Co-authored-by: kli332 <kli332@wisc.edu>

README.md

@@ -31,24 +31,14 @@ If you need any help or want to discuss with other F3D users and developers, hea
 
 # Quickstart
 
-Open a file and visualize it interactively:
-
+Open a file directly in F3D or from the command line by running:
 ```
 f3d /path/to/file.ext
-```
-
-Open a file and save the rendering into an image file:
-
-```
-f3d /path/to/file.ext --output=/path/to/img.png
-```
+``` 
 
-Get help:
+Optionally, append `--output=/path/to/img.png` to save the rendering into an image file.
 
-```
-f3d --help
-man f3d # Linux only
-```
+See the [Quickstart Guide](QUICKSTART.md) for more information about getting started with F3D.
 
 # Documentation
 

_config.yml

@@ -76,8 +76,9 @@ defaults:
 
   -
     scope:
-      path: "doc/user/USAGE.md"
+      path: "doc/user/QUICKSTART.md"
     values:
+      title: Quickstart
       parent: User Documentation
       nav_order: 0
 
@@ -90,61 +91,76 @@ defaults:
 
   -
     scope:
-      path: "doc/user/OPTIONS.md"
+      path: "doc/user/SUPPORTED_FORMATS.md"
     values:
-      title: Options
+      title: Supported File Formats
       parent: User Documentation
       nav_order: 2
 
   -
     scope:
-      path: "doc/user/INTERACTIONS.md"
+      path: "doc/user/OPTIONS.md"
     values:
+      title: Options
       parent: User Documentation
       nav_order: 3
+
+  -
+    scope:
+      path: "doc/user/INTERACTIONS.md"
+    values:
+      parent: User Documentation
+      nav_order: 4
 
   -
     scope:
       path: "doc/user/ANIMATIONS.md"
     values:
       parent: User Documentation
-      nav_order: 4
+      nav_order: 5
 
   -
     scope:
       path: "doc/user/CONFIGURATION_FILE.md"
     values:
       parent: User Documentation
-      nav_order: 5
+      nav_order: 6
 
   -
     scope:
       path: "doc/user/COLOR_MAPS.md"
     values:
       parent: User Documentation
-      nav_order: 6
+      nav_order: 7
 
   -
     scope:
       path: "doc/user/FINAL_SHADER.md"
     values:
       parent: User Documentation
-      nav_order: 7
+      nav_order: 8
 
   -
     scope:
       path: "doc/user/DESKTOP_INTEGRATION.md"
     values:
       parent: User Documentation
-      nav_order: 8
+      nav_order: 9
+
+  -
+    scope:
+      path: "doc/user/PLUGINS.md"
+    values:
+      parent: User Documentation
+      nav_order: 10
 
   -
     scope:
       path: "doc/user/LIMITATIONS_AND_TROUBLESHOOTING.md"
     values:
       title: Limitations and Troubleshooting
       parent: User Documentation
-      nav_order: 9
+      nav_order: 11
 
 # libf3d doc
   -

doc/user/OPTIONS.md

@@ -19,8 +19,8 @@ Options|Default|Description
 \-\-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](USAGE.md) for more info.
-\-\-scan-plugins||Scan standard directories for plugins and display their names, results may be incomplete. See [usage](USAGE.md) for more info.
+\-\-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 [plugins](PLUGINS.md) for more info.
+\-\-scan-plugins||Scan standard directories for plugins and display their names, results may be incomplete. See [plugins](PLUGINS.md) for more info.
 \-\-screenshot-filename=\<png file\>|`{app}/{model}_{n}.png`|Filename to save [screenshots](INTERACTIONS.md#taking-screenshots) to. Can use [template variables](#filename-templating).
 
 ## General Options

doc/user/PLUGINS.md

@@ -0,0 +1,51 @@
+## Plugins
+
+F3D officially supports plugins for certain file formats. If you installed F3D using the binary
+release, there's no need to manually load these plugins when opening your file. 
+F3D will load them automatically. 
+
+However, if you installed F3D using a package manager, 
+it's possible that the packager chose to bundle the plugins into different packages or 
+to list plugin dependencies as optional in order to reduce the number of dependencies of the main package.
+
+In order to open a file that requires a plugin, make sure you've installed all necessary 
+dependencies. You can then specify the `--load-plugins=<path or name>` [option](OPTIONS.md) 
+in the command line to load your plugin. 
+
+Alternatively, you can add your plugin directly in the 
+[configuration file](CONFIGURATION_FILE.md) if it isn't there already. You can specify one or 
+multiple plugins in a single comma-separated list, like in the example below:
+
+```
+{
+    ".*(file_extension)": {
+        "load-plugins": "plugin1", "plugin2"
+    }
+}
+```
+
+### Supported plugins
+
+F3D supports the following plugins and their file formats:
+
+- **alembic**: `.abc`
+- **assimp**: `.fbx`, `.dae`, `.off`, `.dxf`, `.x`, `.3mf`
+- **draco**: `.drc`
+- **exodus**: `.ex2`
+- **occt**: `.step/.stp`, `.iges/.igs`
+- **usd**: `.usd`, `.usda`, `.usdc`, `.usdz`
+- **vdb**: `.vdb` (experimental)
+
+> Note: If you downloaded the binaries from the release page, it's not necessary to specify manually the plugins above. F3D loads them automatically.
+
+Here is how the plugins are searched (in preceding order):
+
+1. Search the static plugins.
+2. Consider the `load-plugins` option given it is a full path.
+3. Search in the paths specified in `F3D_PLUGINS_PATH` environment variable.
+4. Search in a directory relative to the F3D application: `../lib`.
+5. Rely on OS specific paths (e.g. `LD_LIBRARY_PATH` on Linux or `DYLD_LIBRARY_PATH` on macOS).
+
+You can also try plugins maintained by the community. If you have created a plugin and would like it to be listed here, please submit a pull request.
+
+- **Abaqus**: ODB support by @YangShen398 ([repository](https://github.com/YangShen398/F3D-ODB-Reader-Plugin))

doc/user/QUICKSTART.md

@@ -0,0 +1,87 @@
+# Quickstart Guide
+
+This guide will help you get started using F3D.
+
+As an overview, you'll learn how to run F3D and open files, configure basic scene constructions, interact with them, and play animations.
+
+## Prerequisites
+
+To use F3D, you'll need to install F3D. See the [Installation](INSTALLATION.md) page for the latest release package supported by your system.
+
+## Running F3D
+
+Once F3D has been installed, you should be able to open a file in any of the following ways:
+
+* Open a file directly from your file manager.
+* Open the F3D application directly, then drag and drop a file into the application window.
+* Run F3D from the terminal with a set of command-line [options](OPTIONS.md).
+* Configure F3D as a [thumbnailer](DESKTOP_INTEGRATION.md) for supported file formats with certain file managers.
+
+If you choose to run F3D from the terminal, you can open your file by running the following:
+```
+f3d /path/to/file.ext
+```
+
+Optionally, you can also save the rendering into an image file:
+
+```
+f3d /path/to/file.ext --output=/path/to/img.png
+```
+
+If you need help, specify the `--help` [option](OPTIONS.md):
+
+```
+f3d --help
+man f3d # Linux only
+```
+
+Once you've opened your file in F3D, you're all set to start visualizing! Press <kbd>H</kbd> to open a list of shortcuts to help you interact with your scene. 
+
+See the [supported file formats](SUPPORTED_FORMATS.md) page for the full list of file types that F3D can open.
+
+## Constructing scenes
+
+For most file formats, F3D constructs **a default scene**, loading only the *geometry* from the file.
+
+However, formats supporting **full scenes** will automatically load additional scene properties including *lights*, *cameras*, *actors* and *texture*.
+
+If you'd like to disable these properties, you can specify the `--geometry-only` [option](OPTIONS.md) from the command line to construct a default scene instead.
+
+See the table of [supported file formats](SUPPORTED_FORMATS.md) if you're unsure about what kind of scene your file supports.
+
+## Interacting with your scene
+
+Once you've loaded your scene in F3D, you can interact with it by using your mouse and certain hotkeys. 
+
+### Moving the camera
+
+* *Click and drag* with the *left* mouse button to **rotate** around the focal point of the camera.
+* *Click and drag* vertically with the *right* mouse button <u>OR</u> *move the mouse wheel* to **zoom in/out**.
+* *Click and drag* with the *middle* mouse button to **translate** the camera.
+
+### Other shortcuts
+* Press <kbd>Enter</kbd> to reset the camera.
+* Press <kbd>Space</kbd> to play animation, if any.
+* Press <kbd>G</kbd> to toggle the horizontal grid.
+* Press <kbd>H</kbd> to display a cheatsheet of hotkey interactions. 
+
+For more information, see the [Interactions](INTERACTIONS.md) page.
+
+## Playing animations
+
+F3D can play [animations](ANIMATIONS.md) for any [supported files](SUPPORTED_FORMATS.md) that contain them.
+
+With your file loaded into F3D, press the <kbd>W</kbd> hotkey to cycle through available animations. Then, press <kbd>Space</kbd> to play your selected animation. 
+
+Alternatively, you can use the command line to play animations. Use the `--animation-index` [option](OPTIONS.md) to specify which animation you want to play. To play all animations at once, use `--animation-index=-1` (`.gltf`/`.glb` only). 
+
+For more information, see the [Animations](ANIMATIONS.md) page.
+
+## Further Reading
+
+* [A list of all F3D command-line options.](OPTIONS.md)
+* [How to interact with scenes in F3D.](INTERACTIONS.MD)
+* [How to play animations in F3D.](ANIMATIONS.md)
+* [How to specify colormaps in F3D.](COLOR_MAPS.md)
+* [How to configure plugins in F3D.](PLUGINS.md)
+* [Limitations and how to troubleshoot F3D.](LIMITATIONS_AND_TROUBLESHOOTING.md)

doc/user/README_USER.md

@@ -1,12 +1,14 @@
 # User Documentation
 
-- [How to use F3D.](USAGE.md)
+- [How to use F3D.](QUICKSTART.md)
 - [How to install F3D.](INSTALLATION.md)
+- [List of all supported file formats.](SUPPORTED_FORMATS.md)
 - [List of all F3D command line options.](OPTIONS.md)
 - [The different interactions in F3D.](INTERACTIONS.md)
 - [How to use animations in F3D.](ANIMATIONS.md)
 - [How to use colormaps in F3D.](COLOR_MAPS.md)
 - [How to a use custom final shader in F3D.](FINAL_SHADER.md)
 - [How to configure F3D using a configuration file.](CONFIGURATION_FILE.md)
 - [How to integrate F3D in your desktop.](DESKTOP_INTEGRATION.md)
+- [How to configure plugins in F3D.](PLUGINS.md)
 - [Limitations and troubleshooting of F3D.](LIMITATIONS_AND_TROUBLESHOOTING.md)

doc/user/SUPPORTED_FORMATS.md

@@ -0,0 +1,35 @@
+# Supported File Formats
+
+F3D supports the following file formats:
+
+| Name | File Extension(s) | Type of Scene(s) Supported | Animations Supported? | Plugin Supported |
+| -- | -- | -- | -- | -- |
+| Legacy VTK | `.vtk` | Default | 
+| VTK XML | `.vtp`, `.vtu`, `.vtr`, `.vti`, `.vts`, `.vtm` | Default |
+| Polygon File Format | `.ply` | Default |
+| Standard Triangle Language | `.stl` | Default |  
+| DICOM | `.dcm` | Default |
+| NRRD ("nearly raw raster data") | `.nrrd`, `.nhrd` | Default |
+| MetaHeader MetaIO | `.mhd`, `.mha` | Default |
+| Tag Image File Format 2D/3D | `.tif`, `.tiff` | Default |
+| EXODUS II | `.e`, `.ex2`, `.exo`, `.g` | Default | Yes | `exodus` |
+| CityGML | `.gml` | Default |
+| Point Cloud | `.pts` | Default |
+| Standard for the Exchange of Product Data | `.step`, `.stp` | Default | | `occt` |
+| Initial Graphics Exchange Specification | `.iges`, `.igs` | Default | | `occt` |
+| Open CASCADE Technology BRep format | `.brep` | Default |
+| Alembic | `.abc` | Default | |  `alembic` |
+| Wavefront OBJ | `.obj` | Default, Full |
+| GL Transmission Format | `.gltf`, `.glb` | Default, Full | Yes |
+| Autodesk 3D Studio | `.3ds` | Full |
+| Virtual Reality Modeling Language | `.wrl` | Full |
+| Autodesk Filmbox | `.fbx` | Full | Yes | `assimp` |
+| COLLADA | `.dae` | Full | Yes | `assimp` |
+| Object File Format | `.off` | Full | | `assimp` |
+| Drawing Exchange Format | `.dxf` | Full | | `assimp` |
+| DirectX | `.x` | Full | Yes | `assimp` |
+| 3D Manufacturing Format | `.3mf` | Full | | `assimp` |
+| Universal Scene Description | `.usd` | Full | Yes | `usd` |
+| VDB | `.vdb` | Default | | `vdb` |
+
+\***Note:** As of version 2.5.0, F3D support for VDB is still experimental.