Ci e2e flake

.github/workflows/checks.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-20.04
     name: Code check and tests
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Setup node
         uses: actions/setup-node@v1
         with:

.github/workflows/e2e.yml

@@ -12,9 +12,12 @@ jobs:
     env:
       DOWNLOAD_TIMEOUT: 60000
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+      - name: Install node-canvas deps (macos)
+        if: matrix.os != 'ubuntu-20.04'
+        run: brew install pkg-config cairo pango libpng jpeg giflib librsvg pixman
       - name: Install dependencies
         run: npm ci
         env:
@@ -34,9 +37,9 @@ jobs:
         run: npm run test:e2e:chrome
       - name: Archive test results
         if: success() || failure()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         continue-on-error: true
         with:
-          name: image_comparison_results
+          name: image_comparison_results_${{ matrix.os }}
           path: .tmp
           retention-days: 5

.github/workflows/publish.yml

@@ -33,11 +33,11 @@ jobs:
       - name: Install dependencies
         run: npm ci
       - name: Build docs
-        run: npm run doc
+        run: npm run docs:build
       - name: Upload pages artifact
         uses: actions/upload-pages-artifact@v1
         with:
-          path: './documentation/build-tmp/public'
+          path: './docs/.vitepress/dist'
 
   deploy:
     name: Deploy Docs

README.md

@@ -1,6 +1,6 @@
 # VolView
 
-![A screenshot of a sample VolView session](./documentation/content/gallery/VolView-Overview.jpg)
+![A screenshot of a sample VolView session](./docs/assets/VolView-Overview.jpg)
 
 ## Try it
 

docs/.gitignore

@@ -0,0 +1,2 @@
+.vitepress/dist
+.vitepress/cache

docs/.vitepress/config.ts

@@ -0,0 +1,66 @@
+import { defineConfig } from 'vitepress';
+
+const GA_ID = 'G-MH4N62W0Z9';
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: 'VolView',
+  base: '/VolView',
+  description:
+    'Open-source and freely available radiological viewer that runs in your web browser and provide photo-realistic, interactive, 3D visualizations.',
+
+  ignoreDeadLinks: 'localhostLinks',
+
+  head: [
+    ['link', { rel: 'icon', href: '/favicon.ico' }],
+    [
+      'script',
+      {
+        async: 'true',
+        src: `https://www.googletagmanager.com/gtag/js?id=${GA_ID}`,
+      },
+    ],
+    [
+      'script',
+      {},
+      `window.dataLayer = window.dataLayer || [];\nfunction gtag(){dataLayer.push(arguments);}\ngtag('js', new Date());\ngtag('config', '${GA_ID}');`,
+    ],
+  ],
+
+  themeConfig: {
+    logo: './logo.svg',
+    nav: [{ text: 'Live Demo', link: 'https://volview.kitware.app' }],
+
+    sidebar: [
+      {
+        text: 'Introduction',
+        items: [
+          { text: 'What is VolView?', link: '/' },
+          { text: 'Quick Start Guide', link: '/quick_start_guide' },
+          { text: 'Screenshots', link: '/gallery' },
+        ],
+      },
+      {
+        text: 'Features & Operation',
+        items: [
+          { text: 'Welcome Screen', link: '/welcome_screen' },
+          { text: 'Loading Data', link: '/loading_data' },
+          { text: 'Toolbar', link: '/toolbar' },
+          { text: 'Mouse/Keyboard Controls', link: '/mouse_controls' },
+          { text: 'Cinematic Rendering', link: '/rendering' },
+          { text: 'State Files', link: '/state_files' },
+          { text: 'Remote Server Capabilities', link: '/server' },
+          { text: 'Configuration File', link: '/configuration_file' },
+        ],
+      },
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/Kitware/VolView' },
+    ],
+
+    footer: {
+      copyright: 'Copyright © 2020-PRESENT <strong>Kitware, Inc.</strong>',
+    },
+  },
+});

docs/.vitepress/theme/custom.css

@@ -0,0 +1,18 @@
+.gallery {
+  margin-top: 8px;
+}
+
+.gallery img {
+  width: 32%;
+  display: inline-block;
+  padding: 5px;
+}
+
+.gallery br {
+  display: none;
+}
+
+footer.VPFooter {
+  display: block !important;
+  border: none !important;
+}

docs/.vitepress/theme/index.ts

@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme';
+import './custom.css';
+
+export default DefaultTheme;

documentation/content/doc/configuration_file.md → docs/configuration_file.md

@@ -1,6 +1,6 @@
 # Configuration JSON File
 
-By loading a JSON file, you can set VolView's:
+By loading a JSON file, you can set VolView's configuration:
 
 - Starting view layout (Axial Only, 3D Primary, etc).
 - Labels for tools
@@ -49,10 +49,28 @@ VolView will include in the volview.zip file.
 }
 ```
 
-These are the supported file formats:
+Working segment group file formats:
 
 hdf5, iwi.cbor, mha, nii, nii.gz, nrrd, vtk
 
+## Automatic Segment Groups by File Name
+
+When loading files, VolView can automatically convert images to segment groups
+if they follow a naming convention. For example, an image with name like `foo.segmentation.bar`
+will be converted to a segment group for a base image named like `foo.baz`.  
+The `segmentation` extension is defined by the `io.segmentGroupExtension` key, which takes a
+string. Files `foo.[segmentGroupExtension].bar` will be automatilly converted to segment groups for a base image named `foo.baz`. The default is `''` and will disable the feature.
+
+This will define `myFile.seg.nrrd` as a segment group for a `myFile.nii` base file.
+
+```json
+{
+  "io": {
+    "segmentGroupExtension": "seg"
+  }
+}
+```
+
 ## Keyboard Shortcuts
 
 Configure the keys to activate tools, change selected labels, and more.

docs/gallery.md

@@ -0,0 +1,41 @@
+# Screenshot Gallery
+
+<div class="gallery">
+<a href="./assets/VolView-Overview.jpg"><img alt="Overview" src="./assets/VolView-Overview.jpg"></a>
+<a href="./assets/01-volview-welcome.jpg"><img alt="Welcome" src="./assets/01-volview-welcome.jpg"></a>
+<a href="./assets/01-volview-welcome-notes.jpg"><img alt="Welcome notes" src="./assets/01-volview-welcome-notes.jpg"></a>
+<a href="./assets/02-volview-about.jpg"><img alt="About" src="./assets/02-volview-about.jpg"></a>
+<a href="./assets/02-volview-notifications.jpg"><img alt="Notifications" src="./assets/02-volview-notifications.jpg"></a>
+<a href="./assets/02-volview-settings.jpg"><img alt="Settings" src="./assets/02-volview-settings.jpg"></a>
+<a href="./assets/03-volview-sample-datasets.jpg"><img alt="Sample datasets" src="./assets/03-volview-sample-datasets.jpg"></a>
+<a href="./assets/04-volview-active-data.jpg"><img alt="Active data" src="./assets/04-volview-active-data.jpg"></a>
+<a href="./assets/05-volview-select-data-to-delete.jpg"><img alt="Select data to delete" src="./assets/05-volview-select-data-to-delete.jpg"></a>
+<a href="./assets/06-volview-corner-annotation.jpg"><img alt="Corner annotation" src="./assets/06-volview-corner-annotation.jpg"></a>
+<a href="./assets/07-volview-layout.jpg"><img alt="Layout" src="./assets/07-volview-layout.jpg"></a>
+<a href="./assets/09-volview-layout-3DPrimary.jpg"><img alt="3D primary" src="./assets/09-volview-layout-3DPrimary.jpg"></a>
+<a href="./assets/10-volview-wl-pan-zoom.jpg"><img alt="W/L Pan Zoom" src="./assets/10-volview-wl-pan-zoom.jpg"></a>
+<a href="./assets/10-volview-wl-pan-zoom-notes.jpg"><img alt="W/L Pan Zoom notes" src="./assets/10-volview-wl-pan-zoom-notes.jpg"></a>
+<a href="./assets/11-volview-paint.jpg"><img alt="Paint" src="./assets/11-volview-paint.jpg"></a>
+<a href="./assets/11-volview-paint-notes.jpg"><img alt="Paint notes" src="./assets/11-volview-paint-notes.jpg"></a>
+<a href="./assets/12-volview-paint-options.jpg"><img alt="Paint options" src="./assets/12-volview-paint-options.jpg"></a>
+<a href="./assets/13-volview-crop.jpg"><img alt="Crop" src="./assets/13-volview-crop.jpg"></a>
+<a href="./assets/14-volview-ruler.jpg"><img alt="Ruler" src="./assets/14-volview-ruler.jpg"></a>
+<a href="./assets/15-volview-crosshairs.jpg"><img alt="Crosshairs" src="./assets/15-volview-crosshairs.jpg"></a>
+<a href="./assets/16-volview-rendering.jpg"><img alt="Rendering" src="./assets/16-volview-rendering.jpg"></a>
+<a href="./assets/17-volview-colormap.jpg"><img alt="Colormap" src="./assets/17-volview-colormap.jpg"></a>
+<a href="./assets/17-volview-colormap-notes.jpg"><img alt="Colormap notes" src="./assets/17-volview-colormap-notes.jpg"></a>
+<a href="./assets/17-volview-opacity.jpg"><img alt="Opacity" src="./assets/17-volview-opacity.jpg"></a>
+<a href="./assets/17-volview-opacity-notes.jpg"><img alt="Opacity notes" src="./assets/17-volview-opacity-notes.jpg"></a>
+<a href="./assets/17-volview-opacity2.jpg"><img alt="Opacity 2" src="./assets/17-volview-opacity2.jpg"></a>
+<a href="./assets/18-volview-presets.jpg"><img alt="Presets" src="./assets/18-volview-presets.jpg"></a>
+<a href="./assets/19-volview-color.jpg"><img alt="Color" src="./assets/19-volview-color.jpg"></a>
+<a href="./assets/19-volview-color2.jpg"><img alt="Color 2" src="./assets/19-volview-color2.jpg"></a>
+<a href="./assets/20-volview-lightfollowcamera0.jpg"><img alt="Light follows camera 0" src="./assets/20-volview-lightfollowcamera0.jpg"></a>
+<a href="./assets/20-volview-lightfollowcamera1.jpg"><img alt="Light follows camera 1" src="./assets/20-volview-lightfollowcamera1.jpg"></a>
+<a href="./assets/20-volview-lightfollowcamera2.jpg"><img alt="Light follows camera 2" src="./assets/20-volview-lightfollowcamera2.jpg"></a>
+<a href="./assets/20-volview-lightfollowcamera3.jpg"><img alt="Light follows camera 3" src="./assets/20-volview-lightfollowcamera3.jpg"></a>
+<a href="./assets/21-volview-hybrid0.0.jpg"><img alt="Hybrid @ 0.0" src="./assets/21-volview-hybrid0.0.jpg"></a>
+<a href="./assets/21-volview-hybrid0.5.jpg"><img alt="Hybrid @ 0.5" src="./assets/21-volview-hybrid0.5.jpg"></a>
+<a href="./assets/21-volview-hybrid1.0.jpg"><img alt="Hybrid @ 1.0" src="./assets/21-volview-hybrid1.0.jpg"></a>
+<a href="./assets/21-volview-hybrid-final.jpg"><img alt="Hybrid final" src="./assets/21-volview-hybrid-final.jpg"></a>
+</div>

documentation/content/doc/index.md → docs/index.md

@@ -1,9 +1,8 @@
-title: What is VolView?
-----
+# What is VolView?
 
 VolView is an open source radiological viewer developed for clinical professionals. With VolView, you can gain a deeper understanding of your data through high-quality, interactive visualizations, including cinematic volume renderings. Since VolView runs in your browser, you do not need to install software, and your data stays securely on your machine.
 
-![Welcome](../gallery/VolView-Overview.jpg)
+![Welcome](./assets/VolView-Overview.jpg)
 
 ## Features
 

documentation/content/doc/loading_data.md → docs/loading_data.md

@@ -66,4 +66,4 @@ To layer images:
 1. On the Data tab, click the Add Layer button on the upper layer dataset.
 1. Under the Rendering tab, an opacity slider changes the transparency of the upper layer.
 
-![Add Layer](../images/add-layer.jpg)
+![Add Layer](./assets/add-layer.jpg)

documentation/content/doc/mouse_controls.md → docs/mouse_controls.md

@@ -1,11 +1,5 @@
 # Keyboard shortcuts
 
-<style>
-table {
-  width: 100%;
-}
-</style>
-
 ## Data management
 
 | Shortcut | Action |

documentation/content/doc/quick_start_guide.md → docs/quick_start_guide.md

@@ -1,15 +1,8 @@
-title: Quick Start Guide
-----
-
-<style>
-table {
-  width: 100%;
-}
-</style>
+# Quick Start Guide
 
 The Welcome screen for VolView is annotated in the image shown below. More information on the components of the welcome screen is provided in the ["Welcome Screen"](welcome_screen.html) documentation.
 
-![Welcome](../gallery/01-volview-welcome-notes.jpg)
+![Welcome](./assets/01-volview-welcome-notes.jpg)
 
 Starting from the welcome screen, there are four simple constructs needed to generate stunning and insightful visualizations from DICOM data.
 1. Loading data
@@ -36,13 +29,13 @@ VolView can also load many other image data formats.  To learn more, see the doc
 
 The three main radiological controls are as following:
 
-* Layout: This toolbar button is illustrated below. Use it to choose between four useful window arrangements.  As in all things, if you have a particular layout that you would like to see added, please make a feature request on our ["issue tracker"](https://github.com/Kitware/VolView/issues).  ![Layout](../gallery/07-volview-layout-notes.jpg)
+* Layout: This toolbar button is illustrated below. Use it to choose between four useful window arrangements.  As in all things, if you have a particular layout that you would like to see added, please make a feature request on our [issue tracker](https://github.com/Kitware/VolView/issues).  ![Layout](./assets/07-volview-layout-notes.jpg)
 
-* 2D Left mouse button: Window / Level, Pan, Zoom, or Crosshairs: Select these options to control the function of the left mouse button in the 2D windows.  ![Window-Level, Pan, Zoom, Crosshairs](../gallery/10-volview-wl-pan-zoom-notes.jpg)
+* 2D Left mouse button: Window / Level, Pan, Zoom, or Crosshairs: Select these options to control the function of the left mouse button in the 2D windows.  ![Window-Level, Pan, Zoom, Crosshairs](./assets/10-volview-wl-pan-zoom-notes.jpg)
 
-* 2D Annotations: Paint and Ruler: When the ruler tool selected, the left mouse button is used to place and adjust ruler end-markers.  Right clicking on a end-marker displays a pop-up menu for deleting that ruler.  Switch to the "Annotations" tab to see a list of annotations made to currently loaded data.  Select the location icon next to a listed ruler to jump to its slice.  Select the trashcan to delete that ruler.  When the paint tool is selected, you can paint in any 2D window.  Click on the paint tool a second time to bring up a menu of colors and adjust the brush size. ![Paint and Ruler](../gallery/11-volview-paint-notes.jpg)
+* 2D Annotations: Paint and Ruler: When the ruler tool selected, the left mouse button is used to place and adjust ruler end-markers.  Right clicking on a end-marker displays a pop-up menu for deleting that ruler.  Switch to the "Annotations" tab to see a list of annotations made to currently loaded data.  Select the location icon next to a listed ruler to jump to its slice.  Select the trashcan to delete that ruler.  When the paint tool is selected, you can paint in any 2D window.  Click on the paint tool a second time to bring up a menu of colors and adjust the brush size. ![Paint and Ruler](./assets/11-volview-paint-notes.jpg)
 
-* 3D Crop: Select this tool to adjust the extent of data shown in the 3D rendering.  In the 3D window you can pick and move the corner, edge, and side markers to make adjustments.  In the 2D windows, grab and move the edges of the bounding box overlaid on the data. ![Crop](../gallery/13-volview-crop.jpg)
+* 3D Crop: Select this tool to adjust the extent of data shown in the 3D rendering.  In the 3D window you can pick and move the corner, edge, and side markers to make adjustments.  In the 2D windows, grab and move the edges of the bounding box overlaid on the data. ![Crop](./assets/13-volview-crop.jpg)
 
 [***Watch the video!***](https://youtu.be/Bj4ijh_VLUQ)
 
@@ -53,15 +46,15 @@ For information on the toolbar, see the documentation on ["Mouse controls"](mous
 
 VolView reads the DICOM tags of your data to determine appropriate preset parameter values for cinematic volume rendering for your data, but often you will want to tweak those presets to emphasize specific details.  We recommend the following sequence of tweaks to improve your visualizations.
 
-1. Cinematic volume rendering involves two "transfer functions": one maps the recorded intensity values (e.g., CT hounsfield units) to opacity and the other maps recorded intensity values to color.   Both can be adjusted using the controls at the top of the Rendering tab.   The graph at the top shows a histogram of the recorded intensity values in light gray and the current opacity transfer function as an overlaid curve in black.  In that graph, beneath the black curve, is a depiction of the color transfer function. ![Cinematic](../gallery/16-volview-rendering.jpg)
-    a. Begin by adjusting the opacity transfer function by a press-and-drag right/left on the top graph.  ![Opacity](../gallery/17-volview-opacity-notes.jpg)
-    b. Then adjust the color transfer function by moving the blue dots on the colorbar beneath the graph.  ![Color](../gallery/17-volview-colormap-notes.jpg)
+1. Cinematic volume rendering involves two "transfer functions": one maps the recorded intensity values (e.g., CT hounsfield units) to opacity and the other maps recorded intensity values to color.   Both can be adjusted using the controls at the top of the Rendering tab.   The graph at the top shows a histogram of the recorded intensity values in light gray and the current opacity transfer function as an overlaid curve in black.  In that graph, beneath the black curve, is a depiction of the color transfer function. ![Cinematic](./assets/16-volview-rendering.jpg)
+    a. Begin by adjusting the opacity transfer function by a press-and-drag right/left on the top graph.  ![Opacity](./assets/17-volview-opacity-notes.jpg)
+    b. Then adjust the color transfer function by moving the blue dots on the colorbar beneath the graph.  ![Color](./assets/17-volview-colormap-notes.jpg)
 
-2. You may decide that the colormaps and/or transfer function aren't suitable for your data.  Click on the "Presets" bar to expand and show the available presets that offer alternative opacity and color transfer functions. ![Presets](../gallery/18-volview-presets.jpg)
+2. You may decide that the colormaps and/or transfer function aren't suitable for your data.  Click on the "Presets" bar to expand and show the available presets that offer alternative opacity and color transfer functions. ![Presets](./assets/18-volview-presets.jpg)
 3. Next, the lighting can be controlled.  
     a. Ambient lighting is the general brightness of the scene.  
     b. Diffuse lighting controls how the light reflects off the data.  It is influenced by the position of the light relative to the orientation of the data's local surface.
-    c. Light-follows-camera can be enabled / disabled to create shadows that highlights details within the data.  When enabled, the light will be positioned in-line with the camera.   When disabled, the last position of the light stays fixed relative to the data, even if the camera is moved. With light-follows-camera enabled, here is a view when the light is following the camera: ![Default Lighting](../gallery/20-volview-lightfollowcamera1.jpg)  By moving the camera (and thereby the light) to the front of the data and then disabling light-follows-camera, the view should look light this: ![Light Setup](../gallery/20-volview-lightfollowcamera2.jpg)  Then moving back to the side view will show shadows that emphasize depth and details: ![Shadows](../gallery/20-volview-lightfollowcamera3.jpg)
+    c. Light-follows-camera can be enabled / disabled to create shadows that highlights details within the data.  When enabled, the light will be positioned in-line with the camera.   When disabled, the last position of the light stays fixed relative to the data, even if the camera is moved. With light-follows-camera enabled, here is a view when the light is following the camera: ![Default Lighting](./assets/20-volview-lightfollowcamera1.jpg)  By moving the camera (and thereby the light) to the front of the data and then disabling light-follows-camera, the view should look light this: ![Light Setup](./assets/20-volview-lightfollowcamera2.jpg)  Then moving back to the side view will show shadows that emphasize depth and details: ![Shadows](./assets/20-volview-lightfollowcamera3.jpg)
 
 4. Advanced, you can also explore alternative cinematic rendering methods.  Detailed documentation will soon follow that describes these methods and demonstrates their utility for various types of medical data.
     a. Standard