feat(decimatedVolumeLoader): optional downsizing and downsampling of volumes.

packages/core/src/cache/classes/BaseStreamingImageVolume.ts

@@ -320,8 +320,10 @@ export default class BaseStreamingImageVolume
     const { transferSyntaxUID: transferSyntaxUID } =
       metaData.get('transferSyntax', imageId) || {};
 
-    const imagePlaneModule = metaData.get('imagePlaneModule', imageId) || {};
-    const { rows, columns } = imagePlaneModule;
+    // Note: per-image rows/columns may be full-res after in-plane decimation.
+    // Always use the current volume's dimensions for allocation.
+    const targetRows = this.dimensions?.[1];
+    const targetCols = this.dimensions?.[0];
     const imageIdIndex = this.getImageIdIndex(imageId);
 
     const modalityLutModule = metaData.get('modalityLutModule', imageId) || {};
@@ -380,8 +382,8 @@ export default class BaseStreamingImageVolume
 
     const targetBuffer = {
       type: this.dataType,
-      rows,
-      columns,
+      rows: targetRows,
+      columns: targetCols,
     };
 
     return {

packages/core/src/cache/classes/StreamingImageVolume.ts

@@ -11,6 +11,9 @@ import BaseStreamingImageVolume from './BaseStreamingImageVolume';
  * It implements load method to load the imageIds and insert them into the volume.
  */
 export default class StreamingImageVolume extends BaseStreamingImageVolume {
+  private imagePostProcess?: (
+    image: PixelDataTypedArray
+  ) => PixelDataTypedArray;
   constructor(
     imageVolumeProperties: ImageVolumeProps,
     streamingProperties: IStreamingVolumeProperties
@@ -21,6 +24,23 @@ export default class StreamingImageVolume extends BaseStreamingImageVolume {
     }
     super(imageVolumeProperties, streamingProperties);
   }
+  public setImagePostProcess(
+    fn: (image: PixelDataTypedArray) => PixelDataTypedArray
+  ) {
+    this.imagePostProcess = fn;
+  }
+
+  // Override successCallback to apply post-process if set
+  public override successCallback(imageId: string, image: PixelDataTypedArray) {
+    if (this.imagePostProcess) {
+      try {
+        image = this.imagePostProcess(image) || image;
+      } catch (e) {
+        console.warn('imagePostProcess failed, using original image', e);
+      }
+    }
+    super.successCallback(imageId, image);
+  }
 
   /**
    * Return the scalar data (buffer)

packages/core/src/index.ts

@@ -64,6 +64,7 @@ import * as volumeLoader from './loaders/volumeLoader';
 import * as imageLoader from './loaders/imageLoader';
 import * as geometryLoader from './loaders/geometryLoader';
 import ProgressiveRetrieveImages from './loaders/ProgressiveRetrieveImages';
+import decimateVolumeLoader from './loaders/decimateVolumeLoader';
 // eslint-disable-next-line import/no-duplicates
 import type * as Types from './types';
 import type {
@@ -168,6 +169,7 @@ export {
   geometryLoader,
   cornerstoneMeshLoader,
   ProgressiveRetrieveImages,
+  decimateVolumeLoader,
   cornerstoneStreamingImageVolumeLoader,
   cornerstoneStreamingDynamicImageVolumeLoader,
   StreamingDynamicImageVolume,

packages/core/src/loaders/decimateVolumeLoader.ts

@@ -0,0 +1,196 @@
+import cache from '../cache/cache';
+import StreamingImageVolume from '../cache/classes/StreamingImageVolume';
+import { RequestType } from '../enums';
+import imageLoadPoolManager from '../requestPool/imageLoadPoolManager';
+import type { IRetrieveConfiguration } from '../types';
+import { generateVolumePropsFromImageIds } from '../utilities/generateVolumePropsFromImageIds';
+import { loadImage } from './imageLoader';
+import decimate from '../utilities/decimate';
+import decimateImagePixels from '../utilities/decimateImagePixels';
+
+interface IVolumeLoader {
+  promise: Promise<StreamingImageVolume>;
+  cancel: () => void;
+  decache: () => void;
+}
+
+/**
+ * It handles loading of a image by streaming in its imageIds. It will be the
+ * volume loader if the schema for the volumeID is `decimateImageVolume`.
+ * This function returns a promise that resolves to the StreamingImageVolume instance.
+ *
+ *
+ * @param volumeId - The ID of the volume
+ * @param options - options for loading, imageIds
+ * @returns a promise that resolves to a StreamingImageVolume
+ */
+export function decimateVolumeLoader(
+  volumeId: string,
+  options: {
+    imageIds: string[];
+    progressiveRendering?: boolean | IRetrieveConfiguration;
+    kDecimation?: number;
+    iDecimation?: number;
+  }
+): IVolumeLoader {
+  if (!options || !options.imageIds || !options.imageIds.length) {
+    throw new Error(
+      'ImageIds must be provided to create a streaming image volume'
+    );
+  }
+
+  const inPlaneDecimation =
+    options.iDecimation && options.iDecimation > 1 ? options.iDecimation : 1;
+  const kAxisDecimation =
+    options.kDecimation && options.kDecimation > 1 ? options.kDecimation : 1;
+
+  const originalImageIds = options.imageIds.slice();
+  const decimatedResult = decimate(originalImageIds, kAxisDecimation);
+
+  const decimatedImageIds =
+    Array.isArray(decimatedResult) &&
+    decimatedResult.length &&
+    typeof decimatedResult[0] === 'number'
+      ? decimatedResult.map((idx) => originalImageIds[idx])
+      : decimatedResult;
+
+  options.imageIds = decimatedImageIds as string[];
+
+  async function getStreamingImageVolume() {
+    /**
+     * Check if we are using the `wadouri:` scheme, and if so, preload first,
+     * middle, and last image metadata as these are the images the current
+     * streaming image loader may explicitly request metadata from. The last image
+     * metadata would only be specifically requested if the imageId array order is
+     * reversed in the `sortImageIdsAndGetSpacing.ts` file.
+     */
+    if (options.imageIds[0].split(':')[0] === 'wadouri') {
+      const [middleImageIndex, lastImageIndex] = [
+        Math.floor(options.imageIds.length / 2),
+        options.imageIds.length - 1,
+      ];
+      const indexesToPrefetch = [0, middleImageIndex, lastImageIndex];
+      await Promise.all(
+        indexesToPrefetch.map((index) => {
+          // check if image is cached
+          if (cache.isLoaded(options.imageIds[index])) {
+            return Promise.resolve(true);
+          }
+          return new Promise((resolve, reject) => {
+            const imageId = options.imageIds[index];
+            imageLoadPoolManager.addRequest(
+              async () => {
+                loadImage(imageId)
+                  .then(() => {
+                    console.log(`Prefetched imageId: ${imageId}`);
+                    resolve(true);
+                  })
+                  .catch((err) => {
+                    reject(err);
+                  });
+              },
+              RequestType.Prefetch,
+              { volumeId },
+              1 // priority
+            );
+          });
+        })
+      ).catch(console.error);
+    }
+
+    const volumeProps = generateVolumePropsFromImageIds(
+      options.imageIds,
+      volumeId
+    );
+
+    let {
+      dimensions,
+      spacing,
+      origin,
+      direction,
+      metadata,
+      imageIds,
+      dataType,
+      numberOfComponents,
+    } = volumeProps;
+
+    // Start from current props and apply decimations independently
+    let newDimensions = [...dimensions] as typeof dimensions;
+    let newSpacing = [...spacing] as typeof spacing;
+
+    // Apply in‑plane decimation (columns = x = index 0, rows = y = index 1)
+    if (inPlaneDecimation > 1) {
+      newDimensions[0] = Math.ceil(newDimensions[0] / inPlaneDecimation);
+      newDimensions[1] = Math.ceil(newDimensions[1] / inPlaneDecimation);
+      newSpacing[0] = newSpacing[0] * inPlaneDecimation; // column spacing (x)
+      newSpacing[1] = newSpacing[1] * inPlaneDecimation; // row spacing (y)
+
+      // DICOM: Rows = Y, Columns = X
+      metadata.Rows = newDimensions[1];
+      metadata.Columns = newDimensions[0];
+      // DICOM PixelSpacing = [row, column] = [y, x]
+      metadata.PixelSpacing = [newSpacing[1], newSpacing[0]];
+    }
+
+    // Do NOT scale Z spacing here. We decimated imageIds before
+    // generating volume props, so sortImageIdsAndGetSpacing already
+    // computed the effective z-spacing between the kept frames.
+
+    // Commit any updates
+    dimensions = newDimensions;
+    spacing = newSpacing;
+    const streamingImageVolume = new StreamingImageVolume(
+      // ImageVolume properties
+      {
+        volumeId,
+        metadata,
+        dimensions,
+        spacing,
+        origin,
+        direction,
+        imageIds,
+        dataType,
+        numberOfComponents,
+      },
+      // Streaming properties
+      {
+        imageIds,
+        loadStatus: {
+          loaded: false,
+          loading: false,
+          cancelled: false,
+          cachedFrames: [],
+          callbacks: [],
+        },
+      }
+    );
+    streamingImageVolume.setImagePostProcess(
+      (image) =>
+        decimateImagePixels(
+          image as unknown as import('../types').IImage,
+          inPlaneDecimation
+        ) as unknown as import('../types').PixelDataTypedArray
+    );
+    console.debug(streamingImageVolume);
+    return streamingImageVolume;
+  }
+
+  const streamingImageVolumePromise = getStreamingImageVolume();
+
+  return {
+    promise: streamingImageVolumePromise,
+    decache: () => {
+      streamingImageVolumePromise.then((streamingImageVolume) => {
+        streamingImageVolume.destroy();
+        streamingImageVolume = null;
+      });
+    },
+    cancel: () => {
+      streamingImageVolumePromise.then((streamingImageVolume) => {
+        streamingImageVolume.cancelLoading();
+      });
+    },
+  };
+}
+
+export default decimateVolumeLoader;

packages/core/src/loaders/index.ts

@@ -1,6 +1,7 @@
 import { cornerstoneStreamingImageVolumeLoader } from './cornerstoneStreamingImageVolumeLoader';
 import { cornerstoneStreamingDynamicImageVolumeLoader } from './cornerstoneStreamingDynamicImageVolumeLoader';
 import { cornerstoneMeshLoader } from './cornerstoneMeshLoader';
+import { decimateVolumeLoader } from './decimateVolumeLoader';
 import * as geometryLoader from './geometryLoader';
 import * as imageLoader from './imageLoader';
 import * as volumeLoader from './volumeLoader';
@@ -9,6 +10,7 @@ export {
   cornerstoneStreamingImageVolumeLoader,
   cornerstoneStreamingDynamicImageVolumeLoader,
   cornerstoneMeshLoader,
+  decimateVolumeLoader,
   geometryLoader,
   imageLoader,
   volumeLoader,

packages/core/src/loaders/volumeLoader.ts

@@ -28,10 +28,13 @@ import {
 import { generateVolumePropsFromImageIds } from '../utilities/generateVolumePropsFromImageIds';
 import type { StreamingDynamicImageVolume } from '../cache';
 import { cornerstoneStreamingImageVolumeLoader } from './cornerstoneStreamingImageVolumeLoader';
+import { decimateVolumeLoader } from './decimateVolumeLoader';
 
 interface VolumeLoaderOptions {
   imageIds: string[];
   progressiveRendering?: boolean;
+  kDecimation?: number; // Optional parameter for decimation factor
+  iDecimation?: number; // Optional parameter for interleave decimation
 }
 
 interface DerivedVolumeOptions {

packages/core/src/utilities/decimateImagePixels.ts

@@ -0,0 +1,70 @@
+import type { IImage, PixelDataTypedArray } from '../types';
+export default function decimateImagePixels(image: IImage, factor: number) {
+  // Trivial case: no decimation requested
+  if (!factor || factor <= 1) {
+    return image;
+  }
+
+  const rows = image.rows ?? image.height;
+  const cols = image.columns ?? image.width;
+  const newRows = Math.ceil(rows / factor);
+  const newCols = Math.ceil(cols / factor);
+
+  const pixelData = image.getPixelData();
+  const numComponents = image.numberOfComponents || 1;
+  const OutArrayCtor = pixelData.constructor as unknown as new (
+    length: number
+  ) => PixelDataTypedArray;
+  const out = new OutArrayCtor(newRows * newCols * numComponents);
+
+  let outIndex = 0;
+  for (let r = 0; r < newRows; r++) {
+    const inR = r * factor;
+    if (inR >= rows) break;
+    for (let c = 0; c < newCols; c++) {
+      const inC = c * factor;
+      if (inC >= cols) break;
+      const src = (inR * cols + inC) * numComponents;
+      for (let k = 0; k < numComponents; k++) {
+        out[outIndex++] = pixelData[src + k];
+      }
+    }
+  }
+
+  // Spacing: prefer explicit row/column spacing; preserve Z
+  const s = (image as unknown as { spacing?: [number, number, number] })
+    .spacing;
+  const newSpacing: [number, number, number] = [
+    (image.columnPixelSpacing ?? s?.[0] ?? 1) * factor,
+    (image.rowPixelSpacing ?? s?.[1] ?? 1) * factor,
+    s?.[2] ?? image.sliceThickness ?? 1,
+  ];
+  const colSpacing = newSpacing[0];
+  const rowSpacing = newSpacing[1];
+
+  // Carry over imageFrame when present
+  let imageFrame = image.imageFrame
+    ? {
+        ...image.imageFrame,
+        rows: newRows,
+        columns: newCols,
+        pixelData: out,
+        pixelDataLength: out.length,
+      }
+    : undefined;
+  // Note: some loaders attach a non-standard imageInfo; skip updating to avoid type casting.
+
+  return {
+    ...image,
+    rows: newRows,
+    columns: newCols,
+    width: newCols,
+    height: newRows,
+    rowPixelSpacing: rowSpacing,
+    columnPixelSpacing: colSpacing,
+    spacing: newSpacing,
+    sizeInBytes: out.byteLength,
+    getPixelData: () => imageFrame?.pixelData ?? out,
+    imageFrame,
+  };
+}