-
-
Notifications
You must be signed in to change notification settings - Fork 205
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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>
- Loading branch information
1 parent
38054ab
commit 069b482
Showing
8 changed files
with
208 additions
and
122 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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)) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
Oops, something went wrong.