This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.


Ambient light

MuPAD® notebooks are not recommended. Use MATLAB® live scripts instead.

MATLAB live scripts support most MuPAD functionality, though there are some differences. For more information, see Convert MuPAD Notebooks to MATLAB Live Scripts.


plot::AmbientLight(<intensity>, <a = amin .. amax>, options)


plot::AmbientLight(intensity) generates undirected ambient light of the given intensity.

Each 3D scene is illuminated by several light sources that are set automatically and cannot be controlled by the user. Cf. the help page of Lighting.

If special light effects are desired, the user can create alternative light sources of various types such as plot::AmbientLight, plot::DistantLight, plot::PointLight, and plot::SpotLight.

If at least one user defined light source is inserted into the scene (e.g., by simply passing the light objects as input parameters to the plot command), the automatic lights are switched off and the user defined lights are used to illuminate the scene.

While directed lights such as plot::DistantLight etc. create shading effects that add depth to the picture, a certain amount of undirected ambient light is usually needed.

plot::AmbientLight(intensity) creates ambient light whose intensity is given by the parameter intensity. When the intensity is 1, the ambient light dominates all other light sources.

By default, white light is created. Other colours can be chosen by the attribute LightColor.

It does not make sense to have more than one ambient light object in a scene.


AttributePurposeDefault Value
Framesthe number of frames in an animation50
LightColorthe color of lightRGB::White
LightIntensityintensity of light1.0
Namethe name of a plot object (for browser and legend) 
ParameterEndend value of the animation parameter 
ParameterNamename of the animation parameter 
ParameterBegininitial value of the animation parameter 
ParameterRangerange of the animation parameter 
TimeEndend time of the animation10.0
TimeBeginstart time of the animation0.0
TimeRangethe real time span of an animation0.0 .. 10.0


Example 1

We create a 3D function graph in flat white and use ambient white light to illuminate it:

f := plot::Function3d(sin(x + y) + cos(x - y), 
                      x = -PI..PI, y = -PI..PI, 
                      FillColorType = Flat,
                      Color = RGB::White):
ambientlight := plot::AmbientLight(0.7):
plot(f, ambientlight):

We create another ambient light with animated intensity:

ambientlight := plot::AmbientLight(a, a = 0..1):
plot(f, ambientlight)

We add directed yellow light to the scene and study the mixture between the “sunlight” and an increasing amount of ambient light. When the ambient light is at full intensity, it dominates the directed light completely:

sunlight :=  plot::DistantLight([0, 0, 0], [5, 1, -3], 1,
                                LightColor = RGB::Yellow):
plot(f, ambientlight, sunlight)

delete f, ambientlight, sunlight:



The intensity of the light: a numerical value between 0 and 1 or an arithmetical expression of the animation parameter a.

intensity is equivalent to the attribute LightIntensity.


Animation parameter, specified as a = amin..amax, where amin is the initial parameter value, and amax is the final parameter value.

See Also

MuPAD Functions

MuPAD Graphical Primitives

Was this topic helpful?