Light

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

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 an 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 the presentation

1. 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:

   

2. 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.
3. 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.
4. Select the desired type of light source from the Light source type drop-down list.
5. 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:

   

6. 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:

   

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

General

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

Show name — If selected, the name of the light source will be displayed on the presentation diagram.

Ignore — If selected, the light source is excluded from the model.

Predefined type — Sets one of the standard types of the light sources: Street light, Car headlight, Daylight, Moonlight, or Custom. With Custom selected, you can configure all the properties of the light source.

Color — [Visible unless Predefined type: Custom] The color of the light source.

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

Attenuation — [Visible if Light source type: Point or Spot] The attenuation factor for the point or spot light source. You can define the following attenuation component: Constant and Linear. The attenuation factor formula is as follows:
factor = 1 / (k_C + k_L)
where
k_C is the constant attenuation
k_L is the linear attenuation

Cut off angle — [Visible if Light source type: Spot] The maximum angle of light dispersion. Specifically, you specify the half of the angle at the vertex of the cone of light created by this light source. The value is specified in degrees, from 0 to 90.

Drop off rate — [Visible if Light source type: Spot] Determines how quickly the light will fade as the viewer moves away from the axis of the light cone. 0 means there is no drop-off, and the light will have uniform intensity everywhere in the cone.

Position

Level — The level on which this light source is located.

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 at which the light direction intersects the YZ plane, starting from the 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 at which the light direction intersects the 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.

Visibility and presentation

Agent presentation — If selected, the element is included in the presentation of the agent. This means that if the agent hosting this element is embedded in another agent, the element will remain visible in that higher-level agent.

Enabled — The Boolean expression that determines whether the light source is enabled (if the expression returns true) or disabled (if it returns false).

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

Shapes lit by ambient light appear as look like 2D shapes. This is because the source of ambient light is considered a set of uniformly distributed light sources throughout the 3D space.

A directional light source is located at an infinitely distant point. It shines in the specified direction, which is defined using the light’s advanced properties, Angle X and Angle Z. The sun is a good example of a directional light source.

A Point light source is located at a single point in space. It shines uniformly in all directions. You can define an attenuation coefficient for this type of light source.

A Spot light source is a special case of a point light. A spot source creates a beam of light that gradually widens to form a cone of light. A spot source of light can be thought of as a searchlight or a car headlight.

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?

Send