# Documentation

### This is machine translation

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

# `plot`::`DistantLight`

Directed distant light (“sunlight”)

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

## Syntax

```plot::DistantLight(`[px, py, pz]`, `[tx, ty, tz]`, <`intensity`>, <`a = amin .. amax`>, `options`)
```

## Description

```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.

### Note

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.

## Attributes

AttributePurposeDefault Value
`CameraCoordinates`position of light sources relative to the camera?`FALSE`
`Frames`the number of frames in an animation`50`
`LightColor`the color of light`RGB::White`
`LightIntensity`intensity of light`1.0`
`Name`the name of a plot object (for browser and legend)
`ParameterEnd`end value of the animation parameter
`ParameterName`name of the animation parameter
`ParameterBegin`initial value of the animation parameter
`ParameterRange`range of the animation parameter
`Position`positions of cameras, lights, and text objects
`PositionX`x-positions of cameras, lights, and text objects
`PositionY`y-positions of cameras, lights, and text objects
`PositionZ`z-positions of cameras, lights, and text objects
`Target`the target point of a light
`TargetX`the target point of a light, x component
`TargetY`the target point of a light, y component
`TargetZ`the target point of a light, z component
`TimeEnd`end time of the animation`10.0`
`TimeBegin`start time of the animation`0.0`
`TimeRange`the real time span of an animation`0.0` .. `10.0`
`Visible`visibility`TRUE`

## Examples

### 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:`

## Parameters

 `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`. `intensity` 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`. `a` Animation parameter, specified as `a```` = amin..amax```, where `amin` is the initial parameter value, and `amax` is the final parameter value.