refactor(OpenGL/Texture): use named parameters

BREAKING_CHANGES.md

@@ -1,6 +1,8 @@
 ## From 32.x to 33
 
 - **vtkMapper**: many properties have moved to `vtkVolumeProperty`. The full list of changed methods is: `getAnisotropy`, `getComputeNormalFromOpacity`, `getFilterMode`, `getFilterModeAsString`, `getGlobalIlluminationReach`, `getIpScalarRange`, `getIpScalarRangeByReference`, `getLAOKernelRadius`, `getLAOKernelSize`, `getLocalAmbientOcclusion`, `getPreferSizeOverAccuracy`, `getVolumetricScatteringBlending`, `setAnisotropy`, `setAverageIPScalarRange`, `setComputeNormalFromOpacity`, `setFilterMode`, `setFilterModeToNormalized`, `setFilterModeToOff`, `setFilterModeToRaw`, `setGlobalIlluminationReach`, `setIpScalarRange`, `setIpScalarRangeFrom`, `setLAOKernelRadius`, `setLAOKernelSize`, `setLocalAmbientOcclusion`, `setPreferSizeOverAccuracy`, `setVolumetricScatteringBlending`.
+- **vtkOpenGLTexture**: The public `create2D*` and `create3D*` methods used to have positional parameters. These methods now use named parameters via passing in an object record.
+
 ## From 31.x to 32
 
 - **vtkMapper**: remove `mapScalarsToTexture` from the public API. The function becomes protected and its API changes. This shouldn't cause any issue in most cases.

Sources/Common/Core/DataArray/index.d.ts

@@ -83,6 +83,23 @@ export interface vtkDataArray extends vtkObject {
    */
   setRange(rangeValue: vtkRange, componentIndex: number): Range;
 
+  /**
+   * Returns an array of the ranges for each component of the DataArray.
+   * Defaults to computing all the ranges if they aren't already computed.
+   *
+   * If the number of components is greater than 1, the last element in the
+   * ranges array is the min,max magnitude of the dataset. This is the same as
+   * calling `getRange(-1)`.
+   *
+   * Passing `getRanges(false)` will return  a clone of the ranges that have
+   * already been computed. This is useful when you want to avoid recomputing
+   * the ranges, which can be expensive.
+   *
+   * @param {boolean} [computeRanges] (default: true)
+   * @returns {vtkRange[]}
+   */
+  getRanges(computeRanges: boolean): vtkRange[];
+
   /**
    * Set the given tuple at the given index.
    * @param {Number} idx

Sources/Common/Core/DataArray/index.js

@@ -281,6 +281,35 @@ function vtkDataArray(publicAPI, model) {
     return model.rangeTuple;
   };
 
+  publicAPI.getRanges = (computeRanges = true) => {
+    if (!computeRanges) {
+      return structuredClone(model.ranges);
+    }
+    /** @type {import('../../../interfaces').vtkRange[]} */
+    const ranges = [];
+    for (let i = 0; i < model.numberOfComponents; i++) {
+      const [min, max] = publicAPI.getRange(i);
+      /** @type {import('../../../interfaces').vtkRange} */
+      const range = {
+        min,
+        max,
+      };
+      ranges.push(range);
+    }
+    // where the number of components is greater than 1, the last element in
+    // the range array is the min,max magnitude of the entire dataset.
+    if (model.numberOfComponents > 1) {
+      const [min, max] = publicAPI.getRange(-1);
+      /** @type {import('../../../interfaces').vtkRange} */
+      const range = {
+        min,
+        max,
+      };
+      ranges.push(range);
+    }
+    return ranges;
+  };
+
   publicAPI.setTuple = (idx, tuple) => {
     const offset = idx * model.numberOfComponents;
     for (let i = 0; i < model.numberOfComponents; i++) {
@@ -447,12 +476,18 @@ function vtkDataArray(publicAPI, model) {
     return sortedObj;
   };
 
+  /**
+   * @param {import("./index").vtkDataArray} other
+   */
   publicAPI.deepCopy = (other) => {
     // Retain current dataType and array reference before shallowCopy call.
     const currentType = publicAPI.getDataType();
     const currentArray = model.values;
     publicAPI.shallowCopy(other);
 
+    // set the ranges
+    model.ranges = structuredClone(other.getRanges());
+
     // Avoid array reallocation if size already sufficient
     // and dataTypes match.
     if (

Sources/Common/Core/DataArray/test/testDataArray.js

@@ -131,6 +131,36 @@ test('Test vtkDataArray getRange function with NaN values.', (t) => {
   t.end();
 });
 
+test('Test vtkDataArray getRanges function with single-channel data.', (t) => {
+  // create a data array with a single channel.
+  const newArray = new Uint16Array(256 * 3);
+
+  // fill the new array with the pattern 0,1,2,3,4,5, ..., 767.
+  for (let i = 0; i < 256 * 3; ++i) {
+    newArray[i] = i;
+  }
+
+  const da = vtkDataArray.newInstance({
+    numberOfComponents: 1,
+    values: newArray,
+  });
+
+  t.ok(
+    da.getRanges().length === 1,
+    'getRanges should return an array of 1 vtkRange objects'
+  );
+  t.ok(
+    da.getRanges()[0].min === 0,
+    'the first component returned by getRanges minimum value should be 0'
+  );
+  t.ok(
+    da.getRanges()[0].max === 767,
+    'the first component returned by getRanges maximum value should be 767'
+  );
+
+  t.end();
+});
+
 test('Test vtkDataArray getTuple', (t) => {
   const da = vtkDataArray.newInstance({
     numberOfComponents: 3,
@@ -202,6 +232,98 @@ test('Test vtkDataArray getRange function with multi-channel data.', (t) => {
   t.end();
 });
 
+test('Test vtkDataArray getRanges function with multi-channel data.', (t) => {
+  // create a data array with 3 channel data.
+  const numberOfPixels = 10;
+  const numberOfComponents = 4;
+  const newArray = new Uint16Array(numberOfPixels * numberOfComponents);
+
+  // fill the new array with the pattern 1,2,3, 1,2,3
+  // such that each channel has 1,1,1  2,2,2  3,3,3 respectively.
+  for (let i = 0; i < numberOfPixels; ++i) {
+    newArray[i * numberOfComponents] = i;
+    newArray[i * numberOfComponents + 1] = i * 2;
+    newArray[i * numberOfComponents + 2] = i * 3;
+    newArray[i * numberOfComponents + 3] = i * 4;
+  }
+
+  const da = vtkDataArray.newInstance({
+    numberOfComponents,
+    values: newArray,
+  });
+
+  const ranges = da.getRanges();
+
+  t.ok(
+    ranges.length === numberOfComponents + 1,
+    'getRanges should return an array of 5 vtkRange objects'
+  );
+  t.ok(ranges[0].min === 0, 'component:0 minimum value should be 0');
+  t.ok(ranges[0].max === 9, 'component:0 maximum value should be 9');
+  t.ok(ranges[1].min === 0, 'component:1 minimum value should be 0');
+  t.ok(ranges[1].max === 18, 'component:1 maximum value should be 18');
+  t.ok(ranges[2].min === 0, 'component:2 minimum value should be 0');
+  t.ok(ranges[2].max === 27, 'component:2 maximum value should be 27 ');
+  t.ok(
+    ranges[2].min === 0,
+    'component:-1 vector magnitude minimum should be 0'
+  );
+  t.ok(
+    ranges[3].max === 36,
+    'component:-1 vector magnitude maximum should be 36'
+  );
+
+  t.end();
+});
+
+test('Test vtkDataArray getRanges(false) (`computeRanges=false`) function with multi-channel data', (t) => {
+  // create a data array with 3 channel data.
+  const numberOfPixels = 10;
+  const numberOfComponents = 4;
+  const newArray = new Uint16Array(numberOfPixels * numberOfComponents);
+
+  // fill the new array with the pattern 1,2,3, 1,2,3
+  // such that each channel has 1,1,1  2,2,2  3,3,3 respectively.
+  for (let i = 0; i < numberOfPixels; ++i) {
+    newArray[i * numberOfComponents] = i;
+    newArray[i * numberOfComponents + 1] = i * 2;
+    newArray[i * numberOfComponents + 2] = i * 3;
+    newArray[i * numberOfComponents + 3] = i * 4;
+  }
+
+  const da = vtkDataArray.newInstance({
+    numberOfComponents,
+    values: newArray,
+  });
+
+  // set `computeRanges` to false.  This will prevent the ranges from being
+  // computed and will return only the ranges previously computer (if any).
+  const ranges = da.getRanges(false);
+
+  t.ok(ranges === undefined, `getRanges should return undefined`);
+
+  // now fetch the range for component 0.
+  da.getRange(0);
+
+  // now fetch the ranges again with `computeRanges` set to false.
+  const updatedRanges = da.getRanges(false);
+
+  // `updatedRanges` should now be only the range for component 0. because if
+  // was computed in `da.getRange(0)`
+  t.ok(
+    updatedRanges.length === numberOfComponents + 1,
+    'getRanges should return an array of 5 vtkRange objects'
+  );
+  t.ok(updatedRanges[0].min === 0, 'component:0 minimum value should be 0');
+  t.ok(updatedRanges[0].max === 9, 'component:0 maximum value should be 9');
+  t.ok(updatedRanges[1] === null, 'component:1 should be null');
+  t.ok(updatedRanges[2] === null, 'component:2 should be null');
+  t.ok(updatedRanges[3] === null, 'component:3 should be null');
+  t.ok(updatedRanges[4] === null, 'component:-1 should be null');
+
+  t.end();
+});
+
 test('Test vtkDataArray insertNextTuple', (t) => {
   const dataArray = vtkDataArray.newInstance({
     dataType: VtkDataTypes.UNSIGNED_CHAR,

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

@@ -122,6 +122,87 @@ export interface vtkAbstractImageMapper extends vtkAbstractMapper3D {
    * @param customDisplayExtent
    */
   setCustomDisplayExtentFrom(customDisplayExtent: number[]): boolean;
+
+  /**
+   * Set the opacity texture width.
+   *
+   * The default width (1024) should be fine in most instances.
+   * Only set this property if your opacity function range width is
+   * larger than 1024.
+   *
+   * A reasonable max texture size would be either 2048 or 4096, as those
+   * widths are supported by the vast majority of devices. Any width larger
+   * than that will have issues with device support.
+   *
+   * Specifying a width that is less than or equal to 0 will use the largest
+   * possible texture width on the device. Use this with caution! The max texture
+   * width of one device may not be the same for another device.
+   *
+   * You can find more information about supported texture widths at the following link:
+   * https://web3dsurvey.com/webgl/parameters/MAX_TEXTURE_SIZE
+   *
+   * @param {Number} width the texture width (defaults to 1024)
+   */
+  setOpacityTextureWidth(width: number): boolean;
+
+  /**
+   * Get the opacity texture width.
+   */
+  getOpacityTextureWidth(): number;
+
+  /**
+   * Set the color texture width.
+   *
+   * The default width (1024) should be fine in most instances.
+   * Only set this property if your color transfer function range width is
+   * larger than 1024.
+   *
+   * A reasonable max texture size would be either 2048 or 4096, as those
+   * widths are supported by the vast majority of devices. Any width larger
+   * than that will have issues with device support.
+   *
+   * Specifying a width that is less than or equal to 0 will use the largest
+   * possible texture width on the device. Use this with caution! The max texture
+   * width of one device may not be the same for another device.
+   *
+   * You can find more information about supported texture widths at the following link:
+   * https://web3dsurvey.com/webgl/parameters/MAX_TEXTURE_SIZE
+   *
+   * @param {Number} width the texture width (defaults to 1024)
+   */
+  setColorTextureWidth(width: number): boolean;
+
+  /**
+   * Get the color texture width.
+   */
+  getColorTextureWidth(): number;
+
+  /**
+   * Set the label outline texture width.
+   *
+   * The default width (1024) should be fine in most instances.
+   * Only set this property if you have more than 1024 labels
+   * that you want to render with thickness.
+   *
+   * A reasonable max texture size would be either 2048 or 4096, as those
+   * widths are supported by the vast majority of devices. Any width larger
+   * than that will have issues with device support.
+   *
+   * Specifying a width that is less than or equal to 0 will use the largest
+   * possible texture width on the device. Use this with caution! The max texture
+   * width of one device may not be the same for another device.
+   *
+   * You can find more information about supported texture widths at the following link:
+   * https://web3dsurvey.com/webgl/parameters/MAX_TEXTURE_SIZE
+   *
+   * @param {Number} width the texture width (defaults to 1024)
+   */
+  setLabelOutlineTextureWidth(width: number): boolean;
+
+  /**
+   * Get the label outline texture width.
+   */
+  getLabelOutlineTextureWidth(): number;
 }
 
 /**

Sources/Rendering/Core/AbstractImageMapper/index.js

@@ -30,6 +30,9 @@ const DEFAULT_VALUES = {
   customDisplayExtent: [0, 0, 0, 0, 0, 0],
   useCustomExtents: false,
   backgroundColor: [0, 0, 0, 1],
+  colorTextureWidth: 1024,
+  opacityTextureWidth: 1024,
+  labelOutlineTextureWidth: 1024,
 };
 
 // ----------------------------------------------------------------------------
@@ -40,7 +43,13 @@ export function extend(publicAPI, model, initialValues = {}) {
   // Build VTK API
   vtkAbstractMapper3D.extend(publicAPI, model, initialValues);
 
-  macro.setGet(publicAPI, model, ['slice', 'useCustomExtents']);
+  macro.setGet(publicAPI, model, [
+    'slice',
+    'useCustomExtents',
+    'colorTextureWidth',
+    'opacityTextureWidth',
+    'labelOutlineTextureWidth',
+  ]);
   macro.setGetArray(publicAPI, model, ['customDisplayExtent'], 6);
   macro.setGetArray(publicAPI, model, ['backgroundColor'], 4);