Merge pull request #9 from jspanchu/add-cpp-examples

Add cpp examples and update news

Author: jspanchu

.gitignore

@@ -1,3 +1,5 @@
 node_modules
 docs/.vitepress/dist
-docs/.vitepress/cache
+docs/.vitepress/cache
+examples/cpp/vtk
+examples/cpp/*/build

docs/guide/cpp/app-1.md

@@ -1 +1,101 @@
-Write the business logic of your application in C++ and wrap a simple interface to JavaScript with Embind.
+In this approach, you'll code an interactive WebAssembly application that responds to user actions, such as moving sliders on the web page using C++! You'll also enable mouse and keyboard interaction, set up an HTML page with a canvas element, and connect this canvas to a `vtkRenderWindow` and `vtkRenderWindowInteractor` for rendering and interaction.
+
+# Write native code in C++
+In the following code, a `vtkConeSource` generates polygonal geometry, which is rendered by a `vtkPolyDataMapper`. We also wrap the C++ functions `void setConeResolution(int)` and `void setConeHeight(double)` to JavaScript and connect them to separate sliders that allow adjusting the cone's resolution and height, respectively.
+
+::: code-group
+<<< ../../../examples/cpp/cone/main.cpp#emscriptenKeepalive{cpp:line-numbers=28} [Directly expose C functions]
+<<< ../../../examples/cpp/cone/main.cpp#embindFunctions{cpp:line-numbers=40} [Bind C++ functions with embind]
+<<< ../../../examples/cpp/cone/main.cpp#args{cpp:line-numbers=64} [Argument parsing]
+<<< ../../../examples/cpp/cone/main.cpp#vtk{cpp:line-numbers=91} [VTK setup]
+<<< ../../../examples/cpp/cone/main.cpp#bindCanvas{cpp:line-numbers=116} [Bind canvas]
+<<< ../../../examples/cpp/cone/main.cpp#coneSourceLifecycle{cpp:line-numbers=141} [Cleanup globals]
+<<< ../../../examples/cpp/cone/main.cpp#interactor{cpp:line-numbers=158} [Start interactor]
+<<< ../../../examples/cpp/cone/main.cpp{cpp:line-numbers=1} [Full code (main.cpp)]
+:::
+
+Explaination:
+The referenced sections from `../../../examples/cpp/cone/main.cpp` demonstrate the following:
+
+- **Directly expose C functions**
+
+    Native functions which take or return simple C data types can be wrapped conveniently
+    with an `EMSCRIPTEN_KEEPALIVE` macro. This macro makes the function available in JavaScript with a prefix `_`. Here,
+    a C symbol `setConeResolution` becomes `_setConeResolution`.
+
+    ::: warning
+    Symbols that are wrapped using `EMSCRIPTEN_KEEPALIVE` must have C-style linkage (`extern "C"`), otherwise the symbol name will be mangled like `__Z17setConeResolutioni` which is no fun!
+    :::
+
+- **Bind C++ functions with embind**
+
+    You can wrap any C++ function to JavaScript using the `emscripten::function` construct. Member functions of classes can be wrapped with `emscripten::class`. Emscripten does the to and fro conversion for methods that take or return complex types like `std::string`. You can learn more about this style of wrapping at [emscripten.org/docs](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/embind.html).
+
+- **Argument parsing**
+
+    Command-line arguments allow configuration of the application at startup. This is similar to how you would parse arguments in desktop applications. In WASM, arguments are passed via the `arguments` key to the wasm module object.
+
+- **VTK setup**
+
+    Initialize the VTK pipeline by creating a cone source, mapper, actor, renderer, and render window.
+
+- **Bind canvas**
+
+    Connect the HTML canvas element to the VTK render window. This enables rendering output in the browser.
+
+    ::: danger
+    A number of things can go wrong in this step. You will see an error in the console if the binding is performed too late (after a VTK render call), or when the canvas selector has a spelling mistake.
+    ```js
+    vtkWebAssemblyOpenGLRenderWindow (0x1d3c80): Error (0) initializing WebGL2.
+    vtkWebAssemblyOpenGLRenderWindow (0x1d3c80): Failed to create Emscripten opengl context Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'getParameter')
+    at emscriptenWebGLGet (main.js:1:12409402)
+    at _glGetIntegerv (main.js:1:12411165)
+    at 023050d2:0xc1103
+    at 023050d2:0x4d5c4b
+    at 023050d2:0x4a73b9
+    at 023050d2:0x17d647
+    at 023050d2:0x4d3d4a
+    at 023050d2:0x7108c8
+    at callMain (main.js:1:12453949)
+    at doRun (main.js:1:12454368)
+    ```
+    :::
+
+- **Cleanup globals**
+
+    We ensure that global objects are cleaned up when the interactor gets deleted by doing cleanup in a callback function that observes the `DeleteEvent` on the render window interactor. This application uses globals
+    so that wrapped functions like `setConeResolution` and `render` can access the `vtkConeSource` object and `vtkRenderWindow` object respectively.
+
+- **Start interactor**
+
+    Sets up and starts the VTK render window interactor, enabling mouse and keyboard interaction with the rendered scene.
+
+The full code combines these steps to create a minimal interactive 3D visualization in the browser using VTK, C++, and Embind.
+
+# Interface to the web with HTML
+The HTML provides a canvas with `id` "vtk-wasm-canvas". It also passes the resolution of cone and the canvas selector argument strings to the main wasm program using the `arguments` key in the `Module` dictionary.
+The `main.js` script is generated by emscripten. It checks whether a variable named `Module` is defined in the global scope and imports the configuration like program arguments, canvas, etc from the `Module` object.
+UI callbacks can access the wasm module using the `Module` variable.
+
+::: code-group
+<<< ../../public/demo/cpp-app-1/index.html{html:line-numbers=1} [Full HTML (index.html)]
+:::
+
+
+::: tip
+You can also use the `-sMODULARIZE` + `-sEXPORT_NAME=createModule` emscripten link options which offer a different approach to instantiating
+the wasm runtime.
+That approach lets you call a function `createModule({...options})` that returns a Promise resolving with a handle to the wasm runtime.
+See [emscripten.org/docs](https://emscripten.org/docs/tools_reference/settings_reference.html#modularize) for more information.
+:::
+
+# Build system
+Finally, the CMake code creates a WASM executable by compiling the C++ source code and linking with VTK libraries.
+
+::: code-group
+<<< ../../../examples/cpp/cone/CMakeLists.txt{cmake:line-numbers=1} [Full CMake (CMakeLists.txt)]
+:::
+
+## Result
+
+<iframe src="/vtk-wasm/demo/cpp-app-1/index.html" style="width: 100%; height: 40vh; border: none;"></iframe>

docs/news.md

@@ -1,26 +1,239 @@
-## Latest updated
+## VTK 9.5 is out
+
+__June 24, 2025__
+
+The [9.5.0 release](https://www.kitware.com/vtk-9-5-0/) includes many improvments regarding the integration of WASM. In addition to observing VTK objects on the client side, you can also invoke methods on VTK objects. This enables us to implement client/server calls for handling picking with client side objects. The other hidden improvement is related to the increased number of vtk objects available in WASM which should help in reproducing more complex VTK scene more accurately.
+
+You can install the equivalent python wheel with the command
+
+```sh
+pip install "vtk==9.5.0" --extra-index-url https://wheels.vtk.org
+```
+
+The WASM bundle is available here:
+
+[vtk-9.5.0-wasm32-emscripten.tar.gz](https://gitlab.kitware.com/vtk/vtk/-/package_files/5327/download)
+
+## Fix serialization for RenderingAnnotation module
+
+__June 23, 2025__
+
+See [vtk/vtk!12192](https://gitlab.kitware.com/vtk/vtk/-/merge_requests/12192)
+- Fix deserialization of `vtkAlgorithm` inputs
+- Fix serialization of `vtkDataSetMapper` inputs
+- Enables (de)serialization of necessary indexed properties in _RenderingAnnotation_
+- Fix (de)serialization of `vtkLabelPlacementMapper` and `vtkLabelHierarchy`
+
+## Add serialization for vtkGraph and ViewsInfovis module
+
+__June 23, 2025__
+
+See [vtk/vtk!12199](https://gitlab.kitware.com/vtk/vtk/-/merge_requests/12199)
+
+- Added manual (de)serialization helper for `vtkGraph`
+- Enable auto serialization for subclasses of `vtkGraph`
+- Enable serialization in _ViewsInfovis_
+    - Expose relevant properties, exclude redundant ones
+- Serialize child items in vtkContextTransform
+    - Cannot do this in `vtkAbstractContextItem` since some subclasses (like `vtkDendrogramItem`) add items to themselves, leading to extra child items after deserialization and errors when rendering those child items.
+- A few unrelated serialization fixes (`vtkFramebufferPass`, `vtkMapperCollection`)
+
+## 9.5.20250621 is now available!
+__June 21, 2025__
+
+You can install the equivalent python wheel with the command
+
+```sh
+pip install "vtk==9.5.20250621.dev0" --extra-index-url https://wheels.vtk.org
+```
+
+The WASM bundle is available here:
+
+1. [vtk-9.5.20250621-wasm32-emscripten.tar.gz](https://gitlab.kitware.com/vtk/vtk/-/package_files/5329/download)
+2. [vtk-9.5.20250621-wasm64-emscripten.tar.gz](https://gitlab.kitware.com/vtk/vtk/-/package_files/5328/download)
+
+## 9.5.20250614 is now available!
+__June 14, 2025__
+
+You can install the equivalent python wheel with the command
 
-Clipping planes on mapper is now supported. Which allow us to implement that demo in plain client side.
+```sh
+pip install "vtk==9.5.20250614.dev0" --extra-index-url https://wheels.vtk.org
+```
+
+The WASM bundle is available here:
+
+1. [vtk-9.5.20250614-wasm32-emscripten.tar.gz](https://gitlab.kitware.com/vtk/vtk/-/package_files/5323/download)
+2. [vtk-9.5.20250614-wasm64-emscripten.tar.gz](https://gitlab.kitware.com/vtk/vtk/-/package_files/5322/download)
+
+## 9.5.20250607 is now available!
+__June 7, 2025__
+
+You can install the equivalent python wheel with the command
+
+```sh
+pip install "vtk==9.5.20250607.dev0" --extra-index-url https://wheels.vtk.org
+```
+
+The WASM bundle is available here:
+
+1. [vtk-9.5.20250607-wasm32-emscripten.tar.gz](https://gitlab.kitware.com/vtk/vtk/-/package_files/5261/download)
+2. [vtk-9.5.20250607-wasm64-emscripten.tar.gz](https://gitlab.kitware.com/vtk/vtk/-/package_files/5262/download)
+
+## Clipping planes in WASM/WebGL
+
+__June 6, 2025__
+
+Clipping planes on mapper is now supported by [vtk/vtk!12176](https://gitlab.kitware.com/vtk/vtk/-/merge_requests/12176). This allow us to implement the TIE fighter clip plane demo in client side. 
 
 <iframe src="/vtk-wasm/demo/viewer-starfighter2.html" height="592" width="100%" frameborder="0" allowfullscreen="" title="Rendering clipping"></iframe>
 
-## Add support for 32 and 64 bits WASM bundle
+## Fix serialization for 3D widgets
+
+__June 5, 2025__
+
+- [vtk/vtk!12162](https://gitlab.kitware.com/vtk/vtk/-/merge_requests/12162) fixes serialization errors of classes
+in the _InteractionWidgets_ module.
+- Enable auto serialization for `vtkResliceCursorRepresentation`, `vtkDistanceRepresentation`, `vtkTextRepresentation`, and related classes.
+
+## Fix serialization of various classes
+
+__June 4, 2025__
+
+- [vtk/vtk!12167] fixed serialization for various classes and enables serialization for more classes in the _ImagingCore_, _ImagingColor_, _RenderingGridAxes_, and the _RenderingImage_ modules.
+- The `vtkSignedCharArray` class now has serialization enabled.
+- The redundant width/height properties of vtkActor2D are now excluded from (de)serialization.
+
+## 9.5.20250531 is now available!
+
+__May 31, 2025__
+
+You can install the equivalent python wheel with the command
+
+```sh
+pip install "vtk==9.5.20250531.dev0" --extra-index-url https://wheels.vtk.org
+```
+
+The WASM bundle is available here:
 
-....
+1. [vtk-9.5.20250531-wasm32-emscripten.tar.gz](https://gitlab.kitware.com/vtk/vtk/-/package_files/5198/download)
+2. [vtk-9.5.20250531-wasm64-emscripten.tar.gz](https://gitlab.kitware.com/vtk/vtk/-/package_files/5197/download)
+
+
+## Add get/set functions in vtkRemoteSession
+
+__May 27, 2025__
+
+`vtkRemoteSession::getState` is deprecated in favor of `vtkRemoteSession::get`. The new `vtkRemoteSession::set` lets you
+apply properties from JSON in bulk on a VTK object. See [vtrk/vtk!12155](https://gitlab.kitware.com/vtk/vtk/-/merge_requests/12155)
 
 ## Add runtime support for WebGL2 and WebGPU
 
+__May 24, 2025__
+
 You can now choose the backend to use for rendering your VTK scene. The WebGPU is still work in progress but is now available for testing via runtime configuration option.
 
-## Helper JavaScript library
+WebGPU classes in VTK are now serialized and available in the vtkWebAssemblyAsync.{mjs,wasm} files. Subsequent packages will distribute both vtkWebAssemblyAsync.{mjs,wasm} and vtkWebAssembly.{mjs,wasm} files. The async package will only work in browsers that enable JavaScript Promise Integration ([JSPI](https://github.com/WebAssembly/js-promise-integration)). See [vtk/vtk!12143](https://gitlab.kitware.com/vtk/vtk/-/merge_requests/12143)
 
-A new JavaScript library is available under `@kitware/trame-vtklocal` which delivers a set of helper tools for VTK.wasm and JavaScript.
-This include a standalone viewer for a VTK scene dump, a wrapper for pure JavaScript usage and some core handler when creating a widget (i.e. React, Svelt, Angular...) for interating with a trame-vtklocal server implementation.
+## Fix serialization for RenderingVolume module
 
-## API refactor with remote and standalone capabilities
+__May 27, 2025__
 
-bla
+[vtk/vtk!12142] fixes serialization errors that arise when serializing classes in the _RenderingVolume_ module.
 
-## VTK 9.5 is out
+## Add standalone and remote session API
+
+__May 19, 2025__
+
+The `vtkWebAssembly.mjs` library now provides two new classes `vtkRemoteSession` and `vtkStandaloneSession`.
+- Remote session API is concerned with use cases where a "server" creates VTK
+ objects and sends the state to a WASM "client" that deserializes the state
+ into objects to mimic the visualization pipeline on the "server".
+ This API does not allow creating objects in the WASM world. It is possible,
+ although very difficult and prone to bugs.
+
+- Standalone API is important when one wants to directly create and manipulate objects
+ in the local context in the absence of a server. 
+
+See [vtk/vtk!12110](https://gitlab.kitware.com/vtk/vtk/-/merge_requests/12110)
+
+## Fix vtkFieldData deserialization when no. of arrays is the same but some or all individual arrays have changed
+
+__May 19, 2025__
+
+[vtk/vtk!12129](https://gitlab.kitware.com/vtk/vtk/-/merge_requests/12129) fixed a bug where the arrays had their values updated only when the total number of arrays in the vtkFieldData changed between deserializations. Now, it always update the array list because even though the number of arrays remain the same, the arrays themselves might be different.
+
+## Add support for 32 and 64 bits WASM bundle
+
+__May 14, 2025__
+
+Build and distribute artifacts for wasm64. This package allows rendering large meshes bigger than 4GB. It requires a web browser that supports 64-bit wasm memories.
+
+## 9.5.20250513 is now available!
+__May 13, 2025__
 
-The 9.5 release includes many improvment regarding the integration of WASM. With this new release, on top of observing VTK objects on the client side, you can also perform methods call. This enables us to implement some client/server calls for handling picking with client side resolution. The other hidden improvement is related to the increased number of vtk objects available in WASM which should help in reproducing more complex VTK scene more accurately.
+You can install the equivalent python wheel with the command
+
+```sh
+pip install "vtk==-9.5.20250513-wa" --extra-index-url https://wheels.vtk.org
+```
+
+The WASM bundle is available here:
+
+[vtk-9.5.20250513-wasm32-emscripten.tar.gz](https://gitlab.kitware.com/vtk/vtk/-/package_files/5101/download)
+
+## 9.5.20250510 is now available!
+__May 10, 2025__
+
+You can install the equivalent python wheel with the command
+
+```sh
+pip install "vtk==-9.5.20250510-wa" --extra-index-url https://wheels.vtk.org
+```
+
+The WASM bundle is available here:
+
+[vtk-9.5.20250510-wasm32-emscripten.tar.gz](https://gitlab.kitware.com/vtk/vtk/-/package_files/5067/download)
+
+## Add serialization for pickers
+
+__May 5, 2025__
+
+[vtk/vtk!12095](https://gitlab.kitware.com/vtk/vtk/-/merge_requests/12095) enables auto serialization for pickers in the _RenderingCore_ module, as well as `vtkAssemblyNode`, `vtkAssemblyPath`, and `vtkProp3DCollection` for properties of certain pickers. 
+
+## Fix serialization of VTK classes
+
+__April 25, 2025__
+
+Many serialization issues were fixed in [vtk/vtk!12012](https://gitlab.kitware.com/vtk/vtk/-/merge_requests/12012). Serialization capability was also added to some classes. Here's a list of classes
+that were affected:
+
+- vtkActor2D
+- vtkBitArray
+- vtkDataArray
+- vtkDiscretizableColorTransferFunction
+- vtkFieldData
+- vtkInformation
+- vtkLabeledContourMapper
+- vtkLogLookupTable
+- vtkMultiBlockDataSet
+- vtkOpenGLLabeledContourMapper
+- vtkPolyDataMapper2D
+- vtkProp3DFollower
+- vtkProperty
+- vtkRenderWindow
+- vtkScalarsToColors
+- vtkShaderProperty
+- vtkStructuredGrid
+- vtkTextPropertyCollection
+- vtkTexture
+- vtkVariant
+- vtkVariantArray
+- vtkWindow
+
+## Helper JavaScript library
+
+__October 7, 2024__
+
+A new JavaScript library is available under `@kitware/trame-vtklocal` which delivers a set of helper tools for VTK.wasm and JavaScript.
+This include a standalone viewer for a VTK scene dump, a wrapper for pure JavaScript usage and some core handler when creating a widget (i.e. React, Svelt, Angular...) for interating with a trame-vtklocal server implementation.

docs/public/demo/cpp-app-1/index.html

@@ -0,0 +1,29 @@
+<!doctype html>
+<html>
+
+<head>
+  <meta charset="utf-8" />
+</head>
+
+<body>
+  <div>
+    <input type="range" min="3" max="128" value="8" onchange="Module._setConeResolution(this.value); Module.render();"
+      style="position: absolute; top: 1rem; right: 1rem; z-index: 10;" />
+    <input type="range" min="1.0" max="2.0" value="1.0" step="0.1" onchange="Module.setConeHeight(this.value); Module.render();"
+      style="position: absolute; top: 1rem; left: 1rem; z-index: 10;" />
+  </div>
+  <canvas id="vtk-wasm-canvas" tabindex="-1" onclick="focus()"></canvas>
+  <script type="text/javascript">
+    var Module = {
+      arguments: [
+        "--resolution", "8",
+        "--canvas-selector", "#vtk-wasm-canvas"],
+      canvas: () => {
+        return document.querySelector("#vtk-wasm-canvas");
+      },
+    };
+  </script>
+  <script type="text/javascript" src="./main.js"></script>
+</body>
+
+</html>