DEV Community: Matt McCormick

Embed interactive itkwidgets 3D renderings into JupyterLite deployments

Matt McCormick — Wed, 15 Mar 2023 16:05:10 +0000

By: Matt McCormick, Brianna Major, Jeremy Tuloup, Wei Ouyang, Stephen Aylward

Zero-install web applications have transformed the way we consume and deliver software. Browser-based interfaces facilitate rapid discovery, exploration, and universal access.

However, for research software engineers (RSEs), developing traditional software stacks for web applications is not only onerous, but those stacks may limit essential future scalability and may be even more onerous to sustain. A RSE must face difficult questions:

Who is going to pay to keep the servers online?
Who is going to pay to scale the servers for many user or datasets?
When are you going to find the time to learn and keep up-to-date with all the devops knowledge and skills required?
Who is going to maintain the system and address security vulnerabilities as they arise?
How is private data on the server managed and kept secure?

As one of my favorite professors used to say, in cases like this we can look to the advice offered by a wise doctor:

Patient: Oh, Doctor, it hurts badly when I move my knee like this.

Doctor: Stop moving your knee like that!

In some cases, components of the traditional web application software stack are necessary, and some of those components are easier, more scalable, and more sustainable than others. However, for many RSE use cases, we now can create useful web applications while avoiding traditional server-related hardships altogether.

In this tutorial, we will demonstrate how to create a zero-server JupyterLite deployment that embeds interactive 3D renderings into advanced scientific applications, such as for deep learning medical image analysis applications using MONAI.

JupyterLite is a JupyterLab distribution that runs entirely in the browser built from the ground-up using JupyterLab components and extensions. JupyterLite uses a WebAssembly-based distribution of scientific Python called Pyodide.

ITKWidgets provides interactive widgets to visualize images, point sets, and 3D geometry on the web. ITKWidgets is powered by the same WebAssembly technology. It is built on ITK-Wasm and ImJoy, a hybrid computing platform that communicates via symmetrical transparent remote procedure calls. ImJoy and ITKWidgets support browser-based Pyodide communication along with a number of additional server-client communication transport mechanisms.

In this tutorial, we will first demonstrate a zero-server, interactive 3D rendering notebook. Then, we walk through the quick and easy configuration that can be customized to your needs. Let's get started! 🚀

0. Preliminaries

Reproduce the figure below, a rendering of medical imaging volume of an abdominal aortic stent, by running the notebook in your web browser! After the page has loaded, use the standard Shift+Enter keys to execute the Jupyter notebook cells.

Note that unlike other Jupyter deployments, the python code runs on your system instead of a server.

1. Create the JupyterLite environment

To build our sustainable JupyterLite deployment, we will use a Python environment that contains Python packages for:

jupyterlite
imjoy_jupyterlab_extension
Any other JupyterLab federated extensions (JupyterLab 3 extensions) that you want in your JupyterLab deployment.

Create a requirements.txt file with:

jupyterlite[all]==0.1.0b17
imjoy_jupyterlab_extension

And install the packages:

python -m pip install -r ./requirements.txt

See also the related JupyterLite extension addition documentation.

2. Add itkwidgets and other Python packages

Next, we will add itkwidgets, its dependencies, and other Python packages and their dependencies, that we wish to include into the JupyterLite configuration for deployment. These packages, along with the packages available in the Pyodide distribution, will be available in the deployed site.

Create a jupyterlite_config.json file, which specifies the locations of the itkwidgets wheel Python packages. Add other desired packages and their dependencies as follows.

{
    "PipliteAddon": {
        "piplite_urls": [
            "https://files.pythonhosted.org/packages/4c/ee/56f970ca26375176d3e4885f58471a12d5a6794bcefe8ad0ccb8d7158ca3/itkwasm-1.0b82-py3-none-any.whl",
            "https://files.pythonhosted.org/packages/6c/55/c3fc7e2b9671d15f0c0becdcb9fad6c330172988744ad6eaa17b71bace88/imjoy_rpc-0.5.16-py3-none-any.whl",
            "https://files.pythonhosted.org/packages/69/d9/5a6c8af2f4b4f49a809ae316ae4c12937d7dfda4e5b2f9e4167df5f15c0e/imjoy_utils-0.1.2-py3-none-any.whl",
            "https://files.pythonhosted.org/packages/c9/dc/3504845528418aff0b71f4b622bb0e8e12adec2d8f2c1ba21d695b9ac6e6/itkwidgets-1.0a24-py3-none-any.whl",
            "https://files.pythonhosted.org/packages/bb/3e/3667ac685ae83887b874896bcb55584797ba6b52a292df3e4b37736a9610/ngff_zarr-0.1.6-py3-none-any.whl"
        ]
    }
}

You can find links to these URLs by browsing the package on PyPI and copying the link from the Download files page for a package.

For packages that do not have a wheel on PyPI, you can provide one locally by placing them in the pypi/ directory of your JupyterLite configuration. For example, if you want to use a local version of itkwidgets instead of the version on PyPi, you could directly add this dask-image wheel to your pypi/ directory.

$ ls pypi/
pypi/dask_image-2022.9.0-py2.py3-none-any.whl

3. Add notebooks and data

Add notebooks and data you would like available in the deployment in the files/ directory. In this tutorial, we will add a Hello3DWorld.ipynb notebook.

$ ls files/
files/Hello3DWorld.ipynb

In your notebook, install additional packages in the first cell with piplite.

import piplite
await piplite.install(["itkwidgets==1.0a24"])

4. Build and deploy

Build your site with the command:

jupyter lite build

Serve the site locally with python -m http.server --directory ./_output or:

jupyter lite serve

The site can be deployed and shared with free static file hosting services such as GitHub Pages, Netlify, or Fleek.

What's Next

In this post, we learned how to create a scalable, sustainable, zero-server Jupyter deployment that uses ITKWidgets for 3D rendering. In subsequent posts, we will discuss how to create simple, zero-server, custom web applications written in Python with PyScript.

Enjoy ITK!

How to Debug WebAssembly Pipelines in Your Web Browser

Matt McCormick — Wed, 08 Mar 2023 21:45:52 +0000

By: Matt McCormick, Mary Elise Dedicke, Jean-Christophe Fillion-Robin, Will Schroeder

Did you know that your web browser comes bundled with extremely powerful development tools?

Modern web browsers are the foundation of the The Web Platform, a full-featured computing environment. However, full-featured platforms are not useful in and of themselves. A large community of software developers is required to program the applications on a platform that people love. And, effective debugging results in effective programming.

In this tutorial, we will learn how to debug itk-wasm C++ data processing pipelines built to WebAssembly (wasm) with the full-featured graphical debugger built into Chromium-based browsers.

In the following sections, we will first explain how to obtain a useful JavaScript backtrace in Node.js, then debug C++ code built to WebAssembly in a Chromium-based web browser. Let's get started! 🚀

0. Preliminaries

Before starting this tutorial, check out our WASI WebAssembly command line debugging tutorial.

As with the previous tutorial, we will be debugging the following C++ code:

#include <iostream>

int main() {
  std::cout << "Hello debugger world!" << std::endl;

  const char * wasmDetails = "are no longer hidden";

  const int a = 1;
  const int b = 2;
  const auto c = a + b;

  // Simulate a crash.
  abort();
  return 0;
}

The tutorial code provides npm scripts as a convenient way to execute debugging commands, which you may also invoke directly in a command line shell.

1. Node.js Backtrace

When debugging WebAssembly built with the itk-wasm Emscripten toolchain, set the CMAKE_BUILD_TYPE to Debug just like with native binary debug builds.

As with native builds, this build configuration adds debugging symbols, the human-readable names of functions, variables, etc., into the binary. This also adds support for C++ exceptions and retrieving the string name associated with exceptions. Without this itk-wasm instrumentation, a C++ exception will throw an error with an opaque integer value. And, Emscripten JavaScript WebAssembly bindings will not be minified, which facilitates debugging.

When built with the default Release build type:

the JavaScript support code is minified, and difficult to debug:

However, when built with the Debug build type:

you can obtain a useful backtrace:

This is helpful for debugging issues that occur in the Emscripten JavaScript interface. The next section describes how to debug issues inside the Emscripten-generated WebAssembly.

2. Debugging in Chromium-based Browsers

Recent Chromium-based browsers have support for debugging C++ -based WebAssembly in the browser. With a few extra steps described in this section, it is possible to interactively step through and inspect WebAssembly that is compiled with C++ running in the browser.

WebAssembly debugging in DevTools requires a few extra setup steps compared to a default browser installation.

First, install the Chrome WebAssembly Debugging extension.

Next, enable it in DevTools:

In DevTools, click the gear (⚙) icon in the top-right corner.
Go to the Experiments panel.
Select WebAssembly Debugging: Enable DWARF support.

Exit Settings, then reload DevTools as prompted.

Next, open the options for the Chrome WebAssembly Debugging extension:

Since itk-wasm builds in a clean Docker environment, the debugging source paths in the Docker environment are different from the paths on the host system. The debugging extension has a path substitution system that can account for these differences. In the Docker image, the directory where itk-wasm is invoked is mounted as /work. Substitute /work with the directory where the itk-wasm CLI is invoked. For example, if itk-wasm was invoked at /home/matt/src/itk-wasm/examples/Debugging, then set the path substitution as shown below:

Build the project with itk-wasm and the Debug CMAKE_BUILD_TYPE to include DWARF debugging information:

Here we load and run the WebAssembly with a simple HTML file and server:

<html>
  <head>
    <script src="https://cdn.jsdelivr.net/npm/itk-wasm@1.0.0-a.11/dist/umd/itk-wasm.js"></script>
  </head>
  <body>
    <p>This is an example to demonstrate browser-based debugging of
    C++-generated WebAssembly. For more information, please see the
    <a target="_blank" href="https://wasm.itk.org/examples/debugging.html">associated
      documentation</a>.</p>

    <script>
      window.addEventListener('load', (event) => {
        const pipeline = new URL('emscripten-build-debug/DebugMe', document.location)
        itk.runPipeline(null, pipeline)
      });
    </script>

  </body>
</html>

And we can debug the C++ code in Chrome's DevTools debugger alongside the executing JavaScript!

What's Next

In our next post, we will provide a tutorial on how to generate JavaScript and TypeScript bindings for Node.js and the browser.

Enjoy ITK!

Extending ITK for C++ and Python: Build and Test ITK External Modules in a GitHub Action

Matt McCormick — Fri, 03 Mar 2023 18:12:28 +0000

By: Tom Birdsong, Matt McCormick, Lucas Gandel, Simon Rit, Jean-Christophe Fillion-Robin, Stephen Aylward

Medical imaging is an ever-changing domain, with technological advances introducing exciting new data and processing techniques every year. In a rapidly evolving landscape, the open-source Insight Toolkit (ITK) continues to provide essential and cutting-edge tools for medical image processing to aid researchers and practitioners alike. ITK keeps up with rapid advances in the field through the contributions of its community members and their commitment to open science. To support these contributions, ITK provides a robust framework for the development and inclusion of external modules. Recent updates that leverage GitHub Actions workflows have made external module maintenance easier than ever. Any ITK developer can now quickly create and disseminate external modules that enhance ITK's capabilities on multiple Mac, Linux, and Windows platforms, in C++ and for python versions 3.7-3.11 via pip. Furthermore, if an external module is deemed to add sufficient value to the ITK community, then it can be distributed as a “remote module” of ITK, allowing it to be easily enabled and built as part of the ITK C++ library and Python package.

An individual might create a new external module for any of several reasons, such as:

To add domain-specific tools, such as ultrasound despeckle techniques provided in the ITKUltrasound external module or tomographic reconstruction in the reconstruction toolkit (RTK);
To wrap an existing library for medical imaging so that it can be used in the ITK ecosystem, such as wrapping the Elastix registration library in the ITKElastix external module;
To add support for an emerging data formatting standard, such as support for reading from and writing to the OME-Zarr spatial array chunking standard in the ITKIOOMEZarrNGFF external module.

A notable challenge in creating an external module is the learning curve required for new contributors. In order to fully leverage the building blocks that ITK provides, it is generally necessary to have basic knowledge of C++ programming, CMake, and the ITK pipelining system, the latter of which is covered in detail in the ITK Software Guide. Fortunately, new users can make use of the ITKModuleTemplate cookiecutter discussed in the Python Packages for ITK Modules article, rather than starting from scratch. In the past, another significant barrier to entry was familiarity with good software practices, namely setting up continuous integration and continuous deployment (CI/CD) pipelines, so that modules are tested and remain compatible as ITK's core is updated. Initial pipelines populated by the cookiecutter template had limited support for good software practices. This article introduces recent updates that take advantage of Github Action Workflows and make it easy for most ITK modules to follow CI/CD best practices and minimize maintenance requirements.

Introducing an ITK Module Reusable Workflow

The ITKRemoteModuleBuildTestPackageAction GitHub Action is a central repository to collect common procedures for building, testing, and packaging ITK open source external modules that are hosted on GitHub. Scripts leverage the CI/CD framework provided by GitHub Actions to automatically run pipelines on certain events, such as when a user opens a pull request or when a maintainer merges new changes. The repository currently offers two yaml pipeline files that lay out steps for building an external module for C++ or Python targets. These steps can be used by the majority of ITK external modules (a) to verify that the module compiles across platforms with proposed changes; (b) to run and report results from module tests; and (c) to package and deploy cross-platform Python wheels for users to easily install and run.

In most cases community members can leverage ITKRemoteModuleBuildTestPackageAction in their external module projects for several advantages:

Build procedures are provided as GitHub Actions (GHA) reusable workflow .yml files which integrate directly with GHA runners. These can be invoked for a given external module in its GitHub repository with minimal code.
Build procedure updates are centralized. Rather than replicating build step updates directly in a custom build procedure for each external module, developers may simply update workflow commit tags to include process updates in external module CI. For example, an update to a runner platform version from Ubuntu 18.04 to Ubuntu 20.04 would be introduced to ITKRemoteModuleBuildTestPackageAction once and then consumed by a variety of external modules by simply updating the ITKRemoteModuleBuildTestPackageAction commit hash accordingly.

ITK reusable workflows are best leveraged by ITK external modules that are implemented primarily in C++ and have a simple build process. If a developer wants to distribute their filters without requiring that users have prerequisites to build the module, then they can invoke the Python reusable workflow to easily package and distribute the module when new versions of the module are released. If the external module has a more complex build process with one or more external dependencies, but those dependencies can be fetched with CMake and included in the module build process, then the module will likewise be able to leverage external pipelines.

Unfortunately, at this time, external modules that require certain system dependencies in place before the build starts cannot easily leverage the reusable workflows. Pure Python external modules are also unable to be packaged with ITK reusable workflows at this time.

Usage

Developers can take advantage of ITK reusable workflows with just a few lines of code. GitHub Actions will automatically detect and run any yaml pipeline files inside a project’s .github/workflows directory. Here is an example of a basic file to run C++ and Python CI/CD pipelines from an ITK external module:

name: Build, test, package

on: [push,pull_request]

jobs:
  cxx-build-workflow:
    uses: InsightSoftwareConsortium/ITKRemoteModuleBuildTestPackageAction/.github/workflows/build-test-cxx.yml@d4a5ce4f219b66b78269a15392e15c95f90e7e00

  python-build-workflow:
    uses: InsightSoftwareConsortium/ITKRemoteModuleBuildTestPackageAction/.github/workflows/build-test-package-python.yml@d4a5ce4f219b66b78269a15392e15c95f90e7e00
    secrets:
      pypi_password: ${{ secrets.pypi_password }}

The code example above tells GitHub Actions to find and run reusable workflows in the ITKRemoteModuleBuildTestPackageAction repository. cxx-build-workflow is a job that exists to fetch and run the build-test-cxx reusable workflow, while python-build-workflow is a job that fetches and runs the build-test-package-python reusable workflow. Each workflow itself subsequently handles scheduling runners, performing environment setup, and then building the ITK external module.

The example workflow file above is broken down line by line in the ITKRemoteModuleBuildTestPackageAction README file on GitHub.

C++ Workflow

The build-test-cxx workflow provides a common process to build and test a given ITK external module. The workflow offers cross-platform testing on Windows, Ubuntu, and macOS images as provided by GitHub Actions. First, build tools and prerequisites such as CMake and Python are installed, then the Insight Toolkit is built from scratch, and finally the ITK external module is built. Any tests that are defined for CTest are run as part of the procedure and uploaded to the ITK CDash dashboard at https://open.cdash.org/index.php?project=Insight under the Experimental header.

Users can specify a number of input arguments to direct the external module build process, including:

The ITK C++ version to use;
CMake variables for the ITK build or external module build;
Test options and warnings to ignore in reporting results to the ITK dashboard;
Other ITK external modules to build first and include as build prerequisites for the current module.

More information on the C++ workflow can be found in the project README.

Python Workflow

The build-test-package-python workflow provides a common process to build, package, and deploy ITK external module Python wheels to the Python Package Index. A fixed version of ITK is used with cached Python build results in order to avoid long build times.

Several input arguments are available to direct the Python wheel build process:

The ITK Python build cache version to use, which roughly corresponds to ITK minor release versions;
CMake variables for the external module build (but not the underlying ITK build);
The remote reference for build scripts to use, which allows developers to build their modules with custom scripts in a development branch;
Linux toolsets and architectures to target, including building Python wheels for ARM platforms;
Other ITK external modules to build first and include as build prerequisites for the current module.

More information on the Python workflow can be found in the project README.

Examples

Reusable workflows are being actively adopted to streamline ITK external module builds. Developers can reference a number of open source projects to get started with leveraging reusable workflows in a number of ways.

ITKUltrasound uses ITK reusable workflows to minimize complicated build maintenance to track changes in its five prerequisite external modules;
ITKElastix uses reusable workflows to deploy Python wheels for ARM architectures;
RTK, The Reconstruction Toolkit, uses reusable workflows to build Python packages.

When the reusable workflow is not directly usable because the workflow environment must be tuned to the needs of the module, it can serve as a basis.

ITKCudaCommon workflows are used to distribute Python packages with CUDA compatibilty for accelerated computing.
RTK has CUDA specific workflows for distributing Python packages using CUDA 11.6.

What's next

ITK reusable workflows continue to expand due to user contributions. Future workflows may aim to tackle additional challenges that face the ITK community, such as packaging and testing pure Python modules that leverage ITK processing pipelines. VTK remote modules like the LookingGlassVTKModule aim to adopt similar reusable workflows. Additional planned features will address common build issues such as Windows path lengths for modules with long names, large build sizes on GitHub runners, and cross-compiled builds for ARM to improve build times. Longer term, with upgrades to our scikit-build Python package configuration, the action will further build on community tools like cibuildwheel.

Enjoy ITK!

How to Debug WASI Pipelines with ITK-Wasm

Matt McCormick — Thu, 02 Mar 2023 18:16:41 +0000

By: Matt McCormick , Mary Elise Dedicke , Jean-Christophe Fillion-Robin , Will Schroeder

Effective debugging results in effective programming; itk-wasm makes effective debugging of WebAssembly possible. In this tutorial, adapted from the itk-wasm documentation, we walk through how to debug a C++ data processing pipeline with the mature, native binary debugging tools that are comfortable for developers. This is a fully featured way to ensure the base correctness of a processing pipeline. Next, we will walk through an interactive debugging experience for WASI WebAssembly. With itk-wasm, we can debug the same source code in either context with an interactive debugger. We also have a convenvient way to pass data from our local filesystem into a WebAssembly (Wasm) processing pipeline.

Let's get started! 🚀

0. Preliminaries

Before starting this tutorial, check out our Hello Wasm World tutorial.

1. Native Debugging

The tutorial code provides npm scripts as a convenient way to execute debugging commands, which you may also invoke directly in a command line shell.

#include <iostream>

int main() {
  std::cout << "Hello debugger world!" << std::endl;

  const char * wasmDetails = "are no longer hidden";

  const int a = 1;
  const int b = 2;
  const auto c = a + b;

  // Simulate a crash.
  abort();
  return 0;
}

To run these examples, first install and test Docker and Node/NPM. Then, install the package dependencies and run the example commands:

cd itk-wasm/examples/Debugging/
npm install
npm run <name>

where <name> is the npm script. Available names can be found by calling npm run without any arguments.

The CMake-based, itk-wasm build system tooling enables the same C++ build system configuration and code to be reused when building a native system binary or a WebAssembly binary. As a result, native binary debugging tools, such as GDB, LLDB, or the Visual Studio debugger can be utilized.

We can build the project's standard CMake build configuration,

cmake_minimum_required(VERSION 3.10)
project(DebuggingWebAssemblyExample)

add_executable(DebugMe DebugMe.cxx)

with standard CMake commands:

The native binary can then be debugged in the standard way. For example, with gdb on Linux:

2. WASI Debugging

The most direct way to debug WebAssembly is through the WebAssembly System Interface (WASI). In itk-wasm, we can build to WASI with the WASI SDK by specifying the itkwasm/wasi toolchain image. A backtrace can quickly be obtained with the itk-wasm CLI. Or, a fully fledged debugger session can be started with LLDB.

First, build to WASI WebAssembly with debugging symbols available:

Then, the itk-wasm CLI can conveniently run the Wasm binary with the included WASI runtime:

We can see that abort is called in the main function at line 13 in DebugMe.cxx.

A full debugging session is also possible after LLDB >= 13 and Wasmtime are installed.

What's Next

In our next post, we will provide a tutorial on how to debug C++ WebAssembly processing pipelines in a web browser.

Enjoy ITK!

Leverage the powerful Insight Toolkit (ITK) in MATLAB via Python

Matt McCormick — Fri, 24 Feb 2023 16:22:12 +0000

By: Matt McCormick, Tom Birdsong, Brad Moore, Jake McCall, Stephen Aylward

In recent years, MathWork's MATLAB added Python support. This unlocks the capabilities of the powerful open source scientific Python ecosystem inside MATLAB. This post provides a tutorial on how to use Insight Toolkit (ITK) version 5.3 and newer and itkwasm Python packages in MATLAB.

ITK is an open-source, cross-platform library that provides developers with an extensive suite of software tools for image analysis. Developed through extreme programming methodologies, ITK builds on a proven, spatially-oriented architecture for processing, segmentation, and registration of scientific images in two, three, or more dimensions.

To interactively reproduce this tutorial, run the corresponding MATLAB Live Script (source, html).

Installation

This section walks through how to install the itk Python package into the PythonEnvironment available in the MATLAB Online environment.

In general, you can install itk into your local Python environment by simply calling:

!python -m pip install itk

Since MATLAB Online uses Linux, we will use python3to specify the MATLAB Python version. On Windows, you may want to specify a version with'Version', '3.10'or similar. For more information, see the pyenv documentation.

pyenv("Version","python3")

ans = 
  PythonEnvironment with properties:

          Version: "3.8"
       Executable: "/usr/bin/python3"
          Library: "libpython3.8.so.1.0"
             Home: "/usr"
           Status: Loaded
    ExecutionMode: InProcess
        ProcessID: "5004"
      ProcessName: "MATLAB"

Next, we will Install itk via the Python package manager, pip. A standard Linux Python distribution is unusal in that it does not ship with pip, so we will download a self-contained version in this example.

websave("pip.pyz", "https://bootstrap.pypa.io/pip/pip.pyz");

For MATLAB Online, install the package into set the user packages and the setuptools package.

!python3 pip.pyz install --user itk setuptools

Collecting itk
  Downloading itk-5.3.0-cp38-cp38-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (8.3 kB)
Collecting setuptools
  Downloading setuptools-67.4.0-py3-none-any.whl (1.1 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.1/1.1 MB 80.0 MB/s eta 0:00:00

Collecting numpy
  Downloading numpy-1.24.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (17.3 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 17.3/17.3 MB 109.4 MB/s eta 0:00:00

Collecting itk-filtering==5.3.0
  Downloading itk_filtering-5.3.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (75.9 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 75.9/75.9 MB 39.0 MB/s eta 0:00:00

Collecting itk-registration==5.3.0
  Downloading itk_registration-5.3.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (27.3 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 27.3/27.3 MB 84.0 MB/s eta 0:00:00

Collecting itk-io==5.3.0
  Downloading itk_io-5.3.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (26.2 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 26.2/26.2 MB 73.7 MB/s eta 0:00:00

Collecting itk-numerics==5.3.0
  Downloading itk_numerics-5.3.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (60.0 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 60.0/60.0 MB 48.3 MB/s eta 0:00:00

Collecting itk-core==5.3.0
  Downloading itk_core-5.3.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (83.6 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 83.6/83.6 MB 35.1 MB/s eta 0:00:00

Collecting itk-segmentation==5.3.0
  Downloading itk_segmentation-5.3.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (17.2 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 17.2/17.2 MB 106.7 MB/s eta 0:00:00

Installing collected packages: setuptools, numpy, itk-core, itk-numerics, itk-io, itk-filtering, itk-segmentation, itk-registration, itk
  WARNING: The scripts f2py, f2py3 and f2py3.8 are installed in '/home/mluser/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
Successfully installed itk-5.3.0 itk-core-5.3.0 itk-filtering-5.3.0 itk-io-5.3.0 itk-numerics-5.3.0 itk-registration-5.3.0 itk-segmentation-5.3.0 numpy-1.24.2 setuptools-67.4.0

For MATLAB Online, we need to add the user site packages to sys.path so Python will find them.

usp = py.site.getusersitepackages();
pyrun(["import sys", "if usp not in sys.path: sys.path.append(usp)"], usp=usp);
py.sys.path;

If the Python interpreter has already been started, we would need to manually import the Python package for MATLAB.

Again, these steps are unnecessary for local installations where the itk Python package is simply installed before starting MATLAB.

ITK to MATLAB

In this section, we will show how to load an image with ITK and display it with MATLAB.

% download a test image
websave("cthead1.png", "https://bafybeigja4wbultavomsvai433hln7uqabzl2mg24frxzqblx4y4cvd5am.ipfs.w3s.link/ipfs/bafybeigja4wbultavomsvai433hln7uqabzl2mg24frxzqblx4y4cvd5am/cthead1.png");

% load the image with itk
pyrun(["import itk", "image = itk.imread('cthead1.png')"])

% transfer python dict to matlab
image_dict = pyrun(["image_dict = itk.dict_from_image(image)"], "image_dict")

image_dict = 
  Python dict with no properties.

    {'imageType': {'dimension': 2, 'componentType': 'uint8', 'pixelType': 'Scalar', 'components': 1}, 'name': '', 'origin': (0.0, 0.0), 'spacing': (1.0, 1.0), 'size': (256, 256), 'direction': array([[1., 0.],
           [0., 1.]]), 'data': array([[0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0],
           ...,
           [0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0]], dtype=uint8)}

% matlab struct
image_struct = struct(image_dict)

image_struct = 
    imageType: [1x1 py.dict]
         name: [1x0 py.str]
       origin: [1x2 py.tuple]
      spacing: [1x2 py.tuple]
         size: [1x2 py.tuple]
    direction: [1x1 py.numpy.ndarray]
         data: [1x1 py.numpy.ndarray]

spacing = double(image_struct.spacing)

spacing = 1x2    
     1     1

% equivalent
spacing = double(image_dict{'spacing'})

spacing = 1x2    
     1     1

pixels = double(image_struct.data);
imshow(pixels, [0, 255])

image_dict{'imageType'}

ans = 
  Python dict with no properties.

    {'dimension': 2, 'componentType': 'uint8', 'pixelType': 'Scalar', 'components': 1}

% Keep pixel type
pixels = uint8(image_struct.data);
imshow(pixels)

MATLAB to ITK

In this section, we will show how to load an image with MATLAB and transfer it to ITK.

pixels = imread("cthead1.png")

Warning: PNG library warning: sCAL: invalid unit.
pixels = 256x256 uint8 matrix    
   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0
   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0
   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0
   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0
   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0
   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0
   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0
   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0
   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0
   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0   0

pyrun(["import numpy as np", "array = np.asarray(pixels)"], pixels=pixels)
pyrun(["image = itk.image_view_from_array(array)", "print(image)"])

Image (0x7f3aec3261e0)
  RTTI typeinfo:   itk::Image<unsigned char, 2u>
  Reference Count: 1
  Modified Time: 402
  Debug: Off
  Object Name: 
  Observers: 
    none
  Source: (none)
  Source output name: (none)
  Release Data: Off
  Data Released: False
  Global Release Data: Off
  PipelineMTime: 0
  UpdateMTime: 0
  RealTimeStamp: 0 seconds 
  LargestPossibleRegion: 
    Dimension: 2
    Index: [0, 0]
    Size: [256, 256]
  BufferedRegion: 
    Dimension: 2
    Index: [0, 0]
    Size: [256, 256]
  RequestedRegion: 
    Dimension: 2
    Index: [0, 0]
    Size: [256, 256]
  Spacing: [1, 1]
  Origin: [0, 0]
  Direction: 
1 0
0 1

  IndexToPointMatrix: 
1 0
0 1

  PointToIndexMatrix: 
1 0
0 1

  Inverse Direction: 
1 0
0 1

  PixelContainer: 
    ImportImageContainer (0x7f3aec3219f0)
      RTTI typeinfo:   itk::ImportImageContainer<unsigned long, unsigned char>
      Reference Count: 1
      Modified Time: 397
      Debug: Off
      Object Name: 
      Observers: 
        none
      Pointer: 0x7f3aec2a0d80
      Container manages memory: false
      Size: 65536
      Capacity: 65536

Call ITK filters

Let's call an itk filter and look at the result.

pyrun(["smoothed = itk.discrete_gaussian_image_filter(image, sigma=sigma)"], sigma=3.0);
smoothed = pyrun(["smoothed = itk.dict_from_image(smoothed)"], "smoothed");
imshow(uint8(smoothed{"data"}))

% equivalent
smoothed = py.itk.discrete_gaussian_image_filter(py.itk.image_from_dict(image_dict), sigma=3.0);
smoothed = py.itk.dict_from_image(smoothed);
imshow(uint8(smoothed{"data"}))

Beyond images

ITK supports other data structures beyond images, including Mesh's, PointSet's, and spatial Transform's.

websave("cow.vtk", "https://bafybeihqh2e2xyff5fzwygx4m2lmgqmnm3kv7gyzjgtcgv7kpfvvjy4rty.ipfs.w3s.link/ipfs/bafybeihqh2e2xyff5fzwygx4m2lmgqmnm3kv7gyzjgtcgv7kpfvvjy4rty/cow.vtk");

% load the mesh with itk
% pyrun(["mesh = itk.meshread('cow.vtk')"])
mesh = py.itk.meshread("cow.vtk")

mesh = 
  Python itkMeshF3 with properties:

    thisown: 1
       this: [1x1 py.SwigPyObject]

    Mesh (0x7f3aee68b400)
      RTTI typeinfo:   itk::Mesh<float, 3u, itk::DefaultStaticMeshTraits<float, 3u, 3u, float, float, float> >
      Reference Count: 1
      Modified Time: 10117
      Debug: Off
      Object Name: 
      Observers: 
        none
      Source: (none)
      Source output name: (none)
      Release Data: Off
      Data Released: False
      Global Release Data: Off
      PipelineMTime: 669
      UpdateMTime: 10116
      RealTimeStamp: 0 seconds 
      Number Of Points: 2903
      Requested Number Of Regions: 1
      Requested Region: 0
      Buffered Region: 0
      Maximum Number Of Regions: 1
      Point Data Container pointer: 0
      Size of Point Data Container: 0
      Number Of Points: 2903
      Number Of Cell Links: 0
      Number Of Cells: 3263
      Cell Data Container pointer: 0
      Size of Cell Data Container: 0
      Number of explicit cell boundary assignments: 3
      CellsAllocationMethod: itk::MeshEnums::MeshClassCellsAllocationMethod::CellsAllocatedDynamicallyCellByCell


% transfer python dict to matlab
mesh_dict = py.itk.dict_from_mesh(mesh)

mesh_dict = 
  Python dict with no properties.

    {'meshType': {'dimension': 3, 'pointComponentType': 'float32', 'pointPixelComponentType': 'float32', 'pointPixelType': 'Scalar', 'pointPixelComponents': 1, 'cellComponentType': 'uint64', 'cellPixelComponentType': 'float32', 'cellPixelType': 'Scalar', 'cellPixelComponents': 1}, 'name': '', 'numberOfPoints': 2903, 'points': array([3.71636 , 2.34339 , 0.      , ..., 4.23234 , 1.90308 , 0.534362],
          dtype=float32), 'numberOfPointPixels': 0, 'pointData': array([], dtype=float32), 'numberOfCells': 3263, 'cells': array([  4,   4, 250, ..., 966, 961, 970], dtype=uint64), 'numberOfCellPixels': 0, 'cellData': array([], dtype=float32), 'cellBufferSize': 18856}

% x,y,z point positions
points = double(mesh_dict{"points"})

points = 1x8709    
    3.7164    2.3434         0    4.1266    0.6420         0    3.4550    2.1699         0    3.9293    0.4117         0    3.2474    2.0733         0    3.7317    0.1864         0    2.9854    1.9827         0    3.4860   -0.1417         0    2.7235    1.8988         0    3.3352   -0.3758         0    2.3396    1.8077         0    3.1181   -0.7039         0    2.1281    1.7884         0    2.0422    1.7772         0    1.4567    1.7859         0    2.9709   -0.9597         0    2.9318   -1.1297

WebAssembly packages with itkwasm

In addition to native Python packages, itkwasm Python packages can be used, which leverage universal WebAssembly binaries.

Calls are similar, but we use Python's builtin dataclasses.asdict for conversion.

!python3 pip.pyz install --user itkwasm

Collecting itkwasm
  Downloading itkwasm-1.0b74-py3-none-any.whl (18 kB)
Collecting wasmer
  Downloading wasmer-1.1.0-cp38-cp38-manylinux_2_24_x86_64.whl (1.6 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.6/1.6 MB 89.3 MB/s eta 0:00:00

Requirement already satisfied: numpy in /home/mluser/.local/lib/python3.8/site-packages (from itkwasm) (1.24.2)
Collecting wasmer-compiler-cranelift
  Downloading wasmer_compiler_cranelift-1.1.0-cp38-cp38-manylinux_2_24_x86_64.whl (1.9 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.9/1.9 MB 115.2 MB/s eta 0:00:00

Collecting typing-extensions
  Downloading typing_extensions-4.5.0-py3-none-any.whl (27 kB)
Installing collected packages: wasmer-compiler-cranelift, wasmer, typing-extensions, itkwasm
Successfully installed itkwasm-1.0b74 typing-extensions-4.5.0 wasmer-1.1.0 wasmer-compiler-cranelift-1.1.0

itk_image = py.itk.imread("cthead1.png");
itk_image_dict = py.itk.dict_from_image(itk_image)

itk_image_dict = 
  Python dict with no properties.

    {'imageType': {'dimension': 2, 'componentType': 'uint8', 'pixelType': 'Scalar', 'components': 1}, 'name': '', 'origin': (0.0, 0.0), 'spacing': (1.0, 1.0), 'size': (256, 256), 'direction': array([[1., 0.],
           [0., 1.]]), 'data': array([[0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0],
           ...,
           [0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0]], dtype=uint8)}

itkwasm_image = pyrun(["from itkwasm import Image", "itkwasm_image = Image(**itk_image_dict)"], "itkwasm_image", itk_image_dict=itk_image_dict)

itkwasm_image = 
  Python Image with properties:

         data: [1x1 py.numpy.ndarray]
         size: [1x2 py.tuple]
       origin: [1x2 py.tuple]
    imageType: [1x1 py.itkwasm.image.ImageType]
         name: [1x0 py.str]
      spacing: [1x2 py.tuple]
     metadata: [1x1 py.dict]
    direction: [1x1 py.numpy.ndarray]

    Image(imageType=ImageType(dimension=2, componentType='uint8', pixelType='Scalar', components=1), name='', origin=(0.0, 0.0), spacing=(1.0, 1.0), direction=array([[1., 0.],
           [0., 1.]]), size=(256, 256), metadata={}, data=array([[0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0],
           ...,
           [0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0]], dtype=uint8))

itkwasm_image_dict = py.dataclasses.asdict(itkwasm_image)

itkwasm_image_dict = 
  Python dict with no properties.

    {'imageType': {'dimension': 2, 'componentType': 'uint8', 'pixelType': 'Scalar', 'components': 1}, 'name': '', 'origin': (0.0, 0.0), 'spacing': (1.0, 1.0), 'direction': array([[1., 0.],
           [0., 1.]]), 'size': (256, 256), 'metadata': {}, 'data': array([[0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0],
           ...,
           [0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0]], dtype=uint8)}

imshow(uint8(itkwasm_image_dict{"data"}))

Enjoy ITK!

ITKElastix 0.16.0 has been released!

Matt McCormick — Tue, 21 Feb 2023 17:32:07 +0000

By: Matt McCormick, Niels Dekker, Konstantinos Ntatsis, Marius Staring

We are exceedingly pleased to announce the release of ITKElastix 0.16.0, an ITK module that provides Python and C++ interfaces to elastix, a toolbox for rigid and nonrigid registration of N-dimensional images. 🎉 🗺️🧠🙌

Registration is the task of finding a spatial transformation that aligns one image to another by optimizing relevant image similarity metrics.

For more information on how to register scientific images, see the itk-elastix jupyter notebooks and the elastix manual.

MONAI deep learning registration with elastix pre-alignment (jupyter notebook).

💾 Download

To install the binary Python packages:

pip install itk-elastix

✨ Highlights

ITKElastix 0.16.0 is released in conjunction with elastix 5.1.0. Features added include:

🐍 Cross-platform binary Python packages are now 80% smaller
💪 macOS, Linux ARM Python packages
🗣️ Updated example notebook on MONAI deep learning registration with affine pre-alignment using itk-elastix
🚀 Major performance improvements in the calculation of metrics; accelerates registration for some cases by 40% or more
C++14 modernization
Upgraded to ITK 5.3.0
Support ITK Transform types: Translation, Affine, Euler (2D and 3D), Similarity (2D and 3D), and BSpline
Add GetCombinationTransform(), GetNumberOfTransforms(), GetNthTransform(n), ConvertToItkTransform(transform) to itk::ElastixRegistrationMethod
Add SetCombinationTransform(transform) to itk::TransformixFilter, for access and use of transform objects through the library interface

For more details, see the full elastix 5.1.0 release notes and ITKElastix 0.16.0 release notes.

🗣️ What's Next

In the next release, we will publish additional notebooks on how to support medical image deep learning artificial intelligence (AI) with Project MONAI. These improvement are made in collaboration with the MONAI community as itk Python package spatial metadata improvements in monai harden and extend MONAI's medical image registration capabilities. We will update the current elastix_napari for napari integration. Also, WebAssembly builds will be created via itk-wasm.

🙏 Acknowledgments

ITKElastix was developed in part with support from:

NIH NIMH BRAIN Initiative under award 1RF1MH126732.
Chan Zuckerberg Initiative (CZI) Essential Open Source Software for Science award for Open Source Image Registration: The elastix Toolbox.

Enjoy ITK and elastix!

Create Elegant C++ Spatial Processing Pipelines in WebAssembly

Matt McCormick — Fri, 10 Feb 2023 21:22:03 +0000

By: Matt McCormick , Mary Elise Dedicke , Henry Schreiner

WebAssembly's origins date back to Alon Zakai's incredible effort to build C++ to JavaScript. In 2015, we demonstrated the power of this technology to make scientific computational sustainable and accessible. Try it -- reproducibility is still possible all these years later, with no installation (or maintenance!) required.

An interactive, accessible and sustainable open science publication on anisotropic diffusion where C++ is built into JavaScript for browser execution.

Since that time, Emscripten's capabilities have advanced and been standardized with WebAssembly (Wasm) in the Web Platform. Moreover, Wasm's scope has expanded dramatically with the advent of the WebAssembly System Interface, WASI, and The Component Model.

However, there was a significant gap in capabilites for research software developers who aimed to create data and computationally intense scientific processing pipelines for applications like spatial analysis and visualization. Namely,

An elegant, simple way to write processing pipelines in C++.
Handling of non-trivial spatial data structures (Wasm natively only supports integers and floats 😮).
Easy-to-use, reproducible tools to build Wasm modules.
Safe and efficient memory handling.
Parallelism, whether multi-module, multi-threading, or SIMD.
Provide bindings for the command line and functional interfaces for languages like JavaScript, Typescript, Python, Rust, C#, R, and Java.
Debugging support.

In this post, adapted from itk-wasm's documentation, we provide a C++ Wasm processing pipeline tutorial that demonstrates how we can write elegant processing pipelines in C++ via itk-wasm's CLI11 command line parser, which provides a rich feature set with a simple and intuitive interface. At the end of this tutorial, you will have built and executed C++ code to Wasm for standalone execution on the command line and in the browser.

itk-wasm combines the Insight Toolkit (ITK) and WebAssembly to enable high-performance spatial analysis in a web browser, Node.js, and reproducible execution across programming languages and hardware architectures.

CLI11 provides all the features you expect in a powerful command line parser, with a beautiful, minimal syntax and no dependencies beyond C++11. itk-wasm enhances CLI11 with a itk::wasm::Pipeline wrapper to support efficient execution in multiple Wasm contexts, scientific data structures, and lovely colorized help output 🥰.

Let's get started! 🚀

0. Preliminaries

Before starting this tutorial, check out our Hello Wasm World tutorial.

1. Write the code

First, let's create a new directory to house our project.

mkdir hello-pipeline
cd hello-pipeline

Let's write some code! Populate hello-pipeline.cxx first with the headers we need:

#include "itkPipeline.h"
#include "itkInputImage.h"
#include "itkImage.h"

The itkPipeline.h and itkInputImage.h headers come from the itk-wasm WebAssemblyInterface ITK module.

The itkImage.h header is ITK's standard n-dimensional image data structure.

Next, create a standard main C command line interface function and an itk::wasm::Pipeline:

int main(int argc, char * argv[]) {
  // Create the pipeline for parsing arguments. Provide a description.
  itk::wasm::Pipeline pipeline("hello-pipeline", "A hello world itk::wasm::Pipeline", argc, argv);

  return EXIT_SUCCESS;
}

The itk::wasm::Pipeline extends the CLI11 modern C++ command line parser. In addition to all of CLI11's functionality, itk::wasm::Pipeline's adds:

Support for execution in Wasm modules along with command line execution
Support for spatial data structures such as Image, Mesh, PolyData, and Transform
Support for multiple dimensions and pixel types
Colored help output

Add a standard CLI11 flag to the pipeline:

  itk::wasm::Pipeline pipeline("hello-pipeline", "A hello world itk::wasm::Pipeline", argc, argv);


  bool quiet = false;
  pipeline.add_flag("-q,--quiet", quiet, "Do not print image information");

Add an input image argument to the pipeline:

  pipeline.add_flag("-q,--quiet", quiet, "Do not print image information");


  constexpr unsigned int Dimension = 2;
  using PixelType = unsigned char;
  using ImageType = itk::Image<PixelType, Dimension>;

  // Add a input image argument.
  using InputImageType = itk::wasm::InputImage<ImageType>;
  InputImageType inputImage;
  pipeline.add_option("input-image", inputImage,
    "The input image")->required()->type_name("INPUT_IMAGE");

The inputImage variable is populated from the filesystem if built as a native executable or a WASI binary run from the command line. When running in the browser or in a wrapped language, inputImage is read from WebAssembly memory without file IO.

Parse the command line arguments with the ITK_WASM_PARSE macro:

  pipeline.add_option("InputImage", inputImage,
    "The input image")->required()->type_name("INPUT_IMAGE");


  ITK_WASM_PARSE(pipeline);

If -q or --quiet is set, the quiet variable will be set to true. Missing or invalid arguments will print an error and exit. The -h and --help flags are automatically generated from pipeline arguments to print usage information.

Finally, run the pipeline:

  std::cout << "Hello pipeline world!\n" << std::endl;

  if (!quiet)
  {
    // Obtain the itk::Image * from the itk::wasm::InputImage with `.Get()`.
    std::cout << "Input image: " << *inputImage.Get() << std::endl;
  }

  return EXIT_SUCCESS;

Next, provide a CMake build configuration in CMakeLists.txt:

cmake_minimum_required(VERSION 3.16)
project(hello-pipeline)

# Use C++17 or newer with itk-wasm
set(CMAKE_CXX_STANDARD 17)

# We always want to build against the WebAssemblyInterface module.
set(itk_components
  WebAssemblyInterface
  )
# WASI or native binaries
if (NOT EMSCRIPTEN)
  # WebAssemblyInterface supports the .iwi, .iwi.cbor itk-wasm format.
  # We can list other ITK IO modules to build against to support other
  # formats when building native executable or WASI WebAssembly.
  # However, this will bloat the size of the WASI WebAssembly binary, so
  # add them judiciously.
  set(itk_components
    WebAssemblyInterface
    ITKIOPNG
    # ITKImageIO # Adds support for all available image IO modules
    )
endif()
find_package(ITK REQUIRED
  COMPONENTS ${itk_components}
  )
include(${ITK_USE_FILE})

add_executable(hello-pipeline hello-pipeline.cxx)
target_link_libraries(hello-pipeline PUBLIC ${ITK_LIBRARIES})

2. Create and Run WebAssembly binary

Build the WASI binary:

npx itk-wasm@1.0.0-b.70 -i itkwasm/wasi build

And check the generated help output:

npx itk-wasm@1.0.0-b.70 run hello-pipeline.wasi.wasm -- -- --help

The two --'s are to separate arguments for the Wasm module from arguments to the itk-wasm CLI and the WebAssembly interpreter.

Try running on an example image.

> npx itk-wasm@1.0.0-b.65 run hello-pipeline.wasi.wasm -- -- cthead1.png

Hello pipeline world!

Input image: Image (0x2b910)
  RTTI typeinfo:   itk::Image<unsigned char, 2u>
  Reference Count: 1
  Modified Time: 54
  Debug: Off
  Object Name:
  Observers:
    none
  Source: (none)
  Source output name: (none)
  Release Data: Off
  Data Released: False
  Global Release Data: Off
  PipelineMTime: 22
  UpdateMTime: 53
  RealTimeStamp: 0 seconds
  LargestPossibleRegion:
    Dimension: 2
    Index: [0, 0]
    Size: [256, 256]
  BufferedRegion:
    Dimension: 2
    Index: [0, 0]
    Size: [256, 256]
  RequestedRegion:
    Dimension: 2
    Index: [0, 0]
    Size: [256, 256]
  Spacing: [1, 1]
  Origin: [0, 0]
  Direction:
1 0
0 1

  IndexToPointMatrix:
1 0
0 1

  PointToIndexMatrix:
1 0
0 1

  Inverse Direction:
1 0
0 1

  PixelContainer:
    ImportImageContainer (0x2ba60)
      RTTI typeinfo:   itk::ImportImageContainer<unsigned long, unsigned char>
      Reference Count: 1
      Modified Time: 50
      Debug: Off
      Object Name:
      Observers:
        none
      Pointer: 0x2c070
      Container manages memory: true
      Size: 65536
      Capacity: 65536

And with the --quiet flag:

> npx itk-wasm@1.0.0-b.65 run hello-pipeline.wasi.wasm -- -- --quiet cthead1.png

Hello pipeline world!

Congratulations! You just executed a C++ pipeline capable of processsing a scientific image in WebAssembly. 🎉

What's next

We created a processing pipeline that works with real data -- exciting! When creating these pipelines, however, we will sometimes need a more detailed understanding of their execution. In our next post, we will address this need by describing how to debug itk-wasm WASI modules.

Hello Wasm World!

Matt McCormick — Sat, 14 Jan 2023 14:42:44 +0000

In modern computing, the Web Platform has transformed web browsers into a powerful and accessible application interface. Applications built on open web standards work, with no installation, across operating system and hardware platforms. WebAssembly, also known as Wasm, is a portable, binary format for high-performance applications on the web. Wasm has additional properties critical for the web: tiny binary sizes and strong, security-driven sandboxed execution. Wasm's capabilities became even more universal with with the creation of the WebAssembly System Interface, WASI, open standard. WASI enables Wasm to run outside the browser in contexts such as the command line, embedded environments, and within higher level programming languages.

In this post, adapted from itk-wasm's documentation, we provide a C++ Wasm Hello World tutorial. At the end of this tutorial you will have built and executed C++ code to Wasm for standalone execution on the command line and in the browser.

Let's get started! 🚀

Preliminaries

Before getting started, make sure Node.js and Docker are installed. On Linux, make sure you can run docker without sudo. On Windows, we recommend WSL 2 with Docker enabled.

While we recommend following along step-by-step, the complete example can also be found in the examples/ directory of the project repository.

Write the code

First, let's create a new directory to house our project.

mkdir HelloWorld
cd HelloWorld

Let's write some code! Populate hello.cxx with our Hello World program:

#include <iostream>

int main() {
  std::cout << "Hello Wasm world!" << std::endl;
  return 0;
}

Next, provide a CMake build configuration at CMakeLists.txt:

cmake_minimum_required(VERSION 3.16)
project(HelloWorld)

add_executable(hello hello.cxx)

Install itk-wasm

We use the add_executable command to build executables with itk-wasm. The Emscripten and WASI toolchains along with itk-wasm build and execution configurations are contained in itk-wasm dockcross Docker images invoked by the itk-wasm command line interface (CLI). Note that the same code can also be built and tested with native operating system toolchains. This is useful for development and debugging.

Build the program with the itk-wasm CLI, itk-wasm. This is shipped with the itk-wasm Node.js package. First install itk-wasm with the Node Package Manager, npm, the CLI that ships with Node.js.

# Initialize an empty project in the current directory
❯ npm init --yes
❯ npm install itk-wasm@1.0.0-b.70

Run on the command line

Build the project with the WASI itkwasm/wasi toolchain in the ./wasi-build/ directory:

❯ npx itk-wasm -i itkwasm/wasi -b ./wasi-build/ build

A hello.wasi.wasm WebAssembly binary is built in the ./wasi-build/ directory.

❯ ls wasi-build
build.ninja          CMakeFiles          libwasi-exception-shim.a
cmake_install.cmake  hello.wasi.wasm

Execute the binary with the run itk-wasm subcommand.

❯ npx itk-wasm -b ./wasi-build/ run hello.wasi.wasm
Hello Wasm world!

Congratulations! You just executed a C++ program compiled to WebAssembly. 🎉

The binary can also be executed with other WASI runtimes.

Run in the browser

For Node.js or the Browser, build the project with the default Emscripten toolchain.

❯ npx itk-wasm -b ./emscripten-build build

The same Emscripten Wasm module can be executed in a web browser.

Create an HTML file that will call the Wasm module through JavaScript and display
its output in the HTML DOM:

<!DOCTYPE html>
<html>
  <head>
    <title>itk-wasm Browser Hello World!</title>
    <meta charset="UTF-8" />
    <script src="https://cdn.jsdelivr.net/npm/itk-wasm@1.0.0-b.53/dist/umd/itk-wasm.min.js"></script>
  </head>

  <body>
    <textarea readonly>WebAssembly output...</textarea>

    <script>
      const outputTextArea = document.querySelector("textarea");
      outputTextArea.textContent = "Loading...";

      const wasmURL = new URL('emscripten-build/hello', document.location)
      const args = []
      const inputs = null
      const outputs = null
      itk.runPipeline(null, wasmURL, args, inputs, outputs).then(
        ({ stdout, webWorker }) => {
          webWorker.terminate()
          outputTextArea.textContent = stdout
          })
    </script>
  </body>
</html>

Serve the web page and Wasm module with an http server:

❯ npm install http-server
❯ npx http-server .

And point your browser to http://127.0.0.1:8080/.

Congratulations! You just executed a C++ program in your web browser. 🎉

What's Next

Well done!

As you build more advanced C++ projects into WebAssembly, you will find that many CMake-configured projects will just work with itk-wasm since it handles details required for CMake try_run commands, C++ exception handling, optimization of Wasm binary size, etc.

In the next tutorial, we will introduces itk-wasm's ability to elegantly transform standalone C++ command line programs into powerful Wasm modules with a simple, efficient interface.

Welcome and guide first-time contributors with a GitHub Action

Matt McCormick — Thu, 12 Jan 2023 16:50:32 +0000

Back in the day, before open source won the Closed vs. Open Wars (especially in scientific computing),

RTFM.

was a common first response when a new developer sought to contribute to an open source project. RTFM stands for Read the Fine Manual, although there is also another, more crass, interpretation.

We can do better!

And in modern times, we must do better as a pragmatic imperative. In our overloaded, hectic lives, few have the time to read every project's manual before they submit a small fix. Moreover, as a new generation of developers are impatient with interactions beyond swiping a screen, they are not going to proactively sign up for a GNU Mailman mailing list, seek out and read all associated manuals, search mailing list archives, and then post to the list according to the conventions of the community. While forking and maintaining patches should be avoided when possible in the interest of long-term maintainability, modern tooling for version control and testing makes it slightly more feasible. In general, a potential contributor's time, attention, and energy are in short supply, and we need to make their introduction to the contribution process as painless as possible.

At the same time, as community-driven maintainers of open source projects, we must limit our time, which is in even shorter supply, while upholding the project's culture, quality, and sustainability.

In this post, we review how the Insight Toolkit (ITK) leverages the first-interaction GitHub Action to communicate our appreciation of the efforts of first-time contributors, establish norms for behavior, and provide civil pointers on where to find more information.

Example first interaction welcome message

Automated outreach on first interaction

While GitHub has made many improvements that facilitate social coding, including resources to automate pointers to contributing guidelines that are put forward and easily discoverable using relative links and a project's code of conduct for new contributors, configuration of the first-interaction GitHub Action is another mechanism that can be customized to a project's needs.

The first-interaction GitHub Action adds a comment whenever a first-time contributor opens their first issue or pull request. This automated message connects with contributors where their attention is already directed.

A note of welcome and appreciation

Our comment starts with a note of welcome to the community and gratitude for the effort made to contribute back to the project. Software development, regardless of the cold and mechanical nature of computers, is a social endeavor; we respect and acknowledge this by beginning with our gratitude.

Recently, emojis were added to the message to communicate a welcoming culture. 🤗

Communicate mission, values, and culture

Next, we provide a link to our community participation guidelines / Code of Conduct. This establishes culture and communicates behavioral expectations, along with the project's mission:

ITK is one of the largest and long-lived open-source projects within the scientific community. ITK is made by hundreds of community members around the globe with a diverse set of skills, personalities, and experiences working for open and reproducible research in image analysis.

We work to build a great image analysis tool that serves a broad range of applications and environments, from research and education, to industry and beyond, by trying to contribute with amazing features, and teaching and helping our fellows for such a honorable intention. We seek no explicit recognition for this. Hence a sense of additional responsibility is part of why we do what we do.

We want a successful, friendly, agile and growing community that can welcome new ideas in a complex field, continuously improve our community software process, and foster collaboration between groups with very different needs, interests and skills. Openness, collaboration and participation are core aspects of our work - from development of new amazing image analysis features, to collaboratively shaping the necessary tools to make it an ever easier and joyful experience for both developers and end-users. Such an environment enriches the surrounding community and other open communities as well.

We put people first and do our best to recognize, appreciate and respect the diversity of our global contributors. The ITK project welcomes contributions from everyone who shares our goals and strives to contribute in a healthy and constructive manner within our community. This implies diversity of ideas and perspectives on often complex problems. We gain strength from diversity and actively seek participation from those who enhance it.

And our values:

be open
be welcoming
be inclusive
be civil and considerate
be respectful
be collaborative
be careful in the words that we choose
take responsibility for our words and our actions
be concise
be inquisitive
moderate your expectations
ask for help when unsure
lead by example

Share where to find more information

Finally, we provide guidance on where to find more information for contributors with issues or those that would like to integrate a patch. For issues, we point contributors to prior issues and the discussion forum. For pull requests, we point to documentation on our contribution process.

Conclusion

Configuration of a first-interaction GitHub Action is a relatively small step, but it has large impact in the greater battle to achieve software sustainability.

We will continue our aim to move beyond RTFM to WYBC (Welcome Your Brilliant Contributors), CMVC (Communicate Mission, Values, and Culture), SYCD (Share Your Contributor Documentation), and CUBA (Come Up with Better Acronyms) 😊.

How to raise the quality of scientific Jupyter notebooks

Matt McCormick — Thu, 12 Jan 2023 04:21:44 +0000

By: Matt McCormick, Mary Elise Dedicke, Alex Remedios

Reproducibility in Computational Experiments

Jupyter has emerged as a fundamental component in artificial intelligence (AI) solution development and scientific inquiry. Jupyter notebooks are prevelant in modern education, commercial applications, and academic research. The Insight Toolkit (ITK) is an open source, cross-platform toolkit for N-dimensional processing, segmentation, and registration used to obtain quantitative insights from medical, biomicroscopy, material science, and geoscience images. The ITK community highly values scientific reproducibility and software sustainability. As a result, advanced computational methods in the toolkit have a dramatically larger impact because they can be reproducibly applied in derived research or commercial applications.

Since ITK's inception in 1999, there has been a focus on engineering practices that result in high-quality software. High-quality scientific software is driven by regression testing. The ITK project supported the development of CTest and CDash unit testing and software quality dashboard tools for use with the CMake build system. In the Python programming language, the pytest test driver helps developers write small, readable scripts that ensure their software will continue to work as expected. However, pytest can only test Python scripts by default, and errors in untested computational notebooks are more common than well-tested Python code.

In this post, we describe how ITK's Python interface leverages nbmake, a simple, powerful tool that increases the quality of Jupyter notebooks through testing with the pytest test driver.

nbmake

nbmake is a pytest plugin that enables developers to verify that Jupyter notebook files run without error. This lets teams keep notebook-based documents and research up to date in an evolving project.

Quite a few libraries exist that relate to unit testing and notebooks:

nbval is a strong fit for developers who want to check that cells always render to the same value
testbook is maintained by the nteract community, and is good for testing functions written inside notebooks
nbmake is popular for those maintaining documentation and research material; it programmatically runs notebooks from top to bottom to validate the contents

We used nbmake because of the simplicity of its adoption, integration with pytest, and the ability to test locally and in continuous integration (CI) testing systems like GitHub Actions.

Getting Started

A great first step for testing notebooks is to run nbmake with its default settings:

pip install nbmake # install the python library

pytest --nbmake my_notebook.ipynb # Invoke pytest with nbmake on a notebook

This simple command will detect a majority of common issues, such as import errors, in the notebook.

To add more detail on expected notebook content, simply add assertions in two notebook cells like this:

# my_notebook.ipynb

# %% Cell 1
x = 42

# %% Cell 2
assert x == 42

Use assertions to check your notebook is working as expected.

Note: If you want to present a cleaner version of the notebook without assertions, you can use Jupyter book to render it into a site and use the remove-cell tag to omit assertions from the output.

Tips for using nbmake

Starting to test any software package is always difficult, but once begun it becomes easier to maintain quality software.

If your directory contains an assortment of notebooks, you will find different blockers:

some require kernels with different types and names
some raise errors, expectedly or unexpectedly
some require authentication and network dependencies
some will take hours to run

Our advice is to start small.

Try running nbmake locally from your development environment on a single short notebook. If
that is a challenge, use the --nbmake-find-import-errors flag to only check for missing dependencies.

Once you have a minimal quality bar, you can think about what's next for your testing
approach.

Run software quality checks on CI
Test more notebooks
Reduce the test time by using pytest-xdist
Use the --overwrite flag to write the output notebooks to disk to build documentation or commit to version control.

For complete docs and troubleshooting guides, see the nbmake GitHub repo.

ITK Use Cases

When creating spatial analysis processing pipelines, example code, notebook visualization tools, and documents, ITK leverages nbmake to ensure high-quality, easy-to-maintain documentation without common import errors or unexpected errors.

In ITK extensions such as ITKIOScanco (a module to work with 3D microtomography volumes) or ITKElastix (a toolbox for rigid and nonrigid registration of images), nbmake runs notebooks in GitHub Actions CI tests.

ITKElastix GitHub Actions notebook test output, displaying standard pytest status information.

CI testing catching an error and displaying traceback information via pytest.

itkwidgets, a next-generation, simple 3D visualization tool for Python notebooks, uses nbmake to check its functionality.

An itkwidgets visualization notebook tested with nbmake.

In ITK's Sphinx examples, notebooks are embedded into HTML documentation and continuously tested.

An explanation of optimization during image registration. The notebook is rendered in Sphinx and tested with nbmake.

Next Steps

While notebooks have been around for some time, we are still learning how to integrate them into rigorous engineering processes. The nbmake project is continuing to develop ways to remove friction associated with maintaining quality notebooks in many organizations.

Over the next year, there will be updates to both the missing imports checker (to keep virtual environments up to date) and the mocking system (to skip slow and complex cells during testing).

Nbmake is maintained by treebeard.io, a machine learning infrastructure company based in
the UK. ITK is a NumFOCUS project with commercial support offered by Kitware, an open source scientific computing company headquartered in the USA.