Light

Properties
Types of light sources
- Ambient
- Directional
- Point
- Spot
Functions

Use the Light element to add light sources to your 3D animations.

By default, the 3D animation scene is already lit by two standard light sources that are created automatically: one of them is an ambient light and the other one is a directional light. They are not manageable and are not displayed in the graphical editor or the Projects view. Therefore, even if you have not added any light sources using the Light element, all your 3D objects will still be visible. If the default AnyLogic lighting is fine for you, we recommend that you do not add your own light sources. Otherwise, the default light sources will be removed and the whole scene lighting will be managed by your own light sources.

However, if you need to modify the default lighting, you can add your own light sources and control their position, color, direction (optionally), and attenuation.

AnyLogic provides you with predefined and ready-to-use standard types of light sources:

Street light
Car headlight
Daylight
Moonlight

Imported 3D objects may have their own internal light sources. When exposed to additional light source, such objects may be overlit. To avoid this, you can adjust the lighting settings in the properties of the 3D object itself.

To add a light source onto presentation

Drag the Light element from the 3D section of the Presentation palette into the graphical editor. You will see the light icon in the graphical editor:
Go to the Properties view and select the desired source type from the Predefined type drop-down list: Street light, Car headlight, Daylight, Moonlight. By default, all the properties of the light source (attenuation, cut of angle, and so on) are defined automatically and you may only want to change the position or the color of the light source.
If you do not find the predefined types suitable, you can select the Custom option and configure the light source according to your needs using the source properties that appear. In this case, we recommend that you familiarize yourself with the light source types supported by AnyLogic. Having learned their properties and characteristics, you will be able to choose the correct type and number of light sources you need to add to your model to create the appropriate lighting.
Select the desired type of light source from the Light source type drop-down list.
If you select directional or spot, you can set the direction of the light. Select the light source icon in the graphical editor. You will see the arrow pointing in a certain direction from the center of the icon. This arrow shows the projection of the direction of this light source. To rotate it in the XY plane (Angle Z), click and drag the end of this arrow:
The length of the arrow is also important: it indicates the angle that the light direction makes with the YZ plane (Angle X).
The shorter the arrow is, the larger the angle. If you cannot see the arrow, it means that this source is currently set to shine at a right angle to the XY plane — towards us or backwards. You can change this angle by dragging the end of the arrow closer to or further away from the center of the source icon:
If you want to set angles with a high degree of accuracy, you can specify the required values numerically in the additional Angle Z and Angle X properties in the Position section.
The light shines “from above” on the 3D scene when Angle X is positive.

Properties

General

Name — The name of this source of light. It is used to identify the source and to access it from code.

Ignore — If selected, the source of light will be excluded from the model.

Visible on upper agent — If selected, the source will also shine on the upper agent where this agent lives.

Predefined type — Here you can choose one of the standard types of the sources of light: Street light, Car headlight, Daylight, Moonlight, or Custom (in this case you can manually configure all light source properties, which you will find below).

Color — [Visible if Custom is not chosen for Predefined type] Here you can define the color of the light source.

Light source type — [Visible if Predefined type is set to Custom] The type of the light source: Ambient, Directional, Point, and Spot.

Attenuation — [Visible if Light source type is Point or Spot] Here you can define the attenuation factor for the point/spot source of light. To be precise, you define the following components of attenuation: Constant and Linear. Below you can find the formula that is used to calculate the attenuation factor:
factor = 1 / (k_C + k_L)
where
k_C is constant attenuation
k_L is linear attenuation

Cut off angle — [Visible if Light source type is Spot] Here you can define the maximum angle of light dispersion. In particular, you specify the half of the angle in the vertex of the cone of light created by this source (the value is specified in degrees, from 0 to 90).

Drop off rate — [Visible if Light source type is Spot] Here you can specify how quickly the light will fade as we move from the axis of the cone of the light. 0 means there is no drop off and the light will have uniform intensity everywhere in the cone.

Position

Level — Level where this light source belongs to.

X — The x-coordinate of the source.*Enabled if the type of the light source is set to Street light, Car headlight, Custom: Point, Custom: Spot.

Y — The y-coordinate of the source.*Enabled if the type of the light source is set to Street light, Car headlight, Custom: Point, Custom: Spot.

Z — The z-coordinate of the source.*Enabled if the type of the light source is set to Street light, Car headlight, Custom: Point, Custom: Spot.

Angle X — The angle that light direction composes with YZ plane (starting from inverted Y axis, clockwise, in degrees).*Enabled if the type of the light source is set to Car headlight, Custom: Directional, Custom: Spot.

Angle Z — The angle that light direction composes with XY plane (starting from inverted Y axis, clockwise, in degrees).*Enabled if the type of the light source is set to Car headlight, Custom: Directional, Custom: Spot.

Advanced

Enabled — Here you can specify Boolean expression determining whether the source of light is enabled (if the expression returns true) or disabled (if it returns false).

Show name — If selected, the name of this element will be displayed on the presentation diagram.

Types of light sources

AnyLogic supports four types of light sources: Ambient, Directional, Point and Spot.

Ambient

Shapes lit by ambient light look like 2D shapes. The reason is that the source of ambient light can be considered as a set of uniformly distributed sources of lights all over the 3D space.

Directional

Directional source of light is located in some infinitely distant point. It shines in the specified direction (it is defined using light’s advanced properties Angle X and Angle Z). The Sun is a good example of a directional source of light.

To switch a directional source of light

Point

Point source of light is located in one particular point of space. It shines uniformly in all directions. You can define an attenuation coefficient for this kind of source of light.

Spot

Spot source of light is a particular case of a point light. Spot source creates a beam of light that gradually becomes wider and makes a cone of light. You can think of a spot source of light as a searchlight or a car headlight.

Functions

The type of the light source is defined in its properties. Depending on the selected type, the model creates an instance of one of the following classes: Light3DAmbient, Light3DPoint, Light3DSpot, or Light3DDirectional. All of these classes extend the base Light3D class, which provides shared functionality for all 3D light sources.

Color components

A light source consists of a number of different components: ambient, diffuse, and specular.
Ambient light is light that has been scattered many times so that it has no specific direction. Ambient light does not die out and is evenly distributed throughout the room.
Diffuse light shines in a certain direction but is reflected homogeneously from each point of the surface (for example, fluorescent lights).
Specular light is light reflected from a smooth, shiny surface.
The intensity and color of each component is defined in terms of the general Color object. For example, black means “no light”, white — white light with maximum intensity, red — red light with maximum intensity (for example, a green shape will be invisible under this light), dark red — red light with low intensity.

Function	Description
Color getAmbientColor()	Returns the ambient color component.
Color getDiffuseColor()	Returns the diffuse color component.
Color getSpecularColor()	Returns the specular color component.
void setAmbientColor(Color ambientColor)	Sets the ambient color component. ambientColor — the ambient color component
void setDiffuseColor(Color diffuseColor)	Sets the diffuse color component. diffuseColor — the diffuse color component
void setSpecularColor(Color specularColor)	Sets the specular color component. specularColor — the specular color component

State

Function	Description
boolean isEnabled()	Returns true if this light is turned on. Note that the level containing the element may be invisible, and this method only returns the own state of the element.
void setEnabled(boolean enabled)	Enables or disables this light. enabled — if true, the light will be turned on

Globality

Function	Description
boolean isGlobal()	Returns true if this light affects shapes outside the parent group of this light.
void setGlobal(boolean global)	Sets whether this light should affect shapes outside the parent group of this light. global — if true, the light will affect the shapes outside the parent group of this light

Level

Function	Description
Level getLevel()	Returns the level, where this shape is located.

Group

Function	Description
ShapeGroup getGroup()	Returns the group containing this shape.

Type-specific functions

Light3DDirectional

A 3D directional light that can be added to 3D groups to illuminate the scene.
The directional light is located at an infinitely distant point. It shines in the specified direction. You can think of a directional light as the sun.
It shines along the specified direction, which is defined by 2 angles: the orientation around the X-axis and the Z-axis.

Function	Description
float getAngleX()	Returns the orientation of the light around the X axis. Zero corresponds to the horizontal orientation of the light (parallel with the XY plane).
double getAngleZ()	Returns the orientation of the light around the Z axis. Zero corresponds to the orientation of the light towards the -Y direction (the “north”).
void setAngleX(double angleX)	Sets the orientation of the light around the X axis. Zero corresponds to the horizontal orientation of the light (parallel with the XY plane). angleX — a new value for the X angle.
void setAngleZ(double angleZ)	Set the orientation of the light around the Z axis. Zero corresponds to the orientation of the light towards the -Y direction (the “north”). angleZ — a new value for the Z angle.

Light3DPoint

A 3D point light that can be added to 3D groups to provide scene lighting.
A point light is located at a specific point in space. It shines evenly in all directions.
You can define attenuation coefficients for this type of light.

Function	Description
double getX()	Returns the X coordinate of the light source position.
double getY()	Returns the Y coordinate of the light source position.
double getZ()	Returns the Z coordinate of the light source position.
void setPos(double x, double y, double z)	Sets the position of the light source. x, y, z — coordinates of the new light source position.
void setX(double x)	Sets the X coordinate of the light source position. x — a new X coordinate.
void setY(double y)	Sets the Y coordinate of the light source position. y — a new Y coordinate.
void setZ(double z)	Sets the Z coordinate of the light source position. z — a new Z coordinate.
double getConstantAttenuation()	Returns the constant attenuation factor of the light.
double getLinearAttenuation()	Returns the linear attenuation factor of the light.
double getQuadraticAttenuation()	Returns the quadratic attenuation factor of the light.
void setConstantAttenuation(double constantAttenuation)	Sets the constant attenuation factor of the light. constantAttenuation — a new constant attenuation factor.
void setLinearAttenuation(double linearAttenuation)	Sets the linear attenuation factor of the light. linearAttenuation — a new linear attenuation factor.
void setQuadraticAttenuation(double quadraticAttenuation)	Sets the quadratic attenuation factor of the light. quadraticAttenuation — a new quadratic attenuation factor.
void setAttenuation(double constantAttenuation, double linearAttenuation, double quadraticAttenuation)	Sets the attenuation factors that control how the light fades with distance. Light attenuation is calculated using the following formula (where d is the distance from the light source): \text{attenuation factor} = \frac{1}{k_C + k_L d + k_Q d^2} If all provided factors are set to zero, the light does not fade with distance. constantAttenuation — a constant attenuation factor. linearAttenuation — a linear attenuation factor. quadraticAttenuation — a quadratic attenuation factor.

Light3DSpot

A 3D spot light that can be added to 3D groups for scene lighting.
A spot light is a special case of a point light. A spot source produces a beam of light that gradually widens, forming a cone of light (with a cut-off angle and a fall-off rate). You can think of a spot light as a searchlight or a car headlight.
The illumination is performed along the given direction, which is defined by 2 angles: orientation around the X and Z axes.
You can define attenuation coefficients for this type of light source.

Function	Description
double getX()	Returns the X coordinate of the light source position.
double getY()	Returns the Y coordinate of the light source position.
double getZ()	Returns the Z coordinate of the light source position.
void setX(double x)	Sets the X coordinate of the light source position. x — a new X coordinate.
void setY(double y)	Sets the Y coordinate of the light source position. y — a new Y coordinate.
void setZ(double z)	Sets the Z coordinate of the light source position. z — a new Z coordinate.
void setPos(double x, double y, double z)	Sets the position of the light source. x, y, z — coordinates of the new light source position.
double getAngleX()	Returns the orientation of the light around the X axis (clockwise, from +Y to +Z). Zero angle corresponds to the horizontal orientation of the light (parallel with the XY plane).
double getAngleZ()	Returns the orientation of the light around the Z axis (clockwise, from +X to +Y). Zero angle corresponds to the orientation of the light towards the -Y direction (north).
void setAngleX(double angleX)	Sets the orientation of the light around the X axis (clockwise, from +Y to +Z). Zero corresponds to the horizontal orientation of the light (parallel with the XY plane). angleX — a new value for the X angle.
void setAngleZ(double angleZ)	Sets the orientation of the light around the Z axis (clockwise, from +X to +Y). Zero corresponds to the orientation of the light towards the -Y direction (north). angleZ — a new value for the Z angle.
double getConstantAttenuation()	Returns the constant attenuation factor of the light.
double getLinearAttenuation()	Returns the linear attenuation factor of the light.
double getQuadraticAttenuation()	Returns the quadratic attenuation factor of the light.
void setConstantAttenuation(double constantAttenuation)	Sets the constant attenuation factor of the light. constantAttenuation — a new constant attenuation factor.
void setLinearAttenuation(double linearAttenuation)	Sets the linear attenuation factor of the light. linearAttenuation — a new linear attenuation factor.
void setQuadraticAttenuation(double quadraticAttenuation)	Sets the quadratic attenuation factor of the light. quadraticAttenuation — a new quadratic attenuation factor.
void setAttenuation(double constantAttenuation, double linearAttenuation, double quadraticAttenuation)	Sets the attenuation factors that control how the light fades with distance. The attenuation is calculated using the following formula, where d is the distance from the light source: \text{attenuation factor} = \frac{1}{k_C + k_L d + k_Q d^2} If all provided factors are set to zero, the light does not fade with distance. constantAttenuation — a constant attenuation factor. linearAttenuation — a linear attenuation factor. quadraticAttenuation — a quadratic attenuation factor.
double getCutOffAngle()	Returns the cut-off angle of the light source. The angle is measured from the direction axis of the light to the edge of the cut-off cone. The value lies in the range [0, PI/2] radians, where PI/2 corresponds to lighting half of the world’s space.
double getDropOffRate()	Returns the exponent used to control how the light intensity decreases from the center toward the cut-off angle.
void setCutOffAngle(double cutOffAngle)	Sets the cut-off angle of the light source. The angle is measured from the direction axis of the light to the edge of the cut-off cone. It must lie in the range [0, PI/2] radians, where PI/2 corresponds to lighting half of the world’s space. cutOffAngle — a new cut-off angle value.
void setDropOffRate(double dropOffRate)	Sets the exponent value that controls how the light intensity decreases from the center toward the cut-off angle. dropOffRate — an exponent controlling intensity falloff.

How can we improve this article?