feat: Auto multichannel setup for image layers (#770)

Author: seankmartin

src/datasource/index.ts

@@ -54,6 +54,7 @@ import {
   getPrefixMatchesWithDescriptions,
 } from "#src/util/completion.js";
 import { RefCounted } from "#src/util/disposable.js";
+import type { vec3 } from "#src/util/geom.js";
 import { type ProgressOptions } from "#src/util/progress_listener.js";
 import type { Trackable } from "#src/util/trackable.js";
 
@@ -173,12 +174,27 @@ export interface DataSubsourceEntry {
   default: boolean;
 }
 
+export interface ChannelMetadata {
+  name?: string;
+  channels: SingleChannelMetadata[];
+}
+
+export interface SingleChannelMetadata {
+  color?: vec3;
+  label?: string;
+  active?: boolean;
+  window?: [number, number];
+  range?: [number, number];
+  coefficient?: number;
+}
+
 export interface DataSource {
   subsources: DataSubsourceEntry[];
   modelTransform: CoordinateSpaceTransform;
   canChangeModelSpaceRank?: boolean;
   state?: Trackable;
   canonicalUrl?: string;
+  channelMetadata?: ChannelMetadata;
 }
 
 export interface DataSourceRedirect {

src/datasource/zarr/frontend.ts

@@ -26,6 +26,7 @@ import {
   makeIdentityTransformedBoundingBox,
 } from "#src/coordinate_transform.js";
 import type {
+  ChannelMetadata,
   DataSource,
   GetKvStoreBasedDataSourceOptions,
   KvStoreBasedDataSourceProvider,
@@ -509,23 +510,25 @@ export class ZarrDataSource implements KvStoreBasedDataSourceProvider {
           zarrVersion: this.zarrVersion,
           explicitDimensionSeparator: dimensionSeparator,
         });
+        let channelMetadata: ChannelMetadata | undefined;
         if (metadata === undefined) {
           throw new Error("No zarr metadata found");
         }
         let multiscaleInfo: ZarrMultiscaleInfo;
         if (metadata.nodeType === "group") {
           // May be an OME-zarr multiscale dataset.
-          const multiscale = parseOmeMetadata(
+          const omeMetadata = parseOmeMetadata(
             kvStoreUrl,
             metadata.userAttributes,
             metadata.zarrVersion,
           );
-          if (multiscale === undefined) {
+          if (omeMetadata === undefined) {
             throw new Error("Neither array nor OME multiscale metadata found");
           }
+          channelMetadata = omeMetadata.channels;
           multiscaleInfo = await resolveOmeMultiscale(
             sharedKvStoreContext,
-            multiscale,
+            omeMetadata.multiscale,
             {
               ...progressOptions,
               zarrVersion: metadata.zarrVersion,
@@ -545,6 +548,7 @@ export class ZarrDataSource implements KvStoreBasedDataSourceProvider {
         return {
           canonicalUrl: `${kvStoreUrl}|zarr${metadata.zarrVersion}:`,
           modelTransform: makeIdentityTransform(volume.modelSpace),
+          channelMetadata,
           subsources: [
             {
               id: "default",

src/datasource/zarr/ome.ts

@@ -16,16 +16,23 @@
 
 import type { CoordinateSpace } from "#src/coordinate_transform.js";
 import { makeCoordinateSpace } from "#src/coordinate_transform.js";
+import type {
+  SingleChannelMetadata,
+  ChannelMetadata,
+} from "#src/datasource/index.js";
+import { parseRGBColorSpecification } from "#src/util/color.js";
 import {
   parseArray,
   parseFixedLengthArray,
+  verifyBoolean,
   verifyFiniteFloat,
   verifyFinitePositiveFloat,
   verifyObject,
   verifyObjectProperty,
   verifyOptionalObjectProperty,
   verifyString,
 } from "#src/util/json.js";
+import { clampToInterval } from "#src/util/lerp.js";
 import * as matrix from "#src/util/matrix.js";
 import { allSiPrefixes } from "#src/util/si_units.js";
 
@@ -39,6 +46,11 @@ export interface OmeMultiscaleMetadata {
   coordinateSpace: CoordinateSpace;
 }
 
+export interface OmeMetadata {
+  multiscale: OmeMultiscaleMetadata;
+  channels: ChannelMetadata | undefined;
+}
+
 const SUPPORTED_OME_MULTISCALE_VERSIONS = new Set(["0.4", "0.5-dev", "0.5"]);
 
 const OME_UNITS = new Map<string, { unit: string; scale: number }>([
@@ -72,6 +84,75 @@ interface Axis {
   type: string | undefined;
 }
 
+function parseOmeroChannel(omeroChannel: unknown): SingleChannelMetadata {
+  verifyObject(omeroChannel);
+
+  const getProp = <T>(
+    key: string,
+    verifier: (value: unknown) => T,
+  ): T | undefined => verifyOptionalObjectProperty(omeroChannel, key, verifier);
+  const inputWindow = getProp("window", verifyObject);
+  const getWindowProp = <T>(
+    key: string,
+    verifier: (value: unknown) => T,
+  ): T | undefined =>
+    inputWindow
+      ? verifyOptionalObjectProperty(inputWindow, key, verifier)
+      : undefined;
+
+  const active = getProp("active", verifyBoolean);
+  const coefficient = getProp("coefficient", verifyFiniteFloat);
+  let colorString = getProp("color", verifyString);
+  // If six hex digits, needs the # in front of the hex color
+  if (colorString && /^[0-9a-f]{6}$/i.test(colorString)) {
+    colorString = `#${colorString}`;
+  }
+  const color = parseRGBColorSpecification(colorString);
+  const inverted = getProp("inverted", verifyBoolean);
+  const label = getProp("label", verifyString);
+
+  const windowMin = getWindowProp("min", verifyFiniteFloat);
+  const windowMax = getWindowProp("max", verifyFiniteFloat);
+  const windowStart = getWindowProp("start", verifyFiniteFloat);
+  const windowEnd = getWindowProp("end", verifyFiniteFloat);
+
+  const window =
+    windowMin !== undefined && windowMax !== undefined
+      ? ([windowMin, windowMax] as [number, number])
+      : undefined;
+
+  const range =
+    windowStart !== undefined && windowEnd !== undefined
+      ? inverted
+        ? ([windowEnd, windowStart] as [number, number])
+        : ([windowStart, windowEnd] as [number, number])
+      : undefined;
+  // If there is a window, then clamp the range to the window.
+  if (window !== undefined && range !== undefined) {
+    range[0] = clampToInterval(window, range[0]) as number;
+    range[1] = clampToInterval(window, range[1]) as number;
+  }
+
+  return {
+    active,
+    label,
+    color,
+    coefficient,
+    range,
+    window,
+  };
+}
+
+function parseOmeroMetadata(omero: unknown): ChannelMetadata {
+  verifyObject(omero);
+  const name = verifyOptionalObjectProperty(omero, "name", verifyString);
+  const channels = verifyObjectProperty(omero, "channels", (x) =>
+    parseArray(x, parseOmeroChannel),
+  );
+
+  return { name, channels };
+}
+
 function parseOmeAxis(axis: unknown): Axis {
   verifyObject(axis);
   const name = verifyObjectProperty(axis, "name", verifyString);
@@ -266,9 +347,10 @@ export function parseOmeMetadata(
   url: string,
   attrs: any,
   zarrVersion: number,
-): OmeMultiscaleMetadata | undefined {
+): OmeMetadata | undefined {
   const ome = attrs.ome;
   const multiscales = ome == undefined ? attrs.multiscales : ome.multiscales; // >0.4
+  const omero = attrs.omero;
 
   if (!Array.isArray(multiscales)) return undefined;
   const errors: string[] = [];
@@ -301,7 +383,9 @@ export function parseOmeMetadata(
       );
       continue;
     }
-    return parseOmeMultiscale(url, multiscale);
+    const multiScaleInfo = parseOmeMultiscale(url, multiscale);
+    const channelMetadata = omero ? parseOmeroMetadata(omero) : undefined;
+    return { multiscale: multiScaleInfo, channels: channelMetadata };
   }
   if (errors.length !== 0) {
     throw new Error(errors[0]);

src/display_context.ts

@@ -435,6 +435,7 @@ export class DisplayContext extends RefCounted implements FrameNumberCounter {
   updateFinished = new NullarySignal();
   continuousCameraMotionStarted = new NullarySignal();
   continuousCameraMotionFinished = new NullarySignal();
+  multiChannelSetupFinished = new NullarySignal();
   changed = this.updateFinished;
   panels = new Set<RenderedPanel>();
   canvasRect: DOMRect | undefined;

src/layer/index.ts

@@ -43,6 +43,7 @@ import {
   LayerDataSource,
   layerDataSourceSpecificationFromJson,
 } from "#src/layer/layer_data_source.js";
+import { createImageLayerAsMultiChannel } from "#src/layer/multi_channel_setup.js";
 import type {
   DisplayDimensions,
   WatchableDisplayDimensionRenderInfo,
@@ -2468,6 +2469,15 @@ export class AutoUserLayer extends UserLayer {
       detectLayerTypeFromSubsources(subsources)?.layerConstructor;
     if (layerConstructor !== undefined) {
       changeLayerType(this.managedLayer, layerConstructor);
+      this.registerDisposer(
+        this.managedLayer.readyStateChanged.add(() => {
+          if (this.managedLayer.isReady()) {
+            // If you want to restore the old auto image setup, pass true here
+            // This will then make the previous image layer setup
+            createImageLayerAsMultiChannel(this.managedLayer, makeLayer);
+          }
+        }),
+      );
     }
   }
 }