Repository: f3d-app/f3d
Pull request #2022: Add an architecture documentation
Author: login: mwestphal
Created: 2025-02-28T08:04:46Z | Merged: 2025-03-03T08:34:53Z

Add an architecture documentation.
Also update plugins documentation.

Fix: https://github.com/f3d-app/f3d/issues/1887


Diff:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 04ee463652..653c7f9375 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -28,6 +28,8 @@ To get involved more deeply, please take a look at the [roadmaps](doc/dev/ROADMA
 
 It is also recommended to reach out on [Discord](https://discord.f3d.app) to simplify communication, but it is not required.
 
+You may also want to understand the overall [architecture](doc/dev/ARCHITECTURE.md) of the F3D project.
+
 You can then fix the issue or implement the feature on your side and contribute it to the F3D repository by following the workflow described below.
 
 Of course, if you are already using F3D and want to improve it for your specific needs, because you want a feature or found a bug,
diff --git a/_config.yml b/_config.yml
index 0e27ad0d93..720edf36c0 100644
--- a/_config.yml
+++ b/_config.yml
@@ -267,13 +267,21 @@ defaults:
       parent: Developer Documentation
       nav_order: 4
 
+  -
+    scope:
+      path: "doc/dev/ARCHITECTURE.md"
+    values:
+      title: Architecture
+      parent: Developer Documentation
+      nav_order: 5
+
   -
     scope:
       path: "doc/dev/CODING_STYLE.md"
     values:
       title: Coding style
       parent: Developer Documentation
-      nav_order: 5
+      nav_order: 6
 
   -
     scope:
@@ -281,7 +289,7 @@ defaults:
     values:
       title: Roadmaps and release cycle
       parent: Developer Documentation
-      nav_order: 6
+      nav_order: 7
 
   -
     scope:
@@ -289,7 +297,7 @@ defaults:
     values:
       title: Governance
       parent: Developer Documentation
-      nav_order: 7
+      nav_order: 8
 
   -
     scope:
@@ -297,7 +305,7 @@ defaults:
     values:
       title: Maintainers
       parent: Developer Documentation
-      nav_order: 8
+      nav_order: 9
 
   -
     scope:
@@ -305,7 +313,7 @@ defaults:
     values:
       title: Code of conduct
       parent: Developer Documentation
-      nav_order: 9
+      nav_order: 10
 
   -
     scope:
@@ -313,7 +321,7 @@ defaults:
     values:
       title: Build (WebAssembly)
       parent: Developer Documentation
-      nav_order: 10
+      nav_order: 11
 
 # Licenses doc
 # _licenses.md uses front matter      
diff --git a/doc/dev/ARCHITECTURE.md b/doc/dev/ARCHITECTURE.md
new file mode 100644
index 0000000000..61f31bff39
--- /dev/null
+++ b/doc/dev/ARCHITECTURE.md
@@ -0,0 +1,68 @@
+# F3D Architecture
+
+F3D is structured in different parts, interacting with each others and with F3D dependencies.
+This architecture is reflected by the directories organisation.
+
+- **application**: the code of the F3D application itself, see below
+- cmake: cmake macros and functions, used by the CMake build system
+- doc: this very documentation
+- examples: examples usage of the libf3d and plugin framework in python and C++
+- external: dependencies that are included directly in the code
+- java: [java bindings](../libf3d/LANGUAGE_BINDINGS.md#java-experimental) and associated tests.
+- **library**: the [libf3d](../libf3d/README_LIBF3D.md) itself, see below
+- **plugins**: all the [plugins](../libf3d/PLUGINS.md) providing different readers, see below
+- python: [python bindings](../libf3d/LANGUAGE_BINDINGS.md#python) and tests
+- resources: all non code, non doc, like icon, configs and such
+- testing: all testing related resources, does not contain the test themselves
+- **vtkext**: extensions to VTK and related tests, see below
+- webassembly: [webassembly/javascript bindings](../libf3d/LANGUAGE_BINDINGS.md#javascript-experimental) and [F3DWeb](https://f3d.app/web/) application code
+- winshellext: shell extension for Windows, provide [thumbnails for Windows](../user/DESKTOP_INTEGRATION.md#windows)
+
+Here is diagram explaining how some of these parts interact together:
+
+<img src="https://media.githubusercontent.com/media/f3d-app/f3d-media/c43c1367a2aac4c9a3bdd478bdac3ffefe82750e/media/archi.png" width="700">
+
+## vtkext
+
+`vtkext` contains two [VTK modules](https://docs.vtk.org/en/latest/api/cmake/ModuleSystem.html) that are used extensively in the libf3d. The public one is used in the plugins.
+
+`public` is a VTK module that contains classes and utilities that can be installed as part of the `plugin_sdk` and used by plugins, including externals plugins. `vtkF3DImporter` is a class
+that is specifically made for plugin developers to inherit their importers from. The documentation of this module can be found [here](https://f3d.app/doc/libf3d/vtkext_doxygen/).
+
+`private` is a VTK module that contains many classes and utilities used by the libf3d to provide all features of F3D, especially the rendering, interactions and UI.
+A notable class is `vtkF3DRenderer` that is responsible to actually add the different actors in the 3D scene.
+
+Each of these modules also contains [tests](TESTING.md#vtkextensions-layer) in the `Testing` directory.
+
+## plugins
+
+`plugins` contains [libf3d plugins](../libf3d/PLUGINS.md) that are provided by default in the F3D packages. Each of these plugins correspond to a specific dependency and are named accordingly. Each of these plugins provide access to specific readers for specific formats. Without plugins, F3D and the libf3d would not be able to open any file. These plugins can be loaded statically or dynamically, which makes the dependencies truly optional if needed.
+
+## library
+
+`library` contains the code of the libf3d. It is a C++ library with a very limited API surface and larger, private, implementation.
+Most classes in the libf3d are split in two. A public part that contains mostly the public API, and a private part, suffixed "\_impl", that implements that public API
+and also contains hidden methods used to communicate between classes, especially in regards to VTK symbols.
+
+Logically, it is structured in 3 parts, `public` which contains the public API header files and are all installed, `private` which contains the implementation classes headers files and `src` that contains the source files of all the classes, public and private.
+
+There is also a dedicated `testing` directory which contains the [unit and functional testing](TESTING.md#library-layer) of the libf3d.
+
+It also contains the `options.json` file, which is the file used to generate all [options](../libf3d/OPTIONS.md) code.
+
+## application
+
+`application` contains the code of the F3D application itself. It relies of course on the libf3d to implement all the applicative logic.
+The most important class in the `F3DStarter` which contains most of the top logic on the application. `F3DOptionsTools` is also notable as it handles most of
+the command line options logic.
+
+There is also a dedicated `testing` directory which contains all of the [applicative testing](TESTING.md#application-layer) of the F3D application as well as many functional testing of the libf3d.
+
+## Other f3d-app repositories
+
+Although almost everything is contained in the [f3d-app/f3d](https://github.com/f3d-app/f3d) repository, other repositories in the [f3d-app](https://github.com/f3d-app) organisation are handling certains specific tasks in the F3D ecosystem.
+
+- The [f3d-superbuild](https://github.com/f3d-app/f3d-superbuild) handles the packaging and the creation of the binaries provided in the [releases page](https://github.com/f3d-app/f3d/releases).
+- [f3d-media](https://github.com/f3d-app/f3d-media) backups all images and video used in this documentation
+- A collection of actions: [sccache-setup](https://github.com/f3d-app/sccache-setup-action), [lfs-data-cache](https://github.com/f3d-app/lfs-data-cache-action) and [install-mesa-windows](https://github.com/f3d-app/install-mesa-windows-action) used by the CI of F3D
+- A collection of [docker files](https://github.com/f3d-app/f3d-docker-images) used for generating docker images used by the CI of F3D
diff --git a/doc/dev/README_DEV.md b/doc/dev/README_DEV.md
index 99ca0eb2e3..21108d6a86 100644
--- a/doc/dev/README_DEV.md
+++ b/doc/dev/README_DEV.md
@@ -5,6 +5,7 @@
 - [How to test F3D.](TESTING.md)
 - [How to contribute to F3D.](../../CONTRIBUTING.md)
 - [How to Generate coverage and sanitizer report.](GENERATE.md)
+- [Overview of the architecture of F3D.](ARCHITECTURE.md)
 - [Coding Style.](CODING_STYLE.md)
 - [Roadmaps and release cycle.](ROADMAPS_AND_RELEASES.md)
 - [Governance.](GOVERNANCE.md)
diff --git a/doc/libf3d/PLUGINS.md b/doc/libf3d/PLUGINS.md
index d6e945e9f3..94888f32af 100644
--- a/doc/libf3d/PLUGINS.md
+++ b/doc/libf3d/PLUGINS.md
@@ -10,7 +10,7 @@ You will then be able to call `find_package(f3d REQUIRED COMPONENTS pluginsdk)`
 
 You can take a look at the example in the [examples/plugin](https://github.com/f3d-app/f3d/tree/master/examples/plugins) directory or at the official [plugins](https://github.com/f3d-app/f3d/tree/master/plugins).
 
-The first thing (and most difficult part) you have to do is creating a VTK reader (or a VTK importer if you want to support a full scene with materials, lights and cameras), and wrap it into a VTK module. You can create several readers in the same VTK module if you need to support several file formats in a single plugin.
+The first thing (and most difficult part) you have to do is creating a VTK reader (or a VTK importer if you want to support a full scene with materials, lights and cameras), and wrap it into a VTK module. You can create several readers/importers in the same VTK module if you need to support several file formats in a single plugin.
 
 Then, declare the reader(s) and the plugin using the CMake macros:
 
@@ -21,11 +21,20 @@ f3d_plugin_declare_reader(
   NAME "ReaderName"
   EXTENSIONS "myext"                # set the extensions the reader can support
   MIMETYPES "application/vnd.myext" # set the mimetypes the reader can support
-  VTK_READER ${vtk_classname}       # set the name of the VTK class you have created
-  DESCRIPTION "Reader description"  # set the description of the reader
+  VTK_READER ${vtk_classname}       # set the name of the VTK reader class you have created
+  FORMAT_DESCRIPTION "description"  # set the proper name of the file format
   EXCLUDE_FROM_THUMBNAILER          # add this flag if you don't want thumbnail generation for this reader
 )
 
+f3d_plugin_declare_reader(
+  NAME "ReaderNameWithScene"
+  EXTENSIONS "myext2"                # set the extensions the reader can support
+  MIMETYPES "application/vnd.myext2" # set the mimetypes the reader can support
+  VTK_IMPORTER ${vtk_classname}      # set the name of the VTK importer class you have created
+  FORMAT_DESCRIPTION "description"   # set the proper name of the file format
+  CUSTOM_CODE "file.inl"             # set this to add a custom code when instancing your class
+)
+
 # More f3d_plugin_declare_reader calls are possible
 
 f3d_plugin_build(


Reviews:
user: login: Meakk
state: CHANGES_REQUESTED
author_association: MEMBER
submitted_at: 2025-03-02T09:17:54Z
user: login: mwestphal
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-02T09:40:56Z
user: login: Meakk
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-02T20:52:28Z

Review comments:
diff_hunk: @@ -0,0 +1,68 @@
+# F3D Architecture
+
+F3D is structured in different parts, interacting with each others and with F3D dependencies.
+This architecture is reflected by the directories organisation.
+
+- **application**: the code of the F3D application itself, see below
+- cmake: cmake macros and functions, used by the CMake build system
+- doc: this very documentation
+- examples: examples usage of the libf3d and plugin framework in python and C++
+- external: dependencies that are included directly in the code
+- java: [java bindings](../libf3d/LANGUAGE_BINDINGS.md#java-experimental) and associated tests.
+- **library**: the [libf3d](../libf3d/README_LIBF3D.md) itself, see below
+- **plugins**: all the [plugins](../libf3d/PLUGINS.md) providing different readers, see below
+- python: [python bindings](../libf3d/LANGUAGE_BINDINGS.md#python) and tests
+- resources: all non code, non doc, like icon, configs and such
+- testing: all testing related resources, does not contain the test themselves
+- **vtkext**: extensions to VTK and related tests, see below
+- webassembly: [webassembly/javascript bindings](../libf3d/LANGUAGE_BINDINGS.md#javascript-experimental) and [F3DWeb](https://f3d.app/web/) application code
+- winshellext: shell extension for Windows, provide [thumbnails for Windows](../user/DESKTOP_INTEGRATION.md#windows)
+
+Here is diagram explaining how some of these parts interact together:
+
+<img src="https://media.githubusercontent.com/media/f3d-app/f3d-media/c43c1367a2aac4c9a3bdd478bdac3ffefe82750e/media/archi.png" width="700">
path: doc/dev/ARCHITECTURE.md
user: login: Meakk
body: nice diagram :)
created_at: 2025-03-02T09:14:15Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,68 @@
+# F3D Architecture
+
+F3D is structured in different parts, interacting with each others and with F3D dependencies.
+This architecture is reflected by the directories organisation.
+
+- **application**: the code of the F3D application itself, see below
+- cmake: cmake macros and functions, used by the CMake build system
+- doc: this very documentation
+- examples: examples usage of the libf3d and plugin framework in python and C++
+- external: dependencies that are included directly in the code
+- java: [java bindings](../libf3d/LANGUAGE_BINDINGS.md#java-experimental) and associated tests.
+- **library**: the [libf3d](../libf3d/README_LIBF3D.md) itself, see below
+- **plugins**: all the [plugins](../libf3d/PLUGINS.md) providing different readers, see below
+- python: [python bindings](../libf3d/LANGUAGE_BINDINGS.md#python) and tests
+- resources: all non code, non doc, like icon, configs and such
+- testing: all testing related resources, does not contain the test themselves
+- **vtkext**: extensions to VTK and related tests, see below
+- webassembly: [webassembly/javascript bindings](../libf3d/LANGUAGE_BINDINGS.md#javascript-experimental) and [F3DWeb](https://f3d.app/web/) application code
+- winshellext: shell extension for Windows, provide [thumbnails for Windows](../user/DESKTOP_INTEGRATION.md#windows)
+
+Here is diagram explaining how some of these parts interact together:
+
+<img src="https://media.githubusercontent.com/media/f3d-app/f3d-media/c43c1367a2aac4c9a3bdd478bdac3ffefe82750e/media/archi.png" width="700">
+
+## vtkext
+
+`vtkext` contains two [VTK modules](https://docs.vtk.org/en/latest/api/cmake/ModuleSystem.html) that are used extensively in the libf3d and the plugins.
path: doc/dev/ARCHITECTURE.md
user: login: Meakk
body: ```suggestion
`vtkext` contains two [VTK modules](https://docs.vtk.org/en/latest/api/cmake/ModuleSystem.html) that are used extensively in the libf3d. The public one is used in the plugins.
```
created_at: 2025-03-02T09:15:04Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,68 @@
+# F3D Architecture
+
+F3D is structured in different parts, interacting with each others and with F3D dependencies.
+This architecture is reflected by the directories organisation.
+
+- **application**: the code of the F3D application itself, see below
+- cmake: cmake macros and functions, used by the CMake build system
+- doc: this very documentation
+- examples: examples usage of the libf3d and plugin framework in python and C++
+- external: dependencies that are included directly in the code
+- java: [java bindings](../libf3d/LANGUAGE_BINDINGS.md#java-experimental) and associated tests.
+- **library**: the [libf3d](../libf3d/README_LIBF3D.md) itself, see below
+- **plugins**: all the [plugins](../libf3d/PLUGINS.md) providing different readers, see below
+- python: [python bindings](../libf3d/LANGUAGE_BINDINGS.md#python) and tests
+- resources: all non code, non doc, like icon, configs and such
+- testing: all testing related resources, does not contain the test themselves
+- **vtkext**: extensions to VTK and related tests, see below
+- webassembly: [webassembly/javascript bindings](../libf3d/LANGUAGE_BINDINGS.md#javascript-experimental) and [F3DWeb](https://f3d.app/web/) application code
+- winshellext: shell extension for Windows, provide [thumbnails for Windows](../user/DESKTOP_INTEGRATION.md#windows)
+
+Here is diagram explaining how some of these parts interact together:
+
+<img src="https://media.githubusercontent.com/media/f3d-app/f3d-media/c43c1367a2aac4c9a3bdd478bdac3ffefe82750e/media/archi.png" width="700">
+
+## vtkext
+
+`vtkext` contains two [VTK modules](https://docs.vtk.org/en/latest/api/cmake/ModuleSystem.html) that are used extensively in the libf3d and the plugins.
+
+`public` is a VTK module that contains classes and utilities that can be installed and used by plugins, including externals plugins. `vtkF3DImporter` is a class
path: doc/dev/ARCHITECTURE.md
user: login: Meakk
body: Please specify the public is part of the SDK, but the private one is not.
created_at: 2025-03-02T09:15:54Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,68 @@
+# F3D Architecture
+
+F3D is structured in different parts, interacting with each others and with F3D dependencies.
+This architecture is reflected by the directories organisation.
+
+- **application**: the code of the F3D application itself, see below
+- cmake: cmake macros and functions, used by the CMake build system
+- doc: this very documentation
+- examples: examples usage of the libf3d and plugin framework in python and C++
+- external: dependencies that are included directly in the code
+- java: [java bindings](../libf3d/LANGUAGE_BINDINGS.md#java-experimental) and associated tests.
+- **library**: the [libf3d](../libf3d/README_LIBF3D.md) itself, see below
+- **plugins**: all the [plugins](../libf3d/PLUGINS.md) providing different readers, see below
+- python: [python bindings](../libf3d/LANGUAGE_BINDINGS.md#python) and tests
+- resources: all non code, non doc, like icon, configs and such
+- testing: all testing related resources, does not contain the test themselves
+- **vtkext**: extensions to VTK and related tests, see below
+- webassembly: [webassembly/javascript bindings](../libf3d/LANGUAGE_BINDINGS.md#javascript-experimental) and [F3DWeb](https://f3d.app/web/) application code
+- winshellext: shell extension for Windows, provide [thumbnails for Windows](../user/DESKTOP_INTEGRATION.md#windows)
+
+Here is diagram explaining how some of these parts interact together:
+
+<img src="https://media.githubusercontent.com/media/f3d-app/f3d-media/c43c1367a2aac4c9a3bdd478bdac3ffefe82750e/media/archi.png" width="700">
+
+## vtkext
+
+`vtkext` contains two [VTK modules](https://docs.vtk.org/en/latest/api/cmake/ModuleSystem.html) that are used extensively in the libf3d and the plugins.
+
+`public` is a VTK module that contains classes and utilities that can be installed and used by plugins, including externals plugins. `vtkF3DImporter` is a class
path: doc/dev/ARCHITECTURE.md
user: login: mwestphal
body: add a mention of `plugin_sdk` but im not sure this is what you had in mind
created_at: 2025-03-02T09:40:56Z
author_association: MEMBER

PR comments:
user: login: mwestphal
created_at: 2025-03-02T07:46:54Z
body: ![image](https://github.com/user-attachments/assets/e80a70f7-51d4-4828-b11b-71b4ed738544)

author_association: MEMBER
user: login: codecov[bot]
created_at: 2025-03-02T08:23:52Z
body: ## [Codecov](https://app.codecov.io/gh/f3d-app/f3d/pull/2022?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=f3d-app) Report
All modified and coverable lines are covered by tests :white_check_mark:
> Project coverage is 95.76%. Comparing base [(`2e8383a`)](https://app.codecov.io/gh/f3d-app/f3d/commit/2e8383a57c1da382cfd6e4fa774fb35e58441206?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=f3d-app) to head [(`a5b3501`)](https://app.codecov.io/gh/f3d-app/f3d/commit/a5b350134169bbb417087e4e4761f0b45409df47?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=f3d-app).
> Report is 12 commits behind head on master.

<details><summary>Additional details and impacted files</summary>


```diff
@@            Coverage Diff             @@
##           master    #2022      +/-   ##
==========================================
+ Coverage   95.74%   95.76%   +0.02%     
==========================================
  Files         128      128              
  Lines       10340    10396      +56     
==========================================
+ Hits         9900     9956      +56     
  Misses        440      440              
```

</details>

[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/f3d-app/f3d/pull/2022?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=f3d-app).   
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=f3d-app).

author_association: NONE