Light

Introduction

vtkLight is a virtual light for 3D rendering. It provides methods to locate
and point the light, turn it on and off, and set its brightness and color.
In addition to the basic infinite distance point light source attributes,
you also can specify the light attenuation values and cone angle.
These attributes are only used if the light is a positional light.
The default is a directional light (e.g. infinite point light source).

Lights have a type that describes how the light should move with respect
to the camera. A Headlight is always located at the current camera position
and shines on the camera’s focal point. A CameraLight also moves with
the camera, but may not be coincident to it. CameraLights are defined
in a normalized coordinate space where the camera is located at (0, 0, 1),
the camera is looking at (0, 0, 0), and up is (0, 1, 0). Finally, a
SceneLight is part of the scene itself and does not move with the camera.
(Renderers are responsible for moving the light based on its type.)

Lights have a transformation matrix that describes the space in which
they are positioned. A light’s world space position and focal point
are defined by their local position and focal point, transformed by
their transformation matrix (if it exists).

Methods

extend

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

getAttenuationValues

getAttenuationValuesByReference

getColor

Get the color of the light.

getColorByReference

Get the color of the light.

getConeAngle

Get the lighting cone angle of a positional light in degrees.
This is the angle between the axis of the cone and a ray along the edge
of the cone. A value of 90 (or more) indicates that you want no spot
lighting effects just a positional light.

getConeFalloff

Get the lighting falloff angle of a positional light in degrees.
This is the angle that sets how much the cone will be extended to
smooth the border. A value of 0 indicates that the spot light will
have a completely sharp edge (this does not mean completely sharp
lighting, just that the border will be sharp).

getDirection

Set the position and focal point of a light based on elevation and azimuth.
The light is moved so it is shining from the given angle. Angles are
given in degrees. If the light is a positional light, it is made
directional instead.

getExponent

Get the exponent of the cosine used in positional lighting.

getFocalPoint

Get the focal point.

getFocalPointByReference

Get the focal point.

getIntensity

Get the brightness of the light

getLightType

Get the type of the light.

getPosition

Get the position of the light.

getPositionByReference

Get the position of the light.

getPositional

Get if positional lighting is on or off.

getTransformedFocalPoint

Get the focal point of the light, modified by the transformation matrix
(if it exists).

getTransformedPosition

Get the position of the light, modified by the transformation matrix (if
it exists).

lightTypeIsCameraLight

Check if the type of the light is CameraLight.

lightTypeIsHeadLight

Check if the type of the light is HeadLight.

lightTypeIsSceneLight

Check if the type of the light is SceneLight.

newInstance

Method use to create a new instance of vtkLight with the focal point at the origin and its position
set to [0, 0, 1]. The light is a SceneLight, its color is white, intensity=1, the light is turned on,
positional lighting is off, coneAngle=30, coneFalloff=5, AttenuationValues=[1, 0, 0], exponent=1 and the transformMatrix is null.

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

setAttenuationValues

Set the quadratic attenuation constants.

Argument	Type	Required	Description
a	Number	Yes
b	Number	Yes
c	Number	Yes

setAttenuationValuesFrom

Set the quadratic attenuation constants from an array.

Argument	Type	Required	Description
attenuationValues	Array.	Yes	The quadratic attenuation.

setColor

Set the color of the object. Has the side effect of setting the
ambient diffuse and specular colors as well. This is basically
a quick overall color setting method.

Argument	Type	Required	Description
color	RGBColor	Yes	Defines the RGB color array..

setColor

Set the color of the object. Has the side effect of setting the
ambient diffuse and specular colors as well. This is basically
a quick overall color setting method.

Argument	Type	Required	Description
r	Number	Yes	Defines the red component (between 0 and 1).
g	Number	Yes	Defines the green component (between 0 and 1).
b	Number	Yes	Defines the blue component (between 0 and 1).

setColorFrom

Set the color of the object. Has the side effect of setting the
ambient diffuse and specular colors as well. This is basically
a quick overall color setting method.

Argument	Type	Required	Description
color	RGBColor	Yes	Defines the RGB color array..

setColorFrom

Set the color of the object. Has the side effect of setting the
ambient diffuse and specular colors as well. This is basically
a quick overall color setting method.

Argument	Type	Required	Description
r	Number	Yes	Defines the red component (between 0 and 1).
g	Number	Yes	Defines the green component (between 0 and 1).
b	Number	Yes	Defines the blue component (between 0 and 1).

setConeAngle

Set the lighting cone angle of a positional light in degrees.
This is the angle between the axis of the cone and a ray along the edge
of the cone.
A value of 90 (or more) indicates that you want no spot lighting effects
just a positional light.

Argument	Type	Required	Description
coneAngle	Number	Yes	The cone angle.

setConeFalloff

Set the lighting falloff angle of a positional light in degrees.
This is the angle that sets how much the cone will be extended to
smooth the border. A value of 0 indicates that the spot light will
have a completely sharp edge (this does not mean completely sharp
lighting, just that the border will be sharp).

Argument	Type	Required	Description
coneFalloff	Number	Yes	The cone falloff angle.

setDirection

Set the direction vector of the light from X, Y, and Z values

Argument	Type	Required	Description
direction	Vector3	Yes

setDirection

Set the direction vector of the light from X, Y, and Z values

Argument	Type	Required	Description
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.
z	Number	Yes	The z coordinate.

setDirectionAngle

Set the position and focal point of a light based on elevation and
azimuth. The light is moved so it is shining from the given angle. Angles
are given in degrees. If the light is a positional light, it is made
directional instead.

Argument	Type	Required	Description
elevation	Number	Yes
azimuth	Number	Yes

setExponent

Set the exponent of the cosine used in positional lighting.

Argument	Type	Required	Description
exponent	Number	Yes	The exponent of the cosine.

setFocalPoint

Set the focal point.

Argument	Type	Required	Description
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.
z	Number	Yes	The z coordinate.

setFocalPointFrom

Set the focal point from an array

Argument	Type	Required	Description
focalPoint	Vector3	Yes	The focal point array.

setIntensity

Set the brightness of the light (from one to zero).

Argument	Type	Required	Description
intensity	Number	Yes

setLightType

Set the type of the light to lightType

Argument	Type	Required	Description
lightType	LIGHT_TYPES	Yes	The light type.

setLightTypeToCameraLight

Set the type of the light is CameraLight.

setLightTypeToHeadLight

Set the the type of the light is HeadLight.

setLightTypeToSceneLight

Set the the type of the light is SceneLight.

setPosition

Set the position of the light.

Argument	Type	Required	Description
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.
z	Number	Yes	The z coordinate.

setPositionFrom

Set the position of the light.

Argument	Type	Required	Description
position	Vector3	Yes	The position coordinate of the light.

setPositional

Turn positional lighting on or off.

Argument	Type	Required	Description
positional	Boolean	Yes	The positional value.

setShadowAttenuation

Set the shadow intensity By default a light will be completely blocked
when in shadow by setting this value to less than 1.0 you can control how
much light is attenuated when in shadow.

Argument	Type	Required	Description
shadowAttenuation	Number	Yes	The shadow attenuation value.

setSwitch

Turn the light on or off.

Argument	Type	Required	Description
switchValue	Boolean	Yes	The switch value.

setTransformMatrix

Set the light’s transformation matrix.

Argument	Type	Required	Description
transformMatrix	mat4	Yes	The transform matrix.

Source

index.d.ts

import { mat4 } from 'gl-matrix';
import { vtkObject } from '../../../interfaces';
import { RGBColor, Vector3 } from '../../../types';

export enum LIGHT_TYPES {
  'HeadLight',
  'CameraLight',
  'SceneLight',
}

export interface ILightInitialValues {
  switch?: boolean;
  intensity?: number;
  color?: RGBColor;
  position?: Vector3;
  focalPoint?: Vector3;
  positional?: boolean;
  exponent?: number;
  coneAngle?: number;
  coneFalloff?: number;
  attenuationValues?: number[];
  lightType?: LIGHT_TYPES;
  shadowAttenuation?: number;
  direction?: Vector3;
  directionMTime?: number;
}

export interface vtkLight extends vtkObject {
  /**
   *
   */
  getAttenuationValues(): number[];

  /**
   *
   */
  getAttenuationValuesByReference(): number[];

  /**
   * Get the color of the light.
   */
  getColor(): RGBColor;

  /**
   * Get the color of the light.
   */
  getColorByReference(): RGBColor;

  /**
   * Get the lighting cone angle of a positional light in degrees.
   * This is the angle between the axis of the cone and a ray along the edge
   * of the cone. A value of 90 (or more) indicates that you want no spot
   * lighting effects just a positional light.
   */
  getConeAngle(): number;

  /**
   * Get the lighting falloff angle of a positional light in degrees.
   * This is the angle that sets how much the cone will be extended to
   * smooth the border. A value of 0 indicates that the spot light will
   * have a completely sharp edge (this does not mean completely sharp
   * lighting, just that the border will be sharp).
   */
  getConeFalloff(): number;

  /**
   * Set the position and focal point of a light based on elevation and azimuth.
   * The light is moved so it is shining from the given angle. Angles are
   * given in degrees. If the light is a positional light, it is made
   * directional instead.
   */
  getDirection(): Vector3;

  /**
   * Get the exponent of the cosine used in positional lighting.
   */
  getExponent(): number;

  /**
   * Get the focal point.
   */
  getFocalPoint(): Vector3;

  /**
   * Get the focal point.
   */
  getFocalPointByReference(): Vector3;

  /**
   * Get the brightness of the light
   */
  getIntensity(): number;

  /**
   * Get the type of the light.
   */
  getLightType(): string;

  /**
   * Get the position of the light.
   */
  getPosition(): Vector3;

  /**
   * Get the position of the light.
   */
  getPositionByReference(): Vector3;

  /**
   * Get if positional lighting is on or off.
   */
  getPositional(): boolean;

  /**
   * Get the position of the light, modified by the transformation matrix (if
   * it exists).
   */
  getTransformedPosition(): Vector3;

  /**
   * Get the focal point of the light, modified by the transformation matrix
   * (if it exists).
   */
  getTransformedFocalPoint(): Vector3;

  /**
   * Set the quadratic attenuation constants.
   * @param {Number} a
   * @param {Number} b
   * @param {Number} c
   */
  setAttenuationValues(a: number, b: number, c: number): boolean;

  /**
   * Set the quadratic attenuation constants from an array.
   * @param {Number[]} attenuationValues The quadratic attenuation.
   */
  setAttenuationValuesFrom(attenuationValues: number[]): boolean;

  /**
   * Set the color of the object. Has the side effect of setting the
   * ambient diffuse and specular colors as well. This is basically
   * a quick overall color setting method.
   * @param {Number} r Defines the red component (between 0 and 1).
   * @param {Number} g Defines the green component (between 0 and 1).
   * @param {Number} b Defines the blue component (between 0 and 1).
   */
  setColor(r: number, g: number, b: number): boolean;

  /**
   * Set the color of the object. Has the side effect of setting the
   * ambient diffuse and specular colors as well. This is basically
   * a quick overall color setting method.
   * @param {RGBColor} color Defines the RGB color array..
   */
  setColor(color: RGBColor): boolean;

  /**
   * Set the color of the object. Has the side effect of setting the
   * ambient diffuse and specular colors as well. This is basically
   * a quick overall color setting method.
   * @param {Number} r Defines the red component (between 0 and 1).
   * @param {Number} g Defines the green component (between 0 and 1).
   * @param {Number} b Defines the blue component (between 0 and 1).
   */
  setColorFrom(r: number, g: number, b: number): boolean;

  /**
   * Set the color of the object. Has the side effect of setting the
   * ambient diffuse and specular colors as well. This is basically
   * a quick overall color setting method.
   * @param {RGBColor} color Defines the RGB color array..
   */
  setColorFrom(color: RGBColor): boolean;

  /**
   * Set the lighting cone angle of a positional light in degrees.
   * This is the angle between the axis of the cone and a ray along the edge
   * of the cone.
   * A value of 90 (or more) indicates that you want no spot lighting effects
   * just a positional light.
   * @param {Number} coneAngle The cone angle.
   */
  setConeAngle(coneAngle: number): boolean;

  /**
   * Set the lighting falloff angle of a positional light in degrees.
   * This is the angle that sets how much the cone will be extended to
   * smooth the border. A value of 0 indicates that the spot light will
   * have a completely sharp edge (this does not mean completely sharp
   * lighting, just that the border will be sharp).
   * @param {Number} coneFalloff The cone falloff angle.
   */
  setConeFalloff(coneFalloff: number): boolean;

  /**
   * Set the position and focal point of a light based on elevation and
   * azimuth. The light is moved so it is shining from the given angle. Angles
   * are given in degrees. If the light is a positional light, it is made
   * directional instead.
   * @param {Number} elevation
   * @param {Number} azimuth
   */
  setDirectionAngle(elevation: number, azimuth: number): boolean;

  /**
   * Set the direction vector of the light from X, Y, and Z values
   * @param {Number} x The x coordinate.
   * @param {Number} y The y coordinate.
   * @param {Number} z The z coordinate.
   */
  setDirection(x: number, y: number, z: number): boolean;

  /**
   * Set the direction vector of the light from X, Y, and Z values
   * @param {Vector3} direction
   */
  setDirection(direction: Vector3): boolean;

  /**
   * Set the exponent of the cosine used in positional lighting.
   * @param {Number} exponent The exponent of the cosine.
   */
  setExponent(exponent: number): boolean;

  /**
   * Set the focal point.
   * @param {Number} x The x coordinate.
   * @param {Number} y The y coordinate.
   * @param {Number} z The z coordinate.
   */
  setFocalPoint(x: number, y: number, z: number): boolean;

  /**
   * Set the focal point from an array
   * @param {Vector3} focalPoint The focal point array.
   */
  setFocalPointFrom(focalPoint: Vector3): boolean;

  /**
   * Set the brightness of the light (from one to zero).
   * @param {Number} intensity
   */
  setIntensity(intensity: number): boolean;

  /**
   * Set the type of the light to lightType
   * @param {LIGHT_TYPES} lightType The light type.
   */
  setLightType(lightType: LIGHT_TYPES): boolean;

  /**
   * Set the type of the light is CameraLight.
   */
  setLightTypeToCameraLight(): boolean;

  /**
   * Set the the type of the light is HeadLight.
   */
  setLightTypeToHeadLight(): boolean;

  /**
   * Set the the type of the light is SceneLight.
   */
  setLightTypeToSceneLight(): boolean;

  /**
   * Check if the type of the light is CameraLight.
   */
  lightTypeIsCameraLight(): boolean;

  /**
   * Check if the type of the light is HeadLight.
   */
  lightTypeIsHeadLight(): boolean;

  /**
   * Check if the type of the light is SceneLight.
   */
  lightTypeIsSceneLight(): boolean;

  /**
   * Set the position of the light.
   * @param {Number} x The x coordinate.
   * @param {Number} y The y coordinate.
   * @param {Number} z The z coordinate.
   */
  setPosition(x: number, y: number, z: number): boolean;

  /**
   * Set the position of the light.
   * @param {Vector3} position The position coordinate of the light.
   */
  setPositionFrom(position: Vector3): boolean;

  /**
   * Turn positional lighting on or off.
   * @param {Boolean} positional The positional value.
   */
  setPositional(positional: boolean): boolean;

  /**
   * Set the shadow intensity By default a light will be completely blocked
   * when in shadow by setting this value to less than 1.0 you can control how
   * much light is attenuated when in shadow.
   * @param {Number} shadowAttenuation The shadow attenuation value.
   */
  setShadowAttenuation(shadowAttenuation: number): boolean;

  /**
   * Turn the light on or off.
   * @param {Boolean} switchValue The switch value.
   */
  setSwitch(switchValue: boolean): boolean;

  /**
   * Set the light's transformation matrix.
   * @param {mat4} transformMatrix The transform matrix.
   */
  setTransformMatrix(transformMatrix: mat4): boolean;
}

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

/**
 * Method use to create a new instance of vtkLight with the focal point at the origin and its position
 * set to [0, 0, 1]. The light is a SceneLight, its color is white, intensity=1, the light is turned on,
 * positional lighting is off, coneAngle=30, coneFalloff=5, AttenuationValues=[1, 0, 0], exponent=1 and the transformMatrix is null.
 * @param {ILightInitialValues} [initialValues] for pre-setting some of its content
 */
export function newInstance(initialValues?: ILightInitialValues): vtkLight;

/**
 * vtkLight is a virtual light for 3D rendering. It provides methods to locate
 * and point the light, turn it on and off, and set its brightness and color.
 * In addition to the basic infinite distance point light source attributes,
 * you also can specify the light attenuation values and cone angle.
 * These attributes are only used if the light is a positional light.
 * The default is a directional light (e.g. infinite point light source).
 *
 * Lights have a type that describes how the light should move with respect
 * to the camera. A Headlight is always located at the current camera position
 * and shines on the camera’s focal point. A CameraLight also moves with
 * the camera, but may not be coincident to it. CameraLights are defined
 * in a normalized coordinate space where the camera is located at (0, 0, 1),
 * the camera is looking at (0, 0, 0), and up is (0, 1, 0). Finally, a
 * SceneLight is part of the scene itself and does not move with the camera.
 * (Renderers are responsible for moving the light based on its type.)
 *
 * Lights have a transformation matrix that describes the space in which
 * they are positioned. A light’s world space position and focal point
 * are defined by their local position and focal point, transformed by
 * their transformation matrix (if it exists).
 */
export declare const vtkLight: {
  newInstance: typeof newInstance;
  extend: typeof extend;
  LIGHT_TYPES: LIGHT_TYPES;
};
export default vtkLight;

index.js

import macro from 'vtk.js/Sources/macros';
import * as vtkMath from 'vtk.js/Sources/Common/Core/Math';
import { vec3 } from 'gl-matrix';

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

export const LIGHT_TYPES = ['HeadLight', 'CameraLight', 'SceneLight'];

// ----------------------------------------------------------------------------
// vtkLight methods
// ----------------------------------------------------------------------------

function vtkLight(publicAPI, model) {
  // Set our className
  model.classHierarchy.push('vtkLight');
  const tmpVec = new Float64Array(3);

  publicAPI.getTransformedPosition = () => {
    if (model.transformMatrix) {
      vec3.transformMat4(tmpVec, model.position, model.transformMatrix);
    } else {
      vec3.set(tmpVec, model.position[0], model.position[1], model.position[2]);
    }
    return tmpVec;
  };

  publicAPI.getTransformedFocalPoint = () => {
    if (model.transformMatrix) {
      vec3.transformMat4(tmpVec, model.focalPoint, model.transformMatrix);
    } else {
      vec3.set(
        tmpVec,
        model.focalPoint[0],
        model.focalPoint[1],
        model.focalPoint[2]
      );
    }
    return tmpVec;
  };

  publicAPI.getDirection = () => {
    if (model.directionMTime < model.mtime) {
      vec3.sub(model.direction, model.focalPoint, model.position);
      vtkMath.normalize(model.direction);
      model.directionMTime = model.mtime;
    }
    return model.direction;
  };

  // Sets the direction from a vec3 instead of a focal point
  publicAPI.setDirection = (directionVector) => {
    const newFocalPoint = new Float64Array(3);
    vec3.sub(newFocalPoint, model.position, directionVector);
    model.focalPoint = newFocalPoint;
  };

  publicAPI.setDirectionAngle = (elevation, azimuth) => {
    const elevationRadians = vtkMath.radiansFromDegrees(elevation);
    const azimuthRadians = vtkMath.radiansFromDegrees(azimuth);

    publicAPI.setPosition(
      Math.cos(elevationRadians) * Math.sin(azimuthRadians),
      Math.sin(elevationRadians),
      Math.cos(elevationRadians) * Math.cos(azimuthRadians)
    );

    publicAPI.setFocalPoint(0, 0, 0);
    publicAPI.setPositional(0);
  };

  publicAPI.setLightTypeToHeadLight = () => {
    publicAPI.setLightType('HeadLight');
  };

  publicAPI.setLightTypeToCameraLight = () => {
    publicAPI.setLightType('CameraLight');
  };

  publicAPI.setLightTypeToSceneLight = () => {
    publicAPI.setTransformMatrix(null);
    publicAPI.setLightType('SceneLight');
  };

  publicAPI.lightTypeIsHeadLight = () => model.lightType === 'HeadLight';

  publicAPI.lightTypeIsSceneLight = () => model.lightType === 'SceneLight';

  publicAPI.lightTypeIsCameraLight = () => model.lightType === 'CameraLight';
}

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

const DEFAULT_VALUES = {
  switch: true,
  intensity: 1,
  color: [1, 1, 1],
  position: [0, 0, 1],
  focalPoint: [0, 0, 0],
  positional: false,
  exponent: 1,
  coneAngle: 30,
  coneFalloff: 5,
  attenuationValues: [1, 0, 0],
  transformMatrix: null,
  lightType: 'SceneLight',
  shadowAttenuation: 1,
  direction: [0, 0, 0],
  directionMTime: 0,
};

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

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

  // Build VTK API
  macro.obj(publicAPI, model);
  macro.setGet(publicAPI, model, [
    'intensity',
    'switch',
    'positional',
    'exponent',
    'coneAngle',
    'coneFalloff',
    'transformMatrix',
    'lightType',
    'shadowAttenuation',
    'attenuationValues',
  ]);
  macro.setGetArray(
    publicAPI,
    model,
    ['color', 'position', 'focalPoint', 'attenuationValues'],
    3
  );

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

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

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

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

export default { newInstance, extend, LIGHT_TYPES };