Polygonal Node

Nodes and paths are space markup elements that define the locations of agents in the space:

Nodes can be connected with paths. Together they compose a network. In the network, node defines a place where agents may reside, while paths define the routes that agents may take when moving from one node to another.

Polygonal node and Rectangular node are used when your nodes define some areas (offices, rooms, etc.) where agents may stay inside. Use Polygonal node when your area has complex form. If your area is rectangular, use Rectangular node instead. If the node defines a transit transportation node in a network, you can simply use Point Node.

You can define particular waiting points inside a node using attractors.

Speed and access restriction

You can customize the access to the node and the speed of movement through the node for transporters with free-space navigation and path-guided navigation. Speed restrictions and access restrictions do not depend on each other and can be specified separately. The nodes with restrictions can overlap. Each node can have only one type of access restriction enabled.

Demo model: Areas with Limited Access for Transporters

Nodes with enabled access restriction automatically change their color to red:

This change of color doesn't occur if the node with restrictions is created programmatically.

Note: At the start of model run, the nodes change coordinates very slightly for a negligible value. In cases where the ending or the starting point of a path is located at the border of a node, this might affect the simultaneous callback times for:
The order in which these actions are executed will remain unchanged.

To add a polygonal node

  1. Double-click the Polygonal Node element in the Space Markup palette.
  2. The icon of the element should turn into . It means that the drawing mode is activated and now you can draw a polygonal area in the graphical editor point by point.
  3. Click in the graphical editor to put the first point of the area. Do more clicks to add more points.
  4. Finally put the final point with the double-click.

Properties

General

Name – The name of the node. The name is used to identify and access the node from code.

Ignore – If selected, the node is excluded from the model.

Visible on upper agent – If selected, the node is also visible on the upper agent where this agent lives.

Lock – If selected, the node 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. It is frequently needed when you want to prevent editing this shape while drawing other shapes over it.

Visible – Here you specify whether the shape is visible on animation at model runtime, or not. Using the control, choose yes or no.

Locations layout – [Visible if there are no attractors inside the node] Here you can choose the layout inside the node: Random or Arranged.

Attractors... – Click this button to create attractors inside the area. Attractors are the places where the pedestrians will tend to get.

Speed and access restrictions

Restrictions apply to – Here you can specify the agent type whose speed and/or access will be restricted in this node.

Speed restriction – If selected, limits the speed of agents in this node.

Maximum speed – [Visible if the Speed restriction option is selected] Maximum permissible speed for agents in this node.

Access restriction – If selected, limits the access of agents to this node.

Access restricted by – [Visible if the Access restriction option is selected] Here you can select the access restriction policy for this node. The following options are available:
capacity - the number of agents inside the node. As long the number of agents is less than or equal to the value specified in the Capacity parameter, the access to the node is granted.
throughput - the number of agents that can enter the node per 1 model time unit. As long the number of agents is less than or equal to the value specified in the Throughput parameter, the access to the node is granted.
schedule - the access is controlled by the on/off Schedule. The node is closed when the schedule is "on" and open when the schedule is "off".
condition - a Condition is evaluated for every agent that wants to enter the node. If the evaluation returns true, the access is denied. If the evaluation returns false, the access is granted.
call of close() function - the node is closed by the explicit call of the close() function. To open the node, you can call the open() function.

Capacity – [Visible if Access restricted by: capacity] Maximum permissible number of agents in the node. When the value specified here is exceeded, the access to the node is restricted.

Throughput – [Visible if Access restricted by: throughput] Maximum permissible number of agents in the node per 1 model time unit. When the value specified here is exceeded, the access to the node is restricted.

Schedule – [Visible if Access restricted by: schedule] A schedule that governs the access to the node. When "on", the access to the node is restricted for the specified agent type. When "off", any agent can enter the node.

Condition – [Visible if Access restricted by: condition] A boolean expression that must be evaluated for each agent to determine whether the access to the node can be granted. If the evaluation returns true, the access is restricted; otherwise, the node remains open.

Area is avoided if closed – [Visible if Access restricted by: schedule / condition / call of close() function] If this option is selected, the transporters will avoid the closed nodes.

On enter – Here you can place the code that will be executed when the agent enters the node.

On enter denied – Here you can place the code that will be executed when the agent tried to enter the node, was prohibited and put in the queue. This code will be executed only on the agent's first denial of entry. If the same agent tries to enter and is denied again, the code placed here won't be executed.

On exit – Here you can place the code that will be executed when the agent exits the node.

On open – [Cannot be applied if Access restricted by: condition] Here you can place the code that can be executed when the node is opened.

On close – [Cannot be applied if Access restricted by: condition] Here you can place the code that can be executed when the node is closed.

Appearance

Fill color – Shape's fill color. Choose No color, if you do not want shape to be filled.

Line color – Outline color. Choose No color, if you do not want outline to be drawn.

Line width – Outline width.

Line style – [Enabled only if the Show in: 3D only checkbox is not selected] Outline style. Choose from the drop-down list, whether you want solid, dashed, or dotted outline to be drawn.

Position and size

LevelLevel to which this element belongs.

X – X-coordinate of the area's start point.

Y – Y-coordinate of the area's start point.

Z – [Enabled if Show in: 3D only option is selected] Z-coordinate of the area, in meters. The value is relative to the Z-coordinate of the area's level.

Points

The table located in the Points property section enables users to view and adjust coordinates of the area points (corners).

Here you define relative coordinates, not the absolute ones. The first point always has coordinates (0,0) that can not be changed.
Other rows of the table define relative coordinates of the successive points. Coordinates of each point are actually offsets of the corresponding point from the start point along X and Y axes correspondingly.

Advanced

Show in - Here you can choose whether you want the shape to be shown both in 2D and 3D animation, or in 2D only, or in 3D only.

Show name – If selected, the shape's name is displayed on the graphical diagram.

Functions

You can dynamically modify shape properties at model runtime using the following API.
Speed and access restriction

Function

Description

restrictAccessByCapacity(int number)

Restricts access to the node by the specified capacity.

Note: This function can be used to change the number of agents dynamically, but cannot be used after initialization to change the type of restriction in the already existing node.

Parameter:
number - the maximum number of agents that can be inside the node before the access to the node is restricted

restrictAccessByThroughput(double throughput, RateUnits units)

Restricts access to the node by the specified throughput, i.e. the maximum permissible number of agents entering the node during 1 specified rate unit.

Note: This function can be used to change the number of agents dynamically, but cannot be used after initialization to change the type of restriction in the already existing node.

Parameters:
throughput - maximum permissible number of agents entering the node during 1 specified rate unit
units - a constant defining the rate units

restrictAccessBySchedule(Schedule<Boolean> schedule)

Restricts access to the node by the specified "on/off" schedule.

Note: This function can be used to change the schedule dynamically, but cannot be used after initialization to change the type of restriction in the already existing node.

Parameter:
schedule - the "on/off" schedule that controls access to the node. During the "on" periods, agents can enter the node, while during the "off" periods, the access to the node is closed.

restrictAccessManually(boolean initiallyClosed)

Enables manual control over access to the node.

Note: Don't use this function to open or close the access to the node dynamically after initialization. Use open()close(), or setOpen() functions instead.

Parameter:
initiallyClosed - if true, the access to the node is closed initially, if false - the node is open intially

boolean isAccessRestricted()

Returns true if the access to the node is restricted. Otherwise returns false.

void recalculateAccessibility()

Recalculates the accessibility of the node. This function can only be used if Access restricted by condition.

boolean isOpen()

Returns true if the node is open. Otherwise returns false.

This function cannot be used if Access restricted by: condition. In this case the area does not have an open / closed state and the function always returns true.

void open()

Lifts access restrictions from the node. This function can only be used if Access restricted by call of close() function or if the access to this node is controlled by the call of the restrictAccessManually() function.

void close()

Restricts access to the node. This function can only be used if Access restricted by call of close() function or if the access to this node is controlled by the call of the restrictAccessManually() function.

void setOpen(boolean open)

Controls the access to the node.

Parameter:
open - if true, the node is open to all agents; if false, the access to the node is restricted.

This function can only be used if Access restricted by: call of close() function or if the access to this node is controlled by the call of the restrictAccessManually() function.

AreaAccessRestrictionType getAccessRestrictionType()

Returns the access restriction type of the node. Valid values are:

  • AREA_ACCESS_RESTRICTION_BY_CAPACITY - access is restricted by specified capacity

  • AREA_ACCESS_RESTRICTION_BY_THROUGHPUT - access is restricted by specified throughput

  • AREA_ACCESS_RESTRICTION_BY_SCHEDULE - access is restricted by specified schedule

  • AREA_ACCESS_RESTRICTION_BY_CONDITION - access is restricted by specified condition

  • AREA_ACCESS_RESTRICTION_MANUAL - access is restricted by the call of close() function

boolean isAvoidedIfClosed()

Returns true, if the state of the node is taken into account at transporter route calculation. Otherwise, returns false.

void setAvoidedIfClosed(boolean avoided)

Determines whether the state of the node is taken into account at transporter route calculation.

Parameter:
avoided - if true, the transporters will avoid the closed node; if false - they won't.

Agent getRestrictedAgentClass()

Returns the type of agent whose speed and/or access is restricted for this node.

void setRestrictedAgentClass(Agent restrictedClass)

Sets the type of agent whose speed and/or access is restricted for this node.

Parameter:
restrictedClass - agent type

boolean isSpeedRestricted()

Checks whether this node has speed restriction enabled. If the function returns true, the speed is restricted. Otherwise, the function returns false.

double getMaxSpeed(SpeedUnits units)

Returns the maximum permissible speed in the node in specified speed units.

Parameter:
units - a constant defining the speed units

void restrictSpeed(double maxSpeed, SpeedUnits units)

Restricts the speed inside the node to the specified value maxSpeed in the specified speed units.

Parameter:
maxSpeed - maximum permissible speed value
units - a constant defining the speed units

int getCapacity()

Returns the maximum number of agents that can be inside the node before the access to the node is restricted.

double getThroughput(RateUnits units)

Returns the maximum permissible number of agents that can enter the node during 1 specified rate unit.

Parameter:
units - a constant defining the rate units

Schedule<Boolean> getSchedule()

Returns the "on/off" schedule that controls access to the node.

boolean accessRestrictionCondition(T agent)

Evaluates the access condition for the specified agent. If the evaluation returns true, access is restricted; otherwise, returns false.

Parameter:
agent - the agent for whom the access condition is evaluated


Agents

Function

Description

List<T> agents()

Returns the list of agents currently present inside the node.

List<T> getAgentsWaitingToEnter()

Returns the list of agents currently waiting at the border of the node with enabled restriction for permission to enter.

int getNumberOfAdmittedAgents()

Returns the number of agents admitted to the node with enabled restrictions.

List<T> getAdmittedTransporters()

Returns the list of transporters currently present inside the node with enabled restrictions. If the node doesn't have restrictions enabled, returns an empty list.

int getNumberOfTransporters()

Returns the number of transpoters currently present inside the node. Note that this function only works for nodes that are part of a network and for transporters with path-guided navigation.

int getNumberOfAdmittedTransporters()

Returns the number of transporters currently present inside the node with enabled restrictions. If the node doesn't have restrictions enabled, returns nothing.

boolean contains(Agent agent)

Returns true if the node contains the given agent. Otherwise returns false.

Parameter:
agent - the given agent

double density(AreaUnits units)

Returns the average density of agents inside the node measured in agents per given area units.

Parameter:
units - a constant defining the area units


Position

Function

Description

double getX()

Returns the X coordinate of the node's start point.

double getXMin()

Returns the minimum X coordinate of the node, i.e., the coordinate the upper left corner of its bounding rectangle.

double getXMax()

Returns the maximum X coordinate of the node, i.e., the coordinate the bottom right corner of its bounding rectangle.

double getY()

Returns the Y coordinate of the node's start point.

double getYMin()

Returns the minimum Y coordinate of the node, i.e., the coordinate the upper left corner of its bounding rectangle.

double getYMax()

Returns the maximum Y coordinate of the node, i.e., the coordinate the bottom right corner of its bounding rectangle.

double getZ()

Returns the Z coordinate of the node's start point.

double getZ(double x, double y)

Returns the Z coordinate of the given point.

Parameters:
x - the X coordinate of the point.
y - the Y coordinate of the point.

void setPos(double x, double y, double z)

Sets new coordinates for the node.

Parameters:
x - the new value of the X coordinate.
y - the new value of the Y coordinate.
z - the new value of the Z coordinate.


Level

Function

Description

Level getLevel()

Returns the level on which this node is located.


Points

Function

Description

int getNPoints()

Returns the number of points in the markup element.

double getPointDx(int i)

Returns the x coordinate of a particular point of the node relative to the start point.

Parameter:
i - the index of the point (starting from 0).

double getPointDy(int i)

Returns the y coordinate of a particular point of the node relative to the start point.

Parameter:
i - the index of the point (starting from 0).


Visibility

Function

Description

boolean isVisible()

Returns true if the node is visible; returns false otherwise.

void setVisible(boolean v)

Sets the visibility of the node.

Parameter:
v - visibility. If v is true - the node is set to be visible, if it is false - not visible.


Fill color

Function

Description

Color getFillColor()

Returns the fill color of the node, or null if the node has no fill color or has textured fill (in this case use getFillTexture() to get the node's texture).

Texture getFillTexture()

Returns the fill texture of the node or null if the node has no fill texture or has color fill (in this case use getFillColor() to get the node's fill color).

void setFillColor
(Color fillColor)

Sets the fill color of the node.

Parameter:
fillColor - the new fill color, if null, the node is not filled.

void setFillColor
(Paint fillColor)

Sets the fill color (or Texture) of the node.

Parameter:
fillColor - the new fill color, if null, the node is not filled.


Outline

Function

Description

Color getLineColor()

Returns the line color of the node, or null if node has no line color or has textured line (in this case use getLineTexture() to get the line's texture).

Texture getLineTexture()

Returns the outline texture of the node or null if node has no outline texture or has colored line (in this case use getLineColor() to get the line's color).

void setLineColor(Color lineColor)

Sets the line color of the node.

Parameter:
lineColor - the new line color, if null, the node line is not drawn.

void setLineColor(Object lineColor)

Sets the line color (or Texture) of the node.

Parameter:
lineColor - the new line color, if null, the node line is not drawn.

double getLineWidth()

Returns the width of the node outline.

void setLineWidth
(double width)

Sets the width of the node outline; 0 means the thinnest possible outline.

Parameter:
width - the new width of the node outline.

int getLineStyle()

Returns the style of the node outline:

LINE_STYLE_SOLID, LINE_STYLE_DOTTED or LINE_STYLE_DASHED

void setLineStyle
(int style)

Sets the style of the node outline:
LINE_STYLE_SOLID, LINE_STYLE_DOTTED or LINE_STYLE_DASHED

Line style not applied in 3D animation; the only supported line style in 3D is solid.

Parameter:
style - the new style of the node outline.


Attractors

Function

Description

List<Attractor> getAttractors()

Returns a collection of attractors inside the node.

void addAttractor
(Attractor attractor)

Adds an attractor to the node.

Parameter:
attractor - the attractor to be added inside the node.


Network

Function

Description

Network getNetwork()

Returns the network this markup element belongs to or null if this element is not a part of a network.

int getConnectionsCount()

Returns the number of the node's connections with other nodes.

Path getConnection(int index)

Returns the connection between this node and another node by the provided index.

Parameter:
index - the index of required connection in range (0, this.getConnectionsCount() - 1).


Advanced

Function

Description

boolean contains
(double px, double py)

Returns true if the node contains the point with the given coordinates; returns false otherwise.

Parameters:
px - the x coordinate of the point relative to this node's container.
py - the y coordinate of the point relative to this node's container.

double getNearestPoint
(double px, double py, Point output)

Calculates the point in this node nearest to the given (X, Y) point and writes the result into the the output object.

Returns the square of distance to the point (in the XY-projection). All calculations are performed in the horizontal projection (z-coordinates are not used, as if all of the Z coordinates were zero).

Parameters:
px - the X coordinate of the point.
py - the Y coordinate of the point.
output - the output point to write result to. Note that output.z is left unchanged.

double getNearestPoint
(double px, double py, double pz, Point output)

Calculates the point in this node nearest to the given (X, Y, Z) point and writes the result into the the output object.

Returns the square of distance to the point.

Parameters:
px - the X coordinate of the point.
py - the Y coordinate of the point.
pz - the Z coordinate of the point.
output - the output point to write result to. Note that output.z is left unchanged.


Removal

Function

Description

void remove()

Removes the node from the presentation. If the node is not a part of presentation, the function does nothing.
Note that 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.