sim3d.Light

Create light actor

Since R2024a

Description

Use the sim3d.Light object to create a light actor in the 3D environment for custom lighting. After you create a sim3d.Light object, you can modify aspects of the light actor by setting property values. You can create N number of light actors in the 3D environment.

Creation

Syntax

light = sim3d.Light()

light = sim3d.Light(Name=Value)

Description

light = sim3d.Light() creates a default light actor object in the 3D environment.

light = sim3d.Light(Name=Value) specifies options using one or more optional name-value arguments. For example, to create three light actors in the 3D environment, set NumberOfLights to 3.

Input Arguments

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: light = sim3d.Light(ActorName='Light',Translation=[3,4,3],Rotation=[0,pi/2,-pi/4]) creates a light actor with the specified position and rotation.

Example: lights = sim3d.Light(ActorName='Lights',NumberofLights=3,Translation=[0,-1,0; 0,0,0; 0,1,0]) creates three light actors at the specified positions.

ActorName — Name of actor

autogenerated name (default) | character array | string

Name of actor, specified as a character array or string. If you do not specify an actor name, then the software assigns the actor an autogenerated name. Use this argument to set the name of the sim3d.Light object.

Note

If you specify the same name as an actor that already exists, then the software appends actor name you specify with a unique identifier.

NumberOfLights — Total number of lights

1 (default) | real positive scalar

Total number of lights, specified as a real positive scalar. Use this argument to create N number of light actors in the 3D environment.

Example: NumberOfLights=3

Data Types: double

Translation — Relative translation

[0,0,0] (default) | real N-by-3 array

Relative translation (x,y,z) of the actor object to its parent actor, specified as a real N-by-3 array, in m. N specifies the number of actors. When you add an actor to the 3D environment, the default parent actor is the Scene Origin at (0,0,0).

Example: Translation=[3,4,3]

Example: Translation=[0,-1,0; 0,0,0; 0,1,0]

Data Types: double

Rotation — Relative rotation

[0,0,0] (default) | real N-by-3 array

Relative rotation (roll, pitch, yaw) of the actor object to its parent actor, specified as a real N-by-3 array, in rad.

Example: Rotation=[0,pi/2,-pi/4]

Example: Rotation=[0,pi,-pi/2; 0,pi,-pi/2; 0,pi,-pi/2]

Data Types: double

LightType — Type of light

'PointLight' (default) | 'SpotLight' | 'RectLight' | string N-by-1 array

Type of light, specified as 'PointLight', 'SpotLight', or 'RectLight'. To set the LightType of N actors, specify as a string array of size N-by-1. Use this argument to simulate various lighting effects.

Light Type	Description
'PointLight'	A light source that emits light equally in all directions. Use for light sources such as lamps or bulbs.
'SpotLight'	A light source that emits light within a cone shaped region. You can control the cone angle. Use for light sources such as spotlights or flashlights.
'RectLight'	A light source that emits light from a rectangular surface. You can control the size of the light source. Use for light sources such as light panels or area lights.

Example: LightType='SpotLight'

Example: LightType=['SpotLight'; 'SpotLight'; 'SpotLight']

Data Types: string

Properties

Base Attributes

Parent — Parent of actor

handle to parent actor object

Parent of actor, specified as a handle to the parent actor object. After you add an actor to the sim3d.World object, the default parent actor is the Scene Origin at [0,0,0]. Use this property to set any actor in the 3D environment as the parent actor of a sim3d.Light object.

Children — Children of actor

structure

This property is read-only.

Children of actor, specified as a structure. Each field of the structure contains a handle to the child of a sim3d.Light object.

ParentWorld — Parent world

handle to parent world object

Parent world, specified as a handle to the parent sim3d.World object. You can use this property only if the sim3d.Light object is added to the parent sim3d.World object.

CoordinateSystem — Actor orientation

'Default' (default) | 'MATLAB' | 'ISO8855' | 'AERO' | 'VRML' | 'SAE'

Actor orientation representation in the 3D environment, specified as 'Default', 'MATLAB', 'ISO8855', 'AERO', 'VRML', or 'SAE'. The values are not case-sensitive. To display the actor transformation in the specified coordinate system, set this property first, and then set the transform properties Translation, Rotation, and Scale.

Coordinate System	Description
'Default'	The default coordinate system, in m and rad. Axes X-axis points away from the viewer. Y-axis points toward right. Z-axis points upward. Rotation Roll — Clockwise rotation about X-axis Pitch — Clockwise rotation about Y-axis Yaw — Counterclockwise rotation about Z-axis
'MATLAB'	The MATLAB® coordinate system, in m and rad. Axes X-axis points away from the viewer. Y-axis points toward left. Z-axis points upward. Rotation Roll — Clockwise rotation about X-axis Pitch — Clockwise rotation about Y-axis Yaw — Clockwise rotation about Z-axis
'ISO8855'	The ISO 8855 standard coordinate system, in m and deg. For more information, see ISO Standards. Axes X-axis points away from the viewer. Y-axis points toward left. Z-axis points upward. Rotation Roll — Clockwise rotation about X-axis Pitch — Clockwise rotation about Y-axis Yaw — Clockwise rotation about Z-axis
'AERO'	The coordinate system for aerospace applications, in m and rad. For more information, see Body Coordinates (Aerospace Blockset). Axes X-axis points away from the viewer. Y-axis points toward right. Z-axis points downward. Rotation Roll — Clockwise rotation about X-axis Pitch — Clockwise rotation about Y-axis Yaw — Clockwise rotation about Z-axis
'VRML'	The X3D ISO standard coordinate system, in m and rad. Axes X-axis points away from the viewer. Y-axis points upward. Z-axis points toward right. Rotation Roll — Clockwise rotation about X-axis Pitch — Counterclockwise rotation about Y-axis Yaw — Counterclockwise rotation about Z-axis
'SAE'	The SAE J670 standard coordinate system, in m and rad. For more information, see SAE International Standards. Axes X-axis points away from the viewer. Y-axis points toward right. Z-axis points downward. Rotation Roll — Clockwise rotation about X-axis Pitch — Clockwise rotation about Y-axis Yaw — Clockwise rotation about Z-axis

Data Types: string

Translation — Relative translation

[0,0,0] (default) | real N-by-3 array

Relative translation (x,y,z) of the actor object to its parent actor, specified as a real N-by-3 array, in m. N specifies the number of actors. When you add an actor to the 3D environment, the default parent actor is the Scene Origin at (0,0,0).

Example: arrow.Translation = [1,2,1]

Example: arrows.Translation = [1,4,2; 1,3,2; 1,2,2]

Rotation — Relative rotation

[0,0,0] (default) | real N-by-3 array

Relative rotation (roll, pitch, yaw) of the actor object to its parent actor, specified as a real N-by-3 array, in rad.

Example: arrow.Rotation = [0,pi/2,pi/8]

Example: arrows.Rotation = [pi/2,pi/4,pi/2; 0,pi/4,pi/2; pi,pi/2,0]

LightState — Status of light

1 or true (default) | 0 or false | logical N-by-1 vector

Status of light in the 3D environment, specified as 1 (true) to turn on the light or 0 (false) to turn off the light. For N number of lights, specify as a logical N-by-1 vector.

Example: light.LightState = 1

Example: lights.LightState = [1; 1; 1]

Data Types: logical

LightColor — Color of light

[1,1,1] (default) | real N-by-3 vector

Color of light, specified as real N-by-3 array of RGB triplet values. An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0, 1].

Example: light.LightColor = [ 0.5,0.7,0.4]

Example: lights.LightColor = [ 1,0,0; 0,1,0; 0,0,1]

Data Types: double

Intensity — Brightness of light

5000 (default) | real positive N-by-1 vector

Brightness of light, specified as real positive N-by-1 vector.

Example: light.Intensity = 4000

Example: lights.Intensity = [4500; 4500; 4500]

Data Types: double

IntensityUnit — Light intensity unit name

'' (default) | 'Lumens' | 'Candelas'

Light intensity unit name, specified as 'Lumens', or 'Candelas'. The default value for this property is an empty string ' '.

Example: light.IntensityUnit = 'Lumens'

Example: lights.IntensityUnit = ['Candelas'; 'Candelas'; 'Candelas']

Data Types: string

AttenuationRadius — Range of light

10 (default) | real positive N-by-1 vector

Range of light, specified as real positive N-by-1 vector, in m. Use this property to reduce computational load by limiting illumination to necessary areas of the environment.

Example: light.AttenuationRadius = 20

Example: lights.AttenuationRadius = [30; 35; 40]

Data Types: double

Temperature — Temperature of emitted light

6500 (default) | real positive N-by-1 vector

Temperature of emitted light, specified as real positive N-by-1 vector, in K. As temperature value increases, the appearance of the light changes from a warmer tone to a cooler tone.

Example: light.Temperature = 4500

Example: lights.Temperature = [6000; 6000; 6000]

Data Types: double

IESFilePath — Source file for IES texture

"" (default) | string N-by-1 array

Source file for IES texture, specified as string N-by-1array. After you import an IES texture file you can modify other aspects of the light by setting additional properties.

Example: light.IESFilePath = fullfile(pwd,"file.ies")

Example: lights.IESFilePath = fullfile(pwd,["file.ies";"file.ies";"file.ies"])

Data Types: string

Note

If you import an IES texture file, LightType does not impact the light actor.

Point Light Attributes

SourceRadius — Radius of light source

0 (default) | real positive N-by-1 vector

Radius of light source, specified as real positive N-by-1 vector, in m. A larger value creates a diffused spherical light. A smaller value creates a focused spherical light.

Example: light.SourceRadius = 0.5

Example: lights.SourceRadius = [0.5; 0.4; 0.3]

Dependencies

Set LightType to 'PointLight'.

Data Types: double

SourceLength — Length of light source

0 (default) | real positive N-by-1 vector

Length of light source, specified as real positive N-by-1 vector, in m. A larger value spreads the light over a longer area. A smaller value creates a directional light.

Example: light.SourceLength = 1

Example: lights.SourceLength = [2; 2; 2]

Dependencies

Set LightType to 'PointLight'.

Data Types: double

Spot Light Attributes

ConeAngle — Angle of light beam

44 (default) | real positive N-by-1 vector

Angle of light beam, specified as real positive N-by-1 vector, in deg. This property represents the angle between the center axis of the spot light and the outer edge of the light cone.

Example: light.ConeAngle = 30

Example: lights.ConeAngle = [25; 25; 25]

Dependencies

Set LightType to 'SpotLight'.

Data Types: double

Rectangular Light Attributes

SourceWidth — Width of rectangular light source

0.64 (default) | real positive N-by-1 vector

Width of rectangular light source, specified as real positive N-by-1 vector, in m. A larger value provides a wide light source with a broad coverage area. A smaller value provides a narrow light source with focused illumination.

Example: light.SourceWidth = 0.7

Example: lights.SourceWidth = [0.8; 0.8; 0.8]

Dependencies

Set LightType to 'RectLight'.

Data Types: double

SourceHeight — Height of rectangular light source

0.64 (default) | real positive N-by-1 vector

Height of rectangular light source, specified as real positive N-by-1 vector, in m. A larger value provides a taller light source with a larger coverage area. A smaller value provides a shorter light source with focused illumination.

Example: light.SourceHeight = 0.7

Example: lights.SourceHeight = [0.8; 0.8; 0.8]

Dependencies

Set LightType to 'RectLight'.

Data Types: double

Version History

Introduced in R2024a