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

packages/core/examples/volumeViewport3D/index.ts

@@ -81,14 +81,15 @@ addButtonToToolbar({
     viewport.render();
   },
 });
-
 addDropdownToToolbar({
   options: {
     values: CONSTANTS.VIEWPORT_PRESETS.map((preset) => preset.name),
     defaultValue: 'CT-Bone',
   },
   onSelectedValueChange: (presetName) => {
-    viewport.setProperties({ preset: presetName });
+    const renderingEngine = getRenderingEngine(renderingEngineId);
+    const viewport = renderingEngine.getViewport(viewportId);
+    viewport.setProperties({ preset: presetName as string });
     viewport.render();
   },
 });
@@ -99,15 +100,17 @@ addDropdownToToolbar({
     defaultValue: 1,
   },
   onSelectedValueChange: (sampleDistanceMultiplier) => {
-    viewport.setProperties({ sampleDistanceMultiplier });
+    const renderingEngine = getRenderingEngine(renderingEngineId);
+    const viewport = renderingEngine.getViewport(viewportId);
+    viewport.setProperties({
+      sampleDistanceMultiplier: Number(sampleDistanceMultiplier),
+    });
     viewport.render();
   },
 });
 
 // ============================= //
 
-let viewport;
-
 /**
  * Runs the demo
  */

packages/core/src/RenderingEngine/BaseVolumeViewport.ts

@@ -1024,6 +1024,7 @@ abstract class BaseVolumeViewport extends Viewport {
         colormap,
         preset,
         slabThickness,
+        sampleDistanceMultiplier,
       });
     }
 

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

@@ -320,8 +320,9 @@ export class BaseStreamingImageVolume
     const { transferSyntaxUID: transferSyntaxUID } =
       metaData.get('transferSyntax', imageId) || {};
 
-    const imagePlaneModule = metaData.get('imagePlaneModule', imageId) || {};
-    const { rows, columns } = imagePlaneModule;
+    // Use the actual dimensions for this volume in order to support volumes not the same size as the raw data
+    const targetRows = this.dimensions[1];
+    const targetCols = this.dimensions[0];
     const imageIdIndex = this.getImageIdIndex(imageId);
 
     const modalityLutModule = metaData.get('modalityLutModule', imageId) || {};
@@ -380,8 +381,8 @@ export class BaseStreamingImageVolume
 
     const targetBuffer = {
       type: this.dataType,
-      rows,
-      columns,
+      rows: targetRows,
+      columns: targetCols,
     };
 
     return {

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 { decimatedVolumeLoader } from './loaders/decimatedVolumeLoader';
 // eslint-disable-next-line import/no-duplicates
 import type * as Types from './types';
 import type {
@@ -88,6 +89,8 @@ import {
   addImageSlicesToViewports,
 } from './RenderingEngine/helpers';
 
+export * from './loaders/decimatedVolumeLoader';
+
 // Add new types here so that they can be imported singly as required.
 export type {
   Types,
@@ -168,6 +171,7 @@ export {
   geometryLoader,
   cornerstoneMeshLoader,
   ProgressiveRetrieveImages,
+  decimatedVolumeLoader,
   cornerstoneStreamingImageVolumeLoader,
   cornerstoneStreamingDynamicImageVolumeLoader,
   StreamingDynamicImageVolume,

packages/core/src/loaders/decimatedVolumeLoader.ts

@@ -0,0 +1,246 @@
+import StreamingImageVolume from '../cache/classes/StreamingImageVolume';
+import type { IRetrieveConfiguration } from '../types';
+import { generateVolumePropsFromImageIds } from '../utilities/generateVolumePropsFromImageIds';
+import decimate from '../utilities/decimate';
+import VoxelManager from '../utilities/VoxelManager';
+import {
+  applyDecimatedVolumeModifiers,
+  inPlaneDecimationModifier,
+} from './decimatedVolumeModifiers';
+import type {
+  DecimatedVolumeLoaderOptions,
+  DecimatedVolumeModifierContext,
+  points,
+} from './decimatedVolumeModifiers';
+interface IVolumeLoader {
+  promise: Promise<StreamingImageVolume>;
+  cancel: () => void;
+  decache: () => void;
+}
+
+/**
+ * Decimated volume loader that creates a StreamingImageVolume while delegating
+ * volume mutations to a plugin-style modifier chain. The loader still handles the
+ * responsibilities of preparing imageIds (including optional k-axis decimation),
+ * instantiating the streaming volume, and updating VTK/voxel-manager state, but it
+ * now relies on `decimatedVolumeModifiers` to encapsulate any transformations that
+ * are specific to projection parameters such as decimation.
+ *
+ * The loader currently wires a dedicated modifier set for:
+ * - **K-axis decimation handling**: Removes slices before metadata generation so
+ *   that spacing reflects the decimated stack without manual scaling.
+ * - **In-plane decimation**: Implemented by `InPlaneDecimationModifier`, which
+ *   updates dimensions, spacing, and DICOM metadata in a self-contained class.
+ *
+ * Additional modifiers can be introduced by implementing the shared
+ * `DecimatedVolumeModifier` interface. For example:
+ * ```
+ * const modifiers = [
+ *   inPlaneDecimationModifier,
+ *   orientationModifier,         // rotates the direction matrix or redefines axis order
+ *   partialRangeModifier,        // limits the volume to a subset of frames / slices
+ *   windowingModifier,           // applies window/level or LUT adjustments at load time
+ * ];
+ * ```
+ * Modifiers are executed via `applyDecimatedVolumeModifiers`, so the loader still
+ * just selects the set to run and trusts the chain to mutate props appropriately.
+ *
+ * @param volumeId - The unique identifier for the volume
+ * @param options - Configuration options for volume loading
+ * @param options.imageIds - Array of DICOM imageIds to construct the volume from (required)
+ * @param options.progressiveRendering - Enable progressive rendering or provide custom
+ *   retrieve configuration for streaming behavior
+ * @param options.ijkDecimation - Decimation factors for [I, J, K] axes where I/J affect
+ *   in-plane resolution and K affects slice count. Defaults to [1, 1, 1] (no decimation).
+ *   Example: [2, 2, 2] reduces dimensions by half in all axes.
+ *
+ * *
+ * @returns An object containing:
+ *   - `promise`: Resolves to the created StreamingImageVolume instance
+ *   - `cancel`: Function to cancel ongoing volume loading
+ *   - `decache`: Function to destroy and remove the volume from cache
+ *
+ * @throws Error if imageIds are not provided or empty
+ *
+ * @example
+ * ```typescript
+ * const volumeLoader = decimatedVolumeLoader('volumeId', {
+ *   imageIds: ['dicomweb:...', 'dicomweb:...'],
+ *   ijkDecimation: [2, 2, 2], // Half resolution in all dimensions
+ *   progressiveRendering: true
+ * });
+ *
+ * const volume = await volumeLoader.promise;
+ * // Later: volumeLoader.cancel() or volumeLoader.decache()
+ * ```
+ */
+export function decimatedVolumeLoader(
+  volumeId: string,
+  options: {
+    imageIds: string[];
+    progressiveRendering?: boolean | IRetrieveConfiguration;
+    ijkDecimation?: points.points3;
+  }
+): IVolumeLoader {
+  if (!options || !options.imageIds || !options.imageIds.length) {
+    throw new Error(
+      'ImageIds must be provided to create a streaming image volume '
+    );
+  }
+
+  // Use provided decimation or default to [1, 1, 1]
+  // The hanging protocol service is responsible for providing decimation values
+  const [iDecimation = 1, jDecimation = iDecimation, kDecimation = 1] =
+    options.ijkDecimation ?? [];
+  const columnDecimation = Math.max(1, Math.floor(iDecimation));
+  const rowDecimation =
+    jDecimation > 1 ? Math.max(1, Math.floor(jDecimation)) : columnDecimation;
+  const kAxisDecimation = Math.max(1, Math.floor(kDecimation));
+  const hasInPlaneDecimation = columnDecimation > 1 || rowDecimation > 1;
+
+  const modifierOptions: DecimatedVolumeLoaderOptions = {
+    ijkDecimation: [
+      columnDecimation,
+      rowDecimation,
+      kAxisDecimation,
+    ] as points.points3,
+  };
+  const modifiers = [inPlaneDecimationModifier];
+
+  function addDecimationToImageId(imageId: string, factor: number): string {
+    // Only add marker if decimation is applied
+    if (factor === 1) {
+      return imageId;
+    }
+    // URL fragments (after #) are NOT sent to the server in HTTP requests,
+    // so this keeps decimated imageIds unique for caching without affecting backend requests
+    return `${imageId}#decimation=${factor}`;
+  }
+
+  // Check if k-decimation has already been applied at the displaySet level
+  const expectedDecimatedCount = Math.floor(
+    options.imageIds.length / kAxisDecimation
+  );
+  const isAlreadyDecimated =
+    kAxisDecimation > 1 &&
+    options.imageIds.length <= expectedDecimatedCount + 1;
+
+  if (kAxisDecimation > 1 && !isAlreadyDecimated) {
+    const decimatedResult = decimate(options.imageIds, kAxisDecimation);
+
+    const decimatedImageIds =
+      Array.isArray(decimatedResult) &&
+      decimatedResult.length &&
+      typeof decimatedResult[0] === 'number'
+        ? decimatedResult.map((idx) => options.imageIds[idx])
+        : decimatedResult;
+
+    options.imageIds = decimatedImageIds as string[];
+  }
+
+  // Apply in-plane decimation parameter to imageIds
+  // row and column decimation are always the same in this implementation so we use column
+  if (columnDecimation > 1) {
+    options.imageIds = options.imageIds.map((imageId) =>
+      addDecimationToImageId(imageId, columnDecimation)
+    );
+  }
+
+  async function getStreamingImageVolume() {
+    const baseVolumeProps = generateVolumePropsFromImageIds(
+      options.imageIds,
+      volumeId
+    );
+
+    const modifierContext: DecimatedVolumeModifierContext = {
+      volumeId,
+      imageIds: options.imageIds,
+      options: modifierOptions,
+    };
+
+    const volumeProps = applyDecimatedVolumeModifiers(
+      baseVolumeProps,
+      modifiers,
+      modifierContext
+    );
+
+    const {
+      dimensions,
+      spacing,
+      origin,
+      direction,
+      metadata,
+      imageIds,
+      dataType,
+      numberOfComponents,
+    } = volumeProps;
+
+    const streamingImageVolume = new StreamingImageVolume(
+      {
+        volumeId,
+        metadata,
+        dimensions,
+        spacing,
+        origin,
+        direction,
+        imageIds,
+        dataType,
+        numberOfComponents,
+      },
+      {
+        imageIds,
+        loadStatus: {
+          loaded: false,
+          loading: false,
+          cancelled: false,
+          cachedFrames: [],
+          callbacks: [],
+        },
+      }
+    );
+
+    if (hasInPlaneDecimation) {
+      const vtkImageData = streamingImageVolume.imageData;
+      if (vtkImageData) {
+        vtkImageData.setDimensions(streamingImageVolume.dimensions);
+        vtkImageData.setSpacing(streamingImageVolume.spacing);
+        vtkImageData.modified();
+      }
+
+      const newVoxelManager = VoxelManager.createImageVolumeVoxelManager({
+        dimensions: streamingImageVolume.dimensions,
+        imageIds: streamingImageVolume.imageIds,
+        numberOfComponents: numberOfComponents,
+      });
+
+      streamingImageVolume.voxelManager = newVoxelManager;
+
+      if (vtkImageData) {
+        vtkImageData.set({
+          voxelManager: newVoxelManager,
+        });
+      }
+    }
+
+    return streamingImageVolume;
+  }
+
+  const streamingImageVolumePromise = getStreamingImageVolume();
+
+  return {
+    promise: streamingImageVolumePromise,
+    decache: () => {
+      streamingImageVolumePromise.then((streamingImageVolume) => {
+        streamingImageVolume.destroy();
+        streamingImageVolume = null;
+      });
+    },
+    cancel: () => {
+      streamingImageVolumePromise.then((streamingImageVolume) => {
+        streamingImageVolume.cancelLoading();
+      });
+    },
+  };
+}
+
+export default decimatedVolumeLoader;

packages/core/src/loaders/decimatedVolumeModifiers/applyDecimatedVolumeModifiers.ts

@@ -0,0 +1,19 @@
+import type { ImageVolumeProps } from '../../types';
+import type {
+  DecimatedVolumeModifier,
+  DecimatedVolumeModifierContext,
+} from './types';
+
+/**
+ * Runs every modifier sequentially and returns the final props.
+ */
+export function applyDecimatedVolumeModifiers(
+  baseProps: ImageVolumeProps,
+  modifiers: DecimatedVolumeModifier[],
+  context: DecimatedVolumeModifierContext
+): ImageVolumeProps {
+  return modifiers.reduce(
+    (currentProps, modifier) => modifier.apply(currentProps, context),
+    baseProps
+  );
+}