Introduction

vtkImageMapper provides 2D image display support for vtk.
It can be associated with a vtkImageSlice prop and placed within a Renderer.

This class resolves coincident topology with the same methods as vtkMapper.

Methods

extend

Method use to decorate a given object (publicAPI+model) with vtkAbstractImageMapper characteristics.

Argument	Type	Required	Description
`publicAPI`		Yes	object on which methods will be bounds (public)
`model`		Yes	object on which data structure will be bounds (protected)
`initialValues`	IAbstractImageMapperInitialValues	No	(default: {})

getBackgroundColor

Return the currently set background color.

getBackgroundColorByReference

Return the currently set background color.

getBoundsForSlice

Get bounds for a specified slice.
To be implemented by derived classes.

Argument	Type	Required	Description
`slice`	Number	Yes	The slice index. If undefined, the current slice is considered.
`thickness`	Number	Yes	The slice thickness. If undefined, 0 is considered.

getColorTextureWidth

Get the color texture width.

getCurrentImage

Return currently active image for the mapper. Overridden by deriving classes.

getCustomDisplayExtent

getCustomDisplayExtentByReference

getIsOpaque

getLabelOutlineTextureWidth

Get the label outline texture width.

getOpacityTextureWidth

Get the opacity texture width.

getSlice

Get the slice index.

getUseCustomExtents

setBackgroundColor

Argument	Type	Required	Description
`color`		Yes	specify background color as an array of 4 values.

setBackgroundColor

Argument	Required	Description
`r`	Yes	red component of background color
`g`	Yes	green component of background color
`b`	Yes	blue component of background color
`a`	Yes	opacity component of background color

setBackgroundColorFrom

Argument	Type	Required	Description
`color`	RGBAColor	Yes	specify the background color to use in RGBA format as an array of 4 values. Values are copied.

setColorTextureWidth

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

Argument	Type	Required	Description
`width`	Number	Yes	the texture width (defaults to 1024)

setCustomDisplayExtent

Argument	Type	Required	Description
`extents`		Yes	specify extents as an array of 6 values [minx, maxx, …]

setCustomDisplayExtent

Argument	Type	Required	Description
`x1`	Number	Yes	The x coordinate of the first point.
`x2`	Number	Yes	The x coordinate of the second point.
`y1`	Number	Yes	The y coordinate of the first point.
`y2`	Number	Yes	The y coordinate of the second point.
`z1`	Number	Yes	The z coordinate of the first point.
`z2`	Number	Yes	The z coordinate of the second point.

setCustomDisplayExtentFrom

Argument	Type	Required	Description
`customDisplayExtent`		Yes

setLabelOutlineTextureWidth

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.

You can find more information about supported texture widths at the following link:
https://web3dsurvey.com/webgl/parameters/MAX_TEXTURE_SIZE

Argument	Type	Required	Description
`width`	Number	Yes	the texture width (defaults to 1024)

setOpacityTextureWidth

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.

You can find more information about supported texture widths at the following link:
https://web3dsurvey.com/webgl/parameters/MAX_TEXTURE_SIZE

Argument	Type	Required	Description
`width`	Number	Yes	the texture width (defaults to 1024)

setSlice

Argument	Type	Required	Description
`slice`	Number	Yes	The slice index.

setUseCustomExtents

Argument	Type	Required	Description
`useCustomExtents`	Boolean	Yes

Source

helper.js

import { vec3 } from 'gl-matrix';
import vtkPlane from 'vtk.js/Sources/Common/DataModel/Plane';

/**
 * Perform plane-line intersection, where the line is defined by two points (p1, p2),
 * and the plane is defined by the imageData and slice number.
 *
 * @param {Vector3} p1
 * @param {Vector3} p2
 * @param {vtkImageMapper|vtkImageArrayMapper} mapper
 */
function doPicking(p1, p2, mapper) {
  const imageData = mapper.getCurrentImage();
  const extent = imageData.getExtent();

  // Slice origin
  const ijk = [extent[0], extent[2], extent[4]];
  const { ijkMode } = mapper.getClosestIJKAxis();
  let nSlice = mapper.isA('vtkImageArrayMapper')
    ? mapper.getSubSlice()
    : mapper.getSlice();
  if (ijkMode !== mapper.getSlicingMode()) {
    // If not IJK slicing, get the IJK slice from the XYZ position/slice
    nSlice = mapper.getSliceAtPosition(nSlice);
  }
  ijk[ijkMode] += nSlice;
  const worldOrigin = [0, 0, 0];
  imageData.indexToWorld(ijk, worldOrigin);

  // Normal computation
  ijk[ijkMode] += 1;
  const worldNormal = [0, 0, 0];
  imageData.indexToWorld(ijk, worldNormal);
  worldNormal[0] -= worldOrigin[0];
  worldNormal[1] -= worldOrigin[1];
  worldNormal[2] -= worldOrigin[2];
  vec3.normalize(worldNormal, worldNormal);

  const intersect = vtkPlane.intersectWithLine(
    p1,
    p2,
    worldOrigin,
    worldNormal
  );
  if (intersect.intersection) {
    const point = intersect.x;
    const absoluteIJK = [0, 0, 0];
    imageData.worldToIndex(point, absoluteIJK);
    // `t` is the parametric position along the line
    // defined in Plane.intersectWithLine
    return {
      t: intersect.t,
      absoluteIJK,
    };
  }
  return null;
}

/**
 * Implement point picking for image plane.
 * The plane is defined by the imageData and current slice number,
 * set in the input mapper.
 *
 * @param {Vector3} p1
 * @param {Vector3} p2
 * @param {vtkImageMapper|vtkImageArrayMapper} mapper
 */
export function intersectWithLineForPointPicking(p1, p2, mapper) {
  const pickingData = doPicking(p1, p2, mapper);
  if (pickingData) {
    const imageData = mapper.getCurrentImage();
    const extent = imageData.getExtent();

    // Get closer integer ijk
    // NB: point picking means closest slice, means rounding
    const ijk = [
      Math.round(pickingData.absoluteIJK[0]),
      Math.round(pickingData.absoluteIJK[1]),
      Math.round(pickingData.absoluteIJK[2]),
    ];

    // Are we outside our actual extent
    if (
      ijk[0] < extent[0] ||
      ijk[0] > extent[1] ||
      ijk[1] < extent[2] ||
      ijk[1] > extent[3] ||
      ijk[2] < extent[4] ||
      ijk[2] > extent[5]
    ) {
      return null;
    }

    return {
      t: pickingData.t,
      ijk,
    };
  }
  return null;
}

/**
 * Implement cell picking for image plane.
 * The plane is defined by the imageData and current slice number,
 * set in the input mapper.
 *
 * @param {Vector3} p1
 * @param {Vector3} p2
 * @param {vtkImageMapper|vtkImageArrayMapper} mapper
 */
export function intersectWithLineForCellPicking(p1, p2, mapper) {
  const pickingData = doPicking(p1, p2, mapper);
  if (pickingData) {
    const imageData = mapper.getCurrentImage();
    const extent = imageData.getExtent();
    const absIJK = pickingData.absoluteIJK;

    // Get closer integer ijk
    // NB: cell picking means closest voxel, means flooring
    const ijk = [
      Math.floor(absIJK[0]),
      Math.floor(absIJK[1]),
      Math.floor(absIJK[2]),
    ];

    // Are we outside our actual extent
    if (
      ijk[0] < extent[0] ||
      ijk[0] > extent[1] - 1 ||
      ijk[1] < extent[2] ||
      ijk[1] > extent[3] - 1 ||
      ijk[2] < extent[4] ||
      // handle single-slice images
      ijk[2] > (extent[5] ? extent[5] - 1 : extent[5])
    ) {
      return null;
    }

    // Parametric coordinates within cell
    const pCoords = [
      absIJK[0] - ijk[0],
      absIJK[1] - ijk[1],
      absIJK[2] - ijk[2],
    ];

    return {
      t: pickingData.t,
      ijk,
      pCoords,
    };
  }
  return null;
}

index.d.ts

import vtkAbstractMapper3D, {
  IAbstractMapper3DInitialValues,
} from '../AbstractMapper3D';
import vtkImageData from '../../../Common/DataModel/ImageData';
import { Bounds, Extent, Nullable, RGBAColor } from '../../../types';

export interface IAbstractImageMapperInitialValues
  extends IAbstractMapper3DInitialValues {
  customDisplayExtent?: number[];
  useCustomExtents?: boolean;
  slice?: number;
}

export interface vtkAbstractImageMapper extends vtkAbstractMapper3D {
  /**
   *
   */
  getIsOpaque(): boolean;

  /**
   * Return currently active image for the mapper. Overridden by deriving classes.
   */
  getCurrentImage(): Nullable<vtkImageData>;

  /**
   * Get the slice index.
   */
  getSlice(): number;

  /**
   *
   * @param {Number} slice The slice index.
   */
  setSlice(slice: number): boolean;

  /**
   * Get bounds for a specified slice.
   * To be implemented by derived classes.
   * @param {Number} slice The slice index. If undefined, the current slice is considered.
   * @param {Number} thickness The slice thickness. If undefined, 0 is considered.
   */
  getBoundsForSlice(slice?: number, thickness?: number): Bounds;

  /**
   * Return the currently set background color.
   */
  getBackgroundColor(): RGBAColor;

  /**
   * Return the currently set background color.
   */
  getBackgroundColorByReference(): RGBAColor;

  /**
   * @param r red component of background color
   * @param g green component of background color
   * @param b blue component of background color
   * @param a opacity component of background color
   */
  setBackgroundColor(r: number, g: number, b: number, a: number): boolean;

  /**
   *
   * @param color specify background color as an array of 4 values.
   */
  setBackgroundColor(color: RGBAColor): boolean;

  /**
   *
   * @param {RGBAColor} color specify the background color to use
   * in RGBA format as an array of 4 values. Values are copied.
   */
  setBackgroundColorFrom(color: RGBAColor): boolean;

  /**
   *
   */
  getUseCustomExtents(): boolean;

  /**
   *
   * @param {Boolean} useCustomExtents
   */
  setUseCustomExtents(useCustomExtents: boolean): boolean;

  /**
   *
   */
  getCustomDisplayExtent(): Extent;

  /**
   *
   */
  getCustomDisplayExtentByReference(): Extent;

  /**
   *
   * @param {Number} x1 The x coordinate of the first point.
   * @param {Number} x2 The x coordinate of the second point.
   * @param {Number} y1 The y coordinate of the first point.
   * @param {Number} y2 The y coordinate of the second point.
   * @param {Number} z1 The z coordinate of the first point.
   * @param {Number} z2 The z coordinate of the second point.
   */
  setCustomDisplayExtent(
    x1: number,
    x2: number,
    y1: number,
    y2: number,
    z1: number,
    z2: number
  ): boolean;

  /**
   *
   * @param extents specify extents as an array of 6 values [minx, maxx, ...]
   */
  setCustomDisplayExtent(customDisplayExtent: Extent): boolean;

  /**
   *
   * @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;
}

/**
 * Method use to decorate a given object (publicAPI+model) with vtkAbstractImageMapper characteristics.
 *
 * @param publicAPI object on which methods will be bounds (public)
 * @param model object on which data structure will be bounds (protected)
 * @param {IAbstractImageMapperInitialValues} [initialValues] (default: {})
 */
export function extend(
  publicAPI: object,
  model: object,
  initialValues?: IAbstractImageMapperInitialValues
): void;

/**
 * vtkImageMapper provides 2D image display support for vtk.
 * It can be associated with a vtkImageSlice prop and placed within a Renderer.
 *
 * This class resolves coincident topology with the same methods as vtkMapper.
 */
export declare const vtkAbstractImageMapper: {
  extend: typeof extend;
};
export default vtkAbstractImageMapper;

index.js

import macro from 'vtk.js/Sources/macros';
import vtkAbstractMapper3D from 'vtk.js/Sources/Rendering/Core/AbstractMapper3D';
import { createUninitializedBounds } from 'vtk.js/Sources/Common/Core/Math';

// ----------------------------------------------------------------------------
// vtkAbstractImageMapper methods
// ----------------------------------------------------------------------------

function vtkAbstractImageMapper(publicAPI, model) {
  model.classHierarchy.push('vtkAbstractImageMapper');

  publicAPI.getIsOpaque = () => true;

  publicAPI.getCurrentImage = () => null;

  publicAPI.getBoundsForSlice = () => {
    macro.vtkErrorMacro(
      'vtkAbstractImageMapper.getBoundsForSlice - NOT IMPLEMENTED'
    );
    return createUninitializedBounds();
  };
}

// ----------------------------------------------------------------------------
// Object factory
// ----------------------------------------------------------------------------

const DEFAULT_VALUES = {
  slice: 0,
  customDisplayExtent: [0, 0, 0, 0, 0, 0],
  useCustomExtents: false,
  backgroundColor: [0, 0, 0, 1],
  colorTextureWidth: 1024,
  opacityTextureWidth: 1024,
  labelOutlineTextureWidth: 1024,
};

// ----------------------------------------------------------------------------

export function extend(publicAPI, model, initialValues = {}) {
  Object.assign(model, DEFAULT_VALUES, initialValues);

  // Build VTK API
  vtkAbstractMapper3D.extend(publicAPI, model, initialValues);

  macro.setGet(publicAPI, model, [
    'slice',
    'useCustomExtents',
    'colorTextureWidth',
    'opacityTextureWidth',
    'labelOutlineTextureWidth',
  ]);
  macro.setGetArray(publicAPI, model, ['customDisplayExtent'], 6);
  macro.setGetArray(publicAPI, model, ['backgroundColor'], 4);

  vtkAbstractImageMapper(publicAPI, model);
}

// ----------------------------------------------------------------------------
export default { extend };