Hello world example

.circleci/config.yml

@@ -98,6 +98,19 @@ jobs:
             npm run build
             npm run test
 
+  build-test-nodejs-hello-world-example:
+    machine: true
+    steps:
+      - checkout
+      - run:
+          name: Test Node.js Hello World examlpe
+          no_output_timeout: 0.5h
+          command: |
+            cd examples/Node.jsHelloWorld
+            npm install
+            npm run build
+            npm run test
+
 workflows:
     version: 2
     build-test-deploy:
@@ -115,3 +128,5 @@ workflows:
             <<: *ignore-ghpages
         - build-test-unpkgio-example:
             <<: *ignore-ghpages
+        - build-test-nodejs-hello-world-example:
+            <<: *ignore-ghpages

.gitignore

@@ -20,6 +20,8 @@ yarn.lock
 
 examples/Node.js/logo.tif
 examples/Node.js/package-lock.json
+examples/Node.jsHelloWorld/web-build
+examples/Node.jsHelloWorld/package-lock.json
 
 test/BinShrinkPipeline/itk-js
 test/BinShrinkPipeline/web-build
@@ -28,4 +30,3 @@ src/Docker/itk-js/ITKBridgeJavaScriptModuleCopy/
 test/StdoutStderrPipeline/itk-js
 test/StdoutStderrPipeline/web-build/
 test/InputOutputFilesPipeline/web-build/
-

doc/content/api/browser_pipelines.md

@@ -0,0 +1,4 @@
+title: Web Browser Processing Pipelines
+---
+
+Documentation forthcoming.

doc/content/api/index.md

@@ -2,3 +2,13 @@ title: API
 ---
 
 This documentation provides more detailed information about the *itk.js* API.
+
+The **Input/Output** section describes functions that facilitate reading and
+writing data from the local filesystem, if working in Node.js, or from native
+browser data types, encountered when working in the web browser.
+
+The **Processing Pipelines** section describes dow to execute processing
+pipelines written as C/C++ command line executables in Node.js or the browser.
+
+The **Data Structures** section describes data structures produced and consumed
+by both the *Input/Output* and *Processing Pipelines* functions.

doc/content/api/node.md → doc/content/api/node_io.md

@@ -3,7 +3,7 @@ title: Node.js Input/Output
 
 These Input/Output (IO) functions can be used from within a [Node.js](https://nodejs.org/) application or library on a workstation or server. They will read from and write to directories on the local filesystem.
 
-Similar to the [web browser API](./browser.html), most of these functions return a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
+Similar to the [web browser API](./browser_io.html), most of these functions return a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
 
 ---
 

doc/content/api/node_pipelines.md

@@ -0,0 +1,26 @@
+title: Node.js Processing Pipelines
+---
+
+These processing pipeline execution functions can be used from within a [Node.js](https://nodejs.org/) application or library on a workstation or server.
+
+Similar to the [web browser API](./browser_pipelines.html), most of these functions return a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
+
+---
+
+## runPipelineNode(pipelinePath, args, outputs, inputs) -> result
+
+Read an itk.js Emscripten module with Node.js.
+
+*pipelinePath*: Path the the built module, without `.js` or `Wasm.js` extensions.
+
+*args*:         A JavaScript Array of strings to pass to the execution of the `main` function, i.e. arguments that would be passed on the command line to a native executable.
+
+*outputs*:      A JavaScript Array containing JavaScript objects with two properties: `path` and `type`.
+                `path` is the file path on the virtual filesystem to read after execution has completed.
+                `type` is one of the `itk/IOTypes`, i.e. `IOTypes.Text`, `IOTypes.Binary`, `ITKTypes.Image`, or `ITKTypes.Mesh` to read as an UTF8-encoded string, binary `Uint8Array`, [`itk/Image`](./Image.html), or [`itk/Mesh`](./Mesh.html), respectively.
+
+*inputs*:       A JavaScript Array containing JavaScript objects with three properties: `path`, `type`, and `data`.
+                `path` and `type` are the same as *outputs*, while `data` contains the corresponding data to write to the virtual filesystem before executing the module.
+
+*result*:       A JavaScript object with three properties: `stdout`, `stderr`, and `outputs`.
+                `stdout` and `stderr` are strings. `outputs` is an array with `{ path, type, data }` contents corresponding to the values specified in the function call.

doc/content/docs/installation.md

@@ -8,5 +8,5 @@ npm install --save itk
 ```
 
 For more information on build configuration, see how to use *itk.js* [in a
-Node.js server application](../examples/node.html) or in an application that
+Node.js server application](../examples/node_io.html) or in an application that
 [targets the web browser with Webpack](../examples/webpack.html).

doc/content/examples/hello_world_node.md

@@ -0,0 +1,81 @@
+title: Node.js Hello World!
+---
+
+This example, walks through how to complie a *hello world* executable written in C++ to JavaScript and execute it with the [Node.js](https://nodejs.org/) runtime!
+
+Before getting started, make sure [Node.js](https://nodejs.org/en/download/) and [Docker](https://docs.docker.com/install/) are installed.
+
+First, let's create a new folder to house our project.
+
+```
+mkdir Node.jsHelloWorld
+cd Node.jsHelloWorld
+```
+
+Initialize the Node *package.json* file:
+
+```
+npm init --yes
+```
+
+Add `itk` and [`fs-extra`](https://www.npmjs.com/package/fs-extra) to your project's dependencies:
+
+```
+npm install --save itk fs-extra
+```
+
+Let's write some code! Populate *hello.cxx* with our Hello World program:
+
+```
+#include <iostream>
+
+int main() {
+  std::cout << "Hello world!" << std::endl;
+  return 0;
+}
+```
+
+Next, provide a [CMake](https://cmake.org/) build configuration at *CMakeLists.txt*:
+
+```
+cmake_minimum_required(VERSION 3.10)
+project(HelloWorld)
+
+set(hello_SRCS hello.cxx)
+if(EMSCRIPTEN)
+  include(ITKBridgeJavaScript)
+  web_add_executable(hello ${hello_SRCS})
+else()
+  add_executable(hello ${hello_SRCS})
+endif()
+```
+
+We use the `web_add_executable` command to build executables with itk.js. This command is provided by the `ITKBridgeJavaScript` CMake module. This module, along with the [Emscripten](https://kripken.github.io/emscripten-site/) toolchain, is contained in the itk.js [dockcross](https://github.com/dockcross/dockcross) Docker image.
+
+The same code can also be build and tested with native build tools by using the standard `add_executable` CMake command.
+
+Next, build the program with the itk.js CLI, `itk-js`. This is shipped with the `itk` package, and can be executed from the local *node_modules* folder with [`npx`](https://www.npmjs.com/package/npx). The `itk-js` CLI will invoke the toolchain contained in the dockcross Docker image. Pass the local source code directory into `itk-js build` to perform the build.
+
+```
+npx itk-js build .
+```
+
+The project is built in `./web-build`.
+
+To execute the project, create an `index.js` file to [invoke the module](../api/node_pipelines.html):
+
+```
+const path = require('path')
+const runPipelineNode = require('itk/runPipelineNode')
+
+const pipelinePath = path.resolve(__dirname, 'web-build', 'hello')
+runPipelineNode(pipelinePath)
+```
+
+And run it!
+
+```
+npx node ./index.js
+```
+
+Congratulations! You just executed a C++ program compiled to JavaScript. 🎉

doc/content/examples/index.md

@@ -2,3 +2,9 @@ title: Examples
 ---
 
 These examples demonstrate how to apply *itk.js* in your application.
+
+The **Building** section details the processing of building your **itk.js**
+application with Node.js.
+
+The **Tasks** section provides simple demonstrations of how to achieve
+common tasks.

doc/content/examples/node.md

@@ -26,7 +26,7 @@ This adds `itk` to the `dependencies` section of your *package.json* file:
 }
 ```
 
-Next, call functions like [itk/readImageLocalFile](../api/node.html) or [itk/writeImageLocalFile](../api/node.html).
+Next, call functions like [itk/readImageLocalFile](../api/node_io.html) or [itk/writeImageLocalFile](../api/node_io.html).
 
 For example,
 

doc/tpl/__en__

@@ -38,11 +38,16 @@ sidebar:
     nodejs: Node.js
     webpack: Webpack
     unpkgio: Unpkg.com / CDN
+    tasks: Tasks
+    hello_node: Node.js Hello World!
 
   api:
     inputoutput: Input/Output
-    nodejs: Node.js
-    browser: Web Browser
+    nodejs_io: Node.js
+    browser_io: Web Browser
+    pipelines: Processing Pipelines
+    nodejs_pipelines: Node.js
+    browser_pipelines: Web Browser
     datastructures: Data Structures
     image: Image
     imagetype: ImageType

doc/tpl/__sidebar__

@@ -12,11 +12,16 @@ examples:
     nodejs: node.html
     webpack: webpack.html
     unpkgio: unpkgio.html
+  tasks:
+    hello_node: hello_world_node.html
 
 api:
   inputoutput:
-    nodejs: node.html
-    browser: browser.html
+    nodejs_io: node_io.html
+    browser_io: browser_io.html
+  pipelines:
+    nodejs_pipelines: node_pipelines.html
+    browser_pipelines: browser_pipelines.html
   datastructures:
     image: Image.html
     imagetype: ImageType.html

examples/Node.jsHelloWorld/CMakeLists.txt

@@ -0,0 +1,10 @@
+cmake_minimum_required(VERSION 3.10)
+project(HelloWorld)
+
+set(hello_SRCS hello.cxx)
+if(EMSCRIPTEN)
+  include(ITKBridgeJavaScript)
+  web_add_executable(hello ${hello_SRCS})
+else()
+  add_executable(hello ${hello_SRCS})
+endif()

examples/Node.jsHelloWorld/hello.cxx

@@ -0,0 +1,6 @@
+#include <iostream>
+
+int main() {
+  std::cout << "Hello world!" << std::endl;
+  return 0;
+}

examples/Node.jsHelloWorld/index.js

@@ -0,0 +1,5 @@
+const path = require('path')
+const runPipelineNode = require('itk/runPipelineNode')
+
+const pipelinePath = path.resolve(__dirname, 'web-build', 'hello')
+runPipelineNode(pipelinePath)

examples/Node.jsHelloWorld/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "itk-hello-world-node",
+  "version": "1.0.0",
+  "description": "An itk.js Hello World! for Node",
+  "main": "index.js",
+  "scripts": {
+    "build": "itk-js build .",
+    "test": "node ./index.js"
+  },
+  "author": "Matt McCormick <matt.mccormick@kitware.com>",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "fs-extra": "^7.0.1",
+    "itk": "^9.1.2"
+  }
+}