docs(HelloPipeline): Initial addition

Author: thewtex

.github/workflows/examples.yml

@@ -84,6 +84,35 @@ jobs:
         browser: chrome
         start: npm start
 
+  build-hello-pipeline-example:
+    name: Hello Pipeline Build
+    runs-on: ubuntu-20.04
+
+    defaults:
+      run:
+        working-directory: ./examples/HelloPipeline
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - uses: actions/setup-node@v2
+      with:
+        node-version: '16'
+
+    - name: Install
+      run: |
+        npm install
+
+    - name: Build
+      run: |
+        npm run build
+
+    - name: Test
+      run: |
+        npm run test
+        npm run test:quiet
+        npm run test:help
+
   test-umd-example:
     name: UMD
     runs-on: ubuntu-20.04

doc/content/examples/hello_pipeline.md

@@ -0,0 +1,224 @@
+title: Hello Pipeline World!
+---
+
+This example introduces the `itk::wasm::Pipeline`. An `itk::wasm::Pipeline` transforms elegant standalone C++ command line programs into powerful [WebAssembly](https://webassembly.org/) (WASM) modules with a simple, efficient interface for execution in the browser, other programming languages, and on the command line.
+
+First, let's create a new directory to house our project.
+
+```sh
+mkdir HelloPipeline
+cd HelloPipeline
+```
+
+Let's write some code! Populate *HelloPipeline.cxx* first with the headers we need:
+
+```c++
+#include "itkPipeline.h"
+#include "itkInputImage.h"
+#include "itkImage.h"
+```
+
+The *itkImage.h* header is [ITK](https://itk.org)'s standard n-dimensional image data structure.
+
+The *itkPipeline.h* and *itkInputImage.h* headers come from the itk-wasm *WebAssemblyInterface* [ITK module](https://www.kitware.com/advance-itk-with-modules/).
+
+Next, create a standard `main` C command line interface function and an `itk::wasm::Pipeline`:
+
+
+```c++
+int main(int argc, char * argv[]) {
+  // Create the pipeline for parsing arguments. Provide a description.
+  itk::wasm::Pipeline pipeline("A hello world itk::wasm::Pipeline", argc, argv);
+
+  return EXIT_SUCCESS;
+}
+```
+
+The `itk::wasm::Pipeline` extends the most-excellent [CLI11 modern C++ command line parser](https://github.com/CLIUtils/CLI11). 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`'s, `Mesh`'s, `PolyData`, and `Transform`'s
+- Support for multiple dimensions and pixel types
+- Colored help output
+
+Add a standard CLI11 flag to the pipeline:
+
+```c++
+  itk::wasm::Pipeline 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:
+
+```c++
+  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("InputImage", inputImage, "The input image")->required();
+```
+
+The `inputImage` variable is populated from the filesystem if built as a native executable. 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:
+
+```c++
+  pipeline.add_option("InputImage", inputImage, "The input image")->required();
+
+
+  ITK_WASM_PARSE(pipeline);
+```
+
+This parses the command line arguments. 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 our pipeline: 
+```c++
+  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](https://cmake.org/) build configuration at *CMakeLists.txt*:
+
+```cmake
+cmake_minimum_required(VERSION 3.16)
+project(HelloPipeline)
+
+# 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(HelloPipeline HelloPipeline.cxx)
+target_link_libraries(HelloPipeline PUBLIC ${ITK_LIBRARIES})
+```
+
+[Build the WASI binary](../hello_world.html):
+
+```sh
+npx itk-wasm -i itkwasm/wasi build
+```
+
+Check the generated help output:
+
+```sh
+npx itk-wasm run HelloPipeline.wasi.wasm -- -- --help
+```
+
+![Hello pipeline help](./hello_pipeline.png)
+
+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](https://bafybeihibtxtdmwuekb64wnv3ras54lz4ojuqv4gabmigpfdha4dsmcr5y.ipfs.w3s.link/ipfs/bafybeihibtxtdmwuekb64wnv3ras54lz4ojuqv4gabmigpfdha4dsmcr5y/cthead1.png).
+
+```
+> npx itk-wasm run HelloPipeline.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 run HelloPipeline.wasi.wasm -- -- --quiet cthead1.png
+
+Hello pipeline world!
+```
+
+Congratulations! You just executed a C++ pipeline capable of processsing a scientific image in WebAssembly. 🎉

doc/content/examples/hello_pipeline.png

@@ -1,16 +1,16 @@
 title: Hello WASM World!
 ---
 
-This example, walks through how to compile a *hello world* executable written in C++ to [WebAssembly](https://webassembly.org/) and how execute it with standalone WebAssembly runtimes, the Node.js JavaScript runtime, and web browser runtimes!
+This example walks through how to compile a *hello world* executable written in C++ to [WebAssembly](https://webassembly.org/) and how execute it with standalone WebAssembly runtimes, the Node.js JavaScript runtime, and web browser runtimes!
 
 Before getting started, make sure [Node.js](https://nodejs.org/en/download/) and [Docker](https://docs.docker.com/install/) are installed. On Linux, make sure you can run [`docker` without `sudo`](https://askubuntu.com/questions/477551/how-can-i-use-docker-without-sudo). On Windows, we recommend [WSL 2 with Docker enabled](https://docs.docker.com/desktop/windows/wsl/).
 
 
 First, let's create a new directory to house our project.
 
 ```sh
-mkdir itk-wasm-hello-world
-cd itk-wasm-hello-world
+mkdir HelloWorld
+cd HelloWorld
 ```
 
 Let's write some code! Populate *hello.cxx* with our Hello World program:

doc/content/examples/hello_world.md

@@ -44,6 +44,7 @@ sidebar:
     recipes: Recipes
     examples: Examples
     hello_world: Hello World!
+    hello_pipeline: Hello Pipeline!
     vue: Vue.js
 
   api:

doc/tpl/__en__

@@ -11,6 +11,7 @@ docs:
 examples:
   getting_started:
     hello_world: hello_world.html
+    hello_pipeline: hello_pipeline.html
     debugging: debugging.html
   recipes:
     vue: paraview_glance.html

doc/tpl/__sidebar__

@@ -0,0 +1,4 @@
+itk-wasm-hello-world
+wasi-build
+cypress/support
+cypress/videos/

examples/HelloPipeline/.gitignore

@@ -0,0 +1,30 @@
+cmake_minimum_required(VERSION 3.16)
+project(HelloPipeline)
+
+# 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(HelloPipeline HelloPipeline.cxx)
+target_link_libraries(HelloPipeline PUBLIC ${ITK_LIBRARIES})

examples/HelloPipeline/CMakeLists.txt

@@ -0,0 +1,53 @@
+/*=========================================================================
+ *
+ *  Copyright NumFOCUS
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *         https://www.apache.org/licenses/LICENSE-2.0.txt
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *=========================================================================*/
+#include "itkPipeline.h"
+#include "itkInputImage.h"
+#include "itkImage.h"
+
+int main(int argc, char * argv[]) {
+  // Create the pipeline for parsing arguments. Provide a description.
+  itk::wasm::Pipeline pipeline("A hello world itk::wasm::Pipeline", argc, argv);
+
+  // Add a flag to the pipeline.
+  bool quiet = false;
+  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("InputImage", inputImage, "The input image")->required();
+
+  // Parse the arguments. If `-q` or `--quiet` is set, the `quiet` variable will be set to `true`.
+  // The `inputImage` variable is populated from the filesystem if built as a native executable.
+  // When running in the browser or in a wrapped language, `inputImage` is read from WebAssembly memory without file IO.
+  ITK_WASM_PARSE(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;
+}