feat(OpenGL/Texture): update sub-image extents

vtkVolumeMapper, vtkImageCPRMapper, and vtkImageResliceMapper all now
support updating sub-image extents, reducing the GPU upload overhead
when part of the image has updated.

Author: floryst

Sources/Rendering/Core/ImageCPRMapper/index.d.ts

@@ -1,5 +1,5 @@
 import { mat3, mat4, quat, vec3 } from 'gl-matrix';
-import { Nullable } from '../../../types';
+import { Extent, Nullable } from '../../../types';
 import { vtkOutputPort } from '../../../interfaces';
 import vtkAbstractMapper3D, {
   IAbstractMapper3DInitialValues,
@@ -307,6 +307,25 @@ export interface vtkImageCPRMapper
    * @param imageData
    */
   setImageConnection(imageData: vtkOutputPort): void;
+
+  /**
+   * Tells the mapper to only update the specified extents.
+   *
+   * If there are zero extents, the mapper updates the entire volume texture.
+   * Otherwise, the mapper will only update the texture by the specified extents
+   * during the next render call.
+   *
+   * This array is cleared after a successful render.
+   * @param extents
+   */
+  setUpdatedExtents(extents: Extent[]): boolean;
+
+  /**
+   * Retrieves the updated extents.
+   *
+   * This array is cleared after every successful render.
+   */
+  getUpdatedExtents(): Extent[];
 }
 
 /**

Sources/Rendering/Core/ImageCPRMapper/index.js

@@ -331,7 +331,7 @@ function vtkImageCPRMapper(publicAPI, model) {
 // Object factory
 // ----------------------------------------------------------------------------
 
-const DEFAULT_VALUES = {
+const defaultValues = (initialValues) => ({
   width: 10,
   uniformOrientation: [0, 0, 0, 1],
   useUniformOrientation: false,
@@ -344,12 +344,14 @@ const DEFAULT_VALUES = {
   projectionSlabThickness: 1,
   projectionSlabNumberOfSamples: 1,
   projectionMode: ProjectionMode.MAX,
-};
+  updatedExtents: [],
+  ...initialValues,
+});
 
 // ----------------------------------------------------------------------------
 
 export function extend(publicAPI, model, initialValues = {}) {
-  Object.assign(model, DEFAULT_VALUES, initialValues);
+  Object.assign(model, defaultValues(initialValues));
 
   // Inheritance
   vtkAbstractImageMapper.extend(publicAPI, model, initialValues);
@@ -374,6 +376,7 @@ export function extend(publicAPI, model, initialValues = {}) {
     'projectionSlabThickness',
     'projectionSlabNumberOfSamples',
     'projectionMode',
+    'updatedExtents',
   ]);
   CoincidentTopologyHelper.implementCoincidentTopologyMethods(publicAPI, model);
 

Sources/Rendering/Core/ImageResliceMapper/index.d.ts

@@ -1,10 +1,9 @@
 import vtkAbstractImageMapper, {
   IAbstractImageMapperInitialValues,
 } from '../AbstractImageMapper';
-import vtkImageData from '../../../Common/DataModel/ImageData';
 import vtkPlane from '../../../Common/DataModel/Plane';
 import vtkPolyData from '../../../Common/DataModel/PolyData';
-import { Bounds, Nullable, Vector3 } from '../../../types';
+import { Bounds, Extent } from '../../../types';
 import { SlabTypes } from './Constants';
 import CoincidentTopologyHelper, {
   StaticCoincidentTopologyMethods,
@@ -116,6 +115,25 @@ export interface vtkImageResliceMapper
    * @param {vtkPolyData} slicePolyData The polydata to slice the volume with. Default: null
    */
   setSlicePolyData(slicePolyData: vtkPolyData): boolean;
+
+  /**
+   * Tells the mapper to only update the specified extents.
+   *
+   * If there are zero extents, the mapper updates the entire volume texture.
+   * Otherwise, the mapper will only update the texture by the specified extents
+   * during the next render call.
+   *
+   * This array is cleared after a successful render.
+   * @param extents
+   */
+  setUpdatedExtents(extents: Extent[]): boolean;
+
+  /**
+   * Retrieves the updated extents.
+   *
+   * This array is cleared after every successful render.
+   */
+  getUpdatedExtents(): Extent[];
 }
 
 /**

Sources/Rendering/Core/ImageResliceMapper/index.js

@@ -39,18 +39,20 @@ function vtkImageResliceMapper(publicAPI, model) {
 // Object factory
 // ----------------------------------------------------------------------------
 
-const DEFAULT_VALUES = {
+const defaultValues = (initialValues) => ({
   slabThickness: 0.0,
   slabTrapezoidIntegration: 0,
   slabType: SlabTypes.MEAN,
   slicePlane: null,
   slicePolyData: null,
-};
+  updatedExtents: [],
+  ...initialValues,
+});
 
 // ----------------------------------------------------------------------------
 
 export function extend(publicAPI, model, initialValues = {}) {
-  Object.assign(model, DEFAULT_VALUES, initialValues);
+  Object.assign(model, defaultValues(initialValues));
 
   // Build VTK API
   vtkAbstractImageMapper.extend(publicAPI, model, initialValues);
@@ -61,6 +63,7 @@ export function extend(publicAPI, model, initialValues = {}) {
     'slabType',
     'slicePlane',
     'slicePolyData',
+    'updatedExtents',
   ]);
   CoincidentTopologyHelper.implementCoincidentTopologyMethods(publicAPI, model);
 

Sources/Rendering/Core/VolumeMapper/index.d.ts

@@ -1,5 +1,5 @@
 import vtkPiecewiseFunction from '../../../Common/DataModel/PiecewiseFunction';
-import { Bounds, Range } from '../../../types';
+import { Bounds, Range, Extent } from '../../../types';
 import vtkAbstractMapper3D, {
   IAbstractMapper3DInitialValues,
 } from '../AbstractMapper3D';
@@ -281,6 +281,39 @@ export interface vtkVolumeMapper extends vtkAbstractMapper3D {
    */
   setLAOKernelRadius(LAOKernelRadius: number): void;
 
+  /**
+   * Set kernel size for local ambient occlusion. It specifies the number of rays that are randomly sampled in the hemisphere.
+   * Value is clipped between 1 and 32.
+   * @param LAOKernelSize
+   */
+  setLAOKernelSize(LAOKernelSize: number): void;
+
+  /**
+   * Set kernel radius for local ambient occlusion. It specifies the number of samples that are considered on each random ray.
+   * Value must be greater than or equal to 1.
+   * @param LAOKernelRadius
+   */
+  setLAOKernelRadius(LAOKernelRadius: number): void;
+
+  /**
+   * Tells the mapper to only update the specified extents.
+   *
+   * If there are zero extents, the mapper updates the entire volume texture.
+   * Otherwise, the mapper will only update the texture by the specified extents
+   * during the next render call.
+   *
+   * This array is cleared after a successful render.
+   * @param extents
+   */
+  setUpdatedExtents(extents: Extent[]): boolean;
+
+  /**
+   * Retrieves the updated extents.
+   *
+   * This array is cleared after every successful render.
+   */
+  getUpdatedExtents(): Extent[];
+
   /**
    *
    */

Sources/Rendering/Core/VolumeMapper/index.js

@@ -141,7 +141,7 @@ function vtkVolumeMapper(publicAPI, model) {
 // ----------------------------------------------------------------------------
 
 // TODO: what values to use for averageIPScalarRange to get GLSL to use max / min values like [-Math.inf, Math.inf]?
-const DEFAULT_VALUES = {
+const defaultValues = (initialValues) => ({
   bounds: [1, -1, 1, -1, 1, -1],
   sampleDistance: 1.0,
   imageSampleDistance: 1.0,
@@ -163,12 +163,14 @@ const DEFAULT_VALUES = {
   localAmbientOcclusion: false,
   LAOKernelSize: 15,
   LAOKernelRadius: 7,
-};
+  updatedExtents: [],
+  ...initialValues,
+});
 
 // ----------------------------------------------------------------------------
 
 export function extend(publicAPI, model, initialValues = {}) {
-  Object.assign(model, DEFAULT_VALUES, initialValues);
+  Object.assign(model, defaultValues(initialValues));
 
   vtkAbstractMapper3D.extend(publicAPI, model, initialValues);
 
@@ -190,6 +192,7 @@ export function extend(publicAPI, model, initialValues = {}) {
     'localAmbientOcclusion',
     'LAOKernelSize',
     'LAOKernelRadius',
+    'updatedExtents',
   ]);
 
   macro.setGetArray(publicAPI, model, ['ipScalarRange'], 2);

Sources/Rendering/OpenGL/ImageCPRMapper/index.js

@@ -199,6 +199,9 @@ function vtkOpenGLImageCPRMapper(publicAPI, model) {
     const reBuildTex =
       !cachedScalarsEntry?.oglObject?.getHandle() ||
       cachedScalarsEntry?.hash !== volumeTextureHash;
+    const updatedExtents = model.renderable.getUpdatedExtents();
+    const hasUpdatedExtents = !!updatedExtents.length;
+
     if (reBuildTex) {
       model.volumeTexture = vtkOpenGLTexture.newInstance();
       model.volumeTexture.setOpenGLRenderWindow(model._openGLRenderWindow);
@@ -236,6 +239,22 @@ function vtkOpenGLImageCPRMapper(publicAPI, model) {
       model.volumeTexture = cachedScalarsEntry.oglObject;
     }
 
+    if (hasUpdatedExtents) {
+      // If hasUpdatedExtents, then the texture is partially updated.
+      // clear the array to acknowledge the update.
+      model.renderable.setUpdatedExtents([]);
+
+      const dims = image.getDimensions();
+      model.volumeTexture.create3DFilterableFromDataArray(
+        dims[0],
+        dims[1],
+        dims[2],
+        scalars,
+        false,
+        updatedExtents
+      );
+    }
+
     // Rebuild the color texture if needed
     const numComp = scalars.getNumberOfComponents();
     const ppty = actor.getProperty();

Sources/Rendering/OpenGL/ImageResliceMapper/index.js

@@ -232,21 +232,28 @@ function vtkOpenGLImageResliceMapper(publicAPI, model) {
 
     const tex = model._openGLRenderWindow.getGraphicsResourceForObject(scalars);
     const reBuildTex = !tex?.oglObject?.getHandle() || tex?.hash !== toString;
-    if (reBuildTex) {
+    const updatedExtents = model.renderable.getUpdatedExtents();
+    const hasUpdatedExtents = !!updatedExtents.length;
+
+    if (reBuildTex && !hasUpdatedExtents) {
       model.openGLTexture = vtkOpenGLTexture.newInstance();
       model.openGLTexture.setOpenGLRenderWindow(model._openGLRenderWindow);
       // Build the image scalar texture
-      const dims = image.getDimensions();
       // Use norm16 for the 3D texture if the extension is available
       model.openGLTexture.setOglNorm16Ext(
         model.context.getExtension('EXT_texture_norm16')
       );
       model.openGLTexture.resetFormatAndType();
+
+      // Build the image scalar texture
+      const dims = image.getDimensions();
       model.openGLTexture.create3DFilterableFromDataArray(
         dims[0],
         dims[1],
         dims[2],
-        scalars
+        scalars,
+        false,
+        updatedExtents
       );
       model._openGLRenderWindow.setGraphicsResourceForObject(
         scalars,
@@ -268,6 +275,22 @@ function vtkOpenGLImageResliceMapper(publicAPI, model) {
       model.openGLTexture = tex.oglObject;
     }
 
+    if (hasUpdatedExtents) {
+      // If hasUpdatedExtents, then the texture is partially updated.
+      // clear the array to acknowledge the update.
+      model.renderable.setUpdatedExtents([]);
+
+      const dims = image.getDimensions();
+      model.openGLTexture.create3DFilterableFromDataArray(
+        dims[0],
+        dims[1],
+        dims[2],
+        scalars,
+        false,
+        updatedExtents
+      );
+    }
+
     const ppty = actor.getProperty();
     const iComps = ppty.getIndependentComponents();
     const numIComps = iComps ? numComp : 1;

Sources/Rendering/OpenGL/Texture/index.d.ts

@@ -1,6 +1,6 @@
 import { Wrap, Filter } from './Constants';
 import vtkOpenGLRenderWindow from '../RenderWindow';
-import { Nullable } from '../../../types';
+import { Extent, Nullable } from '../../../types';
 import { VtkDataTypes } from '../../../Common/Core/DataArray';
 import { vtkViewNode } from '../../../Rendering/SceneGraph/ViewNode';
 import { vtkObject, vtkRange } from '../../../interfaces';
@@ -275,12 +275,16 @@ export interface vtkOpenGLTexture extends vtkViewNode {
 
   /**
    * Creates a 3D texture from raw data.
+   *
+   * updatedExtents is currently incompatible with webgl1, since there's no extent scaling.
+   *
    * @param width The width of the texture.
    * @param height The height of the texture.
    * @param depth The depth of the texture.
    * @param numComps The number of components in the texture.
    * @param dataType The data type of the texture.
    * @param data The raw data for the texture.
+   * @param updatedExtents Only update the specified extents (default: [])
    * @returns {boolean} True if the texture was successfully created, false otherwise.
    */
   create3DFromRaw(
@@ -289,11 +293,15 @@ export interface vtkOpenGLTexture extends vtkViewNode {
     depth: number,
     numComps: number,
     dataType: VtkDataTypes,
-    data: any
+    data: any,
+    updatedExtents?: Extent[]
   ): boolean;
 
   /**
    * Creates a 3D filterable texture from raw data, with a preference for size over accuracy if necessary.
+   *
+   * updatedExtents is currently incompatible with webgl1, since there's no extent scaling.
+   *
    * @param width The width of the texture.
    * @param height The height of the texture.
    * @param depth The depth of the texture.
@@ -302,6 +310,7 @@ export interface vtkOpenGLTexture extends vtkViewNode {
    * @param values The raw data for the texture.
    * @param preferSizeOverAccuracy Whether to prefer texture size over accuracy.
    * @param [ranges] The precomputed ranges of the data (optional). Provided to
+   * @param updatedExtents Only update the specified extents (default: [])
    * prevent computation of the data ranges.
    * @returns {boolean} True if the texture was successfully created, false
    * otherwise.
@@ -314,24 +323,30 @@ export interface vtkOpenGLTexture extends vtkViewNode {
     dataType: VtkDataTypes,
     values: any,
     preferSizeOverAccuracy: boolean,
-    ranges?: vtkRange[]
+    ranges?: vtkRange[],
+    updatedExtents?: Extent[]
   ): boolean;
 
   /**
    * Creates a 3D filterable texture from a data array, with a preference for size over accuracy if necessary.
+   *
+   * updatedExtents is currently incompatible with webgl1, since there's no extent scaling.
+   *
    * @param width The width of the texture.
    * @param height The height of the texture.
    * @param depth The depth of the texture.
    * @param dataArray The data array to use for the texture.
    * @param preferSizeOverAccuracy Whether to prefer texture size over accuracy.
+   * @param updatedExtents Only update the specified extents (default: [])
    * @returns {boolean} True if the texture was successfully created, false otherwise.
    */
   create3DFilterableFromDataArray(
     width: number,
     height: number,
     depth: number,
     dataArray: any,
-    preferSizeOverAccuracy: boolean
+    preferSizeOverAccuracy: boolean,
+    updatedExtents?: Extent[]
   ): boolean;
 
   /**