GIS Route

With the help of the GIS route, you can draw routes on the map to define a road, a railroad, a river, or any other kind of line on the map. Each point of the route has the latitude and longitude coordinates, defined in degrees.

You can add GIS Route element only onto the GIS map. Add the GIS map shape to your model before you use GIS markup elements.

To add a route from one point to another

1. Pan and zoom the GIS map to display the area where you need the route to start.
2. Right-click 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 the map and select Route to here.
4. Two special marks will appear in these locations on the map, and GIS map will start searching for the route:
   

   

5. You will see the GIS Route object appear on the map:
   

   

6. If you are in some location on the map where the route ends, you are safe to use the Route to here option first and only then Route from here. The route will be built in the same manner as in the example above.
7. Its appearance and type depend on the settings defined in the Routing properties section. If you use a routing server or a routing graph to create routes, an existing route between these two points will be provided for you.
8. To create a route that starts or ends in a GIS point, right-click the point and select one of the options from its context menu. This will help you to create a network automatically.
   

   

9. After the route is created, you can edit it as any other manually drawn GIS route.

To draw a route manually

1. Double-click the GIS Route element in the GIS section of 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 route in the GIS map point by point.
3. Click in the map at the position of the first point of the route.
4. Subsequently click at other points where you want to place other salient points.
   

   

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

   

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

Properties

General

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

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

Visible - Here you specify route is visible on the animation at the model runtime, or not. Using the control, choose yes or no if you want to specify the visibility just once. Otherwise, if you expect visibility to change dynamically or to depend on some other conditions, you may specify here the expression defining the route's visibility. This expression will be dynamically reevaluated at the model runtime. It should return boolean value. The route is visible when the specified expression evaluates to true, and not visible otherwise.

Lock the position - If this option is selected, the shape's position on the map is fixed. The shape cannot be moved, but you can select it to change other properties.

Bidirectional - If this option is selected, the route is bidirectional. Deselect it, if you want the route to have one specific direction.

Appearance

Line color - The line color. Click the control and choose a color using the Colors dialog box. Choose No Color, if you do not want the line to be drawn.

Line width - Choose line width from the drop-down list, or enter the value in pixels in the field to the right. You can specify the dynamic expression, it should return int value.

Line style - The line style of the route. Choose from the drop-down list, whether you want solid, dashed, or dotted line to be drawn.

Editing route

You can edit a route appearance by editing its points. When you then edit the GIS map itself, for instance, if you pan the map or zoom it in or out, the route's points will remain in their positions defined by longitude and latitude.

To move a point of a route

1. Select the route on the map.
2. Drag the route's 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 of a route

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

Functions

You can dynamically modify the GIS route's properties 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 (true by default). Returns: true for routes which allow movements in both directions, false for routes which allow movements from source to target only.
void setBidirectional(boolean bidirectional)	Sets the 'bidirectional' property value (true by default). Parameter: bidirectional - true for routes which allow movements in both directions, false for routes which 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. Parameter: 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. Parameters: lat - the latitude coordinate of the point. lon - the longitude coordinate of the point. Returns: true if the shape contains the point with the given coordinates.
boolean contains(double lat, double lon, double distance)	Checks if the shape contains the point with the given coordinates using the given tolerance. Parameters: 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. Returns: true if the shape contains the point with the given coordinates.
boolean containsSq(double lat, double lon, double squareDistance)	Checks if the shape contains the point with the given coordinates using the given tolerance. Parameters: 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. Returns: true if the shape contains the point with the given coordinates.
Point randomPointInside(Random rng, Point out)	Returns a randomly chosen point inside/along the given space markup element. This method utilises the given Random Number Generator. Parameters: rng - the random number generator. out - 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. Parameters: lat - the latitude of the point. lon - the longitude of the point. out - the output point to write result to. Returns: the square of distance to the nearest point.
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. Parameters: givenPoint - the point distance to which you need to calculate. out - the output point to write result to. Returns: the square of distance to the nearest point.
Position getPositionAtOffset(double offset, Position out)	Returns the position located on the markup element with the given offset distance calculated from start point. Parameters: offset - offset, non-negative value, should be less or equal to the full length. out - output object to write to, may be null. Returns: the Position object with coordinates of the point with the given offset and orientation along markup element line at this point.
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. Parameters: offset - offset, non-negative value, should be less or equal to the full length. units - the length units. out - output object to write to, may be null. Returns: the Position object with coordinates of the point with the given offset and orientation along markup element line at this point.

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. Parameter: 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. Parameter: 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. Note that this function does not check whether the provided GIS node is the source or the target. Parameter: n - the node (one of the route endings). Returns: the node of the opposite end of this route.
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 the segment by its index. Parameter: 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. Parameter: lineColor - the new line color, null - do not draw the markup element line.
LineStyle getLineStyle()	Returns the line style of the markup element. Possible values: LINE_STYLE_SOLID, LINE_STYLE_DOTTED or LINE_STYLE_DASHED
void setLineStyle(LineStyle lineStyle)	Sets the line style of the markup element. Possible values: LINE_STYLE_SOLID, LINE_STYLE_DOTTED or LINE_STYLE_DASHED Parameter: 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: Parameter: 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 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.

Related topics

Defining routes in GIS map

GIS map