sim3d.Light
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
Description
creates a default
light actor object in the 3D environment.light
= sim3d.Light()
specifies options using one or more optional name-value arguments. For example, to create
three light actors in the 3D environment, set light
= sim3d.Light(Name=Value
)NumberOfLights
to
3
.
Input 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 |
---|---|
|
|
|
|
|
|
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
Rotation
|
|
'MATLAB' | The MATLAB® coordinate system, in m and rad. Axes
Rotation
|
|
'ISO8855' | The ISO 8855 standard coordinate system, in m and deg. For more information, see ISO Standards. Axes
Rotation
|
|
'AERO' | The coordinate system for aerospace applications, in m and rad. For more information, see Body Coordinates (Aerospace Blockset). Axes
Rotation
|
|
'VRML' | The X3D ISO standard coordinate system, in m and rad. Axes
Rotation
|
|
'SAE' | The SAE J670 standard coordinate system, in m and rad. For more information, see SAE International Standards. Axes
Rotation
|
|
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
See Also
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)