GIS route

With the  GIS Route element, you can draw any custom routes to define roads, railroads, rivers, or any other kind of trajectories on the map.

A GIS Route element can be added to a GIS map only. You need to add a  GIS Map to your model before you add any GIS markup.

To add a route

1. Pan and zoom the GIS map to display the area where you need the route to start.
2. Right-click a point on the map and select  Route from here from the context menu.

   

3. Pan the map to the location where the route should end, then right-click a point on the map and select  Route to here.
4. These locations on the map will be marked, and the GIS map will start searching for a route.
5. You will see the GIS Route element appear on the map.

   

6. To create a route that starts or ends at an existing GIS point, right-click the point and select  Route from here or  Route to here respectively from its context menu. When you create two or more routes this way, a network is created automatically.

   

7. If you are at a location on the map where a route ends, you can use  Route from here safely. The route will be built in the same manner as in the example above.
8. The routing settings can be defined in the Routes section of the  GIS map properties. If you use a routing server or a routing graph, an existing route between the two points will be provided.
9. The appearance of the route line can be defined in the Appearance properties section of the GIS Route element.
10. Now the route is created and you can edit it.

To draw a route manually

1. Click the  GIS Route element in the GIS section of the  Space Markup palette. The cursor should turn into . This means that the drawing mode is activated and you can now draw a route in the GIS map point by point.
2. Click the map at the location of the first point of the route.
3. Click other locations where you want to place additional points.

   

4. Double-click to place the end point and finish drawing.

   

5. After you finish drawing, you can edit the route.

General

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

Lock — If selected, the element is unresponsive: it will ignore mouse actions at model design time. To select the element, click its icon in the elements view.

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

Fixed position — If selected, repositioning by dragging is disabled. The shape cannot be moved, but you can select it to change other properties.

Appearance

To select a permanent color or no color, use the color picker. To make the color, line width or line style change dynamically, switch the respective field to the dynamic value editor and specify the expression to be re-evaluated.

Line color — The GIS route line color.

Line width — Line width. To define it, use the buttons, define a value or enter a dynamic expression.

Line style — Line style: solid, dashed, or dotted. To define it, use the buttons or insert a dynamic value.

Visibility and presentation

Visible — If selected, the shape is visible in the presentation at model runtime. Can be set to a dynamic expression that makes the route visible when evaluated to true.

You can edit a route by dragging its points. When you edit the GIS map itself, the points remain at their coordinates.

To move a point on a route

1. Select the route on the map.
2. Drag the necessary point.

To add a new point to a route

1. Select the route on the map.
2. Double-click a segment of the route where you want to add a new point.

To remove a point from a route

1. Select the route on the map.
2. Double-click the point you want to remove.

You can dynamically modify the properties of a GIS route at model runtime using the following API.

General

Function	Description
double length()	Returns the length of the GIS route (in meters), used e.g. for desired speed calculation.
double length(LengthUnits units)	Returns the length of the GIS route (in specified units), used e.g. for desired speed calculation.
boolean isBidirectional()	Returns the 'bidirectional' property value. For routes created in the graphical editor, the property value is true by default. For routes created programmatically, the value of the property depends on the value specified initially. Check the description of the method you’ve used for more details. Returns true for routes which allow movements in both directions, false for routes that allow movements from source to target only.
void setBidirectional(boolean bidirectional)	Sets the 'bidirectional' property value. For routes created in the graphical editor, the property value is true by default. For routes created programmatically, the value of the property depends on the value specified initially. Check the description of the method you’ve used for more details. bidirectional — true for routes that allow movements in both directions, false for routes that allow movements from source to target only.
void setOwner(ShapeGISMap map)	Sets the GIS map this route belongs to.
void setVisible(boolean v)	Sets the visibility of the markup element. v — visibility: true — visible, false — not.
boolean isVisible()	Returns true if the element is currently visible; returns false otherwise.
INetwork getNetwork()	Returns the network this markup element belongs to or null if this element is not a part of a network.
boolean contains(double lat, double lon)	Checks if the shape contains the point with the given coordinates. Returns true if the shape contains the point with the given coordinates. lat — the latitude coordinate of the point. lon — the longitude coordinate of the point.
boolean contains(double lat, double lon, double distance)	Checks if the shape contains the point with the given coordinates using the given tolerance. Returns true if the shape contains the point with the given coordinates. lat — the latitude coordinate of the point. lon — the longitude coordinate of the point. distance — the distance tolerance to determine whether the given point lies within the markup element line proximity.
boolean containsSq(double lat, double lon, double squareDistance)	Checks if the shape contains the point with the given coordinates using the given tolerance. Returns true if the shape contains the point with the given coordinates. lat — the latitude coordinate of the point. lon — the longitude coordinate of the point. squareDistance — the square of distance tolerance to determine whether the given point lies within the markup element line proximity.
Point randomPointInside(Random rng, Point out)	Returns a randomly chosen point inside/along the given space markup element. This method utilizes the given Random Number Generator. rng — the random number generator. out — the output object to write to, may be null.

Distance

Function	Description
double getNearestPoint(double lat, double lon, Point out)	Calculates (using the out object) the point in this space markup element nearest to the point with the given latitude and longitude. Returns the square of distance to the point. lat — the latitude of the point. lon — the longitude of the point. out — the output point to write result to.
double getNearestPoint(Point givenPoint, Point out)	Calculates (using the out object) the point in this space markup element nearest to the given point. Returns the square of distance to the point. givenPoint — the point distance to which you need to calculate. out — the output point to write result to.
Position getPositionAtOffset(double offset, Position out)	Returns the position located on the markup element with the given offset distance calculated from start point. offset — offset, non-negative value, should be less or equal to the full length. out — output object to write to, may be null.
Position getPositionAtOffset(double offset, LengthUnits units, Position out)	Returns the position located on the markup element with the given offset distance calculated from start point. offset — offset, non-negative value, should be less or equal to the full length. units — the length units. out — the output object to write to, may be null.

Start and end points

Function	Description
GISNode getSource()	Returns the location of the route’s source node.
GISNode getTarget()	Returns the location of the route’s target node.
Point getStartPoint()	Returns the Point object with the coordinates of the starting point.
Point getStartPoint(Point out)	Returns the Point object with the coordinates of the starting point. out — output object to write to, may be null.
Point getEndPoint()	Returns the Point object with coordinates of the end point.
Point getEndPoint(Point out)	Returns the Point object with coordinates of the end point. out — output object to write to, may be null.
GISNode getOtherNode(GISNode n)	If the given node is the source of this route, returns the route’s target node. Otherwise, returns the source node. This function does not check whether the provided GIS node is the source or the target. n — the node (one of the route endings).
Position getStartPosition(Position position)	Returns the Position object with the coordinates of the route’s starting position.
Position getEndPosition(Position position)	Returns the Position object with coordinates of the route’s ending position.

Route’s segments

Function	Description
int getSegmentCount()	Returns the number of segments.
GISMarkupSegment getSegment(int index)	Returns a segment by its index. index — the segment index, [0 .. IPath.getSegmentCount() - 1]

Appearance

Function	Description
Color getLineColor()	Returns the line color of the markup element, or null if markup element has no line color or has textured line (in this case, getLineTexture() should be used instead).
void setLineColor(Paint lineColor)	Sets the line color (or Texture) of the markup element. lineColor — the new line color, null — do not draw the markup element line.
LineStyle getLineStyle	Returns the line style of the markup element. Valid values: LINE_STYLE_SOLID LINE_STYLE_DOTTED LINE_STYLE_DASHED
void setLineStyle(LineStyle lineStyle)	Sets the line style of the markup element. Valid values: LINE_STYLE_SOLID LINE_STYLE_DOTTED LINE_STYLE_DASHED lineStyle — the new style of the markup element.
double getLineWidth()	Returns the line width of the markup element.
void setLineWidth(double width)	Sets the line width of the markup element: width — the width of the markup element line, in pixels.
Texture getLineTexture()	Returns the line texture of the markup element, if the markup element has line texture.

Removal

Function	Description
void remove()	Removes the GIS route from the presentation. If the GIS route is not a part of the 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?

Send