Mapper2D

Introduction

vtkMapper2D is an abstract class to specify interface between data and
graphics primitives. Subclasses of vtkMapper map data through a
lookuptable and control the creation of rendering primitives that
interface to the graphics library. The mapping can be controlled by
supplying a lookup table and specifying a scalar range to map data
through.

There are several important control mechanisms affecting the behavior of
this object. The ScalarVisibility flag controls whether scalar data (if
any) controls the color of the associated actor(s) that refer to the
mapper. The ScalarMode ivar is used to determine whether scalar point data
or cell data is used to color the object. By default, point data scalars
are used unless there are none, then cell scalars are used. Or you can
explicitly control whether to use point or cell scalar data. Finally, the
mapping of scalars through the lookup table varies depending on the
setting of the ColorMode flag. See the documentation for the appropriate
methods for an explanation.

Another important feature of this class is whether to use immediate mode
rendering (ImmediateModeRenderingOn) or display list rendering
(ImmediateModeRenderingOff). If display lists are used, a data structure
is constructed (generally in the rendering library) which can then be
rapidly traversed and rendered by the rendering library. The disadvantage
of display lists is that they require additional memory which may affect
the performance of the system.

Another important feature of the mapper is the ability to shift the
Z-buffer to resolve coincident topology. For example, if you’d like to
draw a mesh with some edges a different color, and the edges lie on the
mesh, this feature can be useful to get nice looking lines. (See the
ResolveCoincidentTopology-related methods.)

Methods

createDefaultLookupTable

Create default lookup table. Generally used to create one when
none is available with the scalar data.

extend

Method used to decorate a given object (publicAPI+model) with vtkMapper2D 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 IMapper2DInitialValues No (default: {})

getAbstractScalars

Argument Type Required Description
input Yes
scalarMode ScalarMode Yes
arrayAccessMode Yes
arrayId Yes
arrayName Yes

getArrayAccessMode

getColorByArrayName

Get the array name to color by.

getColorMapColors

Provide read access to the color array.

getColorMode

Return the method of coloring scalar data.

getColorModeAsString

Return the method of coloring scalar data.

getCustomShaderAttributes

getLookupTable

Get a lookup table for the mapper to use.

getScalarMode

Return the method for obtaining scalar data.

getScalarModeAsString

Return the method for obtaining scalar data.

getScalarRange

getScalarRangeByReference

getScalarVisibility

Check whether scalar data is used to color objects.

getStatic

Check whether the mapper’s data is static.

getTransformCoordinate

Get the transformCoordinate.

getUseLookupTableScalarRange

getViewSpecificProperties

mapScalars

Map the scalars (if there are any scalars and ScalarVisibility is on)
through the lookup table, returning an unsigned char RGBA array. This is
typically done as part of the rendering process. The alpha parameter
allows the blending of the scalars with an additional alpha (typically
which comes from a vtkActor, etc.)
{
rgba: Uint8Array(),
location: 0/1/2, // Points/Cells/Fields
}

Argument Type Required Description
input Yes
alpha Number Yes

newInstance

Method used to create a new instance of vtkMapper2D

Argument Type Required Description
initialValues IMapper2DInitialValues No for pre-setting some of its content

setArrayAccessMode

Argument Type Required Description
arrayAccessMode Number Yes

setColorByArrayName

Set the array name to color by.

Argument Type Required Description
colorByArrayName String Yes

setColorMode

Argument Type Required Description
colorMode Number Yes

setColorModeToDefault

Sets colorMode to DEFAULT

setColorModeToDirectScalars

Sets colorMode to DIRECT_SCALARS

setColorModeToMapScalars

Sets colorMode to MAP_SCALARS

setCustomShaderAttributes

Sets point data array names that will be transferred to the VBO

Argument Type Required Description
customShaderAttributes Array. Yes

setLookupTable

Set a lookup table for the mapper to use.

setScalarMode

Control how the filter works with scalar point data and cell attribute
data. By default (ScalarModeToDefault), the filter will use point data,
and if no point data is available, then cell data is used. Alternatively
you can explicitly set the filter to use point data
(ScalarModeToUsePointData) or cell data (ScalarModeToUseCellData).
You can also choose to get the scalars from an array in point field
data (ScalarModeToUsePointFieldData) or cell field data
(ScalarModeToUseCellFieldData). If scalars are coming from a field
data array, you must call SelectColorArray before you call GetColors.

When ScalarMode is set to use Field Data (ScalarModeToFieldData),
you must call SelectColorArray to choose the field data array to
be used to color cells. In this mode, the default behavior is to
treat the field data tuples as being associated with cells. If
the poly data contains triangle strips, the array is expected to
contain the cell data for each mini-cell formed by any triangle
strips in the poly data as opposed to treating them as a single
tuple that applies to the entire strip. This mode can also be
used to color the entire poly data by a single color obtained by
mapping the tuple at a given index in the field data array
through the color map. Use SetFieldDataTupleId() to specify
the tuple index.

Argument Type Required Description
scalarMode Yes

setScalarModeToDefault

Sets scalarMode to DEFAULT

setScalarModeToUseCellData

Sets scalarMode to USE_CELL_DATA

setScalarModeToUseCellFieldData

Sets scalarMode to USE_CELL_FIELD_DATA

setScalarModeToUseFieldData

Sets scalarMode to USE_FIELD_DATA

setScalarModeToUsePointData

Sets scalarMode to USE_POINT_DATA

setScalarModeToUsePointFieldData

Sets scalarMode to USE_POINT_FIELD_DATA

setScalarRange

Specify range in terms of scalar minimum and maximum (smin,smax). These
values are used to map scalars into lookup table. Has no effect when
UseLookupTableScalarRange is true.

Argument Type Required Description
scalarRange Yes

setScalarRange

Specify range in terms of scalar minimum and maximum (smin,smax). These
values are used to map scalars into lookup table. Has no effect when
UseLookupTableScalarRange is true.

Argument Type Required Description
min Yes
max Yes

setScalarRangeFrom

Argument Type Required Description
scalarRange Yes

setScalarVisibility

Turn on/off flag to control whether scalar data is used to color objects.

Argument Type Required Description
scalarVisibility Boolean Yes

setStatic

Turn on/off flag to control whether the mapper’s data is static. Static data
means that the mapper does not propagate updates down the pipeline, greatly
decreasing the time it takes to update many mappers. This should only be
used if the data never changes.

Argument Type Required Description
static Boolean Yes

setTransformCoordinate

Set the transformCoordinate.

setUseLookupTableScalarRange

Control whether the mapper sets the lookuptable range based on its
own ScalarRange, or whether it will use the LookupTable ScalarRange
regardless of it’s own setting. By default the Mapper is allowed to set
the LookupTable range, but users who are sharing LookupTables between
mappers/actors will probably wish to force the mapper to use the
LookupTable unchanged.

Argument Type Required Description
useLookupTableScalarRange Boolean Yes

setViewSpecificProperties

If you want to provide specific properties for rendering engines you can use
viewSpecificProperties.

You can go and have a look in the rendering backend of your choice for details
on specific properties.
For example, for OpenGL/WebGL see OpenGL/PolyDataMapper/api.md
If there is no details, viewSpecificProperties is not supported.

Argument Type Required Description
viewSpecificProperties Yes

Source

index.d.ts
import { Nullable } from '../../../types';
import vtkAbstractMapper, {
IAbstractMapperInitialValues,
} from '../AbstractMapper';

export enum ColorMode {
DEFAULT,
MAP_SCALARS,
DIRECT_SCALARS,
}

export enum ScalarMode {
DEFAULT,
USE_POINT_DATA,
USE_CELL_DATA,
USE_POINT_FIELD_DATA,
USE_CELL_FIELD_DATA,
USE_FIELD_DATA,
}

export enum GetArray {
BY_ID,
BY_NAME,
}

interface IPrimitiveCount {
points: number;
verts: number;
lines: number;
triangles: number;
}

interface IAbstractScalars {
cellFlag: boolean;
}

export interface IMapper2DInitialValues extends IAbstractMapperInitialValues {
arrayAccessMode?: number;
colorMode?: number;
customShaderAttributes?: any;
renderTime?: number;
scalarMode?: number;
scalarRange?: Range;
scalarVisibility?: boolean;
static?: boolean;
}

export interface vtkMapper2D extends vtkAbstractMapper {
/**
* Create default lookup table. Generally used to create one when
* none is available with the scalar data.
*/
createDefaultLookupTable(): void;

/**
*
* @param input
* @param {ScalarMode} scalarMode
* @param arrayAccessMode
* @param arrayId
* @param arrayName
*/
getAbstractScalars(
input: any,
scalarMode: ScalarMode,
arrayAccessMode: number,
arrayId: any,
arrayName: any
): IAbstractScalars;

/**
*
*/
getArrayAccessMode(): number;

/**
* Get the array name to color by.
*/
getColorByArrayName(): Nullable<string>;

/**
* Provide read access to the color array.
*/
getColorMapColors(): Nullable<Uint8Array>;

/**
* Return the method of coloring scalar data.
*/
getColorMode(): number;

/**
* Return the method of coloring scalar data.
*/
getColorModeAsString(): string;

/**
*
* @default []
*/
getCustomShaderAttributes(): any;

/**
* Get a lookup table for the mapper to use.
*/
getLookupTable(): any;

/**
* Get the transformCoordinate.
*/
getTransformCoordinate(): any;

/**
* Return the method for obtaining scalar data.
*/
getScalarMode(): number;

/**
* Return the method for obtaining scalar data.
*/
getScalarModeAsString(): string;

/**
*
* @default [0, 1]
*/
getScalarRange(): number[];

/**
*
* @default [0, 1]
*/
getScalarRangeByReference(): number[];

/**
* Check whether scalar data is used to color objects.
* @default true
*/
getScalarVisibility(): boolean;

/**
* Check whether the mapper’s data is static.
* @default false
*/
getStatic(): boolean;

/**
*
* @default false
*/
getUseLookupTableScalarRange(): boolean;

/**
*
* @default null
*/
getViewSpecificProperties(): object;

/**
* Map the scalars (if there are any scalars and ScalarVisibility is on)
* through the lookup table, returning an unsigned char RGBA array. This is
* typically done as part of the rendering process. The alpha parameter
* allows the blending of the scalars with an additional alpha (typically
* which comes from a vtkActor, etc.)
* {
* rgba: Uint8Array(),
* location: 0/1/2, // Points/Cells/Fields
* }
* @param input
* @param {Number} alpha
*/
mapScalars(input: any, alpha: number): void;

/**
*
* @param {Number} arrayAccessMode
*/
setArrayAccessMode(arrayAccessMode: number): boolean;

/**
* Set the array name to color by.
* @param {String} colorByArrayName
*/
setColorByArrayName(colorByArrayName: string): boolean;

/**
*
* @param {Number} colorMode
*/
setColorMode(colorMode: number): boolean;

/**
* Sets colorMode to `DEFAULT`
*/
setColorModeToDefault(): boolean;

/**
* Sets colorMode to `MAP_SCALARS`
*/
setColorModeToMapScalars(): boolean;

/**
* Sets colorMode to `DIRECT_SCALARS`
*/
setColorModeToDirectScalars(): boolean;

/**
* Sets point data array names that will be transferred to the VBO
* @param {String[]} customShaderAttributes
*/
setCustomShaderAttributes(customShaderAttributes: string[]): boolean;

/**
* Set a lookup table for the mapper to use.
*/
setLookupTable(lookupTable: any): boolean;

/**
* Set the transformCoordinate.
*/
setTransformCoordinate(coordinate: any): boolean;

/**
* Control how the filter works with scalar point data and cell attribute
* data. By default (ScalarModeToDefault), the filter will use point data,
* and if no point data is available, then cell data is used. Alternatively
* you can explicitly set the filter to use point data
* (ScalarModeToUsePointData) or cell data (ScalarModeToUseCellData).
* You can also choose to get the scalars from an array in point field
* data (ScalarModeToUsePointFieldData) or cell field data
* (ScalarModeToUseCellFieldData). If scalars are coming from a field
* data array, you must call SelectColorArray before you call GetColors.
*
* When ScalarMode is set to use Field Data (ScalarModeToFieldData),
* you must call SelectColorArray to choose the field data array to
* be used to color cells. In this mode, the default behavior is to
* treat the field data tuples as being associated with cells. If
* the poly data contains triangle strips, the array is expected to
* contain the cell data for each mini-cell formed by any triangle
* strips in the poly data as opposed to treating them as a single
* tuple that applies to the entire strip. This mode can also be
* used to color the entire poly data by a single color obtained by
* mapping the tuple at a given index in the field data array
* through the color map. Use SetFieldDataTupleId() to specify
* the tuple index.
*
* @param scalarMode
*/
setScalarMode(scalarMode: number): boolean;

/**
* Sets scalarMode to DEFAULT
*/
setScalarModeToDefault(): boolean;

/**
* Sets scalarMode to USE_CELL_DATA
*/
setScalarModeToUseCellData(): boolean;

/**
* Sets scalarMode to USE_CELL_FIELD_DATA
*/
setScalarModeToUseCellFieldData(): boolean;

/**
* Sets scalarMode to USE_FIELD_DATA
*/
setScalarModeToUseFieldData(): boolean;

/**
* Sets scalarMode to USE_POINT_DATA
*/
setScalarModeToUsePointData(): boolean;

/**
* Sets scalarMode to USE_POINT_FIELD_DATA
*/
setScalarModeToUsePointFieldData(): boolean;

/**
* Specify range in terms of scalar minimum and maximum (smin,smax). These
* values are used to map scalars into lookup table. Has no effect when
* UseLookupTableScalarRange is true.
*
* @param min
* @param max
* @default [0, 1]
*/
setScalarRange(min: number, max: number): boolean;

/**
* Specify range in terms of scalar minimum and maximum (smin,smax). These
* values are used to map scalars into lookup table. Has no effect when
* UseLookupTableScalarRange is true.
*
* @param scalarRange
* @default [0, 1]
*/
setScalarRange(scalarRange: number[]): boolean;

/**
*
* @param scalarRange
* @default [0, 1]
*/
setScalarRangeFrom(scalarRange: number[]): boolean;

/**
* Turn on/off flag to control whether scalar data is used to color objects.
* @param {Boolean} scalarVisibility
* @default true
*/
setScalarVisibility(scalarVisibility: boolean): boolean;

/**
* Turn on/off flag to control whether the mapper’s data is static. Static data
* means that the mapper does not propagate updates down the pipeline, greatly
* decreasing the time it takes to update many mappers. This should only be
* used if the data never changes.
*
* @param {Boolean} static
* @default false
*/
setStatic(static: boolean): boolean;

/**
* Control whether the mapper sets the lookuptable range based on its
* own ScalarRange, or whether it will use the LookupTable ScalarRange
* regardless of it’s own setting. By default the Mapper is allowed to set
* the LookupTable range, but users who are sharing LookupTables between
* mappers/actors will probably wish to force the mapper to use the
* LookupTable unchanged.
*
* @param {Boolean} useLookupTableScalarRange
* @default false
*/
setUseLookupTableScalarRange(useLookupTableScalarRange: boolean): boolean;

/**
* If you want to provide specific properties for rendering engines you can use
* viewSpecificProperties.
*
* You can go and have a look in the rendering backend of your choice for details
* on specific properties.
* For example, for OpenGL/WebGL see OpenGL/PolyDataMapper/api.md
* If there is no details, viewSpecificProperties is not supported.
* @param viewSpecificProperties
*/
setViewSpecificProperties(viewSpecificProperties: object): boolean;
}

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

/**
* Method used to create a new instance of vtkMapper2D
* @param {IMapper2DInitialValues} [initialValues] for pre-setting some of its content
*/
export function newInstance(
initialValues?: IMapper2DInitialValues
): vtkMapper2D;

/**
* vtkMapper2D is an abstract class to specify interface between data and
* graphics primitives. Subclasses of vtkMapper map data through a
* lookuptable and control the creation of rendering primitives that
* interface to the graphics library. The mapping can be controlled by
* supplying a lookup table and specifying a scalar range to map data
* through.
*
* There are several important control mechanisms affecting the behavior of
* this object. The ScalarVisibility flag controls whether scalar data (if
* any) controls the color of the associated actor(s) that refer to the
* mapper. The ScalarMode ivar is used to determine whether scalar point data
* or cell data is used to color the object. By default, point data scalars
* are used unless there are none, then cell scalars are used. Or you can
* explicitly control whether to use point or cell scalar data. Finally, the
* mapping of scalars through the lookup table varies depending on the
* setting of the ColorMode flag. See the documentation for the appropriate
* methods for an explanation.
*
* Another important feature of this class is whether to use immediate mode
* rendering (ImmediateModeRenderingOn) or display list rendering
* (ImmediateModeRenderingOff). If display lists are used, a data structure
* is constructed (generally in the rendering library) which can then be
* rapidly traversed and rendered by the rendering library. The disadvantage
* of display lists is that they require additional memory which may affect
* the performance of the system.
*
* Another important feature of the mapper is the ability to shift the
* Z-buffer to resolve coincident topology. For example, if you’d like to
* draw a mesh with some edges a different color, and the edges lie on the
* mesh, this feature can be useful to get nice looking lines. (See the
* ResolveCoincidentTopology-related methods.)
*/
export declare const vtkMapper2D: {
newInstance: typeof newInstance;
extend: typeof extend;
};
export default vtkMapper2D;
index.js
import macro from 'vtk.js/Sources/macros';
import vtkAbstractMapper from 'vtk.js/Sources/Rendering/Core/AbstractMapper';
import vtkLookupTable from 'vtk.js/Sources/Common/Core/LookupTable';

import Constants from 'vtk.js/Sources/Rendering/Core/Mapper/Constants';

const { ColorMode, ScalarMode, GetArray } = Constants;

// ---------------------------------------------------------------------------
// vtkMapper2D methods
// ---------------------------------------------------------------------------

function vtkMapper2D(publicAPI, model) {
// Set out className
model.classHierarchy.push('vtkMapper2D');

publicAPI.createDefaultLookupTable = () => {
model.lookupTable = vtkLookupTable.newInstance();
};

publicAPI.getColorModeAsString = () =>
macro.enumToString(ColorMode, model.colorMode);

publicAPI.setColorModeToDefault = () => publicAPI.setColorMode(0);
publicAPI.setColorModeToMapScalars = () => publicAPI.setColorMode(1);
publicAPI.setColorModeToDirectScalars = () => publicAPI.setColorMode(2);

publicAPI.getScalarModeAsString = () =>
macro.enumToString(ScalarMode, model.scalarMode);

publicAPI.setScalarModeToDefault = () => publicAPI.setScalarMode(0);
publicAPI.setScalarModeToUsePointData = () => publicAPI.setScalarMode(1);
publicAPI.setScalarModeToUseCellData = () => publicAPI.setScalarMode(2);
publicAPI.setScalarModeToUsePointFieldData = () => publicAPI.setScalarMode(3);
publicAPI.setScalarModeToUseCellFieldData = () => publicAPI.setScalarMode(4);
publicAPI.setScalarModeToUseFieldData = () => publicAPI.setScalarMode(5);

publicAPI.getAbstractScalars = (
input,
scalarMode,
arrayAccessMode,
arrayId,
arrayName
) => {
// make sure we have an input
if (!input || !model.scalarVisibility) {
return { scalars: null, cellFLag: false };
}

let scalars = null;
let cellFlag = false;

// get scalar data and point/cell attribute according to scalar mode
if (scalarMode === ScalarMode.DEFAULT) {
scalars = input.getPointData().getScalars();
if (!scalars) {
scalars = input.getCellData().getScalars();
cellFlag = true;
}
} else if (scalarMode === ScalarMode.USE_POINT_DATA) {
scalars = input.getPointData().getScalars();
} else if (scalarMode === ScalarMode.USE_CELL_DATA) {
scalars = input.getCellData().getScalars();
cellFlag = true;
} else if (scalarMode === ScalarMode.USE_POINT_FIELD_DATA) {
const pd = input.getPointData();
if (arrayAccessMode === GetArray.BY_ID) {
scalars = pd.getArrayByIndex(arrayId);
} else {
scalars = pd.getArrayByName(arrayName);
}
} else if (scalarMode === ScalarMode.USE_CELL_FIELD_DATA) {
const cd = input.getCellData();
cellFlag = true;
if (arrayAccessMode === GetArray.BY_ID) {
scalars = cd.getArrayByIndex(arrayId);
} else {
scalars = cd.getArrayByName(arrayName);
}
} else if (scalarMode === ScalarMode.USE_FIELD_DATA) {
const fd = input.getFieldData();
if (arrayAccessMode === GetArray.BY_ID) {
scalars = fd.getArrayByIndex(arrayId);
} else {
scalars = fd.getArrayByName(arrayName);
}
}

return { scalars, cellFlag };
};

publicAPI.getLookupTable = () => {
if (!model.lookupTable) {
publicAPI.createDefaultLookupTable();
}
return model.lookupTable;
};

publicAPI.getMTime = () => {
let mt = model.mtime;
if (model.lookupTable !== null) {
const time = model.lookupTable.getMTime();
mt = time > mt ? time : mt;
}
return mt;
};

publicAPI.mapScalars = (input, alpha) => {
const scalars = publicAPI.getAbstractScalars(
input,
model.scalarMode,
model.arrayAccessMode,
model.arrayId,
model.colorByArrayName
).scalars;

if (!scalars) {
model.colorMapColors = null;
return;
}

// we want to only recompute when something has changed
const toString = `${publicAPI.getMTime()}${scalars.getMTime()}${alpha}`;
if (model.colorBuildString === toString) return;

if (!model.useLookupTableScalarRange) {
publicAPI
.getLookupTable()
.setRange(model.scalarRange[0], model.scalarRange[1]);
}

const lut = publicAPI.getLookupTable();
if (lut) {
// Ensure that the lookup table is built
lut.build();
model.colorMapColors = lut.mapScalars(
scalars,
model.colorMode,
model.fieldDataTupleId
);
}
model.colorBuildString = `${publicAPI.getMTime()}${scalars.getMTime()}${alpha}`;
};

publicAPI.getPrimitiveCount = () => {
const input = publicAPI.getInputData();
const pcount = {
points: input.getPoints().getNumberOfValues() / 3,
verts:
input.getVerts().getNumberOfValues() -
input.getVerts().getNumberOfCells(),
lines:
input.getLines().getNumberOfValues() -
2 * input.getLines().getNumberOfCells(),
triangles:
input.getPolys().getNumberOfValues() -
3 * input.getPolys().getNumberOfCells(),
};
return pcount;
};
}

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

const DEFAULT_VALUES = {
static: false,
lookupTable: null,

scalarVisibility: false,
scalarRange: [0, 1],
useLookupTableScalarRange: false,

colorMode: 0,
scalarMode: 0,
arrayAccessMode: 1, // By_NAME

renderTime: 0,

colorByArrayName: null,

transformCoordinate: null,

viewSpecificProperties: null,
customShaderAttributes: [],
};

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

// Inheritance
vtkAbstractMapper.extend(publicAPI, model, initialValues);

macro.get(publicAPI, model, ['colorMapColors']);
macro.setGet(publicAPI, model, [
'arrayAccessMode',
'colorByArrayName',
'colorMode',
'lookupTable',
'renderTime',
'scalarMode',
'scalarVisibility',
'static',
'transformCoordinate',
'useLookupTableScalarRange',
'viewSpecificProperties',
'customShaderAttributes', // point data array names that will be transferred to the VBO
]);
macro.setGetArray(publicAPI, model, ['scalarRange'], 2);

if (!model.viewSpecificProperties) {
model.viewSpecificProperties = {};
}

// Object methods
vtkMapper2D(publicAPI, model);
}

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

export const newInstance = macro.newInstance(extend, 'vtkMapper2D');

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

export default {
newInstance,
extend,
};