Density map

Properties
Functions

AnyLogic enables collecting statistics on the density of moving units in the simulated space and displaying this information on animation as a density map. This functionality is supported for pedestrians and transporters with free space navigation.

Having added the Density Map element, you enable showing the density map of the specified type (pedestrian or transporter) for your simulation model.

If you have transporters and pedestrians moving on the same level and need to track the density for both, you have to add two Density Map elements: one per type.

The density maps located on one level must be of different types, otherwise an error will occur.

You will see that as pedestrians or transporters move in the simulated space, the layout is gradually painted in different colors. The color of every point of the space corresponds to the current density in this particular area. The density map is constantly repainted according to the actual values: when the density changes in some point, the color changes dynamically to reflect this change. In case of zero density the area is not painted at all. If you have transporters and pedestrians moving in the same area, the density maps won’t display the aggregate density, only separate one for each type.

The element itself acts as the color legend for the density map. It displays the correspondence between density values and colors on the map (see the right side on the figure below).

The red color indicates the critical density (by default it is equal to 1.5 units/m²). Blue color is used for low densities. When the density in some area is zero, the density map for this particular area is not drawn at all.

For example, the legend shown in the figure above tells us that yellow color on the map corresponds to the density 0.75 pedestrians/m².

You can change the logarithmic color scheme to linear, or some custom scheme, switch attenuation on/off, etc.

To add the density map

Drag the Density Map element into the graphical editor from either section of the Space Markup palette: Material Handling or Pedestrian. At the runtime it will show the density map legend. The legend displays the correspondence between density values and colors on the density map.
In the Properties specify the Type of the density map:
- Pedestrian — to display the density map for pedestrians
- Transporter — to display the density map for transporters with free space navigation
You can choose your density map to display either historical data, i.e. values collected from the start of the model run (Complete model run option of the Time period parameter) or values collected over the specified period of time (Sliding window option of the Time period parameter). You can also choose the Displayed density value: either Maximum or Mean.
The amount of memory required to handle the data will grow proportionately to the size of the sliding window.
If you collect maximum density values over complete model run, these values can be displayed either as maximum observed density values (if attenuation is turned off), or the actual density map for the recent period of time (if attenuation is turned on). With the attenuation being turned on, when the density goes down, the color for the corresponding zone on the density map changes correspondingly but not immediately. To turn the attenuation on, select the checkbox Enable attenuation
If you are not satisfied with the density map painted over the layout and making it hardly visible, you may increase the transparency level for the density map using the slider Transparency.
The density map is commonly used to detect the areas with critical densities. At the model runtime the areas with the density values equal or greater than the critical density threshold are painted with red color (if some other colors are not set using the Custom option of Color scheme property). By default the critical density value is 1.5 units/m². Units here are either pedestrians or transporters, depending on the type of the density map. You can change this value in the parameter Critical density.
By default AnyLogic uses logarithmic color scheme. In this case the color changes logarithmically from the “minimum” (blue) color to the “maximum” (red) color. This color scheme is frequently used when you need to pay attention only to the density values close to the critical value threshold. You can change the logarithmic color scheme to the linear scheme by choosing Linear option of the parameter Color scheme. It is the simplest color scheme: color changes linearly from the “minimum” color to the “maximum” (red) color. You can even define your own color scheme by choosing the Custom option of Color scheme property.

Properties

General

Name — The name of the shape. The name is used to identify and access the shape.

Ignore — If selected, the shape is excluded from the model.

Visible on upper agent — If selected, the shape is also visible on the upper agent where this agent lives.

Lock — If selected, the shape is locked. Locked shapes do not react to mouse clicks — it is impossible to select them in the graphical editor until you unlock them.

Visible — Here you specify whether the density map legend is visible on the animation at the model runtime, or not. Using the control, choose yes or no.

Type — Here you should specify the type of agents for whom the density map will be displayed: either Pedestrian or Transporter.

Time period – Here you can select how density data is collected. The default option Complete model run where the data is collected from the start of the model run until present moment. The other option is Sliding window which represents a length of time over which the density data is collected. For example, if you specify the sliding window of 5 minutes, the density map will display information collected over the last 5 minutes only, not taking into account any earlier data

Sliding window – [Visible if Time period: Sliding window] Here you can specify the exact time period over which the data will be collected.

Displayed density value – Here you can choose which density value will be used to display on the density map. It can be either Maximum value or Mean value.

Enable attenuation — If the checkbox is selected, the density map will be shown with attenuation. In this case the actual density map for the recent period of time will be shown, not the maximum observed densities. When the density goes down, the color for the corresponding zone on the density map changes correspondingly (but not immediately, with the specified delay).

Transparency — Here you can define the transparency level for the density map. Using the slider, choose the value from the range [0..100%]. 100% means fully transparent map (the density map is not visible), 0% means fully opaque density map (the animation underneath the density map is not visible at all).

Critical density — Here you specify the critical density value. All areas with the density values equal or greater than the critical density threshold will be painted on the animation with red (if some other colors are not set using Custom as their Color scheme).

Color scheme — Here you can choose the color scheme for the density map. There are three alternative options available:

Logarithmic — The color will change logarithmically from the “minimum” (blue) color to the “maximum” (red) color. This color scheme is frequently used when you need to pay attention only to the density values close to the critical value threshold.
Linear — The simplest color scheme: color will change linearly from the “minimum” (blue) color to the “maximum” (red) color.
Custom — You can define your own color scheme and define the correspondence between colors and density values in the Custom color field below.

Custom color — [Visible if Color scheme is set to Custom] If you want to define some custom color scheme for the density map, here you should specify the expression that will return different colors depending on the density value (you can obtain the density value using the local variable density).

You can see the example of such an expression set up as the default value:

density > self.criticalDensity * 0.7 ? red : transparent

It defines that red color will be used for the densities that are higher than the specified threshold value (70% of the critical density value). For the lower densities, the density map will not be drawn at all.

If the transparency argument specified in your custom code equals 0, i.e. the color that your code returns is fully opaque, then the setting of the Transparency parameter will be applied to your custom color scheme.

Position and size

Level — The name of the level for which the density map will be displayed.

X — X-coordinate of the density map legend.

Y — Y-coordinate of the density map legend.

Width — Width of the density map legend (in pixels).

Height — Height of the density map legend (in pixels).

Advanced

Show in — The option defines whether you want the density map to be shown both In 2D and 3D animation, or in 2D only, or in 3D only. Since density map can be shown only in 2D animation, the 2D only option is selected and the control is disabled.

Show name — If selected, the shape’s name is displayed on a presentation diagram.

Functions

Type

Function	Description
DensityMapType getType()	Returns the type of the density map depending on whom the statistics are collected: either pedestrians or transporters. Valid values: PEDESTRIAN_MAP_TYPE — the density map is displayed for pedestrians TRANSPORTER_MAP_TYPE — the density map is displayed for transporters

Displayed density value

Function	Description
DensityMapDisplayedValue getDensityValue()	Returns the type of value used to build the density map. Possible values: DENSITY_VALUE_MAX - maximum density value DENSITY_VALUE_MEAN - mean density value
void setDensityValue(DensityMapDisplayedValue valueType)	Sets the type of density value used to build the density map. valueType - a constant defining density value type. Possible values: DENSITY_VALUE_MAX - maximum density value DENSITY_VALUE_MEAN - mean density value

Statistics

Function	Description
double currentDensity(double x, double y)	Returns the current density value in the area neighboring the specified point, units/m². The units here mean either pedestrians or transporters, depending on the density map type. This value does not reflect exactly the current situation, it accumulates historic data. x — X-coordinate of the point y — Y-coordinate of the point
double maximumDensity(double x, double y)	Returns the maximum density value in the specified point, units/m². x — X-coordinate of the point y — Y-coordinate of the point
void reset()	Resets the values of the density map that the user can see and obtain by calling the maximumDensity() function to the current values of density.

Color scheme

Function	Description
DensityMapColorScheme getColorScheme()	Returns the color scheme of the density map. Valid values: LINEAR_COLOR_SCHEME LOGARITHMIC_COLOR_SCHEME CUSTOM_COLOR_SCHEME
void setColorScheme (DensityMapColorScheme colorScheme)	Sets the new color scheme. colorScheme — the new color scheme. Valid values: LINEAR_COLOR_SCHEME LOGARITHMIC_COLOR_SCHEME CUSTOM_COLOR_SCHEME
double getCriticalDensity()	Returns the critical density for the density map, in units/m².
void setCriticalDensity (double criticalDensity)	Sets the new critical density for the density map, in units/m². criticalDensity — the new critical density value

Attenuation and transparency

Function	Description
double getTransparency()	Returns the density map transparency. The value is in the range [0, 1], 0 means fully opaque, 1 means fully transparent.
void setTransparency(double transparency)	Sets the new density map transparency. transparency — the new transparency value. The value should be in the range [0, 1], 0 means fully opaque, 1 means fully transparent.
boolean isEnableAttenuation()	Returns true if the density map is shown with attenuation; returns false otherwise.
void setEnableAttenuation(boolean enable)	Turns density map attenuation on/off. enable — attenuation. If enable is true — the density map is shown with attenuation, if it is false — attenuation is turned off.

Visibility

Function	Description
void show()	Shows the density map.
void hide()	Hides the density map.
void display(boolean flag)	Sets the visibility of the density map. flag — visibility. If flag is true — the density map is displayed. If it is false — the density map is invisible.
boolean isVisible()	Returns true if the density map legend is visible; returns false otherwise.
void setVisible(boolean v)	Sets the visibility of the density map legend. v — visibility. If v is true — the density map legend is set to be visible, if it is false — not visible.

Level

Function	Description
Level getLevel()	Returns the level, for which the density map is displayed.

Legend position

Function	Description
double getX()	Returns the X-coordinate of the density map legend.
double getY()	Returns the Y-coordinate of the density map legend.
void setX(double x)	Sets the X-coordinate of the density map legend. x — new X-coordinate
void setY(double y)	Sets the Y-coordinate of the density map legend. y — new Y-coordinate

Legend size

Function	Description
double getWidth()	Returns the width of the density map legend (in pixels).
double getHeight()	Returns the height of the density map legend (in pixels).
void setWidth (double width)	Sets the width of the density map legend (in pixels). width — the new width
void setHeight (double height)	Sets the height of the density map legend (in pixels). height — the new height

Removal

Function	Description
void remove()	Removes the density map from the presentation. If the map is not a part of presentation, the function does nothing. Removal from the presentation does not necessarily mean removing from the model logic, since logical networks and routes may have been created before the removal and survive it.

How can we improve this article?