cod-dicomweb-server 1.0.0

package/dist/classes/utils.ts

@@ -0,0 +1,176 @@
+import constants, { Enums } from '../constants';
+import type {
+  JsonMetadata,
+  MetadataUrlCreationParams,
+  ParsedWadoRsUrlDetails,
+} from '../types';
+
+export function parseWadorsURL(
+  url: string,
+  domain: string,
+): ParsedWadoRsUrlDetails | undefined {
+  if (!url.includes(constants.url.URL_VALIDATION_STRING)) {
+    return;
+  }
+
+  const filePath = url.split(domain + '/')[1];
+
+  const prefix = filePath.split('/studies')[0];
+  const prefixParts = prefix.split('/');
+
+  const bucketName = prefixParts[0];
+  const bucketPrefix = prefixParts.slice(1).join('/');
+
+  const imagePath = filePath.split(prefix + '/')[1];
+  const imageParts = imagePath.split('/');
+
+  const studyInstanceUID = imageParts[1];
+  const seriesInstanceUID = imageParts[3];
+  let sopInstanceUID = '',
+    frameNumber = 1,
+    type: Enums.RequestType;
+
+  switch (true) {
+    case imageParts.includes('thumbnail'):
+      type = Enums.RequestType.THUMBNAIL;
+      break;
+    case imageParts.includes('metadata'):
+      if (imageParts.includes('instances')) {
+        sopInstanceUID = imageParts[5];
+        type = Enums.RequestType.INSTANCE_METADATA;
+      } else {
+        type = Enums.RequestType.SERIES_METADATA;
+      }
+      break;
+    case imageParts.includes('frames'):
+      sopInstanceUID = imageParts[5];
+      frameNumber = +(imageParts[7] || frameNumber);
+      type = Enums.RequestType.FRAME;
+      break;
+    default:
+      throw new Error('Invalid type of request');
+  }
+
+  return {
+    type,
+    bucketName,
+    bucketPrefix,
+    studyInstanceUID,
+    seriesInstanceUID,
+    sopInstanceUID,
+    frameNumber,
+  };
+}
+
+export function getFrameDetailsFromMetadata(
+  seriesMetadata: JsonMetadata,
+  sopInstanceUID: string,
+  frameIndex: number,
+  bucketDetails: { domain: string; bucketName: string; bucketPrefix: string },
+): {
+  url: string;
+  startByte: number;
+  endByte: number;
+  thumbnailUrl: string;
+  isMultiframe: boolean;
+} {
+  if (
+    !seriesMetadata ||
+    !seriesMetadata.cod?.instances ||
+    !seriesMetadata.thumbnail
+  ) {
+    throw new Error('Invalid seriesMetadata provided.');
+  }
+
+  if (!sopInstanceUID) {
+    throw new Error('SOP Instance UID is required.');
+  }
+
+  if (frameIndex === null || frameIndex === undefined) {
+    throw new Error('Frame index is required.');
+  }
+
+  const instanceFound = Object.values(seriesMetadata.cod.instances).find(
+    (instance) => instance.metadata['00080018']?.Value?.[0] === sopInstanceUID,
+  );
+
+  if (!instanceFound) {
+    throw new Error(
+      `Instance with SOPInstanceUID ${sopInstanceUID} not found.`,
+    );
+  }
+
+  const { domain, bucketName, bucketPrefix } = bucketDetails;
+  const { url, uri, headers: offsetHeaders, offset_tables } = instanceFound;
+  const modifiedUrl = handleUrl(url || uri, domain, bucketName, bucketPrefix);
+
+  const { CustomOffsetTable, CustomOffsetTableLengths } = offset_tables || {};
+
+  let sliceStart: number | undefined,
+    sliceEnd: number | undefined,
+    isMultiframe = false;
+  if (CustomOffsetTable?.length && CustomOffsetTableLengths?.length) {
+    sliceStart = CustomOffsetTable[frameIndex];
+    sliceEnd = sliceStart + CustomOffsetTableLengths[frameIndex];
+    isMultiframe = true;
+  }
+
+  const { start_byte: fileStartByte, end_byte: fileEndByte } = offsetHeaders;
+
+  const startByte =
+    sliceStart !== undefined ? fileStartByte + sliceStart : fileStartByte;
+  const endByte =
+    sliceEnd !== undefined ? fileStartByte + sliceEnd : fileEndByte;
+
+  const thumbnailGsUtilUri = seriesMetadata.thumbnail.uri;
+  const thumbnailUrl = `${domain}/${thumbnailGsUtilUri.split('gs://')[1]}`;
+
+  return {
+    url: modifiedUrl,
+    startByte,
+    endByte,
+    thumbnailUrl,
+    isMultiframe,
+  };
+}
+
+export function handleUrl(
+  url: string,
+  domain: string,
+  bucketName: string,
+  bucketPrefix: string,
+): string {
+  let modifiedUrl = url;
+
+  const matchingExtension = constants.url.FILE_EXTENSIONS.find((extension) =>
+    url.includes(extension),
+  );
+
+  if (matchingExtension) {
+    const fileParts = url.split(matchingExtension);
+    modifiedUrl = fileParts[0] + matchingExtension;
+  }
+
+  const filePath = modifiedUrl.split('studies/')[1];
+  modifiedUrl = `${domain}/${bucketName}/${bucketPrefix ? bucketPrefix + '/' : ''}studies/${filePath}`;
+
+  return modifiedUrl;
+}
+
+export function createMetadataJsonUrl(
+  params: MetadataUrlCreationParams,
+): string | undefined {
+  const {
+    domain = constants.url.DOMAIN,
+    bucketName,
+    bucketPrefix,
+    studyInstanceUID,
+    seriesInstanceUID,
+  } = params;
+
+  if (!bucketName || !bucketPrefix || !studyInstanceUID || !seriesInstanceUID) {
+    return;
+  }
+
+  return `${domain}/${bucketName}/${bucketPrefix}/studies/${studyInstanceUID}/series/${seriesInstanceUID}/metadata.json`;
+}

package/dist/constants/enums.ts

@@ -0,0 +1,18 @@
+export enum FetchType {
+  /**
+   * Fetch only the part of the file according to the offsets provided.
+   */
+  BYTES_OPTIMIZED,
+  /**
+   * Stream the file and returns the part of the file if offsets are provided.
+   * Or returns the whole file.
+   */
+  API_OPTIMIZED,
+}
+
+export enum RequestType {
+  FRAME,
+  THUMBNAIL,
+  SERIES_METADATA,
+  INSTANCE_METADATA,
+}

package/dist/constants/index.ts

@@ -0,0 +1,8 @@
+import * as Enums from './enums';
+import * as url from './url';
+import * as worker from './worker';
+
+const constants = { Enums, url, worker };
+
+export { Enums, url, worker };
+export default constants;

package/dist/constants/url.ts

@@ -0,0 +1,5 @@
+export const DOMAIN = 'https://storage.googleapis.com';
+
+export const FILE_EXTENSIONS = ['.tar', '.zip'];
+
+export const URL_VALIDATION_STRING = '/dicomweb/';

package/dist/constants/worker.ts

@@ -0,0 +1,4 @@
+export const FILE_PARTIAL_WORKER_NAME = 'filePartial';
+export const FILE_STREAMING_WORKER_NAME = 'fileStreaming';
+
+export const THRESHOLD = 10000;

package/dist/fileManager.ts

@@ -0,0 +1,84 @@
+import type { FileManagerOptions } from './types';
+import { getWebWorkerManager } from './webWorker/workerManager';
+
+class FileManager {
+  private files: Record<string, { data: Uint8Array; position: number }> = {};
+  private fileStreamingWorkerName: string;
+
+  constructor({ fileStreamingWorkerName }: FileManagerOptions) {
+    this.fileStreamingWorkerName = fileStreamingWorkerName;
+  }
+
+  set(url: string, file: { data: Uint8Array; position: number }): void {
+    this.files[url] = file;
+  }
+
+  get(
+    url: string,
+    offsets?: { startByte: number; endByte: number },
+  ): Uint8Array | null {
+    if (
+      !this.files[url] ||
+      (offsets && this.files[url].position <= offsets.endByte)
+    ) {
+      return null;
+    }
+
+    return offsets
+      ? this.files[url].data.slice(offsets.startByte, offsets.endByte)
+      : this.files[url].data;
+  }
+
+  setPosition(url: string, position: number): void {
+    if (this.files[url]) {
+      this.files[url].position = position;
+    }
+  }
+
+  getPosition(url: string): number {
+    return this.files[url]?.position;
+  }
+
+  append(url: string, chunk: Uint8Array, position: number): void {
+    if (this.files[url] && position) {
+      this.files[url].data.set(chunk, position - chunk.length);
+      this.setPosition(url, position);
+    }
+  }
+
+  getTotalSize(): number {
+    return Object.entries(this.files).reduce((total, [url, { position }]) => {
+      return url.includes('?bytes=') ? total : total + position;
+    }, 0);
+  }
+
+  remove(url: string): void {
+    const removedSize = this.getPosition(url);
+    delete this.files[url];
+
+    if (url.includes('?bytes=')) {
+      return;
+    }
+
+    const workerManager = getWebWorkerManager();
+    workerManager.executeTask(
+      this.fileStreamingWorkerName,
+      'decreaseFetchedSize',
+      removedSize,
+    );
+  }
+
+  purge(): void {
+    const totalSize = this.getTotalSize();
+    this.files = {};
+
+    const workerManager = getWebWorkerManager();
+    workerManager.executeTask(
+      this.fileStreamingWorkerName,
+      'decreaseFetchedSize',
+      totalSize,
+    );
+  }
+}
+
+export default FileManager;

package/dist/index.html

@@ -0,0 +1 @@
+<!doctype html><html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width,initial-scale=1"/><meta http-equiv="X-UA-Compatible" content="ie=edge"/><link rel="icon" href="/favicon.ico" type="image/x-icon"/><link rel="shortcut icon" href="/favicon.ico" type="image/x-icon"/><title></title></head><body><noscript><strong>We're sorry but doesn't work properly without JavaScript enabled. Please enable it to continue.</strong></noscript><div id="root" class="root"></div><script defer="defer" src="/assets/js/main.bd27b3d8a119b2e0661f.js"></script></body></html>

package/dist/index.ts

@@ -0,0 +1,5 @@
+import { FetchType } from './constants/enums';
+import CodDicomWebServer from './classes/CodDicomWebServer';
+
+export { FetchType, CodDicomWebServer };
+export default { FetchType, CodDicomWebServer };

package/dist/metadataManager.ts

@@ -0,0 +1,32 @@
+import { createMetadataJsonUrl } from './classes/utils';
+import type { JsonMetadata, MetadataUrlCreationParams } from './types';
+
+const metadata: Record<string, JsonMetadata> = {};
+
+export async function getMetadata(
+  params: MetadataUrlCreationParams,
+  headers: Record<string, string>,
+): Promise<JsonMetadata | null> {
+  const url = createMetadataJsonUrl(params);
+
+  if (!url) {
+    throw new Error('Error creating metadata json url');
+  }
+
+  if (metadata[url]) {
+    return metadata[url];
+  }
+
+  try {
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+      throw new Error(`Failed to fetch metadata: ${response.statusText}`);
+    }
+    const data = await response.json();
+    metadata[url] = data;
+    return data;
+  } catch (error) {
+    console.error(error);
+    throw error;
+  }
+}

package/dist/types/codDicomWebServerOptions.ts

@@ -0,0 +1,7 @@
+type CodDicomWebServerOptions = {
+  [key: string]: number | string;
+  maxWorkerFetchSize: number;
+  domain: string;
+};
+
+export type { CodDicomWebServerOptions };

package/dist/types/fileManagerOptions.ts

@@ -0,0 +1,3 @@
+type FileManagerOptions = { fileStreamingWorkerName: string };
+
+export type { FileManagerOptions };

package/dist/types/index.ts

@@ -0,0 +1,7 @@
+export type * from './codDicomWebServerOptions';
+export type * from './fileManagerOptions';
+export type * from './metadata';
+export type * from './metadataUrlCreationParams';
+export type * from './parsedWadoRsUrlDetails';
+export type * from './requestOptions';
+export type * from './workerCustomMessageEvents';

package/dist/types/metadata.ts

@@ -0,0 +1,57 @@
+/**
+ * Metadata format stored in the metadata.json
+ */
+type JsonMetadata = {
+  deid_study_uid: string;
+  deid_series_uid: string;
+  cod: {
+    instances: Record<
+      string,
+      {
+        metadata: InstanceMetadata;
+        // The metadata will either have url or uri
+        uri: string;
+        url: string;
+        headers: { start_byte: number; end_byte: number };
+        offset_tables: {
+          CustomOffsetTable?: number[];
+          CustomOffsetTableLengths?: number[];
+        };
+        crc32c: string;
+        size: number;
+        original_path: string;
+        dependencies: string[];
+        diff_hash_dupe_paths: [string];
+        version: string;
+        modified_datetime: string;
+      }
+    >;
+  };
+  thumbnail: {
+    version: string;
+    uri: string;
+    thumbnail_index_to_instance_frame: [string, number][];
+    instances: Record<
+      string,
+      {
+        frames: {
+          thumbnail_index: number;
+          anchors: {
+            original_size: { width: number; height: number };
+            thumbnail_upper_left: { row: number; col: number };
+            thumbnail_bottom_right: { row: number; col: number };
+          };
+        }[];
+      }
+    >;
+  };
+};
+
+type InstanceMetadata = Record<
+  string,
+  { vr: string; Value?: unknown[]; BulkDataURI?: string; InlineBinary?: string }
+>;
+
+type SeriesMetadata = InstanceMetadata[];
+
+export type { InstanceMetadata, SeriesMetadata, JsonMetadata };

package/dist/types/metadataUrlCreationParams.ts

@@ -0,0 +1,9 @@
+type MetadataUrlCreationParams = {
+  domain?: string;
+  bucketName: string;
+  bucketPrefix: string;
+  studyInstanceUID: string;
+  seriesInstanceUID: string;
+};
+
+export type { MetadataUrlCreationParams };

package/dist/types/parsedWadoRsUrlDetails.ts

@@ -0,0 +1,13 @@
+import type { Enums } from '../constants';
+
+type ParsedWadoRsUrlDetails = {
+  type: Enums.RequestType;
+  bucketName: string;
+  bucketPrefix: string;
+  studyInstanceUID: string;
+  seriesInstanceUID: string;
+  sopInstanceUID: string;
+  frameNumber: number;
+};
+
+export type { ParsedWadoRsUrlDetails };

package/dist/types/requestOptions.ts

@@ -0,0 +1,12 @@
+import { Enums } from '../constants';
+
+type CODRequestOptions = {
+  useSharedArrayBuffer?: boolean;
+  fetchType?: Enums.FetchType;
+};
+
+type FileRequestOptions = CODRequestOptions & {
+  offsets?: { startByte: number; endByte: number };
+};
+
+export type { CODRequestOptions, FileRequestOptions };

package/dist/types/workerCustomMessageEvents.ts

@@ -0,0 +1,11 @@
+interface FileStreamingMessageEvent extends MessageEvent {
+  data: {
+    url: string;
+    position: number;
+    chunk?: Uint8Array;
+    isAppending?: boolean;
+    fileArraybuffer?: Uint8Array;
+  };
+}
+
+export type { FileStreamingMessageEvent };

package/dist/webWorker/registerWorker.ts

@@ -0,0 +1,33 @@
+import { getWebWorkerManager } from './workerManager';
+
+export function registerWorkers(
+  workerNames: {
+    fileStreamingWorkerName: string;
+    filePartialWorkerName: string;
+  },
+  maxFetchSize: number,
+): void {
+  const { fileStreamingWorkerName, filePartialWorkerName } = workerNames;
+  const workerManager = getWebWorkerManager();
+
+  // fileStreaming worker
+  const streamingWorkerFn = (): Worker =>
+    new Worker(new URL('./workers/fileStreaming.ts', import.meta.url), {
+      name: fileStreamingWorkerName,
+    });
+
+  workerManager.registerWorker(fileStreamingWorkerName, streamingWorkerFn);
+  workerManager.executeTask(
+    fileStreamingWorkerName,
+    'setMaxFetchSize',
+    maxFetchSize,
+  );
+
+  // filePartial worker
+  const partialWorkerFn = (): Worker =>
+    new Worker(new URL('./workers/filePartial.ts', import.meta.url), {
+      name: filePartialWorkerName,
+    });
+
+  workerManager.registerWorker(filePartialWorkerName, partialWorkerFn);
+}

package/dist/webWorker/workerManager.ts

@@ -0,0 +1,83 @@
+import { type Remote, wrap } from 'comlink';
+
+import type { FileStreamingMessageEvent } from '../types';
+
+class WebWorkerManager {
+  private workerRegistry: Record<
+    string,
+    { instance: Remote<Worker>; nativeWorker: Worker }
+  > = {};
+
+  public registerWorker(name: string, workerFn: () => Worker): void {
+    try {
+      const worker: Worker = workerFn();
+      if (!worker) {
+        return;
+      }
+
+      this.workerRegistry[name] = {
+        instance: wrap(worker),
+        nativeWorker: worker,
+      };
+    } catch (error) {
+      console.warn(error);
+    }
+  }
+
+  public async executeTask(
+    workerName: string,
+    taskName: string,
+    options: Record<string, unknown> | unknown,
+  ): Promise<void | ArrayBufferLike> {
+    const worker = this.workerRegistry[workerName]?.instance;
+    if (!worker) {
+      throw new Error(`Worker ${workerName} not registered`);
+    }
+
+    try {
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      return await worker[taskName](options);
+    } catch (error) {
+      console.error(
+        `Error executing task "${taskName}" on worker "${workerName}":`,
+        error,
+      );
+      throw new Error(`Task "${taskName}" failed: ${(error as Error).message}`);
+    }
+  }
+
+  public addEventListener(
+    workerName: string,
+    eventType: keyof WorkerEventMap,
+    listener: (evt: FileStreamingMessageEvent | ErrorEvent) => unknown,
+  ): void {
+    const worker = this.workerRegistry[workerName];
+    if (!worker) {
+      console.error(`Worker type '${workerName}' is not registered.`);
+      return;
+    }
+
+    worker.nativeWorker.addEventListener(eventType, listener);
+  }
+
+  public removeEventListener(
+    workerName: string,
+    eventType: keyof WorkerEventMap,
+    listener: (evt: FileStreamingMessageEvent | ErrorEvent) => unknown,
+  ): void {
+    const worker = this.workerRegistry[workerName];
+    if (!worker) {
+      console.error(`Worker type '${workerName}' is not registered.`);
+      return;
+    }
+
+    worker.nativeWorker.removeEventListener(eventType, listener);
+  }
+}
+
+const webWorkerManager = new WebWorkerManager();
+
+export function getWebWorkerManager(): WebWorkerManager {
+  return webWorkerManager;
+}

package/dist/webWorker/workers/filePartial.ts

@@ -0,0 +1,20 @@
+import { expose } from 'comlink';
+
+const filePartial = {
+  async partial(args: {
+    url: string;
+    headers?: Record<string, string>;
+  }): Promise<ArrayBufferLike | Error> {
+    const { url, headers } = args;
+
+    return fetch(url, { headers })
+      .then((response) => response.arrayBuffer())
+      .catch((error) => {
+        throw new Error(
+          'filePartial.ts: Error when fetching file: ' + error?.message,
+        );
+      });
+  },
+};
+
+expose(filePartial);