MATLAB Function Reference

light

Create a light object

Syntax

• light('PropertyName',PropertyValue,...)
  handle = light(...)
  

Description

light creates a light object in the current axes. lights affect only patch and surface object.

light('PropertyName',PropertyValue,...) creates a light object using the specified values for the named properties. MATLAB parents the light to the current axes unless you specify another axes with the Parent property.

handle = light(...) returns the handle of the light object created.

Remarks

You cannot see a light object per se, but you can see the effects of the light source on patch and surface objects. You can also specify an axes-wide ambient light color that illuminates these objects. However, ambient light is visible only when at least one light object is present and visible in the axes.

You can specify properties as property name/property value pairs, structure arrays, and cell arrays (see set and get for examples of how to specify these data types).

See also the patch and surface AmbientStrength, DiffuseStrength, SpecularStrength, SpecularExponent, SpecularColorReflectance, and VertexNormals properties. Also see the lighting and material commands.

Examples

Light the peaks surface plot with a light source located at infinity and oriented along the direction defined by the vector [1 0 0], that is, along the x-axis.

• h = surf(peaks);
  set(h,'FaceLighting','phong','FaceColor','interp',...
        'AmbientStrength',0.5)
  light('Position',[1 0 0],'Style','infinite');
  

See Also

lighting, material, patch, surface

Lighting as a Visualization Tool for more information about lighting

Lighting for related functions

Object Hierarchy

Setting Default Properties

You can set default light properties on the axes, figure, and root levels:

• set(0,'DefaultLightProperty',PropertyValue...)
  set(gcf,'DefaultLightProperty',PropertyValue...)
  set(gca,'DefaultLightProperty',PropertyValue...)
  

Where Property is the name of the light property and PropertyValue is the value you are specifying. Use set and get to access light properties.

The following table lists all light properties and provides a brief description of each. The property name links take you to an expanded description of the properties.

Property Name	Property Description	Property Value
Defining the Light
Color	Color of the light produced by the light object	Values: ColorSpec
Position	Location of light in the axes	Values: x-, y-, z-coordinates in axes units Default: [1 0 1]
Style	Parallel or divergent light source	Values: infinite, local
Controlling the Appearance
SelectionHighlight	This property is not used by light objects	Values: on, off Default: on
Visible	Make the effects of the light visible or invisible	Values: on, off Default: on
Controlling Access to Objects
HandleVisibility	Determines if and when the the light's handle is visible to other functions	Values: on, callback, off Default: on
HitTest	This property is not used by light objects	Values: on, off Default: on
General Information About the Light
Children	Light objects have no children	Values: [] (empty matrix)
Parent	The parent of a light object is always an axes object	Value: axes handle
Selected	This property is not used by light objects	Values: on, off Default: on
Tag	User-specified label	Value: any string Default: '' (empty string)
Type	The type of graphics object (read only)	Value: the string 'light'
UserData	User-specified data	Values: any matrix Default: [] (empty matrix)
Properties Related to Callback Routine Execution
BusyAction	Specify how to handle callback routine interruption	Values: cancel, queue Default: queue
ButtonDownFcn	This property is not used by light objects	Values: string or function handle Default: empty string
CreateFcn	Define a callback routine that executes when a light is created	Values: string or function handle Default: empty string
DeleteFcn	Define a callback routine that executes when the light is deleted (via close or delete)	Values: string or function handle Default: empty string
Interruptible	Determine if callback routine can be interrupted	Values: on, off Default: on (can be interrupted)
UIContextMenu	This property is not used by light objects	Values: handle of a Uicontrextmenu

license

Light Properties