@vitessce/spatial-utils 3.1.2 → 3.2.0

package/src/index.js

@@ -15,4 +15,21 @@ export {
   getNgffAxes,
   getNgffAxesForTiff,
   coordinateTransformationsToMatrix,
+  physicalSizeToMatrix,
+  hexToRgb,
+  getStatsForResolution,
+  canLoadResolution,
+  normalizeCoordinateTransformations,
 } from './spatial.js';
+export {
+  toRgbUIString,
+  getSingleSelectionStats,
+  getMultiSelectionStats,
+  getPhysicalSizeScalingMatrix,
+  getBoundingCube,
+  abbreviateNumber,
+  filterSelection,
+} from './layer-controller.js';
+export {
+  DOMAINS,
+} from './constants.js';

package/src/layer-controller.js

@@ -1,9 +1,37 @@
-import { Matrix4 } from 'math.gl';
 import { viv } from '@vitessce/gl';
+import { fromEntries } from '@vitessce/utils';
+import { Matrix4 } from 'math.gl';
+
+// Returns an rgb string for display, and changes the color (arr)
+// to use a grey for light theme + white color or if the colormap is on.
+export const toRgbUIString = (on, arr, theme) => {
+  const color = on || (theme === 'light' && arr?.every(i => i === 255))
+    ? [220, 220, 220]
+    : arr;
+  return `rgb(${color})`;
+};
+
+/**
+ * Ensure that the channel selection object does not have
+ * extra dimension keys, as this will cause Viv functions
+ * to throw errors about not being able to access the data.
+ * @param {*} loader
+ * @param {object} selection Mapping from dimension label to slice index.
+ * @returns {object} The filtered selection.
+ */
+export function filterSelection(loader, selection) {
+  if (!selection) {
+    return selection;
+  }
+  const data = Array.isArray(loader) ? loader[loader.length - 1] : loader;
+  const { labels } = data;
+  return fromEntries(Object.entries(selection).filter(([key]) => labels.includes(key)));
+}
 
 async function getSingleSelectionStats2D({ loader, selection }) {
   const data = Array.isArray(loader) ? loader[loader.length - 1] : loader;
-  const raster = await data.getRaster({ selection });
+  const filteredSelection = filterSelection(loader, selection);
+  const raster = await data.getRaster({ selection: filteredSelection });
   const selectionStats = viv.getChannelStats(raster.data);
   const { domain, contrastLimits: slider } = selectionStats;
   return { domain, slider };
@@ -11,17 +39,18 @@ async function getSingleSelectionStats2D({ loader, selection }) {
 
 async function getSingleSelectionStats3D({ loader, selection }) {
   const lowResSource = loader[loader.length - 1];
+  const filteredSelection = filterSelection(lowResSource, selection);
   const { shape, labels } = lowResSource;
   // eslint-disable-next-line no-bitwise
   const sizeZ = shape[labels.indexOf('z')] >> (loader.length - 1);
   const raster0 = await lowResSource.getRaster({
-    selection: { ...selection, z: 0 },
+    selection: { ...filteredSelection, z: 0 },
   });
   const rasterMid = await lowResSource.getRaster({
-    selection: { ...selection, z: Math.floor(sizeZ / 2) },
+    selection: { ...filteredSelection, z: Math.floor(sizeZ / 2) },
   });
   const rasterTop = await lowResSource.getRaster({
-    selection: { ...selection, z: Math.max(0, sizeZ - 1) },
+    selection: { ...filteredSelection, z: Math.max(0, sizeZ - 1) },
   });
   const stats0 = viv.getChannelStats(raster0.data);
   const statsMid = viv.getChannelStats(rasterMid.data);

package/src/layer-controller.test.js

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { toRgbUIString } from './layer-controller.js';
+
+const GREY = [220, 220, 220];
+
+describe('layer-controller/RasterChannelController.js', () => {
+  describe('toRgbUIString()', () => {
+    it('Maps color value to itself when colormap off and not white with dark theme', () => {
+      expect(toRgbUIString(false, [200, 200, 200], 'dark')).toEqual(`rgb(${[200, 200, 200]})`);
+    });
+    it('Maps color value to grey when colormap on with dark theme', () => {
+      expect(toRgbUIString(true, [200, 200, 200], 'dark')).toEqual(`rgb(${GREY})`);
+    });
+    it('Maps color value to grey when colormap on with light theme', () => {
+      expect(toRgbUIString(true, [200, 200, 200], 'light')).toEqual(`rgb(${GREY})`);
+    });
+    it('Maps color value to grey when colormap off and white with light theme', () => {
+      expect(toRgbUIString(false, [255, 255, 255], 'light')).toEqual(`rgb(${GREY})`);
+    });
+    it('Maps color value to grey when colormap off and white with light theme', () => {
+      expect(toRgbUIString(false, [200, 200, 200], 'light')).toEqual(`rgb(${[200, 200, 200]})`);
+    });
+  });
+});

package/src/spatial.js

@@ -53,6 +53,40 @@ export function getSourceFromLoader(loader, level) {
   return source;
 }
 
+export const getStatsForResolution = (loader, resolution) => {
+  const { shape, labels } = loader[resolution];
+  const height = shape[labels.indexOf('y')];
+  const width = shape[labels.indexOf('x')];
+  const depth = shape[labels.indexOf('z')];
+  // eslint-disable-next-line no-bitwise
+  const depthDownsampled = Math.max(1, depth >> resolution);
+  // Check memory allocation limits for Float32Array (used in XR3DLayer for rendering)
+  const totalBytes = 4 * height * width * depthDownsampled;
+  return {
+    height, width, depthDownsampled, totalBytes,
+  };
+};
+
+export const canLoadResolution = (loader, resolution) => {
+  const {
+    totalBytes, height, width, depthDownsampled,
+  } = getStatsForResolution(
+    loader,
+    resolution,
+  );
+  const maxHeapSize = window.performance?.memory
+    && window.performance?.memory?.jsHeapSizeLimit / 2;
+  const maxSize = maxHeapSize || (2 ** 31) - 1;
+  // 2048 is a normal texture size limit although some browsers go larger.
+  return (
+    totalBytes < maxSize
+    && height <= 2048
+    && depthDownsampled <= 2048
+    && width <= 2048
+    && depthDownsampled > 1
+  );
+};
+
 /**
  * Helper method to determine whether pixel data is interleaved and rgb or not.
  * @param {object} loader
@@ -77,6 +111,42 @@ export function isRgb(loader, channels) {
 
 // From spatial/utils.js
 
+export function physicalSizeToMatrix(xSize, ySize, zSize, xUnit, yUnit, zUnit) {
+  const hasZPhyscialSize = Boolean(zSize) && Boolean(zUnit);
+  const hasYPhyscialSize = Boolean(ySize) && Boolean(yUnit);
+  const hasXPhyscialSize = Boolean(xSize) && Boolean(xUnit);
+  if (!hasXPhyscialSize || !hasYPhyscialSize) {
+    return (new Matrix4()).identity();
+  }
+  const sizes = [
+    unit(`${xSize} ${xUnit}`.replace('µ', 'u')),
+    unit(`${ySize} ${yUnit}`.replace('µ', 'u')),
+  ];
+  if (hasZPhyscialSize) {
+    sizes.push(unit(`${zSize} ${zUnit}`.replace('µ', 'u')));
+  }
+  // Find the ratio of the sizes to get the scaling factor.
+  const scale = sizes.map(i => divide(i, unit('1 um')));
+
+  // TODO: is this still needed
+  // sizes are special objects with own equals method - see `unit` in declaration
+  if (!sizes[0].equals(sizes[1])) {
+    // Handle scaling in the Y direction for non-square pixels
+    scale[1] = divide(sizes[1], sizes[0]);
+  }
+  // END TODO: is this still needed
+
+  // Add in z dimension needed for Matrix4 scale API.
+  if (!scale[2]) {
+    scale[2] = 1;
+  }
+  // no need to store/use identity scaling
+  if (isEqual(scale, [1, 1, 1])) {
+    return (new Matrix4()).identity();
+  }
+  return new Matrix4().scale([...scale]);
+}
+
 function getMetaWithTransformMatrices(imageMeta, imageLoaders) {
   // Do not fill in transformation matrices if any of the layers specify one.
   const sources = imageLoaders.map(loader => getSourceFromLoader(loader));
@@ -367,11 +437,11 @@ export function getNgffAxesForTiff(dimOrder) {
 /**
  * Convert an array of coordinateTransformations objects to a 16-element
  * plain JS array using Matrix4 linear algebra transformation functions.
- * @param {object[]} coordinateTransformations List of objects matching the
+ * @param {object[]|undefined} coordinateTransformations List of objects matching the
  * OME-NGFF v0.4 coordinateTransformations spec.
- * @param {object[]} axes Axes in OME-NGFF v0.4 format, objects
+ * @param {object[]|undefined} axes Axes in OME-NGFF v0.4 format, objects
  * with { type, name }.
- * @returns {Array<number>} Array of 16 numbers representing the Matrix4.
+ * @returns {Matrix4} Array of 16 numbers representing the Matrix4.
  */
 export function coordinateTransformationsToMatrix(coordinateTransformations, axes) {
   let mat = (new Matrix4()).identity();
@@ -416,3 +486,71 @@ export function coordinateTransformationsToMatrix(coordinateTransformations, axe
   }
   return mat;
 }
+
+export function hexToRgb(hex) {
+  const result = /^#?([A-F\d]{2})([A-F\d]{2})([A-F\d]{2})$/i.exec(hex);
+  return [
+    parseInt(result[1].toLowerCase(), 16),
+    parseInt(result[2].toLowerCase(), 16),
+    parseInt(result[3].toLowerCase(), 16),
+  ];
+}
+
+/**
+ * Normalize coordinate transformations to the OME-NGFF v0.4 format,
+ * despite potentially being in the new format proposed in
+ * https://github.com/ome/ngff/pull/138 (As of 2023-09-02).
+ * @param {object[]|undefined} coordinateTransformations Value of
+ * multiscales[0].coordinateTransformations in either OME-NGFF v0.4 format
+ * or that proposed in https://github.com/ome/ngff/pull/138.
+ * @param {object[]} datasets Value of multiscales[0].datasets in OME-NGFF v0.4 format.
+ * @returns {object[]} Array of coordinateTransformations in OME-NGFF v0.4 format.
+ */
+export function normalizeCoordinateTransformations(coordinateTransformations, datasets) {
+  // "The transformations in the list are applied sequentially and in order."
+  // Reference: https://ngff.openmicroscopy.org/0.4/index.html#trafo-md
+  let result = [];
+
+  if (Array.isArray(coordinateTransformations)) {
+    result = coordinateTransformations.map((transform) => {
+      if (transform.input && transform.output) {
+        // This is a new-style coordinate transformation.
+        // (As proposed in https://github.com/ome/ngff/pull/138)
+        const { type } = transform;
+        if (type === 'translation') {
+          return {
+            type,
+            translation: transform.translation,
+          };
+        }
+        if (type === 'scale') {
+          return {
+            type,
+            scale: transform.scale,
+          };
+        }
+        if (type === 'identity') {
+          return { type };
+        }
+        console.warn(`Coordinate transformation type "${type}" is not supported.`);
+      }
+      // Assume it was already an old-style (NGFF v0.4) coordinate transformation.
+      return transform;
+    });
+  }
+
+  if (Array.isArray(datasets?.[0]?.coordinateTransformations)) {
+    // "Datasets SHOULD define a transformation from array space
+    // to their "native physical space."
+    // This transformation SHOULD describe physical pixel spacing
+    // and origin only, and therefore SHOULD consist of
+    // `scale` and/or `translation` types only.""
+    // Reference: https://github.com/ome/ngff/blob/b92f540dc95440f2d6b7012185b09c2b862aa744/latest/transform-details.bs#L99
+
+    result = [
+      ...datasets[0].coordinateTransformations,
+      ...result,
+    ];
+  }
+  return result;
+}

package/src/spatial.test.js

@@ -1,5 +1,9 @@
 import { describe, it, expect } from 'vitest';
-import { square, coordinateTransformationsToMatrix } from './spatial.js';
+import {
+  square,
+  coordinateTransformationsToMatrix,
+  normalizeCoordinateTransformations,
+} from './spatial.js';
 
 const defaultAxes = [
   { type: 'time', name: 't' },
@@ -43,4 +47,159 @@ describe('Spatial.js', () => {
       ]);
     });
   });
+  describe('normalizeCoordinateTransformations', () => {
+    it('does nothing for OME-NGFF v0.4 input', () => {
+      const datasets = [
+        {
+          coordinateTransformations: [
+            {
+              scale: [
+                1,
+                0.5002025531914894,
+                0.3603981534640209,
+                0.3603981534640209,
+              ],
+              type: 'scale',
+            },
+          ],
+          path: '0',
+        },
+        {
+          coordinateTransformations: [
+            {
+              scale: [
+                1,
+                0.5002025531914894,
+                0.7207963069280418,
+                0.7207963069280418,
+              ],
+              type: 'scale',
+            },
+          ],
+          path: '1',
+        },
+        {
+          coordinateTransformations: [
+            {
+              scale: [
+                1,
+                0.5002025531914894,
+                1.4415926138560835,
+                1.4415926138560835,
+              ],
+              type: 'scale',
+            },
+          ],
+          path: '2',
+        },
+      ];
+      expect(normalizeCoordinateTransformations(undefined, datasets)).toEqual([
+        // Here, we expect only the first dataset to be used.
+        // However, we should eventually support transforms
+        // specified for each dataset individually,
+        // since there could in theory be irregular ways of downsampling.
+        {
+          scale: [
+            1,
+            0.5002025531914894,
+            0.3603981534640209,
+            0.3603981534640209,
+          ],
+          type: 'scale',
+        },
+      ]);
+    });
+    it('transforms SpatialData input', () => {
+      const newCoordinateTransformations = [
+        {
+          input: {
+            axes: [
+              {
+                name: 'c',
+                type: 'channel',
+              },
+              {
+                name: 'y',
+                type: 'space',
+                unit: 'unit',
+              },
+              {
+                name: 'x',
+                type: 'space',
+                unit: 'unit',
+              },
+            ],
+            name: 'cyx',
+          },
+          output: {
+            axes: [
+              {
+                name: 'c',
+                type: 'channel',
+              },
+              {
+                name: 'y',
+                type: 'space',
+                unit: 'unit',
+              },
+              {
+                name: 'x',
+                type: 'space',
+                unit: 'unit',
+              },
+            ],
+            name: 'ST8059048',
+          },
+          scale: [
+            1.0,
+            8.670500183814605,
+            8.670500183814605,
+          ],
+          type: 'scale',
+        },
+      ];
+      const datasets = [
+        {
+          coordinateTransformations: [
+            {
+              scale: [
+                1.0,
+                1.0,
+                1.0,
+              ],
+              type: 'scale',
+            },
+          ],
+          path: '0',
+        },
+      ];
+      expect(normalizeCoordinateTransformations(newCoordinateTransformations, datasets)).toEqual([
+        // Here, we expect only the first dataset to be used.
+        // However, we should eventually support transforms
+        // specified for each dataset individually,
+        // since there could in theory be irregular ways of downsampling.
+        {
+          scale: [
+            1.0,
+            1.0,
+            1.0,
+          ],
+          type: 'scale',
+        },
+        // We expect the dataset transform to be prepended
+        // to the newCoordinateTransformations items.
+        // We do not check the input/output coordinate systems, but we should eventually allow
+        // the user to specify this somehow and use that information to filter which transforms
+        // are included here.
+        {
+          scale: [
+            1.0,
+            8.670500183814605,
+            8.670500183814605,
+          ],
+          type: 'scale',
+        },
+      ]);
+    });
+  });
 });