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.


Directed distant light (“sunlight”)

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::DistantLight([px, py, pz], [tx, ty, tz], <intensity>, <a = amin .. amax>, options)


plot::DistantLight([px, py, pz], [tx, ty, tz], intensity) creates a distant light source emitting parallel light shining into the direction [tx - px, ty - py, tz - pz]

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.


The vector [px, py, pz] does not represent the position of a distant light in space. The light source is infinitely far away.

When using [tx, ty, tz] = [0, 0, 0], you may think of [px, py, pz] as the direction where the light source is located.

When using [px, py, pz] = [0, 0, 0], you may think of [tx, ty, tz] as the direction into which the light is shining.

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

When using the attribute CameraCoordinates = TRUE, the light source is fixed to the camera. It moves automatically, when the camera is moved.

Directed light such as plot::DistantLight create shading effects that add depth to the picture. Usually, a certain amount of undirected ambient light of type plot::AmbientLight enhances the picture.


AttributePurposeDefault Value
CameraCoordinatesposition of light sources relative to the camera?FALSE
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 
Positionpositions of cameras, lights, and text objects 
PositionXx-positions of cameras, lights, and text objects 
PositionYy-positions of cameras, lights, and text objects 
PositionZz-positions of cameras, lights, and text objects 
Targetthe target point of a light 
TargetXthe target point of a light, x component 
TargetYthe target point of a light, y component 
TargetZthe target point of a light, z component 
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 white sphere and use a single directed white light to illuminate it:

f := plot::Surface(
        [cos(u)*sin(v), sin(u)*sin(v), cos(v)],
        u = 0..2*PI, v = 0..PI,
        FillColorType = Flat,
        FillColorFunction = RGB::White,
        Scaling = Constrained):
sunlight1 := plot::DistantLight([1, -2, 3], [0, 0, 0], 1/2):
plot(f, sunlight1):

We create another distant light source shining from another direction, of yellow color and with animated intensity:

sunlight2 := plot::DistantLight([-2, 1, 3], [0, 0, 0], a,
                                LightColor = RGB::Yellow,
                                a = 0..1):
plot(f, sunlight2)

We use both lights simultaneously:

plot(f, sunlight1, sunlight2)

delete f, sunlight1, sunlight2:


px, py, pz

The coordinates of the sun's “position”: numerical values or arithmetical expressions of the animation parameter a.

px, py, pz are equivalent to the attributes PositionX, PositionY, PositionZ.

tx, ty, tz

The coordinates of the point the light is shining to: numerical values or arithmetical expressions of the animation parameter a.

tx, ty, tz are equivalent to the attributes TargetX, TargetY, TargetZ.


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?