feat: add automatic layering by file name for non-DICOM images

Implements automatic layering based on file name patterns.
When loading files with matching names like base-image.nii and base-image.layer.nii, the layer file is automatically placed on top of the base image.

Author: PaulHax

docs/configuration_file.md

@@ -181,15 +181,15 @@ Working segment group file formats:
 
 hdf5, iwi.cbor, mha, nii, nii.gz, nrrd, vtk
 
-## Automatic Segment Groups by File Name
+## Automatic Layers and 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.
+When loading multiple files, VolView can automatically associate related images based on file naming patterns.
+Files matching `base.[extension].format` will be associated with a base image named `base.format`.
+Both features default to `''` which disables them.
 
-This will define `myFile.seg.nrrd` as a segment group for a `myFile.nii` base file.
+### Segment Groups
+
+Use `segmentGroupExtension` to automatically convert matching non-DICOM images to segment groups. For example, `myFile.seg.nrrd` becomes a segment group for `myFile.nii`:
 
 ```json
 {
@@ -199,6 +199,18 @@ This will define `myFile.seg.nrrd` as a segment group for a `myFile.nii` base fi
 }
 ```
 
+### Layering
+
+Use `layerExtension` to automatically layer matching non-DICOM images on top of the base image. For example, `myImage.layer.nii` is layered on top of `myImage.nii`:
+
+```json
+{
+  "io": {
+    "layerExtension": "layer"
+  }
+}
+```
+
 ## Keyboard Shortcuts
 
 Configure the keys to activate tools, change selected labels, and more.
@@ -285,7 +297,9 @@ To configure a key for an action, add its action name and the key(s) under the `
     "showKeyboardShortcuts": "t"
   },
   "io": {
-    "segmentGroupSaveFormat": "nrrd"
+    "segmentGroupSaveFormat": "nrrd",
+    "segmentGroupExtension": "seg",
+    "layerExtension": "layer"
   }
 }
 ```

src/actions/loadUserFiles.ts

@@ -80,17 +80,21 @@ function isSegmentation(extension: string, name: string) {
   return extensions.includes(extension);
 }
 
-// does not pick segmentation images
+// does not pick segmentation or layer images
 function findBaseImage(
   loadableDataSources: Array<LoadableResult>,
-  segmentGroupExtension: string
+  segmentGroupExtension: string,
+  layerExtension: string
 ) {
   const baseImages = loadableDataSources
     .filter(({ dataType }) => dataType === 'image')
     .filter((importResult) => {
       const name = getDataSourceName(importResult.dataSource);
       if (!name) return false;
-      return !isSegmentation(segmentGroupExtension, name);
+      return (
+        !isSegmentation(segmentGroupExtension, name) &&
+        !isSegmentation(layerExtension, name)
+      );
     });
 
   if (baseImages.length) return baseImages[0];
@@ -138,13 +142,18 @@ function getStudyUID(volumeID: string) {
 
 function findBaseDataSource(
   succeeded: Array<ImportResult>,
-  segmentGroupExtension: string
+  segmentGroupExtension: string,
+  layerExtension: string
 ) {
   const loadableDataSources = filterLoadableDataSources(succeeded);
   const baseDicom = findBaseDicom(loadableDataSources);
   if (baseDicom) return baseDicom;
 
-  const baseImage = findBaseImage(loadableDataSources, segmentGroupExtension);
+  const baseImage = findBaseImage(
+    loadableDataSources,
+    segmentGroupExtension,
+    layerExtension
+  );
   if (baseImage) return baseImage;
   return loadableDataSources[0];
 }
@@ -164,7 +173,7 @@ function filterOtherVolumesInStudy(
 }
 
 // Layers a DICOM PET on a CT if found
-function loadLayers(
+function autoLayerDicoms(
   primaryDataSource: LoadableVolumeResult,
   succeeded: Array<ImportResult>
 ) {
@@ -190,6 +199,26 @@ function loadLayers(
   layersStore.addLayer(primarySelection, layerSelection);
 }
 
+function autoLayerByName(
+  primaryDataSource: LoadableVolumeResult,
+  succeeded: Array<ImportResult>,
+  layerExtension: string
+) {
+  if (isDicomImage(primaryDataSource.dataID)) return;
+  const matchingLayers = filterMatchingNames(
+    primaryDataSource,
+    succeeded,
+    layerExtension
+  ).filter(isVolumeResult);
+
+  const primarySelection = toDataSelection(primaryDataSource);
+  const layersStore = useLayersStore();
+  matchingLayers.forEach((ds) => {
+    const layerSelection = toDataSelection(ds);
+    layersStore.addLayer(primarySelection, layerSelection);
+  });
+}
+
 // Loads other DataSources as Segment Groups:
 // - DICOM SEG modalities with matching StudyUIDs.
 // - DataSources that have a name like foo.segmentation.bar and the primary DataSource is named foo.baz
@@ -254,19 +283,25 @@ function loadDataSources(sources: DataSource[]) {
     if (succeeded.length && shouldShowData) {
       const primaryDataSource = findBaseDataSource(
         succeeded,
-        loadDataStore.segmentGroupExtension
+        loadDataStore.segmentGroupExtension,
+        loadDataStore.layerExtension
       );
 
       if (isVolumeResult(primaryDataSource)) {
         const selection = toDataSelection(primaryDataSource);
         viewStore.setDataForAllViews(selection);
-        loadLayers(primaryDataSource, succeeded);
+        autoLayerDicoms(primaryDataSource, succeeded);
+        autoLayerByName(
+          primaryDataSource,
+          succeeded,
+          loadDataStore.layerExtension
+        );
         loadSegmentations(
           primaryDataSource,
           succeeded,
           loadDataStore.segmentGroupExtension
         );
-      } // then must be primaryDataSource.type === 'model'
+      } // else must be primaryDataSource.type === 'model', which are not dealt with here yet
     }
 
     if (errored.length) {

src/io/import/configJson.ts

@@ -59,6 +59,7 @@ const io = z
   .object({
     segmentGroupSaveFormat: z.string().optional(),
     segmentGroupExtension: z.string().default(''),
+    layerExtension: z.string().default(''),
   })
   .optional();
 
@@ -145,7 +146,9 @@ const applyIo = (manifest: Config) => {
 
   if (manifest.io.segmentGroupSaveFormat)
     useSegmentGroupStore().saveFormat = manifest.io.segmentGroupSaveFormat;
-  useLoadDataStore().segmentGroupExtension = manifest.io.segmentGroupExtension;
+  const loadDataStore = useLoadDataStore();
+  loadDataStore.segmentGroupExtension = manifest.io.segmentGroupExtension;
+  loadDataStore.layerExtension = manifest.io.layerExtension;
 };
 
 const applyWindowing = (manifest: Config) => {

src/store/load-data.ts

@@ -100,9 +100,11 @@ const useLoadDataStore = defineStore('loadData', () => {
     useLoadingNotifications();
 
   const segmentGroupExtension = ref('');
+  const layerExtension = ref('');
 
   return {
     segmentGroupExtension,
+    layerExtension,
     isLoading,
     startLoading,
     stopLoading,

tests/specs/automatic-layering.e2e.ts

@@ -0,0 +1,36 @@
+import { DOWNLOAD_TIMEOUT } from '@/wdio.shared.conf';
+import { volViewPage } from '../pageobjects/volview.page';
+import { FETUS_DATASET } from './configTestUtils';
+import { writeManifestToFile } from './utils';
+
+describe('Automatic Layering by File Name', () => {
+  it('should automatically layer files matching the layer extension pattern', async () => {
+    const config = {
+      io: {
+        layerExtension: 'layer',
+      },
+    };
+
+    const configFileName = 'automatic-layering-config.json';
+    await writeManifestToFile(config, configFileName);
+
+    await volViewPage.open(
+      `?config=[tmp/${configFileName}]&urls=[${FETUS_DATASET.url},${FETUS_DATASET.url}]&names=[base-image.mha,base-image.layer.mha]`
+    );
+    await volViewPage.waitForViews();
+
+    const renderTab = await volViewPage.renderingModuleTab;
+    await renderTab.click();
+
+    await browser.waitUntil(
+      async function layerSlidersExist() {
+        const layerOpacitySliders = await volViewPage.layerOpacitySliders;
+        return (await layerOpacitySliders.length) > 0;
+      },
+      {
+        timeout: DOWNLOAD_TIMEOUT,
+        timeoutMsg: `Expected at least one layer opacity slider to verify automatic layering`,
+      }
+    );
+  });
+});

tests/specs/configTestUtils.ts

@@ -26,6 +26,11 @@ export const MRA_HEAD_NECK_DATASET = {
   name: 'MRA-Head_and_Neck.zip',
 } as const;
 
+export const FETUS_DATASET = {
+  url: 'https://data.kitware.com/api/v1/item/635679c311dab8142820a4f4/download',
+  name: 'fetus.zip',
+} as const;
+
 export type DatasetResource = {
   url: string;
   name?: string;