ITK Sphinx Examples Part II: WebGL Visualizations


This is the second in a series of articles that describes how Sphinx has been extended to create a powerful example documentation system, the ITK Sphinx Examples.

For previous posts, see

Part I: Credits via GitStats

WebGL is quickly becoming a standard for 3D, GPU-accelerated, pluginless, browser-based visualizations. In this post, we will describe how WebGL visualizations were added to the ITK Sphinx Examples.


The Insight Toolkit (ITK) is intended for analysis instead of visualization, so we generate the visualizations with other tools whose purpose is visualization, like the Visualization Toolkit (VTK) or ParaView. Using the VTKWeb capabilities available in VTK 6.1, a PolyData visualization can be generated with a simple Python script. Or, a WebGL visualization can be generated with Paraview by clicking File -> Export Scene -> WEBGL files.

The resulting HTML file with embedded data is easiest to archive. The file is self-contained and only requires a static web server to serve interactive 3D files. Since the visualization is self contained, including data, it can be relatively large, so we use the CMake ExternalData system to store a content link in the Git repository. 

Browser Support Check

Since not all hardware or browsers support WebGL yet, we want the website to fallback gracefully when these features are not available and send an informative message to the reader. We wrote a little Javascript that will detect when WebGL is not supported by the current browser or by current video drivers.  It will then modify and expose a helpful note in the Sphinx layout template when not available.


To embed the content, we use an iframe HTML element with the raw:: html reStructuredText directive. 

.. raw:: html

  <div class="figure">
    <iframe src="InputMesh.html" width="200" height="225" seamless></iframe>
    <p class="caption">Interactive input mesh</p>

An example visualization iframe (may not work in all browsers):

Enjoy ITKExamples!

Questions or comments are always welcome!