volview 4.0.0

package/src/utils/__tests__/lps.spec.ts

@@ -0,0 +1,102 @@
+import chai, { expect } from 'chai';
+import chaiAlmost from 'chai-almost';
+import { vec3, mat3 } from 'gl-matrix';
+
+import { getLPSDirections } from '@src/utils/lps';
+
+chai.use(chaiAlmost());
+
+describe('getLPSDirections', () => {
+  it('correctly assigns LPS directions from an orientation', () => {
+    // Only need 3 of the 6 due to negation
+    interface Expected {
+      Left: vec3;
+      Posterior: vec3;
+      Superior: vec3;
+      Coronal: number;
+      Sagittal: number;
+      Axial: number;
+    }
+
+    function evaluate(desc: string, mat: mat3, expected: Expected) {
+      const actual = getLPSDirections(mat);
+
+      expect(actual.Coronal, `${desc}: Coronal`).to.equal(expected.Coronal);
+      expect(actual.Sagittal, `${desc}: Coronal`).to.equal(expected.Sagittal);
+      expect(actual.Axial, `${desc}: Coronal`).to.equal(expected.Axial);
+
+      expect(actual.Left, `${desc}: Left`).to.deep.almost(expected.Left);
+      expect(actual.Right, `${desc}: Right`).to.deep.almost(
+        expected.Left.map((c) => c * -1)
+      );
+      expect(actual.Posterior, `${desc}: Posterior`).to.deep.almost(
+        expected.Posterior
+      );
+      expect(actual.Anterior, `${desc}: Anterior`).to.deep.almost(
+        expected.Posterior.map((c) => c * -1)
+      );
+      expect(actual.Superior, `${desc}: Superior`).to.deep.almost(
+        expected.Superior
+      );
+      expect(actual.Inferior, `${desc}: Inferior`).to.deep.almost(
+        expected.Superior.map((c) => c * -1)
+      );
+    }
+
+    evaluate(
+      'Identity',
+      // prettier-ignore
+      [
+        1, 0, 0,
+        0, 1, 0,
+        0, 0, 1,
+      ],
+      {
+        Left: [1, 0, 0],
+        Posterior: [0, 1, 0],
+        Superior: [0, 0, 1],
+        Sagittal: 0,
+        Coronal: 1,
+        Axial: 2,
+      }
+    );
+    evaluate(
+      'Axis-aligned case #1',
+      // prettier-ignore
+      [
+        0,  0, -1,
+        1,  0,  0,
+        0, -1,  0,
+      ],
+      {
+        Left: [1, 0, 0],
+        Posterior: [0, 1, 0],
+        Superior: [0, 0, 1],
+        Sagittal: 1,
+        Coronal: 2,
+        Axial: 0,
+      }
+    );
+    evaluate(
+      'Oblique case #1',
+      // prettier-ignore
+      [
+        0.5986634492874146, 0.22716301679611206, -0.7681139707565308,
+        0.5627936124801636, 0.5630670785903931 , 0.6051601767539978,
+        0.569969654083252 , -0.7945769429206848, 0.20924176275730133,
+      ],
+      {
+        Left: [0.5627936124801636, 0.5630670785903931, 0.6051601767539978],
+        Posterior: [
+          -0.569969654083252, 0.7945769429206848, -0.20924176275730133,
+        ],
+        Superior: [
+          -0.5986634492874146, -0.22716301679611206, 0.7681139707565308,
+        ],
+        Sagittal: 1,
+        Coronal: 2,
+        Axial: 0,
+      }
+    );
+  });
+});

package/src/utils/color.ts

@@ -0,0 +1,23 @@
+/**
+ * Converts an RGBA tuple to a hex string with alpha.
+ *
+ * Adds the prefix '#'.
+ *
+ * @param rgba a 4-tuple with components ranging from 0-255.
+ */
+export function rgbaToHexa(rgba: number[]) {
+  const hexa = rgba.map((comp) => `0${comp.toString(16)}`.slice(-2));
+  return `#${hexa.join('')}`;
+}
+
+/**
+ *
+ * @param hexa a hexa color in the format "#AABBCCDD"
+ */
+export function hexaToRGBA(hexa: string) {
+  const rgba = [0, 0, 0, 0];
+  for (let i = 0; i < 4; i++) {
+    rgba[i] = Number.parseInt(hexa.substring(i + 1, i + 3), 16);
+  }
+  return rgba;
+}

package/src/utils/errors.js

@@ -0,0 +1,3 @@
+/* eslint-disable max-classes-per-file */
+
+export class IndexError extends Error {}

package/src/utils/fetch.ts

@@ -0,0 +1,101 @@
+/**
+ * Percent is in [0, 1]. If it's Infinity, then the progress is indeterminate.
+ */
+export type ProgressCallback = (percent: number) => void;
+
+export interface FetchOptions {
+  progress?: ProgressCallback;
+}
+
+interface URLHandler {
+  testURL(url: string): boolean;
+  fetchURL(url: string, options?: FetchOptions): Promise<Blob | null>;
+}
+
+/**
+ * Handles HTTP(S) connections.
+ *
+ * Progress is approximate, given that data can be sent over gzipped.
+ */
+const HTTPHandler: URLHandler = {
+  testURL: (url) => {
+    const { protocol } = new URL(url);
+    return protocol === 'http:' || protocol === 'https:';
+  },
+  fetchURL: async (url, options = {}) => {
+    const { progress } = options;
+
+    const response = await fetch(url);
+    const contentLength = Number(response.headers.get('content-length')) ?? -1;
+
+    if (!progress) {
+      return response.blob();
+    }
+
+    if (contentLength < 0) {
+      progress(Infinity);
+      return response.blob();
+    }
+
+    const reader = response.body?.getReader();
+    if (!reader) {
+      return null;
+    }
+
+    const bytes = new Uint8Array(contentLength);
+    let recv = 0;
+    let done = false;
+    do {
+      // eslint-disable-next-line no-await-in-loop
+      const readData = await reader.read();
+      done = readData.done;
+      if (readData.value && !done) {
+        bytes.set(readData.value, recv);
+        recv += readData.value.length;
+        progress(recv / contentLength);
+      }
+    } while (!done);
+
+    return new Blob([bytes]);
+  },
+};
+
+/**
+ * Handles Google Bucket URLs
+ */
+const GoogleBucketHandler: URLHandler = {
+  testURL: (url) => new URL(url).protocol === 'gs:',
+  fetchURL: async (url, options = {}) => {
+    const urlComponents = new URL(url);
+    // gs URIs look like gs://bucket_name/file_name,
+    // and pathname is everything after gs:
+    // strip off both of the leading slashes.
+    const bucketPath = urlComponents.pathname.slice(2);
+    const httpURL = `https://storage.googleapis.com/${bucketPath}`;
+    return HTTPHandler.fetchURL(httpURL, options);
+  },
+};
+
+const HANDLERS = [GoogleBucketHandler, HTTPHandler];
+
+/**
+ * Fetches a file.
+ * @returns a File instance.
+ */
+export async function fetchFile(
+  url: string,
+  name: string,
+  options?: FetchOptions
+) {
+  const handler = HANDLERS.find((h) => h.testURL(url));
+  if (!handler) {
+    throw new Error(`Cannot find a handler for URL: ${url}`);
+  }
+
+  const blob = await handler.fetchURL(url, options);
+  if (!blob) {
+    throw new Error(`Failed to download ${url}`);
+  }
+
+  return new File([blob], name);
+}

package/src/utils/hacks.ts

@@ -0,0 +1,14 @@
+/**
+ * document.exitPointerLock is undefined on iOS.
+ * - Tested on iOS Safari 15.6.1.
+ */
+export function patchExitPointerLock() {
+  const { exitPointerLock } = document;
+  document.exitPointerLock = () => {
+    try {
+      exitPointerLock?.call(document);
+    } catch (e) {
+      // ignore if undefined
+    }
+  };
+}

package/src/utils/index.ts

@@ -0,0 +1,83 @@
+type PromiseResolveFunction<T> = (value: T) => void;
+type PromiseRejectFunction = (reason?: Error) => void;
+export interface Deferred<T> {
+  promise: Promise<T>;
+  resolve: PromiseResolveFunction<T>;
+  reject: PromiseRejectFunction;
+}
+
+export function defer<T>(): Deferred<T> {
+  let innerResolve: PromiseResolveFunction<T> | null = null;
+  let innerReject: PromiseRejectFunction | null = null;
+
+  const resolve = (value: T) => {
+    if (innerResolve) innerResolve(value);
+  };
+  const reject = (reason?: Error) => {
+    if (innerReject) innerReject(reason);
+  };
+
+  const promise = new Promise<T>((res, rej) => {
+    innerResolve = res;
+    innerReject = rej;
+  });
+
+  return { promise, resolve, reject };
+}
+
+export function removeFromArray<T>(arr: Array<T>, el: T) {
+  const idx = arr.indexOf(el);
+  if (idx > -1) {
+    arr.splice(idx, 1);
+  }
+}
+
+export function clampValue(value: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, value));
+}
+
+export function pick<T, K extends keyof T>(obj: T, ...keys: K[]): Pick<T, K> {
+  return keys.reduce((o, k) => ({ ...o, [k]: obj[k] }), {} as Pick<T, K>);
+}
+
+export function plural(n: number, word: string, pluralWord?: string) {
+  return n > 1 ? pluralWord ?? `${word}s` : word;
+}
+
+export const ensureDefault = <T>(
+  key: string,
+  records: Record<string, T>,
+  default_: T
+) => {
+  if (!(key in records)) {
+    // eslint-disable-next-line no-param-reassign
+    records[key] = default_;
+  }
+
+  return records[key];
+};
+
+export function arrayEquals<T>(a: T[], b: T[]) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Wraps non-arrays in an array.
+ * @param maybeArray
+ */
+export function wrapInArray<T>(maybeArray: T | T[]): T[] {
+  return Array.isArray(maybeArray) ? maybeArray : [maybeArray];
+}
+
+/**
+ * Extracts the basename from a URL.
+ *
+ * Requires that the URL global be present.
+ */
+export function getURLBasename(url: string) {
+  return new URL(url).pathname.split('/').at(-1) ?? '';
+}

package/src/utils/lps.ts

@@ -0,0 +1,129 @@
+import { Bounds } from '@kitware/vtk.js/types';
+import { vec3, mat3 } from 'gl-matrix';
+import {
+  LPSAxis,
+  LPSAxisDir,
+  LPSBounds,
+  LPSDirections,
+  LPSPoint,
+} from '../types/lps';
+
+export const LPSAxes: LPSAxis[] = ['Sagittal', 'Coronal', 'Axial'];
+
+export function createLPSPoint(): LPSPoint {
+  return {
+    Sagittal: 0,
+    Coronal: 0,
+    Axial: 0,
+  };
+}
+
+export function createLPSBounds(): LPSBounds {
+  return {
+    Sagittal: [0, 0],
+    Coronal: [0, 0],
+    Axial: [0, 0],
+  };
+}
+
+export function getAxisBounds(
+  bounds: Bounds,
+  axis: LPSAxis,
+  directions: LPSDirections
+) {
+  const index = 2 * directions[axis];
+  return bounds.slice(index, index + 2) as [number, number];
+}
+
+export function getLPSAxisFromDir(dir: LPSAxisDir): LPSAxis {
+  switch (dir) {
+    case 'Superior':
+    case 'Inferior':
+      return 'Axial';
+    case 'Left':
+    case 'Right':
+      return 'Sagittal';
+    case 'Posterior':
+    case 'Anterior':
+      return 'Coronal';
+    default:
+      throw new Error(`Invalid LPS direction: ${dir}`);
+  }
+}
+
+export const defaultLPSDirections = () => ({
+  Left: vec3.fromValues(1, 0, 0),
+  Right: vec3.fromValues(-1, 0, 0),
+  Posterior: vec3.fromValues(0, 1, 0),
+  Anterior: vec3.fromValues(0, -1, 0),
+  Superior: vec3.fromValues(0, 0, 1),
+  Inferior: vec3.fromValues(0, 0, -1),
+
+  Sagittal: 0 as const,
+  Coronal: 1 as const,
+  Axial: 2 as const,
+});
+
+/**
+ * Associates the column vectors of a 3x3 matrix with the LPS axes.
+ *
+ * For each of the LPS axes, this function returns the associated column index (0, 1, 2)
+ * in the provided 3x3 column-major matrix.
+ *
+ * Approach:
+ *   - find the max of the direction matrix, ignoring columns and rows marked as done
+ *   - assign the column vector of that max value to the row axis
+ *   - mark that row and column as done
+ *   - continue until all rows and columns are done
+ */
+export function getLPSDirections(direction: mat3): LPSDirections {
+  // Track the rows and columns that have yet to be assigned.
+  const availableCols = [0, 1, 2];
+  const availableRows = [0, 1, 2];
+  const lpsDirs: LPSDirections = defaultLPSDirections();
+
+  for (let i = 0; i < 3; i++) {
+    let bestValue = 0;
+    let bestValueLoc = [0, 0]; // col, row
+    let removeIndices = [0, 0]; // indices into availableCols/Rows for deletion
+
+    availableCols.forEach((col, colIdx) => {
+      availableRows.forEach((row, rowIdx) => {
+        const value = direction[col * 3 + row];
+        if (Math.abs(value) > Math.abs(bestValue)) {
+          bestValue = value;
+          bestValueLoc = [col, row];
+          removeIndices = [colIdx, rowIdx];
+        }
+      });
+    });
+
+    // the row index corresponds to the index of the LPS axis
+    const [col, axis] = bestValueLoc;
+    const axisVector = direction.slice(col * 3, (col + 1) * 3);
+    const vecSign = Math.sign(bestValue);
+    const posVector = axisVector.map((c) => c * vecSign) as vec3;
+    const negVector = axisVector.map((c) => c * -vecSign) as vec3;
+    if (axis === 0) {
+      // Sagittal
+      lpsDirs.Left = posVector;
+      lpsDirs.Right = negVector;
+      lpsDirs.Sagittal = col as 0 | 1 | 2;
+    } else if (axis === 1) {
+      // Coronal
+      lpsDirs.Posterior = posVector;
+      lpsDirs.Anterior = negVector;
+      lpsDirs.Coronal = col as 0 | 1 | 2;
+    } else if (axis === 2) {
+      // Axial
+      lpsDirs.Superior = posVector;
+      lpsDirs.Inferior = negVector;
+      lpsDirs.Axial = col as 0 | 1 | 2;
+    }
+
+    availableCols.splice(removeIndices[0], 1);
+    availableRows.splice(removeIndices[1], 1);
+  }
+
+  return lpsDirs;
+}

package/src/utils/manipulators.ts

@@ -0,0 +1,35 @@
+import { Vector3 } from '@kitware/vtk.js/types';
+import vtkPlaneManipulator from '@kitware/vtk.js/Widgets/Manipulators/PlaneManipulator';
+import { vec3 } from 'gl-matrix';
+import { ImageMetadata } from '../store/datasets-images';
+import { LPSAxisDir } from '../types/lps';
+import { getLPSAxisFromDir } from './lps';
+
+export function updatePlaneManipulatorFor2DView(
+  manipulator: vtkPlaneManipulator,
+  viewDir: LPSAxisDir,
+  slice: number,
+  imageMetadata: ImageMetadata
+) {
+  const { lpsOrientation } = imageMetadata;
+  const axis = lpsOrientation[getLPSAxisFromDir(viewDir)];
+
+  const normal: vec3 = lpsOrientation[viewDir];
+  const origin: vec3 = [0, 0, 0];
+  origin[axis] = slice;
+
+  vec3.transformMat4(origin, origin, imageMetadata.indexToWorld);
+
+  manipulator.setUserNormal(normal as Vector3);
+  manipulator.setUserOrigin(origin as Vector3);
+}
+
+export function createPlaneManipulatorFor2DView(
+  viewDir: LPSAxisDir,
+  slice: number,
+  imageMetadata: ImageMetadata
+) {
+  const manipulator = vtkPlaneManipulator.newInstance();
+  updatePlaneManipulatorFor2DView(manipulator, viewDir, slice, imageMetadata);
+  return manipulator;
+}

package/src/utils/promise-worker.ts

@@ -0,0 +1,45 @@
+/* eslint-disable */
+import { defer, Deferred } from './index';
+
+// to be used to instantiate a worker
+export default class PromiseWorker {
+  private msgID: number;
+  private worker: Worker;
+  private waiting: Record<string, Deferred<any>>;
+
+  constructor(worker: Worker) {
+    this.msgID = 0;
+    this.worker = worker;
+    this.waiting = {};
+
+    this.worker.onmessage = this.handleMessage.bind(this);
+  }
+
+  postMessage(message: any, transferables: any[] = []) {
+    const wrappedMsg = {
+      id: this.msgID,
+      message,
+    };
+
+    const deferred = defer();
+    this.waiting[wrappedMsg.id] = deferred;
+
+    this.worker.postMessage(wrappedMsg, transferables);
+
+    this.msgID += 1;
+    return deferred.promise;
+  }
+
+  handleMessage(ev: any) {
+    const { id, error, message } = ev.data;
+    if (id in this.waiting) {
+      const deferred = this.waiting[id];
+      delete this.waiting[id];
+      if (error) {
+        deferred.reject(new Error(error));
+      } else {
+        deferred.resolve(message);
+      }
+    }
+  }
+}