Road

Road is a graphical space markup element that represents a continuous road (that is, the one that does not contain any intersections). Roads, intersections, and other space markup elements are used to draw road networks for Road Traffic Library models.

The road can contain multiple linear or curved segments. For example, the road in the figure above has two linear segments and one curved segment in the middle.

Some of the road attributes, such as the traffic direction (right-hand or left-hand), lane width, road surface color, and so on, are not configured in the road properties, but in the properties of the road network to which this road belongs. The road network is created automatically when you draw a single road and can be extended according to your modeling needs.

The road can have an arbitrary number of lanes. The road can be one-way (all cars move in one direction) or two-way (the road has a number of forward lanes and a number of backward lanes). The road in the figure above has two forward lanes (the arrow on the road shows the forward direction) and two backward lanes (the ones at the top, cars move there from right to left). The Road Traffic Library does not support lanes where cars can move in both directions.

A road has a constant number of lanes along its entire length. To model a lane merge, connect two roads with different numbers of lanes.

The road can have sloping segments, you can adjust the road shape by changing the Z coordinates of the road segment ends in the road’s Points properties section.

The road is aware of all cars that are on it (fully or partially), and you can obtain those cars using the road API.

Let us demonstrate how to draw a road using the example of Broadway near Madison Square Park and the Flatiron Building:

If you want to follow this short tutorial, use this image in your model (save the image to your computer by right-clicking the image above and selecting Save Image As from the context menu).

To draw a road

1. Before modifying the shape, if you need to adjust it with more precision, you can turn grid alignment off by selecting Scale > Snap to grid on the toolbar.
2. Click the  Road element in the Space Markup section of  Road Traffic Library palette.
   The drawing mode is activated. You can now draw the pathway in the graphical editor point by point.
3. Click in the graphical editor to draw the first point of the road.

   

4. Continue to draw the road segment by segment. Our road begins with a linear segment. To draw a linear segment, click where you want the endpoint of the segment to be (see the figure below).

   

5. The next segment of our road is curved. To draw a curved segment, click the left mouse button at the next turning point of the road (at the beginning of the next linear segment) and move the mouse with the left mouse button pressed until you get the segment with the desired shape. Release the mouse button when you have finished adjusting the shape of the road segment.

   

6. Finally, double-click to set the last point of the road.

   

7. You will need to adjust the scale of the layout to the scale typically used in the road traffic models. Drag the canvas down to see the automatically created Scale element above the X axis, and adjust the model scale in its properties. Set the Length (in pixels) to 40: this will scale the actual length to 4 pixels per meter. This will automatically attune the width of your road, setting it to something similar to the one in the figure below:

   

8. Customize the road attributes in the Properties view. By default, roads are drawn as two-way, with two lanes for cars moving in one direction (forward lanes), and two lanes for cars moving in the opposite direction (backward lanes). Broadway is a one-way road with two lanes, that is why you should select the One way option. The number of lanes will automatically decrease to 2. As a result, the road may shift a bit and you may need to adjust the road position.
   The arrow on the road indicates the direction of the car movement.
   As you can see, the road is drawn opaque. Let’s make the road semi-transparent to see if the resulting road matches the road on the map perfectly. The transparency setting (as well as traffic direction and lane width) is not defined in the road properties, but in the properties of the road network to which this road belongs.
9. Right-click the road and select the Select network option from the context menu.
10. In the Appearance section of the network properties, click in the Road color edit box. The rightmost box visible at the top of the of the subsequent dialog allows you to change the transparency level; set it to 150. You can also use the slider below for the same purpose.

    

11. If necessary, you can make some additional adjustments: move the points to better fit the layout image, or enable the guiding lines to change the curvature of the road (the Show guiding lines option of the context menu).
    You can also adjust the width of the road in the properties of the Scale element mentioned above (the Length (in pixels) property). The width of the road changes according to the changes you make.
12. In the example below, the Length (in pixels) property is set to 25. This will result in a road that looks like the one shown in the image below:

    

Further road network creation (adding intersections, drawing other roads) is described in Intersection.

General

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

Show name — If selected, the shape name is displayed in the graphical editor.

Lock — If selected, the road is locked. Locked elements do not respond to mouse clicks, and they cannot be selected in the graphical editor until you unlock them. This is often needed when you want to prevent the element from being edited while other elements are placed over it.

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

One way — If selected, the road is one-way. Otherwise, it contains separate lanes for forward and backward traffic.

Number of forward lanes — Specifies the number of lanes with forward traffic.

Number of backward lanes — [Visible and applies only if the One way option is disabled] Specifies the number of lanes in which the traffic moves backwards.

Median strip width — [Visible and applies only if the One way option is disabled] Defines the width of the median that separates the lanes of oncoming traffic.

Median strip color — [Visible and applies only if the One way option is disabled] Defines the color of the median that separates the lanes with oncoming traffic.

Position and size

X — The X-coordinate of the road’s starting point.

Y — The Y-coordinate of the road’s starting point.

Z — The Z-coordinate of the road’s starting point.

Points

The table located in the Points property section enables users to view and adjust coordinates of the road points.

The table defines relative coordinates, not absolute coordinates. The first point always has coordinates (0,0,0) that cannot be changed.

Other rows of the table define relative coordinates of the successive points. The coordinates of each point are actually offsets of the corresponding point from the start point along the X and Y axes, respectively.

Visibility and presentation

Visible — If selected, the road is visible during animation at model runtime.

Show in — Select whether the shape is displayed in both 2D and 3D animation, 2D only, or 3D only.

Agent presentation — If selected, the road is also visible on the upper-level agent that hosts the agent containing this road.

You can change the linear shape of any road segment to curved and vice versa, and you can edit the curved shape at any time.

To make a road segment linear or curved

1. Right-click the road segment in the graphical editor and select Make segment line or Make segment curve from the context menu.

If the shape of the curved segment does not match the shape of the actual road, you can change the shape of the segment with the guiding lines.

To change the shape of the curved road segment

1. Right-click the road and select Show guiding lines from the context menu. The guiding lines for editing points appear.
2. You will see multiple handles. The round markers show the endpoints of the segment, and the straight lines with the diamond handles at their ends are the guiding lines. Each endpoint of the segment has its own guiding line. The guiding lines will appear for each editing point of the road’s curve.

   

3. Drag the handle of the guiding line with the mouse. You will see that the shape of the corresponding curved segment changes as you drag the mouse. Release the mouse button when you have finished adjusting the shape of the road segment. You may also need to adjust the length or position of the other guiding line of this segment.
4. To exit the editing mode, right-click the road and select Hide guiding lines from the context menu.

To add a segment to a road

1. Right-click the road and select Append from the context menu.
2. Select the side of the street from which you want to append the line. Click the appropriate endpoint of the road.
3. You are in the drawing mode now. You can add as many new segments as you need, both linear and curved.
4. Finish drawing by double-clicking where you want to place the new endpoint of the road.

The arrow drawn on the road in the graphical editor indicates the direction of forward movement.

To change the direction of the road

1. Right-click the road in the graphical diagram and select Change direction from the context menu. The arrow drawn on the road will change direction.

Cars

Function	Description
int nCars(boolean isOnForwardSide)	Returns the number of cars located in forward or backward lanes of the road depending on the argument value. isOnForwardSide — pass true to return the number of cars located in road’s forward lanes, false to count cars located in backward lanes.
int nCarsOnLane(boolean isOnForwardSide, int laneIndex)	Returns the number of cars located in the specified lane. isOnForwardSide — pass true to return the number of cars located in road’s forward lane, false to count cars located in a backward lane. laneIndex — the zero-based index of the lane. Lanes are numbered from the outermost (index: 0) to the innermost.
List<Agent> getCars(boolean isOnForwardSide)	Returns the ordered list of cars located in the forward or backward lanes of the road depending on the argument value. The first car in the list is the nearest one to the exit point from road (seems like the first one to exit the road, if there is no acceleration). isOnForwardSide — pass true to return cars located on the road’s forward lanes, false to return cars in backward lanes.

Speed

Function	Description
double averageSpeed(boolean isOnForwardSide, double offset)	Returns the average speed in the forward or backward lanes of the road (depending on the argument value) in the road segment at the specified offset. isOnForwardSide — pass true to return the speed in forward lanes, false to return the speed in backward lanes offset — the offset from the start of the corresponding lane
double averageSpeed(boolean isOnForwardSide, double offset, SpeedUnits units)	Returns the average speed (in the given speed units) in forward or backward lanes of the road (depending on the argument value) in the road segment near the specified offset. isOnForwardSide — pass true to return speed in forward lanes, false to return speed in backward lanes offset — the offset from the start of the corresponding lane units — a speed units constant

Lanes

Function	Description
int getForwardLanesCount()	Returns the number of forward lanes.
getBackwardLanesCount()	Returns the number of backward lanes.
void setForwardLanesCount(int forwardLanesCount)	Sets the number of forward lanes. forwardLanesCount — a new number of forward lanes
void setBackwardLanesCount(int backwardLanesCount)	Sets the number of backward lanes. backwardLanesCount — a new number of backward lanes

Median strip

Function	Description
double getMedianStripWidth()	Returns the median strip width in pixels.
double getMedianStripWidth(LengthUnits units)	Returns the median strip width measured in the given length units. units — a length unit constant
void setMedianStripWidth(double medianStripWidthInPixels)	Sets the median strip width in pixels. medianStripWidthInPixels — the specified median strip width in pixels
void setMedianStripWidth(double medianStripWidth, LengthUnits units)	Sets the median strip width measured in the given units. medianStripWidth — a new median strip width units — a length unit constant
void setMedianStripColor(Color color)	Sets the color of the median strip. color — the new color, if null the median strip is not drawn
void setMedianStripColor(Paint color)	Sets the color (or texture) of the median strip. color — the new texture, if null the median strip is not drawn
Color getMedianStripColor()	Returns the color of the median strip, or null if the median strip has no color or has a texture (in this case getMedianStripTexture() should be used instead).
Texture getMedianStripTexture()	Returns the texture of the median strip, if the median strip has a texture.

Level

Function	Description
Level getLevel()	Returns the level on which this road is located.

Visibility

Function	Description
void setVisible(boolean v)	Sets the visibility of the road. v — the visibility of the road. If true, road is visible, if false — not visible.
boolean isVisible()	Returns the visibility of the road. If it returns true, the road is visible, if false — not visible.

Advanced

Function	Description
RoadNetwork getRoadNetwork()	Returns the road network to which the road belongs.
List<StopLine> getStopLines()	Returns all stop lines belonging to this road.
List<ParkingLot> getParkingLots()	Returns all parking lots adjacent to this road.
List<BusStop> getBusStops()	Returns all bus stops adjacent to this road.
MarkupSegment getSegment(int index)	Returns the segment by its index. index — the segment index, [0 .. getSegmentCount() - 1]
int getSegmentCount()	Returns the number of segments.
double getWidth()	Returns the total width of the road segment in pixels. The total width consists of the width of all forward lanes, the width of all backward lanes, and the width of median strip.
double getWidth(LengthUnits units)	Returns the total width of road segment in the given units. he total width consists of the width of all forward lanes, the width of all backward lanes, and the width of median strip. units — a length unit constant

Removal

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

How can we improve this article?

Send