diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000000..d3ba173f53 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,239 @@ +--- +layout: default +title: Changelog +nav_order: 6 +--- + +# Changelog + +## v1.3.1 + +- Fix raytracing support +- Fix macOS window positioning + +Contributors: @mwestphal @Meakk + +## v1.3.0 + +Main new features and fixes: +- Introducing an alpha version of the libf3d, see below for more information +- Added a --font-file option +- Added support for Alembic file format (.abc). Geometry only. Thanks a lot @nyue. +- Fixed many HDRI issues +- Fixed an important drag and drop issue on linux + +Other fixes: +- Fixed many doc and UI typos +- Fixed shell completion +- Fixed multiple issue with image comparison +- Fixed an issue with --line-width and --point-size with full scene formats +- Fixed an issue with translucent object and RGBA texture +- Fixed issues with a few specific .gltf files +- Fixed a window title issue on MacOS +- Fixed multiple issues with the output window on Windows +- Fixed issues with file association and thumbnails on Windows +- Fixed a small issue with the cheatsheet not appearing in some cases +- Fixed an issue with certain .obj files +- Fixed a clipping issue when setting camera position +- Removed fullscreen hotkey + +For F3D developers: +- Updated cxxopts to 3.0.0 +- Now using json.hpp for parsing json config file +- Better reproducible build support +- Improved CI with coverage, sanitizer, dedicated actions for dependencies +- Complete rework of the architecture to separate F3D, the application, the libf3d (see below) and a VTKExtensions layer. +- Improved unit testing by adding test in the libf3d and VTKExtensions layer + +For libf3d users: +- Introducing an alpha version of the libf3d! +- The libf3d is a C++ library to open and render 3D meshes, it is of course used by F3D and supports python bindings +- More info available in README_libf3d.md + +Binary Release Information: +- The binary release is **not** built with raytracing support +- This binary release is built with assimp 5.1.2, animation for assimp formats is not working well + +Contributors: @schuhumi @herrriehm @rafcon-dev @mzf-guest @nyue @jpouderoux @Meakk @mwestphal + +## v1.2.1 + +Bug fixes and features: +- Fixed a build issue on MacOS +- Fixed a critical issue with the Windows Thumbnailer that could crash explorer.exe +- Fixed the --quiet option so that it actually quiets VTK errors and warnings +- Fixed an issue with output window poping up at each log on Windows +- Added a `.deb` package for Linux Debian-based distros + +For Packagers: +- LFS file have been added in source code release, this seems to be retroactive, so hash of previous releases may have changed +- Flatpack org name has been fixed + +Contributors: @Meakk @mwestphal @jpouderoux + +## v1.2.0 + +Main New Features: +- Added STEP and IGES file format support thanks to @Open-Cascade-SAS /[OCCT](https://github.com/Open-Cascade-SAS/OCCT) (thanks @drtrigon) +- Added FBX, DAE, OFF, and DXF file format support thanks to @assimp /[assimp](https://github.com/assimp/assimp) +- Added thumbnail support with many linux file managers +- Added thumbnail support on Windows +- Added desktop environnement integration in linux +- Added scalar and scalar component looping + +Other New Features: +- Added support for KHR_materials_unlit with glTF files (thanks @spiraloid) +- Added option for selecting camera `--camera-index` (thanks @spiraloid) +- Added coloring the to Windows error output window +- Added a man entry on Linux +- Added a `--config` option to select a config file to load instead of using default location +- Added a `--quiet` option +- Added `--camera-azimuth` and `--camera-elevation` options (thanks @tatsuya-s) +- Added a metainfo.xml file (thanks @kevinsmia1939) + +Issue Fixes: +- Fixed an issue with opening files with accented char in the name on Windows (thanks @shankarsivarajan) +- Fixed HDRI orientation with --up option (thanks @truhlikfredy) +- Fixed an issue with point cloud rendering +- Fixed a crash on exit on Windows +- Fixed an issue with fullscreen window size on Windows +- Fixed offscreen rendering (`--output` and `--ref` ) to actually use offscreen rendering +- Fixed a memory leak when no rendering is performed (thanks @CharlesGueunet) +- Fixed a rendering issue with certain GPU drivers +- Fixed tone mapping with background opacity +- Fixed non-working drag and drop implementation in VTK (thanks @msbit) +- Fixed a potential sorting issue when opening a folder +- Fixed a crash with unsupported glTF files in VTK + +For Developpers: +- Full rework of the CI framework, including coverage report support +- Full rework of the testing framework +- Separation of vtkF3DRenderer in two classes +- Separation of f3d executable into a libf3d library and f3d executable to support windows thumbnails + +For Packagers: +- New CMake options to select file to install, all documented and starting with F3D_ +- mime types file can be installed, make sure to trigger update-mime-databse +- dekstop file can be installed, make sure to trigger update-desktop-database + +Packagers: AndnoVember @jokersus @kevinsmia1939 @yurivict @bcdarwin @mzf-guest @Meakk @mwestphal + +Binary Release Information: +- The binary release is **not** built with raytracing support +- This binary release is built with assimp 5.1.2, animation for assimp formats is not working well + +Contributors: @CharlesGueunet @kevinsmia1939 @mzf-guest @jpouderoux @Meakk @mwestphal + +## v1.1.1 + +A patch release dedicated to package managers that makes F3D v1.1 compatible with vtk v9.1.0 + +- Fix a render pass build issue with vtk 9.1.0 +- Fix a renderer build issue with vtk 9.1.0 + +Contributors: @Meakk @mwestphal + +## v1.1.0 + +New Important Features: + +* **Added direct scalars color rendering mode**, see doc. +* **Added a turntable interactor** and made it default. The previous interactor can still be used using a dedicated option. Thanks @orangebowlerhat @filip.sund and @jjomier for your suggestions. +* **Added animation support** for glTF and Exodus files. Press space for playing the animation. +* Added animation related option, --animation-index, only for glTF when using the full scene. + +New Readers and format compatibility features: + +* Added skinning and morphing support with glTF files. +* Added TIFF format support. Thanks @proudot for your suggestion. +* Added exodus format support. Thanks @gvernon for your suggestion. +* Added support for OBJ with color directly inside of it instead of using a .mtl file. Thanks @Chenge321 for your suggestion. + +Quality of life features: + +* Added a hotkey (UP) to reload current file, thanks @caioaao. +* Improved Alpha blending performance, thanks @paul.lafoix. +* Changed the progress bar to a more nice looking one and made it appears only if loading takes time. Thanks @finetjul for the suggestion. +* Improved logging mechanism with color on all OS and a dedicated output window on windows. +* Added a warning when using RayTracing but it is not available. + +Fixes: + +* Fixed an issue with skybox and edges. +* Fixed a crash when an array had no name. +* Fixed a window naming issue on OSX. +* Fixed a symlink issue. +* Fixed a coloring issue with dataset containing only cell data. + +Packaging: +* Upgraded the AUR f3d package to 1.1.0 : https://aur.archlinux.org/packages/f3d. +* Added a Brew f3d 1.1.0 package : https://formulae.brew.sh/formula/f3d. +* FreeBSD now contains a f3d 1.1.0 package, thanks to yuri@freebsd.org. +* NixOS now contains a f3d package, 1.1.0 should come soon, thanks to bcdarwin@gmail.com. + +How to support F3D: +* Use the software. +* Share it with anyone interested. +* Star us on github: https://github.com/kitware/F3D. + +Note: Binaries have no raytracing support. + +Contributors: @Meakk @mwestphal + +## v1.0.1 + +- VisualStudio Runtime is now included into the windows release +- Ensure VTK compatibility +- Improve STL binary reader performances +- Fix default configuration issues +- Add support for Window icon on all OSes + +Note: Binaries have no raytracing support. + +Contributors: @Meakk @mwestphal + +## v1.0.0 + +- Documentation + - Online documentation based on Hexo (https://kitware.github.io/F3D/) +- Rendering + - Add volume rendering for 3D images + - HDRI support (skyboxes, HDR files, Filmic tone mapping) + - Point sprites for displaying point clouds + - Color map customization (default one changed to “inferno”) +- Interface + - Drag&Drop files support + - Supports opening of several files (or folder), use left/right arrow to navigate + - Scalars field handling improvements + - Cheat Sheet + - Interactive hotkeys have been reworked + - File association on Windows and OSX + - Fullscreen mode + - No background mode (useful when saving image to a PNG file with alpha channel) +- Command line + - Camera configuration + - Metadata (field data) display + - File name display + - No render mode (useful to read information in the file) + - Shell completion (supports bash, zsh, fish) +- New readers + - CityGML + - PTS +- Packages + - Default config provide + +Note: Binaries have no raytracing support. + +Contributors: @Meakk @mwestphal @hlngrandmontagne Paul Lafoix + +## v0.1.1 + +- Fixes `--version` and `--help` crash + +Contributors: @Meakk @mwestphal @jpouderoux + +## v0.1.0 + +First release! + +Contributors: @Meakk @mwestphal @jpouderoux diff --git a/GALLERY.md b/GALLERY.md new file mode 100644 index 0000000000..64a0b52733 --- /dev/null +++ b/GALLERY.md @@ -0,0 +1,76 @@ +--- +layout: default +title: Gallery +nav_order: 1 +--- + +# Gallery + +Examples renderings with their associated command lines. +Images and videos displayed below use public datasets, you can download them [here](https://drive.google.com/file/d/1iRh0OeJjMjjaBDLG6b_iJSkC_Jt_YQuo/view?usp=sharing). + + + +*Animated realistic rendering*: `f3d gearbox/scene.gltf --hdri=future_parking_2k.hdr -uqxtgas` + + + +*Animated, skinned and morphed rendering*: `f3d dota/scene.gltf --hdri=future_parking_2k.hdr -uqxtgas` + + + +*Animated scientific visualization rendering*: `f3d can.ex2 -xtgans --up=+Z --scalars=VEL` + + + +*Direct scalars rendering of a point cloud*: `f3d Carola_PointCloud.ply --point-size=0 --comp=-2 -so --up=+Z --hdri=venice_sunset_8k.hdr` + + + +*Raytraced CAD assembly*: `f3d 202.vtp -xtgans -rd --samples=10 --range=-2,9` + + + +*Volume rendering of a security bag scan*: `f3d backpack.vti -vmn --range=300,1000 --colormap=0,0,0,0,1,1,1,1` + + + +*Realistic rendering #1*: `f3d DamagedHelmet.glb --hdri=lebombo_4k.hdr -tuqap` + + + +*Showcase of interactive widgets*: `f3d dragon.vtu -xtganse --comp=0` + + + +*Metallic Rendering of a STEP file*: `f3d eta_asm.stp –hdri=future_parking_2k.hdr -uqxtga –up=+Z –metallic=1 –roughness=0.6 –color=0.98,0.90,0.59` + + + +*Rendering of a FBX file*: `f3d zeldaPosed001.fbx –hdri=hikers_cave_2k.hdr -uqxtga` + + + +*Realistic rendering #2*: `f3d FlightHelmet.glb --hdri=lebombo_4k.hdr -tuqap` + + + +*Visualization of a CFD velocity field*: `f3d single-pin.vtp -xtbgans --range=-2,8 --colormap=0,0.3,0.7,0,0.7,0,0.1,1,1,0.8,0.8,0` + + + +*Volume rendering of a medical skull scan*: `f3d skull.vti -vxbt --range=40,200` + + + +*Point cloud rendering using sprites*: `f3d pointCloud.vtp -o --point-size=0.2 --colormap=0,0,0.8,0,0.4,0.9,0,0,0.8,0.9,0.9,0,1,0.5,0.5,1` + +## Acknowledgments + +- Bristleback DOTA Fan-Art by [Nikolay_Tsys](https://sketchfab.com/Tolst). +- SY Carola (point cloud) by [Scottish Maritime Museum](https://sketchfab.com/ScottishMaritimeMuseum) +- Gearbox Animation by [DZHUSI ØNE](https://sketchfab.com/dzhusione) +- Watch movement by [Greg Brown](https://grabcad.com/greg.brown) +- Zelda - Breath Of The Wild by [theStoff](https://sketchfab.com/theStoff) +- Venice Sunset HDRI and Hiker’s Cave HDRI by [Greg Zaal](https://polyhaven.com/hdris?a=Greg%20Zaal) +- Future Parking HDRI by [Sergej Majboroda](https://polyhaven.com/hdris?a=Sergej%20Majboroda) diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000000..1723426d44 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,39 @@ +--- +layout: default +title: License +parent: Licenses +nav_order: 0 +--- + +BSD 3-Clause License + +``` +Copyright 2019-2021 Kitware SAS +Copyright 2021-2022 Michael Migliore, Mathieu Westphal +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +* Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +``` diff --git a/README.md b/README.md new file mode 100644 index 0000000000..3500b9d970 --- /dev/null +++ b/README.md @@ -0,0 +1,67 @@ +[![CI](https://github.com/f3d-app/f3d/actions/workflows/ci.yml/badge.svg)](https://github.com/f3d-app/f3d/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/f3d-app/f3d/branch/master/graph/badge.svg?token=siwG82IXK7)](https://codecov.io/gh/f3d-app/f3d) [![Downloads](https://img.shields.io/github/downloads/f3d-app/f3d/total.svg)](https://github.com/f3d-app/f3d/releases) + +# F3D - Fast and minimalist 3D viewer +By Michael Migliore and Mathieu Westphal. + + +F3D (pronounced `/fɛd/`) is a fast and minimalist 3D viewer. It supports many file formats, from digital content to scientific datasets (including glTF, STL, STEP, PLY, OBJ, FBX, Alembic), can show animations and support lot of rendering and texturing options including real time physically based rendering and raytracing. +
+ +It is fully controllable from the command line and support configuration files. It can provide thumbnails, support interactive hotkeys, drag&drop and integration into file managers. + +F3D also contains the libf3d, a simple library to render meshes, with C++, Python and Java Bindings. + + + +*A typical render by F3D* + + + +*Animation of a glTF file within F3D* + + + +*A direct scalars render by F3D* + +See the [gallery](GALLERY.md) for more images, take a look at the [changelog](CHANGELOG.md) or go to the [releases page](https://github.com/f3d-app/f3d/releases) to download F3D! + +# Quickstart + +Open a file and visualize it interactively: + +``` +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: + +``` +f3d --help +man f3d # Linux only +``` + +# Documentation + +- To get started, please take a look at the [user documentation](doc/README.md). +- If you need any help, are looking for a feature or found a bug, please open an [issue](https://github.com/f3d-app/f3d/issues). +- If you want to use the libf3d, please take a look at its [documentation](doc/libf3d/README.md). +- If you want to build F3D and contribute to it, please take a look at the [developper documentation](doc/dev/README.md). + +# Support + +F3D is developed by a team of passionate devs. Please use F3D and star it on github to support us! + +# Acknowledgments + +F3D was initially created by [Kitware SAS](https://www.kitware.eu/) and is relying on many awesome open source projects, including [VTK](https://vtk.org/), [OCCT](https://dev.opencascade.org/), [Assimp](https://www.assimp.org/), [Alembic](http://www.alembic.io/) and [OSPRay](https://www.ospray.org/). + +# License + +F3D can be used and distributed under the 3-Clause BSD License, see the [license](LICENSE.md). +F3D rely on other libraries and tools, all under permissive licenses, see the [third party licenses](THIRD_PARTY_LICENSES.md). diff --git a/THIRD_PARTY_LICENSES.md b/THIRD_PARTY_LICENSES.md new file mode 100644 index 0000000000..252718d9c6 --- /dev/null +++ b/THIRD_PARTY_LICENSES.md @@ -0,0 +1,253 @@ +--- +layout: default +title: Third Party Licenses +parent: Licenses +nav_order: 1 +--- + +# Third Party Copyrights and License within F3D source + +## cxxopts.hpp: +``` +Copyright (c) 2014, 2015, 2016, 2017 Jarryd Beck + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. +``` + +## json.hpp: +``` + __ _____ _____ _____ + __| | __| | | | JSON for Modern C++ +| | |__ | | | | | | version 3.10.5 +|_____|_____|_____|_|___| https://github.com/nlohmann/json + +Licensed under the MIT License . +SPDX-License-Identifier: MIT +Copyright (c) 2013-2022 Niels Lohmann . + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` + +## FileAssociation.nsh: +``` +by Vytautas Krivickas from https://nsis.sourceforge.io/File_Association. + +No license provided. +``` + +# Third Party Copyrights and License within F3D binary release + +## VTK License: + +``` + Program: Visualization Toolkit + Module: Copyright.txt + +Copyright (c) 1993-2015 Ken Martin, Will Schroeder, Bill Lorensen +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + + * Neither name of Ken Martin, Will Schroeder, or Bill Lorensen nor the names + of any contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR +ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +``` + +## Assimp License: +``` +Open Asset Import Library (assimp) + +Copyright (c) 2006-2021, assimp team +All rights reserved. + +Redistribution and use of this software in source and binary forms, +with or without modification, are permitted provided that the +following conditions are met: + +* Redistributions of source code must retain the above + copyright notice, this list of conditions and the + following disclaimer. + +* Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other + materials provided with the distribution. + +* Neither the name of the assimp team, nor the names of its + contributors may be used to endorse or promote products + derived from this software without specific prior + written permission of the assimp team. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +Poly2Tri Copyright (c) 2009-2010, Poly2Tri Contributors +http://code.google.com/p/poly2tri/ + +All rights reserved. +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. +* Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. +* Neither the name of Poly2Tri nor the names of its contributors may be + used to endorse or promote products derived from this software without specific + prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR +CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +``` + +## Alembic License: +``` +TM & © 2009-2015 Lucasfilm Entertainment Company Ltd. or Lucasfilm Ltd. +All rights reserved. + +Industrial Light & Magic, ILM and the Bulb and Gear design logo are all +registered trademarks or service marks of Lucasfilm Ltd. + +© 2009-2015 Sony Pictures Imageworks Inc. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: +* Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. +* Redistributions in binary form must reproduce the above +copyright notice, this list of conditions and the following disclaimer +in the documentation and/or other materials provided with the +distribution. +* Neither the name of Industrial Light & Magic nor the names of +its contributors may be used to endorse or promote products derived +from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + +------------------------------------------------------------------------------- + +ALEMBIC ATTACHMENT A — +REQUIRED NOTICES FOR DISTRIBUTION + +The Alembic Software is distributed along with certain third party +components licensed under various open source software licenses ("Open +Source Components"). In addition to the warranty disclaimers contained +in the open source licenses found below, Industrial Light & Magic, a +division of Lucasfilm Entertainment Company Ltd. ("ILM") makes the +following disclaimers regarding the Open Source Components on behalf of +itself, the copyright holders, contributors, and licensors of such Open +Source Components: + +TO THE FULLEST EXTENT PERMITTED UNDER APPLICABLE LAW, THE OPEN SOURCE +COMPONENTS ARE PROVIDED BY THE COPYRIGHT HOLDERS, CONTRIBUTORS, +LICENSORS, AND ILM "AS IS" AND ANY REPRESENTATIONS OR WARRANTIES OF ANY +KIND, WHETHER ORAL OR WRITTEN, WHETHER EXPRESS, IMPLIED, OR ARISING BY +STATUTE, CUSTOM, COURSE OF DEALING, OR TRADE USAGE, INCLUDING WITHOUT +LIMITATION THE IMPLIED WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR +A PARTICULAR PURPOSE, AND NON-INFRINGEMENT, ARE DISCLAIMED. IN NO EVENT +WILL THE COPYRIGHT OWNER, CONTRIBUTORS, LICENSORS, OR ILM AND/OR ITS +AFFILIATES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +PROFITS; OR BUSINESS INTERRUPTION), HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THE OPEN +SOURCE COMPONENTS, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +``` + +## Imath License: +``` +Copyright Contributors to the OpenEXR Project. All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +``` diff --git a/_config.yml b/_config.yml new file mode 100644 index 0000000000..90449ad795 --- /dev/null +++ b/_config.yml @@ -0,0 +1,29 @@ +remote_theme: just-the-docs/just-the-docs +plugins: + - jekyll-remote-theme + - jekyll-relative-links +relative_links: + enabled: true + collections: true +include: + - _readme.md + - _licenses.md +exclude: + - testing/data/DATA_LICENSES.md +title: F3D +description: Fast and minimalist 3D viewer +logo: /resources/logotype.svg +color_scheme: dark + +# Aux links for the upper right navigation +aux_links: + "": + - "//github.com/f3d-app/f3d" + +# Makes Aux links open in a new tab. +aux_links_new_tab: true + +# External navigation links +nav_external_links: + - title: Download F3D + url: https://github.com/f3d-app/f3d/releases diff --git a/_includes/head_custom.html b/_includes/head_custom.html new file mode 100644 index 0000000000..c622912ecd --- /dev/null +++ b/_includes/head_custom.html @@ -0,0 +1 @@ + diff --git a/_licenses.md b/_licenses.md new file mode 100644 index 0000000000..eedcef0630 --- /dev/null +++ b/_licenses.md @@ -0,0 +1,6 @@ +--- +layout: default +title: Licenses +nav_order: 5 +has_children: true +--- diff --git a/_readme.md b/_readme.md new file mode 100644 index 0000000000..3580cf3ecf --- /dev/null +++ b/_readme.md @@ -0,0 +1,9 @@ +--- +layout: default +title: Home +nav_order: 0 +description: "F3D - Fast and minimalist 3D viewer" +permalink: / +--- + +{% include_relative README.md %} diff --git a/cmake/installing.cmake b/cmake/installing.cmake index 6470d304e6..3856721963 100644 --- a/cmake/installing.cmake +++ b/cmake/installing.cmake @@ -46,7 +46,7 @@ if (UNIX AND NOT APPLE AND NOT ANDROID) set(F3D_DOC_DIR ${CMAKE_INSTALL_DOCDIR}) endif() -install(FILES LICENSE THIRD_PARTY_LICENSES.md README.md +install(FILES LICENSE.md THIRD_PARTY_LICENSES.md README.md DESTINATION ${F3D_DOC_DIR} COMPONENT documentation) list(APPEND config_files diff --git a/cmake/packaging.cmake b/cmake/packaging.cmake index b4520a5a6a..51f1f86af5 100644 --- a/cmake/packaging.cmake +++ b/cmake/packaging.cmake @@ -7,7 +7,7 @@ set(CPACK_PACKAGE_VENDOR "${PROJECT_NAME}-app") set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "${PROJECT_DESCRIPTION}") set(CPACK_PACKAGE_DESCRIPTION_FILE "${CMAKE_SOURCE_DIR}/README.md") set(CPACK_RESOURCE_FILE_README "${CMAKE_SOURCE_DIR}/README.md") -set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_SOURCE_DIR}/LICENSE") +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_SOURCE_DIR}/LICENSE.md") set(CPACK_PACKAGE_EXECUTABLES f3d f3d) set(CPACK_CREATE_DESKTOP_LINKS f3d) @@ -20,7 +20,7 @@ if(WIN32 AND NOT UNIX) # For some reason, we need Windows backslashes # https://www.howtobuildsoftware.com/index.php/how-do/PNb/cmake-nsis-bmp-cpack-how-to-set-an-icon-in-nsis-install-cmake # BMP3 format is also required (recommended size is 150x57) - set(CPACK_PACKAGE_ICON "${CMAKE_SOURCE_DIR}/resources\\\\logo.bmp") + set(CPACK_PACKAGE_ICON "${CMAKE_SOURCE_DIR}/resources\\\\logotype64.bmp") set(CPACK_NSIS_MENU_LINKS ${f3d_url} "F3D Website") set(CPACK_NSIS_MODIFY_PATH ON) set(CPACK_NSIS_MUI_ICON ${f3d_ico}) diff --git a/doc/CONFIGURATION_FILE.md b/doc/CONFIGURATION_FILE.md new file mode 100644 index 0000000000..3ba1a4ea10 --- /dev/null +++ b/doc/CONFIGURATION_FILE.md @@ -0,0 +1,82 @@ +--- +layout: default +title: Configuration File +parent: User Documentation +nav_order: 5 +--- + +# Configuration File + +Almost all the command-line options can be controlled using a configuration file. +This configuration file uses the "long" version of the 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. + +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", + "fxaa": true, + "timer": true, + "progress": true, + "axis": true, + "bar": true, + "roughness": 0.2, + "grid": true, + "scalars": true, + }, + ".*vt.": { + "edges": true + }, + ".*gl(tf|b)": { + "raytracing": true, + "denoise": true, + "samples": 3 + }, + ".*mhd": { + "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. + +F3D provides a default config file for generic usage (`config.json`) and a thumbnail specific config file (`thumbnail.json`). +You can edit these files 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`, `quiet`, `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`. + +The configuration file possible locations depends on your operating system. +They are considered in the below order and only the first found will be used. + + * Linux: `${XDG_CONFIG_HOME}/.config/f3d/config.json`, `~/.config/f3d/config.json`, `/etc/f3d/config.json`, `/usr/share/f3d/config.json`, `[install_dir]/share/f3d/config.json` + * Windows: `%APPDATA%\f3d\config.json`, `[install_dir]\config.json` + * macOS: `${XDG_CONFIG_HOME}/.config/f3d/config.json`, `~/.config/f3d/config.json`, `/usr/local/etc/f3d/config.json`, `f3d.app/Contents/Resources/config.json` + +The binary release will install the config files. +On Linux, they will be installed in `[install_dir]/share/f3d/`, on Windows, it will be installed in the install directory, 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` will be added) to look for in the locations listed above, instead of looking for `config.json`, eg: `f3d --config=custom_config` will look +for `custom_config.json` in locations listed above. diff --git a/doc/DESKTOP_INTEGRATION.md b/doc/DESKTOP_INTEGRATION.md new file mode 100644 index 0000000000..5ffbcec9de --- /dev/null +++ b/doc/DESKTOP_INTEGRATION.md @@ -0,0 +1,55 @@ +--- +layout: default +title: Desktop Integration +parent: User Documentation +nav_order: 6 +--- + +# Desktop Integration + +F3D can be integrated in the desktop experience. + +## Linux + +For Linux desktop integration, F3D rely on mime types files as defined by the [XDG standard](https://specifications.freedesktop.org/mime-apps-spec/mime-apps-spec-latest.html), .thumbnailer file as specified [here](https://wiki.archlinux.org/title/File_manager_functionality#Thumbnail_previews) and .desktop file as specified [here](https://wiki.archlinux.org/title/desktop_entries). Many file managers use this mechanism, including nautilus, thunar, pcmanfm and caja. + +The simplest way to obtain desktop integration on linux is to use a package for your distribution, or the .deb binary release package we provide if compatible with your distribution. +In other cases, the binary release archive can be used like this: + +0. Make sure `~/.local/bin` is part of your `PATH` +1. Extract F3D binary release archive in `~/.local/` +2. Update your [mime database](https://linux.die.net/man/1/update-mime-database) pointing to `~/.local/share/mime` +3. Update your [desktop database](https://linuxcommandlibrary.com/man/update-desktop-database) pointing to `~/.local/share/application` + +```bash +export PATH=$PATH:~/.local/bin +tar -xzvf f3d-1.3.0-Linux.tar.gz -C ~/.local/ +sudo update-mime-database ~/.local/share/mime/ +sudo update-desktop-database ~/.local/share/applications +``` + +If you have any issues, refer to the [troubleshooting](LIMITATIONS_AND_TROUBLESHOOTING.md) part. + +## Windows + +For Windows desktop integration, F3D rely on a registered shell extension. + +Using the F3D NSIS installer (.exe) is the simplest way to enable thumbnails and integrate F3D on windows. + +It is also possible to do it manually when using the zipped binary release archive, on installation, just run: + +``` +cd C:\path\to\f3d\bin\ +regsvr32 F3DShellExtension.dll +``` + +To remove the shell extension, run: + +``` +cd C:\path\to\f3d\bin\ +regsvr32 /u F3DShellExtension.dll +``` + +## MacOS + +There is no support for thumbnails on MacOS, the .dmg binary release provides automatic file openings. diff --git a/doc/INSTALLATION.md b/doc/INSTALLATION.md new file mode 100644 index 0000000000..4ffe6db50e --- /dev/null +++ b/doc/INSTALLATION.md @@ -0,0 +1,27 @@ +--- +layout: default +title: Installation +parent: User Documentation +nav_order: 1 +--- + +# Installation + +You can find the binary release packages for Windows, Linux and macOS on the [releases page](https://github.com/f3d-app/f3d/releases). +See the [desktop integration](DESKTOP_INTEGRATION.md) section in order actually integrate the binary release in your desktop. +Alternatively, you can build F3D yourself by following the [build](dev/BUILD.md) guide. + +You can also find packages for the following package managers: + +- [Ubuntu](https://packages.ubuntu.com/search?keywords=f3d&searchon=names&exact=1&suite=all§ion=all) +- [Debian](https://packages.debian.org/search?keywords=f3d&searchon=names&exact=1&suite=all§ion=all) +- [Arch User Repository](https://aur.archlinux.org/packages/f3d) +- [FreeBSD](https://cgit.freebsd.org/ports/tree/graphics/f3d) +- [NixOS](https://search.nixos.org/packages?channel=22.05&show=f3d&from=0&size=50&sort=relevance&type=packages&query=f3d) +- [openSUSE](https://software.opensuse.org/package/f3d) +- Fedora and others through [openSUSE OBS](https://build.opensuse.org/package/show/home:AndnoVember:F3D/f3d) +- [MacOS Homebrew](https://formulae.brew.sh/formula/f3d) +- [Windows Scoop](https://scoop.sh/#/apps?q=f3d&s=0&d=1&o=true) +- [Flathub](https://flathub.org/apps/details/io.github.f3d_app.f3d) +- [Spack](https://packages.spack.io/package.html?name=f3d) +- [Guix](https://guix.gnu.org/en/packages/f3d-1.3.1/) diff --git a/doc/INTERACTIONS.md b/doc/INTERACTIONS.md new file mode 100644 index 0000000000..c52e35493a --- /dev/null +++ b/doc/INTERACTIONS.md @@ -0,0 +1,87 @@ +--- +layout: default +title: Interactions +parent: User Documentation +nav_order: 4 +--- + +# 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. +* *Click and drag* with the *middle* mouse button to translate the camera. +* Drag and drop a file or directory into the F3D window to load it + +> 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](#cycling-coloring) section for more info. + +Other options can be toggled directly by pressing the following hotkeys: + +* `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`: depth peeling. +* `Q`: Screen-Space Ambient Occlusion. +* `A`: Fast Approximate Anti-Aliasing. +* `T`: tone mapping. +* `E`: the display of cell edges. +* `X`: the trihedral axes display. +* `G`: the XZ 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 when using a HDRi. +* `K`: trackball interaction mode. + +Note that some hotkeys can be available or not depending on the file being loaded and the F3D configuration. + +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. +* `ENTER`: reset the camera to its initial parameters. +* `SPACE`: play the animation if any. +* `LEFT`: load the previous file if any. +* `RIGHT`: load the next file if any. +* `UP`: reload the current file. + +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. + +## 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, 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 +if the array contains 4 or less components, -1 otherwise. + +When changing the array, the component in use will be kept if valid with the new array, if not it will be reset to 0 +when coloring with an invalid higher than zero component, and to -1 when using direct scalars rendering with an array +having more than 4 components. + +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. diff --git a/doc/LIMITATIONS_AND_TROUBLESHOOTING.md b/doc/LIMITATIONS_AND_TROUBLESHOOTING.md new file mode 100644 index 0000000000..a9b3247bd6 --- /dev/null +++ b/doc/LIMITATIONS_AND_TROUBLESHOOTING.md @@ -0,0 +1,89 @@ +--- +layout: default +title: Limitations and Troubleshooting +parent: User Documentation +nav_order: 7 +--- + +# Limitations + +Here is a non exhaustive list of F3D limitations: + +* No support for specifying manual lighting in the default scene. +* Multiblock (.vtm, .gml) support is partial, non-surfacic data will be converted into surfaces. +* Animation support with full scene data format require VTK >= 9.0.20201016. +* Full drag and drop support require VTK >= 9.0.20210620 +* Drag and drop interaction cannot be recorded nor played back. +* Volume rendering and HDRI support requires a decent GPU. + +## Assimp +FBX, DAE, OFF, and DXF file formats rely on [Assimp](https://github.com/assimp/assimp) library. It comes with some known limitations: +- PBR materials are not supported for FBX file format. +- Animations are not working very well with Assimp 5.1, it's recommended to use Assimp 5.0. +- Some files can be empty, crash, or show artifacts. +- DXF support is very limited: only files with polylines and 3D faces are displayed. + +## Alembic +ABC file formats rely on [Alembic](https://github.com/alembic/alembic) library. It comes with some known limitations: +- Supports only simple polygonal geometry. +- Does not support ArbGeomParam feature in Alembic. +- Does not support Subdivision Meshes. +- Does not support Materials. + +# Troubleshooting + +## General +> I have built F3D with raytracing support but the denoiser is not working. + +Make sure that VTK has been built with *OpenImageDenoise* support (`VTKOSPRAY_ENABLE_DENOISER` option). + +## Linux + +> I have a link error related to `stdc++fs` not found. + +With some C++ STD library version, explicit linking to `stdc++fs` is not supported. We provide a CMake option `F3D_APPLICATION_LINK_FILESYSTEM` that you can set to `OFF` to workaround this issue. + +### Thumbnails +> Thumbnails are not working in my file manager. + + * Check that your file manager supports the thumbnailer mechanism. + * Check that you have updated your mime type database. + * If all fails, remove your `.cache` user dir and check that `pcmanfm` thumbnails are working. + * If they are working, then it is an issue specific to your file manager (see below for a potential work around). + * If only a few format have working thumbnails, then it is an issue with the mime types database. + * If no formats have working thumbnails, then it is an issue with the `f3d.thumbnailer` file. + * If only big file do not have thumbnails, this is intended, you can modify this behavior in the `thumbnail.json` configuration file using the `max-size` option. + +### Sandboxing +Some file managers (eg: Nautilus) are using sandboxing for thumbnails, which the F3D binary release does not support as it needs +access to the Xorg server for rendering anything. +A work around to this issue is to use a virtual Xorg server like Xephyr or Xvfb in the `f3d.thumbnailer` file. +Here is how your `Exec` line should look to use `xvfb-run`. Keep in mind running xvfb can be very slow. + +`Exec=xvfb-run f3d --dry-run -sta --no-background --output=%o --resolution=%s,%s %i` + +Another workaround is to build VTK with EGL or osmesa support and then build F3D yourself against +this custom VTK build. + +## Windows +> After installing F3D or registering the shell extension, my explorer is broken. + +Unregister the shell extension by running: + +``` +cd C:\path\to\f3d\bin\ +regsvr32 /u F3DShellExtension.dll +``` + +> I use F3D in a VM, the application fails to launch. + +OpenGL applications like F3D can have issues when launched from a guest Windows because the access to the GPU is restricted. +You can try to use a software implementation of OpenGL, called [Mesa](https://github.com/pal1000/mesa-dist-win/releases). + * Download the latest `release-msvc`. + * copy `x64/OpenGL32.dll` and `x64/libglapi.dll` in the same folder as `f3d.exe`. + * set the environment variable `MESA_GL_VERSION_OVERRIDE` to 4.5. + * run `f3d.exe`. + +> I run f3d from the command prompt and my Unicode characters are not displayed properly. + +Set the codepage to UTF-8, run `chcp 65001`. diff --git a/doc/OPTIONS.md b/doc/OPTIONS.md new file mode 100644 index 0000000000..d3e8dfbf0d --- /dev/null +++ b/doc/OPTIONS.md @@ -0,0 +1,130 @@ +--- +layout: default +title: Options +parent: User Documentation +nav_order: 3 +--- + +# Command line options + +F3D behavior can be fully controled from the command line using the following options. + +## Applicative Options + +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. +\-\-no-background||Use with \-\-output to output a png file with a transparent background. +-h, \-\-help||Print *help* and exit. +\-\-version||Show *version* information and exit. +\-\-readers-list||List available *readers* and exit. +\-\-config=\|config|Specify the [configuration file](CONFIGURATION_FILE.md) 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||Print information about the first provided file (as with \-\-verbose) and exit, without rendering anything, useful to recover information about a file. +\-\-max-size=\|-1|Prevent F3D to load a file bigger than the provided size in Mib, -1 means unlimited, useful for thumbnails. + +## General Options + +Options|Default|Description +------|------|------ +\-\-verbose||Enable *verbose* mode, providing more information about the loaded data in the console output. +\-\-quiet||Enable quiet mode, which superseed any verbose options. No console output will be generated at all. +\-\-progress||Show a *progress bar* when loading the file. +\-\-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. +\-\-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 XZ plane. +-e, \-\-edges||Show the *cell edges*. +\-\-camera-index=\|-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-index=\|0|Select the animation to show.
Any negative value means all animations.
The default scene always has at most one animation. +\-\-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=\|10.0|Set the *size* of points when showing vertices and point sprites. +\-\-line-width=\|1.0|Set the *width* of lines when showing edges. +\-\-color=\|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=\|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=\|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=\|0.0|Set the *metallic coefficient* on the geometry (0.0-1.0). Multiplied with the material texture when present.
Requires a default scene. +\-\-hrdi=\||Set the *HDRI* image used to create the environment.
The environment act as a light source and is reflected on the material.
Valid file format are hdr, png, jpg, pnm, tiff, bmp. +\-\-texture-base-color=\||Set the texture file to control the color of the object. Please note this will be multiplied with the color and opacity options. +\-\-texture-material=\||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. +\-\-texture-emissive=\||Set the texture file to control the emitted light of the object. Please note this will be multiplied with the emissive factor. +\-\-emissive-factor=\|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=\|0.2, 0.2, 0.2|Set the window *background color*.
Ignored if *hdri* is set. +\-\-resolution=\|1000, 600|Set the *window resolution*. +\-\-position=\||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. +-u, \-\-blur-background||Blur background.
Requires an HDRi. +\-\-light-intensity|1.0|*Adjust the intensity* of every light in the scene. + +## Scientific visualization options + +Options|Default|Description +------|------|------ +-s, \-\-scalars=\||Specify an array to *Color* with if present in the file. If no array_name is provided, one will be picked if any are available.
Requires a default scene.
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. +-b, \-\-bar||Show *scalar bar* of the coloring by array.
Use with the scalar option. +\-\-colormap=\||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).
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=\||Set the camera position. +\-\-camera-focal-point=\||Set the camera focal point. +\-\-camera-view-up=\||Set the camera view up vector. Will be orthogonalized. +\-\-camera-view-angle=\||Set the camera view angle, a non-zero value in degrees. +\-\-camera-azimuth-angle=\|0.0|Apply an azimuth transformation to the camera, in degrees. +\-\-camera-elevation-angle=\|0.0|Apply an elevation transformation to the camera, in degrees. + +## Raytracing options + +Options|Default|Description +------|------|------ +-r, \-\-raytracing||Enable *OSPRay raytracing*. Requires OSPRay raytracing to be enabled in the linked VTK dependency. +\-\-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, \-\-depth-peeling|Enable *depth peeling*. This is a technique used to correctly render translucent objects. +-q, \-\-ssao|Enable *Screen-Space Ambient Occlusion*. This is a technique used to improve the depth perception of the object. +-a, \-\-fxaa|Enable *Fast Approximate 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. + +## Testing options + +Options|Default|Description +------|------|------ +\-\-ref=\||Render and compare with the provided *reference image*, for testing purposes. Use with output option to generate new baselines and diff images. +\-\-ref-threshold=\|50|Set the *comparison threshold* to trigger a test failure or success. The default (50) correspond to almost visually identical images. +\-\-interaction-test-record=\||Path to an interaction log file to *record interaction events* to. +\-\-interaction-test-play=\||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`) diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000000..772ea7a93e --- /dev/null +++ b/doc/README.md @@ -0,0 +1,17 @@ +--- +layout: default +title: User Documentation +nav_order: 2 +has_children: true +has_toc: false +--- + +# User Documentation + +- [How to use F3D.](USAGE.md) +- [How to install F3D.](INSTALLATION.md) +- [List of all F3D command line options.](OPTIONS.md) +- [The different interactions in F3D.](INTERACTIONS.md) +- [How to configure F3D using a configuration file.](CONFIGURATION_FILE.md) +- [How to integrate F3D in your desktop.](DESKTOP_INTEGRATION.md) +- [Limitations and troubleshooting of F3D.](LIMITATIONS_AND_TROUBLESHOOTING.md) diff --git a/doc/USAGE.md b/doc/USAGE.md new file mode 100644 index 0000000000..4cc695622f --- /dev/null +++ b/doc/USAGE.md @@ -0,0 +1,49 @@ +--- +layout: default +title: Usage +parent: User Documentation +nav_order: 0 +--- + +# Usage + +Once F3D has been [installed](INSTALLATION.md), you should be able to open any [supported file](#supported-file-formats), +by either: +* Using F3D automatically, from your file manager, by directly opening a file. +* Running F3D and then dragging and dropping files into it to open them. +* By running F3D from the terminal with a set of command-line [options](OPTIONS.md). +* As a [thumbnailer](DESKTOP_INTEGRATION.md) for all supported file formats with certain file managers. + +## Supported file formats + +Here is the list of supported file formats: + +* **.vtk** : the legacy VTK format +* **.vt[p\|u\|r\|i\|s\|m]** : XML based VTK formats +* **.ply** : Polygon File format +* **.stl** : Standard Triangle Language format +* **.dcm** : DICOM file format +* **.nrrd/.nhrd** : "nearly raw raster data" file format +* **.mhd/.mha** : MetaHeader MetaIO file format +* **.tif/.tiff** : TIFF 2D/3D file format +* **.ex2/.e/.exo/.g** : Exodus 2 file format +* **.gml** : CityGML file format +* **.pts** : Point Cloud file format +* **.step/.stp** : CAD STEP exchange ISO format +* **.iges/.igs** : CAD Initial Graphics Exchange Specification format +* **.abc** : Alembic format +* **.obj** : Wavefront OBJ file format (full scene and default scene) +* **.gltf/.glb** : GL Transmission Format (full scene and default scene) +* **.3ds** : Autodesk 3D Studio file format (full scene) +* **.wrl** : VRML file format (full scene) +* **.fbx** : Autodesk Filmbox (full scene) +* **.dae** : COLLADA (full scene) +* **.off** : Object File Format (full scene) +* **.dxf** : Drawing Exchange Format (full scene) + +## Scene construction + +The **full scene** formats (.gltf/.glb, .3ds, .wrl, .obj, .fbx, .dae, .off) contain not only *geometry*, +but also some scene information like *lights*, *cameras*, *actors* in the scene, as well as *texture* properties. +By default, all this information will be loaded from the file and displayed. Use the `--geometry-only` [options](OPTIONS.md) +to modify this behavior. For file formats that do not support it, **a default scene** is created. diff --git a/doc/dev/BUILD.md b/doc/dev/BUILD.md new file mode 100644 index 0000000000..8670438df3 --- /dev/null +++ b/doc/dev/BUILD.md @@ -0,0 +1,51 @@ +--- +layout: default +title: Build +parent: Developer Documentation +nav_order: 0 +--- + +# Build guide + +F3D uses a CMake based build system, so building F3D just requires installing +needed dependencies, configuring and building. + +## Dependencies + +* [CMake](https://cmake.org) >= 3.1. +* [VTK](https://vtk.org) >= 9.0.0 (9.2.2 recommended). +* A C++17 compiler. +* A CMake-compatible build system (Visual Studio, XCode, Ninja, Make, etc.). +* Optionally, [Assimp](https://flathub.org/apps/details/io.github.f3d_app.f3d) >= 5.0. +* Optionally, Open CASCADE [OCCT](https://flathub.org/apps/details/io.github.f3d_app.f3d) >= 7.5.2. +* Optionally, [Alembic](http://www.alembic.io/) >= 1.7. +* Optionally, [Python](https://www.python.org/) >= 3.6 and [pybind11](https://github.com/pybind/pybind11) >= 2.2. +* Optionally, [Java](https://www.java.com) >= 18. + +## VTK compatibility + +As stated in the dependencies, F3D is compatible with VTK >= 9.0.0, however, many features are only available in certain conditions. We suggest using VTK 9.2.2 with RenderingRayTracing, RenderingExternal and IOExodus modules enabled in order to get as many features as possible in F3D. + +## Configuration and building + +Configure and generate the project with CMake, +then build the software using your build system. + +Here is some CMake options of interest:: +* `F3D_BUILD_APPLICATION`: Build the F3D executable. +* `F3D_INSTALL_SDK`: Install the F3D SDK for the [libf3d](../libf3d/README.md). +* `BUILD_TESTING`: Enable the [tests](TESTING.md). +* `F3D_MACOS_BUNDLE`: On macOS, build a `.app` bundle. +* `F3D_WINDOWS_GUI`: On Windows, build a Win32 application (without console). +* `F3D_BUILD_WINDOWS_SHELL_THUMBNAILS_EXTENSION`: On Windows, build the shell thumbnails extension. + +Some modules and bindings depending on external libraries can be optionally enabled with the following CMake variables: + +* `F3D_MODULE_EXODUS`: Support for ExodusII (.ex2) file format. Requires that VTK has been built with `IOExodus` module (and `hdf5`). Enabled by default. +* `F3D_MODULE_RAYTRACING`: Support for raytracing rendering. Requires that VTK has been built with `OSPRay` and `VTK_MODULE_ENABLE_VTK_RenderingRayTracing` turned on. Disabled by default. +* `F3D_MODULE_EXTERNAL_RENDERING`: Support for external render window, Requires that VTK has been built with `VTK_MODULE_ENABLE_VTK_RenderingExternal` turned on. Disabled by default. +* `F3D_MODULE_OCCT`: Support for STEP and IGES file formats. Requires `OpenCASCADE`. Disabled by default. +* `F3D_MODULE_ASSIMP`: Support for FBX, DAE, OFF and DXF file formats. Requires `Assimp`. Disabled by default. +* `F3D_MODULE_ALEMBIC`: Support for ABC file format. Requires `Alembic`. Disabled by default. +* `F3D_BINDINGS_PYTHON`: Generate python bindings (requires `Python` and `pybind11`). Disabled by default. +* `F3D_BINDINGS_JAVA`: Generate java bindings (requires `Java` and `JNI`). Disabled by default. diff --git a/doc/dev/CODING_STYLE.md b/doc/dev/CODING_STYLE.md new file mode 100644 index 0000000000..24358d6643 --- /dev/null +++ b/doc/dev/CODING_STYLE.md @@ -0,0 +1,58 @@ +--- +layout: default +title: Coding Style +parent: Developer Documentation +nav_order: 4 +--- + +# F3D Coding Style + +F3D use different coding styles in each component, however there are some common rules + +## Common rules + +Overall syntax: + - CamelCase. + - Avoid using `using`. + - Initialize variables in header when possible. + - Local variables starts with a lower case char. + - Class members starts with a upper case char. + - Indents are two spaces. + - One space between instruction and parenthesis. + - Always add curly brace after instruction. + - Curly brace one a new line, aligned with instruction. + - Add `//----------------------------------------------------------------------------` before any method in implementation. + +Example: + +```cpp +//---------------------------------------------------------------------------- +void class::method() +{ + if (condition) + { + std::vector myIntVector = {13}; + } +} +``` + +Includes: + - Organized by category: `F3DApplication`, `libf3d`, `VTKExtensions`, `other deps`, `std`, `system`. + - Sorted inside category. + +## F3D Application rules + +- Class starts with `F3D` +- Method starts with an uppercase char. + +## libf3d rules + +- Class starts with a lower case char. +- Method starts with an lower case char. + +## VTKExtensions rules + +- Follow VTK rules +- Method starts with an uppercase char. +- Class starts with `vtk` if inheriting from vtkObject. +- Class starts with `F3D` if not inheriting from vtkObject. diff --git a/doc/dev/CONTRIBUTE.md b/doc/dev/CONTRIBUTE.md new file mode 100644 index 0000000000..e4f5397a12 --- /dev/null +++ b/doc/dev/CONTRIBUTE.md @@ -0,0 +1,61 @@ +--- +layout: default +title: Contribute +parent: Developer Documentation +nav_order: 2 +--- + +# How to contribute + +F3D welcomes all contributors, regardless of skill level or experience! + +## How to get started + +To contribute to F3D, you may want to take a look at the opened [issues](https://github.com/f3d-app/f3d/issues), +especially, the ones with the ["good first issue"](https://github.com/f3d-app/f3d/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) label. +If one sounds interesting to you, then you should just go ahead and comment on the issue and ask for any help or clarification needed. +F3D maintainers will see your comment and provide guidance as needed. +You can also open your own issue or feature request and F3D maintainers will try to help you with it! + +You can then fix the issue in your side and contribute it to the F3D repository, +by following the workflow described below. + +## F3D Development workflow + +F3D uses the [gitlab flow](https://docs.gitlab.com/ee/topics/gitlab_flow.html). In a few words, here is how to contribute: +- [Fork](https://github.com/f3d-app/f3d/fork) F3D repository on github. +- Create and push a feature branch on your fork containing new commits. +- When it is ready for review or when you want to run the CI, create a pull request against `f3d-app/f3d/master`. +- Once the PR is approved and CI comes back clean, a F3D maintainer will merge your pull request in the master branch +- The master now contains your changes and will be present in the next release! + +## Continuous Integration + +F3D has a pretty extensive continuous integration trying to cover all usecases for F3D. +It means that if your change break the CI in your PR, it will not be merged until the breaking change are adressed. +It also means that adding a new feature or behavior means adding a associated test. +Make sure to check the results for yourself, and ask for help if needed. + +F3D continuous integration will also check the coverage as it is a good way to evaluate if new features are being tested or not. +When adding code to F3D, always to to cover it by adding/modifying [tests](TESTING.md). + +F3D continuous integration also check formatting using clang-format and will inform you if changes needs to be made. +However, some [formatting rules](CODING_STYLE.md) are not enforced by clang-format and will be checked during the review process. + +## F3D architecture + +F3D is seperated in three main components: +- The F3D application, in the application folder. +- The libf3d, in the library folder. +- The VTKExtensions in the library/VTKExtensions folder. + +VTKExtensions are separated in different modules. +- Core, that do not depend on any other VTKExtensions modules are provide services for all modules +- Readers, that depends on Core and implements many new VTK readers and importers +- Rendering, that depends on Core and implements the rendering specificities of F3D +- Applicative, the depends on all other VTKExtension modules and provide services for the libf3d library + +The libf3d implements the whole logic of instancing and manipulating the different VTK classes, it is fully documented [here](../libf3d/README.md). + +The F3D application itself uses the libf3d but adds an applicative layer on top of it, especially the handling of [command line options](../OPTIONS.md) +and [configuration file](../CONFIGURATION_FILE.md). diff --git a/doc/dev/GENERATE.md b/doc/dev/GENERATE.md new file mode 100644 index 0000000000..dcdd3e46ee --- /dev/null +++ b/doc/dev/GENERATE.md @@ -0,0 +1,31 @@ +--- +layout: default +title: Generate +parent: Developer Documentation +nav_order: 3 +--- + +# How to generate the full coverage report + +Requires `gcovr` program and `gcc` toolchain. + +1. Build with `F3D_COVERAGE` option enabled. +2. Run all tests. +3. Generate the report with: `gcovr -r /path/to/sources --html --html-details -o coverage.html`. + +# How to build and test with sanitizer + +Requires `clang` toolchain. + +1. Build with `F3D_SANITIZER` option to any of the possible values. +2. `export LSAN_OPTIONS=suppressions=/path/to/f3d/.lsan.supp:use_tls=0`. +3. `export TSAN_OPTIONS=suppressions=/path/to/f3d/.tsan.supp`. +4. Run all tests. + +# How to locally generate the jekyll based website + +1. Install `ruby` and make sure ruby binaries directory is added to your `PATH` +2. Install jekyll and all dependencies: `gem install jekyll jekyll-remote-theme jekyll-relative-links jekyll-seo-tag` +3. Run jekyll locally: `jekyll server` + +Please note the favicon and search bar are not working locally, this is expected. diff --git a/doc/dev/README.md b/doc/dev/README.md new file mode 100644 index 0000000000..5d8e61d487 --- /dev/null +++ b/doc/dev/README.md @@ -0,0 +1,13 @@ +--- +layout: default +title: Developer Documentation +nav_order: 4 +has_children: true +has_toc: false +--- + +# Developer Documentation +- [How to build F3D.](BUILD.md) +- [How to test F3D.](TESTING.md) +- [How to contribute to F3D.](CONTRIBUTE.md) +- [How to Generate coverage and sanitizer report.](GENERATE.md) diff --git a/doc/dev/TESTING.md b/doc/dev/TESTING.md new file mode 100644 index 0000000000..5a775876fd --- /dev/null +++ b/doc/dev/TESTING.md @@ -0,0 +1,108 @@ +--- +layout: default +title: Testing +parent: Developer Documentation +nav_order: 1 +--- + +# Testing in F3D + +F3D has an expansive suite of tests, you may want to run them locally, +either to validate your build or because you are contributing to F3D and want to add/modify a test. + +## CMake Options + +There is a few CMake options to enable when configuring F3D with testing: +* `BUILD_TESTING`: Enable the tests, enable this one. +* `F3D_ENABLE_LONG_TIMEOUT_TESTS`: Certain tests can take a bit longer to run, hence they are disabled by default, you may want to enable this one. +* `F3D_DISABLE_DEFAULT_LIGHTS_TESTS_COMPARISON`: With VTK < 9.0.0, rendering can be very different, although not incorrect, so this option is provided, you may want to keep this one disabled + +## Running the tests + +To run the tests, just use ctest from the build directory: + +``` +ctest +``` + +To run a specific test, use the -R ctest option: + +``` +ctest -R PLY +``` + +## Testing architecture + +There is multiple layers of tests to ensure F3D test coverage is as high as possible + - Application layer + - Library layer + - Bindings layer + - VTK Extension layer + +When contributing to F3D, it is necessary that any new code is covered by at least one layer +of test, but it could make sense to cover it with more if necessary. + +### Application layer + +All application test are just a command line runned by ctest using the `f3d` executable. +ctest then check the output for any failure. Most of these tests are just using the `--output` +and `--ref` F3D option in order to check if a rendering behave correctly with specific options. + +Everything is handled in `cmake/testing.cmake`. + +Usually, adding a test is a simple as adding a line like this one: + +``` +f3d_test(NAME TestName DATA datafile.ext ARGS --args-to-test DEFAULT_LIGHTS) +``` + + - `NAME` should be the name of the test, which must be unique + - `DATA` should be a file in `testing/data` directory, though adding new file is possible + - `ARGS` should be the F3D options to pass to the f3d executable, if any + - `DEFAULT_LIGHTS` is expected when performing baselines comparison + +Once the new test has been added, configure and build F3D, then run the test once: + +``` +ctest -R TestName +``` + +The test will fail but an image output will be generated in you build in `Testing/Temporary/TestName.png`. +Visually check that the generated file looks as expected, then add it to the F3D sources in `testing/baselines`. +Rerun the test, it should now pass. + +### Library layer + +When for some reason adding a test in the application layer is not possible, it is possible +to add a C++ test in the library layer. These tests are simple C++ methods that should return +`EXIT_SUCCESS` or `EXIT_FAILURE`. + +Everything is handled in `src/library/testing`. + +To add a test, create a new `TestName.cxx` file containing a `int TestName(int argc, char* argv[])` method, +then implement your test in C++ using the [libf3d](../libf3d/README.md) API. +Then add you new file to `src/library/testing/CMakeLists.txt`. + +It is supported to read file as input and perform image comparison against baselines as an output, see other tests as examples. + +### Bindings layer + +The libf3d supports multiple bindings, including Java and Python. + +When improving/modifying these bindings, it is necessary to also improve/modify the bindings tests accordingly. +Please take a look into `src//testing` for examples to follow. + +### VTKExtensions layer + +When for some reason adding a test in the application or library layer is not possible, it is possible +to add a C++ test in the VTKExtensions layer. These tests are simple C++ methods that should return +`EXIT_SUCESS` or `EXIT_FAILURE`. + +Everything is handled in `src/library/VTKExtensions/ModuleName/Testing`. + +To add a test, first identify which VTKExtensions module you need to add a test into, +then create a new `TestName.cxx` file containing a `int TestName(int argc, char* argv[])` method, +then implement your test in C++ using VTK and F3D VTKExtensions modules. +Then add you new file to `src/library/VTKExtensions/ModuleName/Testing/CMakeLists.txt`. + +It is supported to read file as input if needed, see other tests as examples. diff --git a/doc/libf3d/BINDINGS.md b/doc/libf3d/BINDINGS.md new file mode 100644 index 0000000000..d0454f3ba7 --- /dev/null +++ b/doc/libf3d/BINDINGS.md @@ -0,0 +1,53 @@ +--- +layout: default +title: Bindings +parent: libf3d Documentation +nav_order: 3 +--- + +# Bindings + +## Python Bindings + +If the python bindings have been generated using the `F3D_BINDINGS_PYTHON` CMake option, the libf3d can be used directly from python. +Make sure to set `PYTHONPATH` to path where the python module is built. +Here is an example showing how to use libf3d python bindings: + +```python +import f3d + +eng = f3d.engine(f3d.window.NATIVE) +eng.getOptions() + .set("model.scivis.array-name", "Normals") + .set("model.scivis.component", 0) + .set("ui.bar", True) + .set("scene.grid", True) + +eng.getLoader().addFile("f3d/testing/data/dragon.vtu").loadFile() +eng.getInteractor().start() +``` + +## Java Bindings + +If the Java bindings have been generated using the `F3D_BINDINGS_JAVA` CMake option, the libf3d can be used directly from Java. +You can import the `f3d.jar` package and use the provided Java classes directly. +Make sure to set `java.library.path` to the path where the JNI library is built. +Here is an example showing how to use libf3d Java bindings: + +```java +import io.github.f3d_app.f3d.*; + +public class F3DExample { + public static void main(String[] args) { + + // Always use try-with-resources idiom to ensure the native engine is released + try (Engine engine = new Engine(Window.Type.NATIVE)) { + Loader loader = engine.getLoader(); + loader.addFile("f3d/testing/data/dragon.vtu"); + loader.loadFile(Loader.LoadFileEnum.LOAD_FIRST); + + engine.getWindow().render(); + } + } +} +``` diff --git a/doc/libf3d/CLASSES.md b/doc/libf3d/CLASSES.md new file mode 100644 index 0000000000..362fcdea4f --- /dev/null +++ b/doc/libf3d/CLASSES.md @@ -0,0 +1,58 @@ +--- +layout: default +title: Class listing +parent: libf3d Documentation +nav_order: 1 +--- + +# Class Listing + +## Engine class + +The engine class is the main class that needs to be instantiated. All other classes instance are provided by the engine using getters, `getLoader`, `getWindow`, `getInteractor`, `getOptions`. + +The engine constructor lets you choose the type of window in its constructor, `NONE`, `NATIVE`, `NATIVE_OFFSCREEN`, `EXTERNAL`. Default is `NATIVE`. See [Window class](window-class) documentation for more info. Please note that the engine will not provide a interactor with `NONE` and `EXTERNAL`. + +## Loader class + +The loader class is responsible to read and load the file from the disk. It supports reading multiple files and even folders. + +## Window class + +The window class is responsible for rendering the meshes. It supports multiple modes. + +* `NONE`: A window that will not render anything, very practical when only trying to recover meta-information about the data. + +* `NATIVE`: Default mode where a window is shown onscreen using native graphical capabilities. + +* `NATIVE_OFFSCREEN`: Use native graphical capabilities for rendering, but unto an offscreen window, which will not appear on screen, practical when generating screenshots. + +* `EXTERNAL`: A window where the OpenGL context is not created but assumed to have been created externally. To be used with other frameworks like Qt or GLFW. + +Window lets you `render`, `renderToImage` and control other parameters of the window, like icon or windowName. + +## Interactor class + +When provided by the engine, the interactor class lets you choose how to interact with the data. + +It contains the animation API to start and stop animation. + +Interactor also lets you set your interaction callbacks in order to modify how the interaction with the data is done. + +Of course, you can use `start` and `stop` to control the interactor behavior. + +## Camera class + +Provided by the window, this class lets you control the camera. You can either specify the camera position, target, and up direction directly, or specify movements relative to the current camera state. + +## Image class + +A generic image class that can either be created from a window, from an image filepath or even from a data buffer. It supports comparison making it very practical in testing context. + +## Log class + +A class to control logging in the libf3d. Simple using the different dedicated methods (`print`, `debug`, `info`, `warn`, `error`) and `setVerboseLevel`, you can easily control what to display. Please note that, on windows, a dedicated output window may be created. + +## Options class + +This class lets you control the behavior of the libf3d. An option is basically a string used as a key associated with a value, see the exhaustive [list](OPTIONS.md). diff --git a/doc/libf3d/OPTIONS.md b/doc/libf3d/OPTIONS.md new file mode 100644 index 0000000000..45ee43d84a --- /dev/null +++ b/doc/libf3d/OPTIONS.md @@ -0,0 +1,91 @@ +--- +layout: default +title: Options +parent: libf3d Documentation +nav_order: 2 +--- + +# Options exhaustive list + +An option is a string used as a key associated with a value, which are stored in an `options` instance. +The possible option are listed below and are organized by categories and subcategories, here is a non-exhaustive explanation of the categories. + + * `scene` options are related to how the scene is being displayed + * `render` options are related to the way the render is done + * `render.effect` options are related to specific techniques used that modify the render + * `ui` options are related to the screenspace UI element displayed + * `model` options are related to modifications on the model, they are only meaningful when using the default scene + * `interactor` options requires an interactor to be present to have any effect. + +Please note certain options are taken into account when rendering, others when loading a file. +See the exhaustive list below, but note that this may change in the future. + +## Scene Options + +Option|Type
Default
Trigger|Description|F3D option +:---:|:---:|:---|:---: +scene.animation.index|int
0
load|Select the animation to load.
Any negative value means all animations.
The default scene always has at most one animation.|\-\-animation-index +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.geometry-only|bool
false
load|For certain **full scene** file formats (gltf/glb and obj),
reads *only the geometry* from the file and use default scene construction instead.|\-\-geometry-only +scene.up-direction|string
+Y
load|Define the Up direction|\-\-up +scene.grid|bool
false
render|Show *a grid* aligned with the XZ plane.|\-\-grid +scene.background.blur|bool
false
render|Blur background when using a HDRI.|\-\-blur-background +scene.background.color|vector\
0.2,0.2,0.2
render|Set the window *background color*.
Ignored if *hdri* is set.|\-\-bg-color +scene.background.hdri|string
-
render|Set the *HDRI* image used to create the environment.
The environment act as a light source and is reflected on the material.
Valid file format are hdr, png, jpg, pnm, tiff, bmp. Override the color.|\-\-hdri + +## 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.color.opacity|double
1.0
load|Set *opacity* on the geometry. Usually used with Depth Peeling option. Multiplied with the `model.color.texture` when present.|\-\-opacity +model.color.rgb|vector\
1.0,1.0,1.0
load|Set a *color* on the geometry. Multiplied with the `model.color.texture` when present.|\-\-color +model.color.texture|string
-
load|Path to a texture file that sets the color of the object. Will be mulitplied with rgb and opacity.|\-\-texture-base-color +model.emissive.factor|vector\
1.0,1.0,1.0
load| Multiply the emissive color when an emissive texture is present.|\-\-emissive-factor +model.emissive.texture|string
-
load|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
load|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
load|Set the *roughness coefficient* on the geometry (0.0-1.0). Multiplied with the `model.material.texture` when present.|\-\-roughness +model.material.texture|string
-
load|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
load|Normal scale affects the strength of the normal deviation from the normal texture.|\-\-normal-scale +model.normal.texture|string
-
load|Path to a texture file that sets the normal map of the object.|\-\-texrture-normal +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.range|vector\
-
render|Set a *custom range for the coloring*.|\-\-range + +## Render Options + +Option|Type
Default
Trigger|Description|F3D option +:---:|:---:|:---|:---: +render.effect.depth-peeling|bool
false
render|Enable *depth peeling*. This is a technique used to correctly render translucent objects.|\-\-depth-peeling +render.effect.fxaa|bool
false
render|Enable *Fast Approximate Anti-Aliasing*. This technique is used to reduce aliasing.|\-\-fxaa +render.effect.ssao|bool
false
render|Enable *Screen-Space Ambient Occlusion*. This is a technique used to improve the depth perception of the object.|\-\-ssao +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.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.point-sprites.enabled|bool
false
render|Show sphere *points sprites* instead of the geometry.|\-\-point-sprites +render.volume.enabled|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 +render.volume.inverse|bool
false
render|Inverse the linear opacity function.|\-\-inverse +render.raytracing.denoise|bool
false
render|*Denoise* the raytracing rendering.|\-\-denoise +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 + +## UI Options + +Option|Type
Default
Trigger|Description|F3D option +:---:|:---:|:---|:---: +ui.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 *name of the file*.|\-\-filename +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.metadata|bool
false
render|Display the *metadata*.|\-\-metadata diff --git a/doc/libf3d/OVERVIEW.md b/doc/libf3d/OVERVIEW.md new file mode 100644 index 0000000000..bf870e9657 --- /dev/null +++ b/doc/libf3d/OVERVIEW.md @@ -0,0 +1,89 @@ +--- +layout: default +title: Overview +parent: libf3d Documentation +nav_order: 0 +--- + +# libf3d - A library to render 3D meshes + +By Michael Migliore and Mathieu Westphal. + +libf3d is a BSD-licensed C++ library to open and render 3D meshes. It is of course used by F3D. +libf3d API is simple and easy to learn. Python bindings are provided through pybind11. Java bindings are also available. +libf3d API is still in alpha version and may change drastically in the future. + +## Getting Started + +Rendering a file and starting the interaction is very easy: + +```cpp +#include +#include +#include + +// Create a f3d::engine +f3d::engine eng(); + +// Add a file to the loader and load it +eng.getLoader().addFile("path/to/file.ext").loadFile(); + +// Start rendering and interacting +eng.getInteractor().start(); +``` + +Manipulating the window directly can be done this way: + +```cpp +#include +#include +#include +#include + +// Create a f3d::engine +f3d::engine eng(f3d::window::Type::NATIVE_OFFSCREEN); + +// Add a file to the loader and load it +eng.getLoader().addFile("path/to/file.ext").loadFile(); + +// Set the window size and render to an image +f3d::image img = eng.getWindow().setSize(300, 300).renderToImage(); + +// Save the image to a file +img.save("/path/to/img.png"); +``` + +Changing some options can be done this way: + +```cpp +#include +#include +#include +#include + +// Create a f3d::engine +f3d::engine eng(); + +// Recover the options and set the wanted value +eng.getOptions() + .set("render.effect.ssao", true) + .set("render.effect.fxaa", true); + +// Standard libf3d usage +eng.getLoader().addFile("path/to/file.ext").loadFile(); +eng.getInteractor().start(); +``` +Most options are dynamic, some are only taken into account when loading a file. See the [options](OPTIONS.md) documentation. + +For more advanced usage, please take a look in the [testing directory](https://github.com/f3d-app/f3d/tree/master/library/testing). + +## Building against the libf3d + +Please follow instructions in the [F3D build guide](../dev/BUILD.md), then use CMake to find the libf3d +and link against it like this in your CMakeLists.txt: + +```cmake +find_package(f3d REQUIRED) +[...] +target_link_libraries(target f3d::libf3d) +``` diff --git a/doc/libf3d/README.md b/doc/libf3d/README.md new file mode 100644 index 0000000000..97e478ae71 --- /dev/null +++ b/doc/libf3d/README.md @@ -0,0 +1,13 @@ +--- +layout: default +title: libf3d Documentation +nav_order: 3 +has_children: true +has_toc: false +--- + +# libf3d Documentation +- [Overview of the libf3d.](OVERVIEW.md) +- [libf3d class listing.](CLASSES.md) +- [Exhaustive list of libf3d options.](OPTIONS.md) +- [How to use libf3d bindings.](BINDINGS.md) diff --git a/resources/logo.bmp b/resources/logo.bmp deleted file mode 100644 index 5099b9bb44..0000000000 Binary files a/resources/logo.bmp and /dev/null differ diff --git a/testing/data/small.dae b/testing/data/small.dae new file mode 100644 index 0000000000..1965b55017 --- /dev/null +++ b/testing/data/small.dae @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:44f79c768c37132c84028414a04c0ceaa44b19e75ce1888fed2bbe0ecc34b443 +size 3692