a simple but quality lighting kit More...

#include <vtkLightKit.h>

Inheritance diagram for vtkLightKit:

Collaboration diagram for vtkLightKit:

Public Types
enum	LightKitType { TKeyLight, TFillLight, TBackLight, THeadLight }

enum	LightKitSubType { Warmth, Intensity, Elevation, Azimuth, KFRatio, KBRatio, KHRatio }

typedef vtkObject	Superclass

Public Member Functions
virtual vtkTypeBool	IsA (const char *type)
	Return 1 if this class is the same type of (or a subclass of) the named class. More...

vtkLightKit *	NewInstance () const

void	PrintSelf (ostream &os, vtkIndent indent) override
	Methods invoked by print to print information about the object including superclasses. More...

virtual void	SetFillLightWarmth (double)

virtual double	GetFillLightWarmth ()

virtual void	SetHeadLightWarmth (double)

virtual double	GetHeadLightWarmth ()

virtual void	SetBackLightWarmth (double)

virtual double	GetBackLightWarmth ()

void	SetKeyLightAngle (double elevation, double azimuth)
	Get/Set the position of the key, fill, and back lights using angular methods. More...

void	SetKeyLightAngle (double angle[2])

void	SetKeyLightElevation (double x)

void	SetKeyLightAzimuth (double x)

virtual double *	GetKeyLightAngle ()

virtual void	GetKeyLightAngle (double data[2])

double	GetKeyLightElevation ()

double	GetKeyLightAzimuth ()

void	SetFillLightAngle (double elevation, double azimuth)

void	SetFillLightAngle (double angle[2])

void	SetFillLightElevation (double x)

void	SetFillLightAzimuth (double x)

virtual double *	GetFillLightAngle ()

virtual void	GetFillLightAngle (double data[2])

double	GetFillLightElevation ()

double	GetFillLightAzimuth ()

void	SetBackLightAngle (double elevation, double azimuth)

void	SetBackLightAngle (double angle[2])

void	SetBackLightElevation (double x)

void	SetBackLightAzimuth (double x)

virtual double *	GetBackLightAngle ()

virtual void	GetBackLightAngle (double data[2])

double	GetBackLightElevation ()

double	GetBackLightAzimuth ()

void	DeepCopy (vtkLightKit *kit)

void	Modified () override
	Update the modification time for this object. More...

void	Update ()


virtual void	SetKeyLightIntensity (double)
	Set/Get the intensity of the key light. More...

virtual double	GetKeyLightIntensity ()
	Set/Get the intensity of the key light. More...


virtual void	SetKeyToFillRatio (double)
	Set/Get the key-to-fill ratio. More...

virtual double	GetKeyToFillRatio ()
	Set/Get the key-to-fill ratio. More...


virtual void	SetKeyToHeadRatio (double)
	Set/Get the key-to-headlight ratio. More...

virtual double	GetKeyToHeadRatio ()
	Set/Get the key-to-headlight ratio. More...


virtual void	SetKeyToBackRatio (double)
	Set/Get the key-to-back light ratio. More...

virtual double	GetKeyToBackRatio ()
	Set/Get the key-to-back light ratio. More...


virtual void	SetKeyLightWarmth (double)
	Set the warmth of each the lights. More...

virtual double	GetKeyLightWarmth ()
	Set the warmth of each the lights. More...


virtual double *	GetKeyLightColor ()
	Returns the floating-point RGB values of each of the light's color. More...

virtual void	GetKeyLightColor (double data[3])
	Returns the floating-point RGB values of each of the light's color. More...

virtual double *	GetFillLightColor ()
	Returns the floating-point RGB values of each of the light's color. More...

virtual void	GetFillLightColor (double data[3])
	Returns the floating-point RGB values of each of the light's color. More...

virtual double *	GetHeadLightColor ()
	Returns the floating-point RGB values of each of the light's color. More...

virtual void	GetHeadLightColor (double data[3])
	Returns the floating-point RGB values of each of the light's color. More...

virtual double *	GetBackLightColor ()
	Returns the floating-point RGB values of each of the light's color. More...

virtual void	GetBackLightColor (double data[3])
	Returns the floating-point RGB values of each of the light's color. More...


virtual void	MaintainLuminanceOn ()
	If MaintainLuminance is set, the LightKit will attempt to maintain the apparent intensity of lights based on their perceptual brightnesses. More...

virtual void	MaintainLuminanceOff ()
	If MaintainLuminance is set, the LightKit will attempt to maintain the apparent intensity of lights based on their perceptual brightnesses. More...

virtual vtkTypeBool	GetMaintainLuminance ()
	If MaintainLuminance is set, the LightKit will attempt to maintain the apparent intensity of lights based on their perceptual brightnesses. More...

virtual void	SetMaintainLuminance (vtkTypeBool)
	If MaintainLuminance is set, the LightKit will attempt to maintain the apparent intensity of lights based on their perceptual brightnesses. More...


void	AddLightsToRenderer (vtkRenderer *renderer)
	Add lights to, or remove lights from, a renderer. More...

void	RemoveLightsFromRenderer (vtkRenderer *renderer)
	Add lights to, or remove lights from, a renderer. More...

Public Member Functions inherited from vtkObject
	vtkBaseTypeMacro (vtkObject, vtkObjectBase)

virtual void	DebugOn ()
	Turn debugging output on. More...

virtual void	DebugOff ()
	Turn debugging output off. More...

bool	GetDebug ()
	Get the value of the debug flag. More...

void	SetDebug (bool debugFlag)
	Set the value of the debug flag. More...

virtual vtkMTimeType	GetMTime ()
	Return this object's modified time. More...

void	RemoveObserver (unsigned long tag)

void	RemoveObservers (unsigned long event)

void	RemoveObservers (const char *event)

void	RemoveAllObservers ()

vtkTypeBool	HasObserver (unsigned long event)

vtkTypeBool	HasObserver (const char *event)

int	InvokeEvent (unsigned long event)

int	InvokeEvent (const char *event)

unsigned long	AddObserver (unsigned long event, vtkCommand *, float priority=0.0f)
	Allow people to add/remove/invoke observers (callbacks) to any VTK object. More...

unsigned long	AddObserver (const char event, vtkCommand , float priority=0.0f)
	Allow people to add/remove/invoke observers (callbacks) to any VTK object. More...

vtkCommand *	GetCommand (unsigned long tag)
	Allow people to add/remove/invoke observers (callbacks) to any VTK object. More...

void	RemoveObserver (vtkCommand *)
	Allow people to add/remove/invoke observers (callbacks) to any VTK object. More...

void	RemoveObservers (unsigned long event, vtkCommand *)
	Allow people to add/remove/invoke observers (callbacks) to any VTK object. More...

void	RemoveObservers (const char event, vtkCommand )
	Allow people to add/remove/invoke observers (callbacks) to any VTK object. More...

vtkTypeBool	HasObserver (unsigned long event, vtkCommand *)
	Allow people to add/remove/invoke observers (callbacks) to any VTK object. More...

vtkTypeBool	HasObserver (const char event, vtkCommand )
	Allow people to add/remove/invoke observers (callbacks) to any VTK object. More...

template<class U , class T >
unsigned long	AddObserver (unsigned long event, U observer, void(T::*callback)(), float priority=0.0f)
	Overloads to AddObserver that allow developers to add class member functions as callbacks for events. More...

template<class U , class T >
unsigned long	AddObserver (unsigned long event, U observer, void(T::callback)(vtkObject , unsigned long, void *), float priority=0.0f)
	Overloads to AddObserver that allow developers to add class member functions as callbacks for events. More...

template<class U , class T >
unsigned long	AddObserver (unsigned long event, U observer, bool(T::callback)(vtkObject , unsigned long, void *), float priority=0.0f)
	Allow user to set the AbortFlagOn() with the return value of the callback method. More...

int	InvokeEvent (unsigned long event, void *callData)
	This method invokes an event and return whether the event was aborted or not. More...

int	InvokeEvent (const char event, void callData)
	This method invokes an event and return whether the event was aborted or not. More...

Public Member Functions inherited from vtkObjectBase
const char *	GetClassName () const
	Return the class name as a string. More...

virtual void	Delete ()
	Delete a VTK object. More...

virtual void	FastDelete ()
	Delete a reference to this object. More...

void	InitializeObjectBase ()

void	Print (ostream &os)
	Print an object to an ostream. More...

virtual void	Register (vtkObjectBase *o)
	Increase the reference count (mark as used by another object). More...

virtual void	UnRegister (vtkObjectBase *o)
	Decrease the reference count (release by another object). More...

int	GetReferenceCount ()
	Return the current reference count of this object. More...

void	SetReferenceCount (int)
	Sets the reference count. More...

void	PrintRevisions (ostream &)
	Legacy. More...

virtual void	PrintHeader (ostream &os, vtkIndent indent)
	Methods invoked by print to print information about the object including superclasses. More...

virtual void	PrintTrailer (ostream &os, vtkIndent indent)
	Methods invoked by print to print information about the object including superclasses. More...

Static Public Member Functions
static vtkLightKit *	New ()

static vtkTypeBool	IsTypeOf (const char *type)

static vtkLightKit *	SafeDownCast (vtkObjectBase *o)

static const char *	GetStringFromType (int type)
	Helper method to go from a enum type to a string type. More...

static const char *	GetStringFromSubType (int type)
	Helper method to go from a enum subtype to a string subtype. More...

static const char *	GetShortStringFromSubType (int subtype)
	Helper method to go from a enum subtype to a string subtype The difference from GetStringFromSubType is that it returns a shorter strings (useful for GUI with minimum space) More...

static LightKitSubType	GetSubType (LightKitType type, int i)
	Return the possible subtype from a given type. More...

Static Public Member Functions inherited from vtkObject
static vtkObject *	New ()
	Create an object with Debug turned off, modified time initialized to zero, and reference counting on. More...

static void	BreakOnError ()
	This method is called when vtkErrorMacro executes. More...

static void	SetGlobalWarningDisplay (int val)
	This is a global flag that controls whether any debug, warning or error messages are displayed. More...

static void	GlobalWarningDisplayOn ()
	This is a global flag that controls whether any debug, warning or error messages are displayed. More...

static void	GlobalWarningDisplayOff ()
	This is a global flag that controls whether any debug, warning or error messages are displayed. More...

static int	GetGlobalWarningDisplay ()
	This is a global flag that controls whether any debug, warning or error messages are displayed. More...

Static Public Member Functions inherited from vtkObjectBase
static vtkTypeBool	IsTypeOf (const char *name)
	Return 1 if this class type is the same type of (or a subclass of) the named class. More...

static vtkObjectBase *	New ()
	Create an object with Debug turned off, modified time initialized to zero, and reference counting on. More...

Protected Member Functions
virtual vtkObjectBase *	NewInstanceInternal () const

	vtkLightKit ()

	~vtkLightKit () override

void	WarmthToRGBI (double w, double rgb[3], double &i)

void	WarmthToRGB (double w, double rgb[3])

void	InitializeWarmthFunctions ()

double	WarmthToIntensity (double w)

Protected Member Functions inherited from vtkObject
	vtkObject ()

	~vtkObject () override

void	RegisterInternal (vtkObjectBase *, vtkTypeBool check) override

void	UnRegisterInternal (vtkObjectBase *, vtkTypeBool check) override

void	InternalGrabFocus (vtkCommand mouseEvents, vtkCommand keypressEvents=nullptr)
	These methods allow a command to exclusively grab all events. More...

void	InternalReleaseFocus ()
	These methods allow a command to exclusively grab all events. More...

Protected Member Functions inherited from vtkObjectBase
	vtkObjectBase ()

virtual	~vtkObjectBase ()

virtual void	CollectRevisions (ostream &)

virtual void	ReportReferences (vtkGarbageCollector *)

	vtkObjectBase (const vtkObjectBase &)

void	operator= (const vtkObjectBase &)

Protected Attributes
double	KeyLightIntensity

double	KeyToFillRatio

double	KeyToHeadRatio

double	KeyToBackRatio

vtkLight *	KeyLight

double	KeyLightWarmth

double	KeyLightAngle [2]

double	KeyLightColor [3]

vtkLight *	FillLight

double	FillLightWarmth

double	FillLightAngle [2]

double	FillLightColor [3]

double	BackLightWarmth

double	BackLightColor [3]

vtkLight *	BackLight0

vtkLight *	BackLight1

double	BackLightAngle [2]

vtkLight *	HeadLight

double	HeadLightWarmth

double	HeadLightColor [3]

vtkTypeBool	MaintainLuminance

vtkPiecewiseFunction *	WarmthFunction [4]

Protected Attributes inherited from vtkObject
bool	Debug

vtkTimeStamp	MTime

vtkSubjectHelper *	SubjectHelper

Protected Attributes inherited from vtkObjectBase
vtkAtomicInt32	ReferenceCount

vtkWeakPointerBase **	WeakPointers

Detailed Description

a simple but quality lighting kit

vtkLightKit is designed to make general purpose lighting of vtk scenes simple, flexible, and attractive (or at least not horribly ugly without significant effort). Use a LightKit when you want more control over your lighting than you can get with the default vtk light, which is a headlight located at the camera. (HeadLights are very simple to use, but they don't show the shape of objects very well, don't give a good sense of "up" and "down", and don't evenly light the object.)

A LightKit consists of three lights, a key light, a fill light, and a headlight. The main light is the key light. It is usually positioned so that it appears like an overhead light (like the sun, or a ceiling light). It is generally positioned to shine down on the scene from about a 45 degree angle vertically and at least a little offset side to side. The key light usually at least about twice as bright as the total of all other lights in the scene to provide good modeling of object features.

The other lights in the kit (the fill light, headlight, and a pair of back lights) are weaker sources that provide extra illumination to fill in the spots that the key light misses. The fill light is usually positioned across from or opposite from the key light (though still on the same side of the object as the camera) in order to simulate diffuse reflections from other objects in the scene. The headlight, always located at the position of the camera, reduces the contrast between areas lit by the key and fill light. The two back lights, one on the left of the object as seen from the observer and one on the right, fill on the high-contrast areas behind the object. To enforce the relationship between the different lights, the intensity of the fill, back and headlights are set as a ratio to the key light brightness. Thus, the brightness of all the lights in the scene can be changed by changing the key light intensity.

All lights are directional lights (infinitely far away with no falloff). Lights move with the camera.

For simplicity, the position of lights in the LightKit can only be specified using angles: the elevation (latitude) and azimuth (longitude) of each light with respect to the camera, expressed in degrees. (Lights always shine on the camera's lookat point.) For example, a light at (elevation=0, azimuth=0) is located at the camera (a headlight). A light at (elevation=90, azimuth=0) is above the lookat point, shining down. Negative azimuth values move the lights clockwise as seen above, positive values counter-clockwise. So, a light at (elevation=45, azimuth=-20) is above and in front of the object and shining slightly from the left side.

vtkLightKit limits the colors that can be assigned to any light to those of incandescent sources such as light bulbs and sunlight. It defines a special color spectrum called "warmth" from which light colors can be chosen, where 0 is cold blue, 0.5 is neutral white, and 1 is deep sunset red. Colors close to 0.5 are "cool whites" and "warm whites," respectively.

Since colors far from white on the warmth scale appear less bright, key-to-fill and key-to-headlight ratios are skewed by key, fill, and headlight colors. If the flag MaintainLuminance is set, vtkLightKit will attempt to compensate for these perceptual differences by increasing the brightness of more saturated colors.

A LightKit is not explicitly part of the vtk pipeline. Rather, it is a composite object that controls the behavior of lights using a unified user interface. Every time a parameter of vtkLightKit is adjusted, the properties of its lights are modified.

Credits:: vtkLightKit was originally written and contributed to vtk by Michael Halle (mhall.nosp@m.e@bw.nosp@m.h.har.nosp@m.vard.nosp@m..edu) at the Surgical Planning Lab, Brigham and Women's Hospital.

Tests:: vtkLightKit (Tests)

Definition at line 105 of file vtkLightKit.h.

Member Typedef Documentation

typedef vtkObject vtkLightKit::Superclass

Definition at line 109 of file vtkLightKit.h.

Member Enumeration Documentation

enum vtkLightKit::LightKitType

Enumerator
TKeyLight
TFillLight
TBackLight
THeadLight

Definition at line 112 of file vtkLightKit.h.

enum vtkLightKit::LightKitSubType

Enumerator
Warmth
Intensity
Elevation
Azimuth
KFRatio
KBRatio
KHRatio

Definition at line 119 of file vtkLightKit.h.

Constructor & Destructor Documentation

vtkLightKit::vtkLightKit ( )

protected

vtkLightKit::~vtkLightKit ( )

overrideprotected

Member Function Documentation

static vtkLightKit* vtkLightKit::New ( )

static

static vtkTypeBool vtkLightKit::IsTypeOf ( const char * type )

static

virtual vtkTypeBool vtkLightKit::IsA ( const char * name )

virtual

Return 1 if this class is the same type of (or a subclass of) the named class.

Returns 0 otherwise. This method works in combination with vtkTypeMacro found in vtkSetGet.h.

Reimplemented from vtkObjectBase.

static vtkLightKit* vtkLightKit::SafeDownCast ( vtkObjectBase * o )

static

virtual vtkObjectBase* vtkLightKit::NewInstanceInternal ( ) const

protectedvirtual

vtkLightKit* vtkLightKit::NewInstance ( ) const

void vtkLightKit::PrintSelf	(	ostream &	os,
		vtkIndent	indent
	)

overridevirtual

Methods invoked by print to print information about the object including superclasses.

Typically not called by the user (use Print() instead) but used in the hierarchical print process to combine the output of several classes.

Reimplemented from vtkObject.

virtual void vtkLightKit::SetKeyLightIntensity ( double )

virtual

Set/Get the intensity of the key light.

The key light is the brightest light in the scene. The intensities of the other two lights are ratios of the key light's intensity.

virtual double vtkLightKit::GetKeyLightIntensity ( )

virtual

Set/Get the intensity of the key light.

The key light is the brightest light in the scene. The intensities of the other two lights are ratios of the key light's intensity.

virtual void vtkLightKit::SetKeyToFillRatio ( double )

virtual

Set/Get the key-to-fill ratio.

This ratio controls how bright the fill light is compared to the key light: larger values correspond to a dimmer fill light. The purpose of the fill light is to light parts of the object not lit by the key light, while still maintaining contrast. This type of lighting may correspond to indirect illumination from the key light, bounced off a wall, floor, or other object. The fill light should never be brighter than the key light: a good range for the key-to-fill ratio is between 2 and 10.

virtual double vtkLightKit::GetKeyToFillRatio ( )

virtual

Set/Get the key-to-fill ratio.

This ratio controls how bright the fill light is compared to the key light: larger values correspond to a dimmer fill light. The purpose of the fill light is to light parts of the object not lit by the key light, while still maintaining contrast. This type of lighting may correspond to indirect illumination from the key light, bounced off a wall, floor, or other object. The fill light should never be brighter than the key light: a good range for the key-to-fill ratio is between 2 and 10.

virtual void vtkLightKit::SetKeyToHeadRatio ( double )

virtual

Set/Get the key-to-headlight ratio.

Similar to the key-to-fill ratio, this ratio controls how bright the headlight light is compared to the key light: larger values correspond to a dimmer headlight light. The headlight is special kind of fill light, lighting only the parts of the object that the camera can see. As such, a headlight tends to reduce the contrast of a scene. It can be used to fill in "shadows" of the object missed by the key and fill lights. The headlight should always be significantly dimmer than the key light: ratios of 2 to 15 are typical.

virtual double vtkLightKit::GetKeyToHeadRatio ( )

virtual

Set/Get the key-to-headlight ratio.

Similar to the key-to-fill ratio, this ratio controls how bright the headlight light is compared to the key light: larger values correspond to a dimmer headlight light. The headlight is special kind of fill light, lighting only the parts of the object that the camera can see. As such, a headlight tends to reduce the contrast of a scene. It can be used to fill in "shadows" of the object missed by the key and fill lights. The headlight should always be significantly dimmer than the key light: ratios of 2 to 15 are typical.

virtual void vtkLightKit::SetKeyToBackRatio ( double )

virtual

Set/Get the key-to-back light ratio.

This ratio controls how bright the back lights are compared to the key light: larger values correspond to dimmer back lights. The back lights fill in the remaining high-contrast regions behind the object. Values between 2 and 10 are good.

virtual double vtkLightKit::GetKeyToBackRatio ( )

virtual

Set/Get the key-to-back light ratio.

This ratio controls how bright the back lights are compared to the key light: larger values correspond to dimmer back lights. The back lights fill in the remaining high-contrast regions behind the object. Values between 2 and 10 are good.

virtual void vtkLightKit::SetKeyLightWarmth ( double )

virtual

Set the warmth of each the lights.

Warmth is a parameter that varies from 0 to 1, where 0 is "cold" (looks icy or lit by a very blue sky), 1 is "warm" (the red of a very red sunset, or the embers of a campfire), and 0.5 is a neutral white. The warmth scale is non-linear. Warmth values close to 0.5 are subtly "warmer" or "cooler," much like a warmer tungsten incandescent bulb, a cooler halogen, or daylight (cooler still). Moving further away from 0.5, colors become more quickly varying towards blues and reds. With regards to aesthetics, extremes of warmth should be used sparingly.

virtual double vtkLightKit::GetKeyLightWarmth ( )

virtual

Set the warmth of each the lights.

Warmth is a parameter that varies from 0 to 1, where 0 is "cold" (looks icy or lit by a very blue sky), 1 is "warm" (the red of a very red sunset, or the embers of a campfire), and 0.5 is a neutral white. The warmth scale is non-linear. Warmth values close to 0.5 are subtly "warmer" or "cooler," much like a warmer tungsten incandescent bulb, a cooler halogen, or daylight (cooler still). Moving further away from 0.5, colors become more quickly varying towards blues and reds. With regards to aesthetics, extremes of warmth should be used sparingly.

virtual void vtkLightKit::SetFillLightWarmth ( double )

virtual

virtual double vtkLightKit::GetFillLightWarmth ( )

virtual

virtual void vtkLightKit::SetHeadLightWarmth ( double )

virtual

virtual double vtkLightKit::GetHeadLightWarmth ( )

virtual

virtual void vtkLightKit::SetBackLightWarmth ( double )

virtual

virtual double vtkLightKit::GetBackLightWarmth ( )

virtual

virtual double* vtkLightKit::GetKeyLightColor ( )

virtual