This is not feature complete in any sense. The purpose of this PR is to fold in the base changes to include building and linking the new/additional Alembic library/SDK

Once this is confirmed acceptable, additional work on the Alembic feature shall follow.

#138

@mwestphal

Describe the solution you'd like It would be very nice if this app also supports alembic/alembic caches

Describe alternatives you've considered Open the Alembic files in Maya

Additional context

Contribution I am not a developer.

libf3d was introduced in !259 (closed), let's brainstorm a stable API for it.

Tasklist:

libf3d

• [x] Introduce f3d::options: #191
• [x] Refactor F3DLoader and F3D to use f3d::options cleanly
• [x] Introduce f3d::loader and use it
• [x] Introduce f3d::window and use it
• [x] modularize VTK code
• [x] Add unit test for VTK modules : https://github.com/f3d-app/f3d/issues/265
• [x] sanity check call order with window and interactor
• [x] transform F3DLog into f3d::log
• [x] fix #32 by using categories for options
• [x] improve f3d_options by providing initialization methods
• [x] store init value in f3d::options for easier reset ?
• [x] support std::initializer_list to be able to call options.set("color", { 1., 1., 1. });
• [x] add a way to inform user when an options does not exist
• [x] introduce a factory and use it to create classes to hide the private API
• [x] Add SDK test infrastructure
• [x] Adress as many TODOs as possible
• [x] Rework engine for bit flag and init early
• [x] Add SDK tests
• [x] (optional) expand f3d_interactor to support user set behavior for many more context
• [x] add more window types
• [x] improve all classes from f3d namespaces to ensure all santiy checks are done correctly
• [x] unit testing of the API and general coverage improvements
• [x] Add a vtkNoRenderWindow
• [x] modernization of API
• [x] constness of API
• [x] Public Review of the API to anyone willing to help: #351

F3D

• [x] Rework F3DOptions and F3DOptionsParser to interface with f3d::options
• [x] (Optional) introduce f3d::config in libf3d ?
• [x] rewrite F3DStarter from scratch to not depends on VTK

Doc

• [x] In header doc
• [x] example doc
• [x] website doc

Have just started using this software and it saves a whole lot of time finding things as an artist, just curious if there is a way to limit the CPU usage to around 70 percent when generating thumbnails?

Currently, we provide a .tar.gz and a .tar.xz package for Linux.
It's not clear how to use it after extraction to have a better integration with the system.

We need to document the installation steps.
We can also provide a .deb package easily with the CPack generator but we need help for testing.

Documentation is hard to maintain, here is the current state:

• README.md contains the whole user documentation
• GENERATE.md contains some developper oriented documentation
• documentation/* contains a duplicate, segmented and slightly modified version of the README.md
• src/F3DOptions code contains options, hotkeys and examples documentations to be delivered with --help
• man contains documentations generated from --help and --version
• We potentially will have one more version of the doc thanks to #47 There is a few issues with this approach:

1. Generic doc is duplicated two times
2. Options/Hotkeys doc is duplicated three times
3. main README.md is getting very long and hard to read

This should be improved, here is what we need to have:

1. Complete user documentation should be available in a gitlab markdown format from the main README.md
2. Complete user documentation should be available in the webdoc
3. Limit duplication as much as possible

Here is a proposition to fix that:

1. Put only the most esential and nice looking information in the main README.md
2. Link from the main README.md to other logically organized .md files in a dedicated directory (see below for an example organization)
3. Generate webdocumentation .md files during build thanks to cmake custom commands (see below for more info)
4. If adressing #47, generate simple html doc during build OR generate actual web doc during build
5. (Optional) Find a way to generate a .h from the options/hotkeys .md file during build so that it can be used in the --help output (and other usages?)
6. (Optional) Use Pandoc instead of help2man to generate man, relying on generated .md file during build (see expected format here: https://www.pragmaticlinux.com/2021/01/create-a-man-page-for-your-own-program-or-script-with-pandoc/)

Example .md file organization, that could also be used as a webdoc organisation:

- README.md
- doc
-- OPTIONS.md
-- HOTKEYS.md
-- INSTALATION.md
-- USAGE.md
-- BUILD.md (should this go into dev?)
-- CONFIGURATION_FILE.md
-- LIMITATIONS.md
-- TROUBLESHOOTING.md
-- dev
--- GENERATE_WEBDOC.md
--- GENERATE_COVERAGE.md
--- GENERATE_MAN.md
--- DEVELOP.md
- webdoc
...

Differences between README.md and webdoc md files:

• Image paths are differents (could be fixable):

+ ![F3D Logo](./resources/logo.svg) 
- ![F3D Logo](logo.png) 

+ <img src="https://kitware.github.io/F3D/gallery/04-f3d.png"  width="640">
- ![F3D Demo](../gallery/04-f3d.png)

• many nbsp in the webdoc (could be fixable?)

+ Options                         &|Description
- Options|Description                                                                                                                                     

• Internals links are removed (should be fixable)

+ See the coloring cycle section for more info.
- See the [coloring cycle](#Cycling Coloring) section for more info. 

If all slight change are removed, simply symlinking from the webdoc to the doc.md could be a very easy solution to put into place.

1.2.0 Release

• [x] Fix remainings issues:
  • [x] #37
  • [x] #58
  • [x] #73
  • [x] #65
  • [x] #60
• [x] Last fixups: #95
• [x] Update version strings: #96
• [x] Write the changelog
• [x] Last fixups again: #100
• [x] Generate communication images and gifs
• [x] Trigger a CI build
• [x] Download and quickly test Linux artifacts : run, render, drag&drop, thumbnails
• [x] Download and quickly test MacOS artifacts: run, render, drag&drop
• [x] Download and quickly test Windows artifacts: run, render, drag&drop, thumbnails
• [x] Generate google analytics: #105
• [x] Update github-pages branch and check website
• [x] Merge website update: #112
• [x] Cleanup repo
• [x] Tag the commit and push the tag
• [x] merge master into release
• [x] Create release on gitlab with changelog and artifacts
• [x] Update Aur package
• [x] Update Brew package: https://github.com/Homebrew/homebrew-core/pull/90575
• [x] Inform package maintainers
• [x] Inform Assimp team
• [x] Communicate LinkedIn
• [x] Communicate Reddit

Describe the bug f3d-git AUR package fails to build in a clean chroot

System Information:

• OS: Arch Linux
• GPU and GPU driver: N/A

F3D Information https://aur.archlinux.org/packages/f3d-git

Additional context This was found due to a request to add it to Chaotic-AUR: https://github.com/chaotic-aur/packages/issues/1760

Build log after applying a missing dependency via https://github.com/chaotic-aur/interfere/commit/0096f72366a7e695423a3c7bdc7ded8ed47244b8: f3d-git.log

• [x] Update version strings: https://github.com/f3d-app/f3d/pull/368
• [x] Merge master into release: https://github.com/f3d-app/f3d/pull/370 https://github.com/f3d-app/f3d/pull/386
• [x] Write the changelog
• [x] Trigger a CI build: https://github.com/f3d-app/f3d/actions/runs/2925413544
• [x] Check raytracing locally
• [x] Download and test Linux artifacts : run, config, render, drag&drop, thumbnails, exec from file manager, sdk
• [x] Download and test MacOS artifacts: run, config, render, drag&drop
• [x] Download and test Windows artifacts: run, config, render, drag&drop, thumbnails, exec from file manager, sdk
• [x] Update github-pages branch and check website (not needed this time)
• [x] Merge website update (not needed this time)
• [x] Cleanup repo
• [x] Tag the commit and push the tag
• [x] Create release on gitlab with changelog and artifacts
• [x] Update Aur package
• [x] Update Brew package:
• [x] Inform package maintainers
• [x] Communicate Reddit
• [x] Communicate forums (Kronos, blender)
• [x] Communicate VTK (discourse, internal)
• [x] Communicate LinkedIn

This PR adds a --light-intensity option to address problem described in #352.

It is implemented by simply adding a vtkLightKit to the renderer.

Here are some samples using the same model as in previous issue:

f3d 'ROKN Chung Mu.glb' --camera-position 37.3,20.4,61.6 --camera-focal-point -5.5,1.4,6.7 --camera-view-up -0.2,1.0,-0.2 --camera-view-angle 30 --ssao --fxaa --tone-mapping

f3d 'ROKN Chung Mu.glb' --light-intensity=1 --camera-position 37.3,20.4,61.6 --camera-focal-point -5.5,1.4,6.7 --camera-view-up -0.2,1.0,-0.2 --camera-view-angle 30 --ssao --fxaa --tone-mapping --light-intensity=1

f3d 'ROKN Chung Mu.glb' --light-intensity=2 --camera-position 37.3,20.4,61.6 --camera-focal-point -5.5,1.4,6.7 --camera-view-up -0.2,1.0,-0.2 --camera-view-angle 30 --ssao --fxaa --tone-mapping --light-intensity=2

f3d 'ROKN Chung Mu.glb' --light-intensity=4 --camera-position 37.3,20.4,61.6 --camera-focal-point -5.5,1.4,6.7 --camera-view-up -0.2,1.0,-0.2 --camera-view-angle 30 --ssao --fxaa --tone-mapping --light-intensity=4

$ f3d backpack.vti -vmn --range=300,1000 --colormap=0,0,0,0,1,1,1,1
2021-11-22 18:42:59.099 (   4.367s) [           19718]     vtkOpenGLState.cxx:1069  WARN| Error glEnable/Disable1 OpenGL errors detected
  0 : (1282) Invalid operation

 with stack trace of
WARNING: The stack trace will not use advanced capabilities because this is a release build.
0x803f87dd4 : vtksys::SystemInformation::GetProgramStack(int, int) [(libvtksys-9.1.so.1) ???:-1]
0x803f87cae : vtksys::SystemInformation::GetProgramStack(int, int) [(libvtksys-9.1.so.1) ???:-1]
0x801ad3338 : vtkOpenGLState::vtkglColorMask(unsigned char, unsigned char, unsigned char, unsigned char) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x801ad5a63 : vtkOpenGLState::SetEnumState(unsigned int, bool) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x801ad8402 : vtkOpenGLState::vtkglBlitFramebuffer(int, int, int, int, int, int, int, int, unsigned int, unsigned int) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x800983667 : vtkOpenGLGPUVolumeRayCastMapper::vtkInternal::CaptureDepthTexture(vtkRenderer*) [(libvtkRenderingVolumeOpenGL2-9.1.so.1) ???:-1]
0x80098fe95 : vtkOpenGLGPUVolumeRayCastMapper::GPURender(vtkRenderer*, vtkVolume*) [(libvtkRenderingVolumeOpenGL2-9.1.so.1) ???:-1]
0x8020fd9db : vtkGPUVolumeRayCastMapper::Render(vtkRenderer*, vtkVolume*) [(libvtkRenderingVolume-9.1.so.1) ???:-1]
0x8027c65e7 : vtkVolume::RenderVolumetricGeometry(vtkViewport*) [(libvtkRenderingCore-9.1.so.1) ???:-1]
0x80276e101 : vtkProp::RenderFilteredVolumetricGeometry(vtkViewport*, vtkInformation*) [(libvtkRenderingCore-9.1.so.1) ???:-1]
0x8019f57e5 : vtkDefaultPass::RenderFilteredVolumetricGeometry(vtkRenderState const*) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x801b3dc6f : vtkSequencePass::Render(vtkRenderState const*) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x8019d8346 : vtkCameraPass::Render(vtkRenderState const*) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x8019f5e24 : vtkDepthImageProcessingPass::RenderDelegate(vtkRenderState const*, int, int, int, int, vtkOpenGLFramebufferObject*, vtkTextureObject*, vtkTextureObject*) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x801a0acb0 : vtkFramebufferPass::Render(vtkRenderState const*) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x25a691 : _ZNSt3__127__tree_balance_after_insertIPNS_16__tree_node_baseIPvEEEEvT_S5_ [(f3d) ???:-1]
0x801ab701c : vtkOpenGLRenderer::DeviceRender() [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x802797702 : vtkRenderer::Render() [(libvtkRenderingCore-9.1.so.1) ???:-1]
0x8027a8260 : vtkRendererCollection::Render() [(libvtkRenderingCore-9.1.so.1) ???:-1]
0x80278394e : vtkRenderWindow::DoStereoRender() [(libvtkRenderingCore-9.1.so.1) ???:-1]
0x8027837e9 : vtkRenderWindow::Render() [(libvtkRenderingCore-9.1.so.1) ???:-1]
0x801ab5e6b : vtkOpenGLRenderWindow::Render() [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x801b6fa6f : vtkXOpenGLRenderWindow::Render() [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x26edb5 : _ZNSt3__127__tree_balance_after_insertIPNS_16__tree_node_baseIPvEEEEvT_S5_ [(f3d) ???:-1]

2021-11-22 18:42:59.576 (   4.845s) [           19718]     vtkOpenGLState.cxx:1069  WARN| Error glEnable/Disable1 OpenGL errors detected
  0 : (1282) Invalid operation

 with stack trace of
WARNING: The stack trace will not use advanced capabilities because this is a release build.
0x803f87dd4 : vtksys::SystemInformation::GetProgramStack(int, int) [(libvtksys-9.1.so.1) ???:-1]
0x803f87cae : vtksys::SystemInformation::GetProgramStack(int, int) [(libvtksys-9.1.so.1) ???:-1]
0x801ad3338 : vtkOpenGLState::vtkglColorMask(unsigned char, unsigned char, unsigned char, unsigned char) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x801ad5a63 : vtkOpenGLState::SetEnumState(unsigned int, bool) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x801ad8402 : vtkOpenGLState::vtkglBlitFramebuffer(int, int, int, int, int, int, int, int, unsigned int, unsigned int) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x800983667 : vtkOpenGLGPUVolumeRayCastMapper::vtkInternal::CaptureDepthTexture(vtkRenderer*) [(libvtkRenderingVolumeOpenGL2-9.1.so.1) ???:-1]
0x80098fe95 : vtkOpenGLGPUVolumeRayCastMapper::GPURender(vtkRenderer*, vtkVolume*) [(libvtkRenderingVolumeOpenGL2-9.1.so.1) ???:-1]
0x8020fd9db : vtkGPUVolumeRayCastMapper::Render(vtkRenderer*, vtkVolume*) [(libvtkRenderingVolume-9.1.so.1) ???:-1]
0x8027c65e7 : vtkVolume::RenderVolumetricGeometry(vtkViewport*) [(libvtkRenderingCore-9.1.so.1) ???:-1]
0x80276e101 : vtkProp::RenderFilteredVolumetricGeometry(vtkViewport*, vtkInformation*) [(libvtkRenderingCore-9.1.so.1) ???:-1]
0x8019f57e5 : vtkDefaultPass::RenderFilteredVolumetricGeometry(vtkRenderState const*) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x801b3dc6f : vtkSequencePass::Render(vtkRenderState const*) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x8019d8346 : vtkCameraPass::Render(vtkRenderState const*) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x8019f5e24 : vtkDepthImageProcessingPass::RenderDelegate(vtkRenderState const*, int, int, int, int, vtkOpenGLFramebufferObject*, vtkTextureObject*, vtkTextureObject*) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x801a0acb0 : vtkFramebufferPass::Render(vtkRenderState const*) [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x25a691 : _ZNSt3__127__tree_balance_after_insertIPNS_16__tree_node_baseIPvEEEEvT_S5_ [(f3d) ???:-1]
0x801ab701c : vtkOpenGLRenderer::DeviceRender() [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x802797702 : vtkRenderer::Render() [(libvtkRenderingCore-9.1.so.1) ???:-1]
0x8027a8260 : vtkRendererCollection::Render() [(libvtkRenderingCore-9.1.so.1) ???:-1]
0x80278394e : vtkRenderWindow::DoStereoRender() [(libvtkRenderingCore-9.1.so.1) ???:-1]
0x8027837e9 : vtkRenderWindow::Render() [(libvtkRenderingCore-9.1.so.1) ???:-1]
0x801ab5e6b : vtkOpenGLRenderWindow::Render() [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x801b6fa6f : vtkXOpenGLRenderWindow::Render() [(libvtkRenderingOpenGL2-9.1.so.1) ???:-1]
0x802789fa7 : vtkRenderWindowInteractor::Render() [(libvtkRenderingCore-9.1.so.1) ???:-1]
0x801ba7733 : vtkXRenderWindowInteractor::DispatchEvent(_XEvent*) [(libvtkRenderingUI-9.1.so.1) ???:-1]
0x801ba8657 : vtkXRenderWindowInteractor::StartEventLoop() [(libvtkRenderingUI-9.1.so.1) ???:-1]
0x26edc8 : _ZNSt3__127__tree_balance_after_insertIPNS_16__tree_node_baseIPvEEEEvT_S5_ [(f3d) ???:-1]

f3d-1.1.1 vtk-9.1.0 FreeBSD 13

Is your feature request related to a problem? Please describe. The thumbnail manager doesn't work with 32-bit apps like XYplorer

Describe the solution you'd like Compile the 32bit version to include in the F3D installation

• Move plugin.h and reader.h from public to plugin folder. Fix #537
• Plugins have responsibility to install the mimetype XML files, so the xml files have been moved from resources to the plugins folder.

Note that the option to install the mimetypes files have been removed and we know rely on component-specific install using the built-in generated cmake_install.cmake script because xml files installation is EXCLUDE_FROM_ALL.

There is currently only minimal differences between libf3d and F3D in terms of functionality and scope. While this is not a problem in itself it would be nice to have a more library-like, ie. more general-purpose, libf3d to cover more use-cases than just F3D's.

This could be done by mostly moving logic away form the library and into the application and doing some refactoring and API design along the way.

As requested through other channels, here are some [possibly rambling] points about what I think could be helpful improvements to either/both improve the lib and untangle some logic which could help solve some pending issues with the app...

File Loading

Currently the loader handles both loading models form files and managing a list of filenames to navigate between.

The library should only handle the actual loading of the models. Applications based on libf3d, starting with F3D, can handle how to go between multiple files themselves.

The loading API could be reduced to:

• loadModel(filename, options) clear scene, load a model from disk
• loadModel(buffer, options) clear scene, load a model from memory

If technically possible, expanding it to allow loading of multiple models at once would be even better:

• model_id = loadModel(filename, options) load a model from disk, returns an id
• model_id = loadModel(buffer, options) load a model from memory, returns an id
• unloadModel(model_id) unload a loaded model by id
• setModelVisibility(model_id, bool) toggle visibility of a loaded model by id (without unloading it)

Interactions

The library should provide meaningful actions to interact with the current scene independently of any UI bindings.

The actions could be identified/registered by unique key strings (based on the options naming scheme for consistency?) to facilitate later UI bindings.

Examples:

• do_action("render.effect.ssao.toggle") toggle ambient occlusion
• do_action("render.effect.ssao.on") activate ambient occlusion
• do_action("render.effect.ssao.off") deactivate ambient occlusion
• do_action("render.effect.ssao.reset") reset ambient occlusion to default
• do_action("camera.fit") fit camera to scene

Ideally we should expose an action type/object for apps to register their own (eg: std::function<void(interactor_impl::internals*)> would be in line with the current interactor impl), bonus points if plugins can register new actions (no idea if/how that is possible tho).

Calling actions by simple strings with no parameters would make it relatively easy to have configurable keyboard bindings from a configuration file on the app side, eg:

{
  "Q": "render.effect.ssao.toggle",
  "ctrl+Q": "render.effect.ssao.reset",
  "Space": "camera.fit",
}

and wherever the keyboard events are received:

std::stringstream ss;
if (rwi->GetControlKey()) ss << "ctrl+";
if (rwi->GetAltKey()) s << "alt+";
if (rwi->GetShiftKey()) ss << "shift+";
ss << keySym;
const std::string keyCombo = ss.str();

f3d_instance.do_action(keybindings[keyCombo]);

The lib could provide a simple VTK-based events implementation, apps could choose to replace it with their own if needed.

Cheatsheet

Not fully clear on this one but if we had a keybinding -> action_id mapping we should be able to reverse-lookup which key triggers which action and display the cheatsheet accordingly.

It would probably be hard to have a fully dynamically built cheatsheet but having the currently hardcoded one with just the bindings looked-up from the config should be a good start.

Camera positioning

Reworking the model loading logic would ideally cut out any camera manipulation from it.

The library should provide appropriate camera controls that would be called by the application after a file is loaded if appropriate.

Options

Options as a string -> whatever map is already nice and simple. A few minor improvements could be:

• maybe separating dynamic and load-time options?
• sorting out optional vs default-valued options
• having a schema of some sort if we need to be extra fancy?

Discussion

I definitely do not have the authority or knowledge to claim that any of the above is feasible or even objectively desirable.

Please augment or correct (or just plain trash and dismiss if warranted) any of the points or ask for clarification on anything that doesn't make sense.

Is your feature request related to a problem? Please describe. I really like how F3D is set up in its minimal and bloat-free way. The only downside I experienced so far is that libf3d does not expose its rendering pipeline to the client. Sometimes I just have a vtkObject (e.g., vtkUnstructuredGrid or vtkPolyData) which I want to visualize. But if I use F3D as a dependency in my project without changing the source, I can only read a file from disk.

Something as easy as this will satisfy all my needs.

vtkNew<vtkUnstructuredGrid> ug;
// build my ug and then add it to f3d engine
f3d::engine eng;
eng->getRenderer()->addDataSet(ug);

Or maybe there is already a way to achieve this using the plugin? Please advise.

Describe the solution you'd like Expose vktRenderer in the engine so we can use it to add vtkObject from memory.

Describe alternatives you've considered None.

Additional context None.

Contribution Yes, I can contribute.