trame-vtklocal 0.16.4

License

This library is OpenSource and follow the Apache Software License

Installation

# to install VTK yourself
pip install trame-vtklocal

# for the latest VTK capabilities
pip install "vtk>=9.6" --pre --index-url https://wheels.vtk.org

Development

Build and install the Vue components

cd vue-components
npm i
npm run build
cd -

Install the library

# Create venv and install all dependencies
uv sync --all-extras --dev

# Activate environment
source .venv/bin/activate

# Install commit analysis
pre-commit install
pre-commit install --hook-type commit-msg

# Allow live code edit
uv pip install -e .

Optionally, you can develop with bleeding edge VTK by following these steps. Make sure you’ve these tools

1. git

2. CMake

3. Ninja

4. Python

5. NodeJS >= 24.0.1: https://nodejs.org/en/download/package-manager

6. Emscripten SDK version 4.0.10: See https://emscripten.org/docs/getting_started/downloads.html#download-and-install

# Compile VTK for wasm32 architecture using emscripten. Build artifacts can be found in dev/vtk/build/wasm
python ./utils/build_vtk.py -u https://gitlab.kitware.com/vtk/vtk.git -b master -t wasm32 -c RelWithDebInfo

# Compile VTK with python wrappings using system C++ compiler. Build artifacts can be found in dev/vtk/build/py
python ./utils/build_vtk.py -u https://gitlab.kitware.com/vtk/vtk.git -b master -t py -c RelWithDebInfo

# Windows: Set environment variables
./utils/dev_environment.ps1 -b master -c RelWithDebInfo

# Unix: Set environment variables
source ./utils/dev_environment.sh -b master -c RelWithDebInfo

Running examples

pip install trame "trame-vtklocal[vtk]" trame-vuetify trame-vtk

# regular trame app
python ./examples/vtk/cone.py

Some example are meant to test and validate WASM rendering. Some will default for remote rendering but if you want to force them to use WASM just run export USE_WASM=1 before executing them.

Progress events

The client-side VtkLocal component emits a progress event while wasm sync is happening. This can be used to keep a global loader visible until the first sync completes.

from trame.widgets import vtklocal, vuetify

state.app_loading = True
state._vtklocal_seen_active = False

def on_vtklocal_progress(event):
    if event.get("active"):
        state._vtklocal_seen_active = True
        state.app_loading = True
    elif state._vtklocal_seen_active:
        state.app_loading = False

with vuetify.VOverlay(v_model=("app_loading",), absolute=True):
    vuetify.VProgressCircular(indeterminate=True, size=64)

view = vtklocal.LocalView(
    render_window,
    progress=(on_vtklocal_progress, "[$event]"),
)

If you are using the Vue component directly, you can override the built-in loader with the loader slot.

<vtk-local>
  <template #loader="{ progress, wasmLoading, statePercent, hashPercent }">
    <div v-if="wasmLoading">Loading wasm...</div>
    <div v-else>
      States: {{ progress.state.current }}/{{ progress.state.total }}
      Blobs: {{ progress.hash.current }}/{{ progress.hash.total }}
    </div>
  </template>
</vtk-local>

SharedArrayBuffer

To enable SharedArrayBuffer within trame you can just set the following on the server. This option is not required anymore but still available if needed.

server.http_headers.shared_array_buffer = True

This will download the threaded WASM version. Otherwise, the non-threaded version will be used as it does not require SharedArrayBuffer.

VTK.wasm vs trame-vtklocal

This repository trame-vtklocal focus on providing a web component that is capable of mirroring a vtkRenderWindow defined on the server side. This include a JavaScript section for the browser and a Python section for the server.

The server include a definition of a custom network protocol over our WebSocket (wslink/trame) and some helper class to ease the vtkRenderWindow binding with a web component in the browser. While the Python package include a Vue.js component for a seamless integration with trame, we also publish a npm package. That pure JavaScript library let you still use the trame infrastructure on the server side but with your own stack on the client side. A usage example of that pure JavaScript option is covered in that directory.

For the pure Python trame usage, you can find the documented API.

By design there is a nice separation between VTK.wasm and trame-vtklocal which should make trame-vtklocal fairly independent of VTK.wasm version. But since we are still building capabilities, when the C++ API expend, we will also expand the Python/JavaScript component properties/methods. Hopefully we should be able to evolve trame-vtklocal with some reasonable fallback when the version of VTK is not in par with what is exposed in trame-vtklocal.

Also most the testing of VTK.wasm is in VTK repository as many validation can be done in pure C++ or Python. Then we have the WASM module API with its node/chrome testing.

The documented API of vtkWasmSceneManager and vtkObjectManager parent of vtkWasmSceneManager

For the moment we rely on manual testing for when we change the network and/or API at the trame-vtklocal by going over a specific set of examples.

Currently the WASM implementation is used in the following set of projects:

• Pan3D: Pan3D aims to be an utility package for viewing and processing a wide variety of multidimensional datasets. Any dataset that can be interpreted with xarray can be explored and rendered with Pan3D.

Professional Support

• Training: Learn how to confidently use trame from the expert developers at Kitware.

• Support: Our experts can assist your team as you build your web application and establish in-house expertise.

• Custom Development: Leverage Kitware’s 25+ years of experience to quickly build your web application.