Using Docker to Simplify the VTK WASM Build Process

Are you a C++ developer looking to bring the Visualization Toolkit (VTK) to web applications? As many of you know, transforming a complex C++ library like VTK to compile with WebAssembly (WASM) is a tedious and time-consuming process. The good news is that we’ve made it easier so that you can use pre-built VTK.wasm libraries from a Docker image.

The vtk-wasm-sdk Docker image is a self-contained version of the VTK C++ library, already compiled with the Emscripten toolchain for both WASM32, and WASM64 architectures. This means you can skip the long process and jump straight into building your application code.

This is the third post in a blog series about VTK WASM . This series is part of a larger effort to describe recent innovation efforts in the VTK project. Here is the introduction to the series, along with the first and second WASM posts.)

What’s in the image?

The SDK image provides a neatly organized file structure, making it easy to find what you need:
Essential build tools for WASM are situated under the /opt directory and can be built as follows:

C:\dev> docker run --rm -it kitware/vtk-wasm-sdk:latest /bin/bash
root@7b4e26743ebe:/work# ls /opt
cmake  ninja  node

The /VTK-install/Release subdirectory has all libraries for all four supported wasm architectures organized under wasm32, wasm32-threads, wasm64, or wasm64-threads. Note that besides the 32- and 64-bit variants, threading is available which supports VTK SMP Tools with the STDThread backend.

root@7b4e26743ebe:/work# ls /VTK-install/Release
wasm32  wasm32-threads  wasm64  wasm64-threads
root@7b4e26743ebe:/work# ls /VTK-install/Release/wasm32
bin  include  lib  share
root@7b4e26743ebe:/work# ls /VTK-install/Release/wasm64
bin  include  lib  share
root@7b4e26743ebe:/work# ls /VTK-install/Release/wasm32-threads
bin  include  lib  share
root@7b4e26743ebe:/work# ls /VTK-install/Release/wasm64-threads
bin  include  lib  share

The Emscripten SDK is organized under /emsdk.

root@7b4e26743ebe:/work# ls /emsdk -l
total 200
-rw-r--r-- 1 root root   1326 Jun  7 00:16 LICENSE
drwxr-xr-x 2 root root   4096 Jun  7 00:16 docker
drwxr-xr-x 2 root root   4096 Jun  7 00:17 downloads
-rw-r--r-- 1 root root  16051 Jun  7 00:16 emscripten-releases-tags.json
-rwxr-xr-x 1 root root   1221 Jun  7 00:16 emsdk
-rw-r--r-- 1 root root 114791 Jun  7 00:16 emsdk.py
-rw-r--r-- 1 root root   1977 Jun  7 00:16 emsdk_env.sh
-rw-r--r-- 1 root root  17912 Jun  7 00:16 emsdk_manifest.json
-rw-r--r-- 1 root root     25 Jun  7 00:17 hello.c
-rw-r--r-- 1 root root    562 Jun  7 00:17 hello.o
-rw-r--r-- 1 root root    659 Jun  7 00:16 legacy-binaryen-tags.txt
-rw-r--r-- 1 root root   1190 Jun  7 00:16 legacy-emscripten-tags.txt
-rw-r--r-- 1 root root   2380 Jun  7 00:16 llvm-tags-64bit.txt
drwxr-xr-x 3 root root   4096 Jun  7 00:17 node
drwxr-xr-x 5 root root   4096 Jun  7 00:17 upstream

A Quickstart Guide to Using the SDK

To see how easy it is to use this vtk-wasm-sdk, we’ll work through the existing VTK C++ GeometryViewer example from the VTK repository. Upon completion, you will have produced an application similar to this which will appear something like the image below.

1. Get the source code: Start by downloading the example code.

$ curl -L --output GeometryViewer.zip "https://gitlab.kitware.com/vtk/vtk/-/archive/master/vtk-master.zip?path=Examples/Emscripten/Cxx/GeometryViewer"

$ unzip -j GeometryViewer.zip -d GeometryViewer

2. Configure with CMake: Using the vtk-wasm-sdk docker image, you can configure the GeometryViewer project with this command.

$ docker run \
  --rm \
  -v"$PWD"/work:/work \
  kitware/vtk-wasm-sdk \
  emcmake cmake -S /work -B /work/build -DCMAKE_BUILD_TYPE=Release -DVTK_DIR=/VTK-install/Release/wasm64/lib/cmake/vtk

This command invokes emcmake cmake inside the container, configuring your build. Let’s break down the key parts of the command:

• docker run --rm: Runs the command in a container and removes the container after it’s done.
• -v “$PWD”/work:/work: Mounts your local GeometryViewer directory into the container. This is crucial as it allows the container to access your source code.
• kitware/vtk-wasm-sdk: Specifies the Docker image to use.

Note the -DVTK_DIR=/VTK-install/* argument to CMake, it tells the GeometryViewer project where the VTK library can be found.

3. Build with CMake: Then, you can build it with this command.

$ docker run \
  --rm \
  -v"$PWD"/work:/work \
  kitware/vtk-wasm-sdk \
  cmake --build /GeometryViewer/build

4. Run it! Finally, serve the build directory and see your WASM application.

$ python3 -m http.server -d ./build

Now, open http://localhost:8000 in your web browser and click on the Choose file button on the top right corner to open your own .vtk, .vtu, or .vtp VTK input data files.

Conclusion

In this blog, we saw how using the Docker vtk-wasm-sdk eliminates the most challenging parts of bringing VTK to the web. We began with C++ source code, and produced a running browser app in just a few minutes! The process is designed to simplify the build process, allowing developers and users to focus on creating incredible visualizations and applications.

Acknowledgments

VTK is a creative work produced from an extended community. Refer to VTK’s GitLab repository for a detailed capture of contributions and enhancements. Research reported in this publication was supported by the National Institute Of Biomedical Imaging And Bioengineering of the National Institutes of Health under Award Number R01EB014955. The content is solely the responsibility of the authors and does not necessarily represent the official views of the National Institutes of Health.