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 GIS map shape first 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 in a second:

  6. If you are in some location on the map where the route ends, you are safe to use the option Route to here 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 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 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 the exact positions, defined in 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 new editing point to a route

  1. Select the route on the map.
  2. Double-click a segment of the route, where you want to add new editing 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 route's properties at model runtime using the following API. 

General

Function

Description

double length()

Returns the length of markup element, used e.g. for desired velocity calculation

Returns:
the length of markup element (measured in meters)

double length(LengthUnits units)

Returns the length of markup element, used e.g. for desired velocity calculation

Returns:
the length of markup element in the specified units

boolean isBidirectional()

Returns the 'bidirectional' property (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 (true by default).

Parameters:
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.

Parameters:
v - visibility: true - visible, false - not

boolean isVisible()

Returns the visibility of the markup element.

Returns:
visibility: true - visible, false - not

INetwork getNetwork()

Returns the network this markup element belongs to or null if this element isn't 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.

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 on the markup element line or not

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 on the markup element line or not

Returns:
true if the shape contains the point with the given coordinates

Point randomPointInside(Random rng, Point out)

Returns the 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)

Returns the nearest point.

Parameters:
lat -  the latitude of the point
lon - the longitude of the point
out - the output point to write result to

Returns:
distance, in meters

double getNearestPoint(Point givenPoint, Point out)

Calculates (using the output 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 getPosition(double value, double maxValue, Position out)

Returns position with offset corresponding to the given value, assuming that 0 is start and maxValue is end.

Returns:
position by offset

Position getPositionAtOffset(double offset, Position out)

Returns the point (+rotations) 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 point (+rotations) 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 start point

void setSource(GISNode node)

Sets the start node of the route.

Parameter:
node - GIS point or region

GISNode getTarget()

Returns the location of the end point

void setTarget(GISNode node)

Sets the end node of the route.

Parameter:
node - GIS point or region

Point getStartPoint()

Returns the location of the start point

Returns:
the Point object with coordinates of the first point

Point getStartPoint(Point out)

Returns the location of the start point.

Parameters:
out - output object to write to, may be null

Returns:
the Point object with coordinates of the first point

Point getEndPoint()

Returns the location of the end point.

Returns:
the Point object with coordinates of the last point

Point getEndPoint(Point out)

Returns the location of the end point.

Parameters:
out - output object to write to, may be null

Returns:
the Point object with coordinates of the last point

GISNode getOtherNode(GISNode n)

If the given node is source of this route, returns route's target, otherwise returns source. Note that this function doesn't check that the given is either source or target: this is the responsibility of user calling this function. 

Parameters:
n - the node (one of the route endings)

Returns:
the node of the other end of this route

Position getStartPosition(Position position)

Returns the start position.

Returns:
the Position object with coordinates of the first position

Position getEndPosition(Position position)

Returns the end position

Returns:
the Position object with coordinates of the last position

Route's segments

Function

Description

void addSegment(GISMarkupSegment segment)

Adds segment to this markup element

Parameter:
segment - the segment, should be initialized if was created using no-argument constructor

GISMarkupSegment getSegment(int index)

Returns the segment by its index

Parameter:
index - the segment index, [0 .. IPath.getSegmentCount() - 1]

int getSegmentCount()

Returns the number of segments.

GISMarkupSegment getSegment(int index)

Returns the segment by its index

Parameter:
index - the segment index

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: 
{LINE_STYLE_SOLID, LINE_STYLE_DOTTED or LINE_STYLE_DASHED}

void setLineStyle(LineStyle lineStyle)

Sets the line style of the markup element:
{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.


Related topics

Defining routes in GIS map

 GIS Map generalization