# camlight

Create or move light object in camera coordinates

## Syntax

``camlight``
``camlight(position)``
``camlight(az,el)``
``camlight(___,style)``
``camlight(lt,___)``
``camlight(ax,___)``
``cl = camlight(___)``

## Description

````camlight` creates a light to the right and up from the camera position.```

example

````camlight(position)` creates a light at the specified position. For example, `camlight("left")` creates a light to the left and up from the camera position.```

example

````camlight(az,el)` creates a light at the specified azimuth `az` and elevation `el` with respect to the camera position. The camera target is the center of rotation.```

example

````camlight(___,style)` creates the light with the specified light style.```

example

````camlight(lt,___)` uses the specified light instead of creating a new light. Specify `lt` as the first argument followed by any of the input argument combinations in the previous syntaxes.```

example

````camlight(ax,___)` creates the light in the axes specified by `ax` instead of in the current axes (`gca`). Specify the axes as the first argument in any of the previous syntaxes.```

example

````cl = camlight(___)` returns a `Light` object. Use `cl` to move the light or modify properties of the light after creating it. For a list of properties, see Light Properties.```

example

## Examples

collapse all

Create a sphere and shine a light on it. Position the light to the right and up from the camera position.

```sphere axis equal camlight```

Add a second light to the left and up from the camera position.

`camlight("left")`

Create a sphere and shine a light on it. Position the light to the left and up from the camera position.

```sphere axis equal cl = camlight("left");```

Move the light directly in front of the camera position.

`camlight(cl,0,0);`

Delete the light.

`delete(cl)`

Since R2019b

You can display a tiling of plots using the `tiledlayout` and `nexttile` functions. Use the `tiledlayout` function to create a 1-by-2 tiled chart layout. Use the `nexttile` function to create the `Axes` objects `ax1` and `ax2`. Create a surface and corresponding light in each plot by specifying each `Axes` object as the first argument to `surf` and `camlight`.

In the left axes, create a surface and position a light at infinity shining directly towards the surface. In the right axes, create a surface and position a light at infinity shining from the right and above the surface.

```tiledlayout(1,2) % Left surface ax1 = nexttile; surf(ax1,peaks,EdgeColor="none") lt1 = camlight(ax1,"headlight","infinite"); title("Infinite light shining at surface") % Right surface ax2 = nexttile; surf(ax2,peaks,EdgeColor="none") lt2 = camlight(ax2,"right","infinite"); title("Infinite light shining from the right of surface")```

## Input Arguments

collapse all

Position of the light source, specified as one of these values:

• `"right"` — Place light to the right and up from the camera position

• `"left"` — Place light to the left and up from the camera position.

• `"headlight"` — Place light at the camera position.

The location of the light depends on the value of the `style` argument.

Azimuth of the light position, specified as a scalar value in degrees.

Elevation of the light position, specified as a scalar value in degrees.

Type of light source, specified as one of these values:

• `"local"` — The light is a point source that radiates in all directions from the location specified by the light position.

• `"infinite"` — The light is placed at infinity and shines in parallel rays in the direction specified by the light position.

Light to move, specified as a `Light` object.

Target axes, specified as an `Axes` object. If you do not specify the axes, then `camlight` creates the `Light` object in the current axes.

## Tips

• The `camlight` function sets the `Position` and `Style` properties of the `Light` object. The light does not track the camera. To keep the light in a constant position relative to the camera, call `camlight` whenever you move the camera.

## Version History

Introduced before R2006a