GIS map

The GIS Map shape (found on the Space Markup palette) enables you to display and manage GIS (Geographic Information System) maps in a model. The GIS Map shape accommodates two GIS map types:

Tiled map:  A map that is downloaded in real time from special online map services, such as OpenStreetMap. Such maps are called “tiled maps” because they are downloaded as tiles, which are small, usually square, images that are placed seamlessly side-by-side to construct the maps.

Shapefile map:  A GIS map that is based on data in a set of files that is called a “shapefile” (a shapefile consists of at least three files, with suffixes “.shp”, “.shx”, and “.dbf”). A shapefile contains data about the points, lines, and polygons that make up a GIS map.

With the GIS Map shape you can display layers of both map types, superimposed one over another. On a map you can also add points, routes, and regions. 

The GIS Map shape uses the Mercator projection, which is a cylindrical map projection. It distorts the size and shape of large objects, as the scale increases from the Equator to the poles, where it becomes infinite.

If you are connected to the Internet, when you add a GIS Map shape to an agent’s canvas the tiles of a default tiled map start to load automatically so that you can start using a map right away. 

You can add only one GIS Map shape to an agent's canvas. When you add a GIS map shape, the space type for all agents that will live in this environment becomes GIS space

 To add a GIS map
  1. Drag the  GIS Map element from the GIS section of the  Space Markup palette into the graphical editor. 

  2. You can then edit the GIS Map shape. For example, it is common to fill the entire agent's presentation window with the map and to disable run-time panning of this window.
  3. Next, you might need to edit a map inside the shape. For example, in order to choose the area of the map to be displayed in the presentation window, you might navigate through the map, pan it, or zoom it. 
  4. Then you can search for locations on the map to add to your model. 
  5. Next, you may add GIS markup objects to a map, by locating them on the map using the GIS Search Results view or by adding them from the Space Markup palette.
  6. Using GIS markup objects or special code, you can then place the agents on a map
  7. Using supported online map services, or an “osm.” file, you can also add routes to a GIS map.

Properties

General

Name – The name of the GIS map shape. The name is used to identify the shape and access it from code.

Ignore – If selected, the GIS map is excluded from the model.

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

Lock – If selected, the 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. 

Visible – If selected, the shape is visible as part of the agent's presentation at model runtime.

Tiles

Show tiles – The option Show tiles is selected by default, so that you can use a GIS map as soon as you add the GIS map shape to the agent's diagram. Deselect it if you do not want the tile layer to be visible.

Tile provider – Here is a list of supported online tile map services: AnyLogic, OSM (OpenStreetMap) classic, OSM german, LandSat, or Cycle map. Select the one you would like to use. Once you choose a new online map service from the list, the GIS Map shape will start to display new tiles.

Note that you can also use a custom tile provider by specifiying its URL in the Use custom tile URL field in the Advanced properties section. If a custom tile provider is used, selecting tile providers from the Tile provider list is disabled.

Routing

Routes are – Here you can choose the way the routes in the GIS map are created. You can choose the routes to be requested from OSM server (then you can choose the routing server), or use the option Loaded from PBF file to create a routing graph from a file on your hard drive. If you select the Straight lines option, the routes will be drawn as simple straight lines on the GIS map.

Routing server – [Available if Routes are requested from OSM server] There are three routing servers available: AnyLogic (recommended), YOURS and BRouter.

Routing method – [Available if Routes are requested from OSM server: YOURS or loaded from PBF file] Choose here, if you want agents to take Shortest or Fastest routes in the network.

Road type – [Available if Routes are requested from OSM server] Choose here the road network type: Road, Rail, Bike, or Foot.

Pathfinding algorithm – [Available if Routes are loaded from PBF file] Choose the pathfinding algorithm: A*, bidirectional A*, Dijkstra, Dijkstra bidirectional, Dijkstra native bidirectional.

Specify routing graph – [Available if Routes are loaded from PBF file] Click this button to open the routing graph wizard where you can create a new graph or select to use an existing one. The supported file types are .pbf and .osm

If route not found – Here you indicate what you want AnyLogic to do if a route cannot be created (typically because the route does not exist). If you want AnyLogic to approximate a route with a straight line and continue running the model, select the option Create straight route. If you want AnyLogic to notify you about such a problem and stop, choose Show error dialog.

Search

Here you choose whether the search of locations at model startup will be performed within the area visible when launching the model (default option) or within the custom user-defined area. 

Custom search bounds - allows to set the currently visible GIS area as the custom search area. If set, you will be able to launch the model with any other area visible. If a specified agent location cannot be found within the custom search bounds, the closest location with the same name outside this area will be chosen.

Don't use custom search bounds - removes the coordinates of the custom defined area, allowing to perform search within the GIS area visible at when launching the model.

Shapefiles

Here you specify shapefile(s) to be shown by this GIS map. To add a shapefile, use the  button. You will see a dialog box prompting you to choose a shapefile. Having selected the file, you will see the GIS map displaying the data from the selected shapefile.

In the Shapefiles properties section, you will see a set of properties of this shapefile:

Visible - Using this checkbox, you can show / hide the shapefile data on the GIS map.

Shapefile, Dbf - read-only fields displaying the shapefile names.

Name column index - Here you specify the name of the shapefile's column that contains the shapefile element names. It is very important to find out the name of this column in the shapefile and specify it here if you want to convert your GIS shapefile to rail network, or to road space markup shapes. In this case space markup elements created on the conversion will have meaningful names (and will not be randomly named like road145, road146).

Default line color, Default fill color - You can customize the shapefile's line color and fill color.
To remove a shapefile, select its section, then click the  button.

Center and scale
You can also pan and zoom the map using map edit mode.

Latitude, deg – The latitude of the map's center, measured in degrees (-90 ... )

Longitude, deg – The longitude of the map's center, measured in degrees (-180 ... )

Scale     1: – Scale of the map projection, 1:<specified value>, e.g. 1:10000.

Appearance

Border color – Color of the shape's border.

Fill color – Fill color of the GIS map. You will not see this color if the option Show tiles is selected.

Position and size

X – X-coordinate of the upper left corner of the GIS map shape.

Y – Y-coordinate of the upper left corner of the GIS map shape.

Width – The width of the GIS map shape, in pixels.

Height – The height of the GIS map shape, in pixels.

Advanced

On click – Code that will be called each time the user clicks on the GIS map at runtime.

Use custom tile URL  If you want to use a custom online tile map service, select this option and provide the URL of the service in the text field below. The URL must end with the [x]/[y]/[zoom].png placeholder, which handles requesting the tile with the appropriate x and y coordinates and zoom level from the tile server, e.g.: http://a.tile.openstreetmap.org/[zoom]/[x]/[y].png. Note that if a custom tile provider is used, selecting tile providers manually from the Tile provider list is disabled. For details on the custom tile URL scheme, see the OpenStreetMap wiki page.

Use custom route provider – If you want to use a custom online route service, click here and the edit box labeled Custom route provider will appear. In this box, AnyLogic has provided sample code with comments.

Routes and regions generalization uses – Here you can define the generalization (that is, the degree of simplification) for routes and regions when you run the model, i.e. how many points they should contain when displayed. Depending on your needs, choose either Current map scale or define the Absolute precision in meters.

 To enter and exit the map edit mode

  1. Double-click a map to enter its edit mode, or right-click a map and select Edit map from the context menu. The rest of the graphical editor will then be grayed out.
  1. To choose the area of the map you want to use for the model, pan the map or zoom in and out.

  2. To exit the edit mode click the grayed out area of the graphical editor, or double-click the map. Alternatively, right-click the map and select Finish Map Editing from the menu.

You can edit the properties of a multiple selection of markup objects, for example, change their appearance or lock their positions on the map.

To select several objects on the map

  1. Hold down the Ctrl key and click the markup objects on the map one by one to select or deselect objects. 
  2. Also, in order to select several objects while editing the map, you can hold down the Ctrl or Shift key and drag the selection rectangle around the objects.

When you are in the map edit mode, the AnyLogic status bar displays the latitude and longitude coordinates of the current mouse cursor position:

The GIS map tiles and routes are cached when you run the model and request the data, and the model performance may depend on your Internet connection. You can check the network access indicator in the status bar of the presentation window that shows that data is currently being requested:

If you do not want to use a tiled map, or do not have Internet access, you can add a shapefile map from a shapefile. In this case you need to add a file manually to the shapefile table in the Shape files section.

 To load a GIS map from a shape file

  1. Go to the Shapefiles section of the map's Properties view. 
  2. Add a shapefile (with file extension “.shp”) by clicking the  button. This opens the Open dialog box. Browse to the file you want to add, then select it and click Open. The files for the shapefile will be copied to the model folder.

Functions

Using functions, you can access and manipulate many map characteristics.
Map center

Function

Description

double getCenterLatitude()

[Not supported by AnyLogic Cloud] Returns the latitude of the map projection center, measured in degrees (-90 ... (South) ... 0 ... (North) ... +90) 

double getCenterLongitude()

[Not supported by AnyLogic Cloud] Returns the longitude of the map projection center, measured in degrees (-180 ... (West) ... 0 ... (East) ... +180)

void setCenterLatitude(double centerLatitude)

Sets the latitude of the map projection center.

Parameter:
centerLatitude - new latitude of the map projection center, measured in degrees (-90 ... (South) ... 0 ... (North) ... +90)

void setCenterLongitude(double centerLongitude)

Sets the longitude of the map projection center.

Parameter:
centerLongitude - new longitude of the map projection center, measured in degrees (-180 ... (West) ... 0 ... (East) ... +180)

void setProjectionCenter
(double centerLongitude,

double centerLatitude)

Sets the center of the map projection.

Parameters:
centerLongitude - new longitude of the map projection center, measured in degrees (-180 ... (West) ... 0 ... (East) ... +180)
centerLatitude - new latitude of the map projection center, measured in degrees (-90 ... (South) ... 0 ... (North) ... +90)


Map scale

Function

Description

double getMapScale()

Returns the scale of map projection (ratio between meters on the screen and meters on the Earth surface), e.g. 1/100000 means "1 km in 1 cm".

double getMinMapScale()

Returns the minimum available scale of the map projection (ratio between meters on the screen and meters on the Earth surface), e.g. 1/100000 means "1 km in 1 cm".

double getMaxMapScale()

Returns the maximum available scale of the map projection (ratio between meters on the screen and meters on the Earth surface), e.g. 1/100000 means "1 km in 1 cm".

void setMapScale(double mapScale)

Sets the scale of map projection

Parameter:
mapScale - the scale (ratio between meters on the screen and meters on the Earth surface), e.g. 1/100000 means "1 km in 1 cm"

void pan(int toEast,
int toNorth)

Moves the map projection center. Parameters are amounts of delta in the resulting offset. One horizontal delta is a half of longitude difference from map projection center to the west/east bound of projection.One vertical delta is a half of latitude difference from map projection center to the south/north bound of projection.

Parameters:
toEast - number of horizontal deltas to be added to the projection center, if positive, center is moved to the East, if negative - to the West
toNorth - number of vertical deltas to be added to the projection center, if positive, center is moved to the North, if negative - to the South

void zoomIn()

Increases scale of map projection (x 2).

void zoomOut()

Decreases scale of map projection (x 1/2).


Projections, distances

Function

Description

double getDistance
(double lonFrom,
double latFrom,
double lonTo,
double latTo)

Returns distance, in meters, between 2 given points.

Parameters:
lonFrom - the longitude of the 1st point, measured in degrees (-180 ... (West) ... 0 ... (East) ... +180)
latFrom - the latitude of the 1st point, measured in degrees (-90 ... (South) ... 0 ... (North) ... +90)
lonTo - the longitude of the 2nd point, measured in degrees (-180 ... (West) ... 0 ... (East) ... +180)
latTo - the latitude of the 2nd point, measured in degrees (-90 ... (South) ... 0 ... (North) ... +90)

boolean projectionContains
(double longitude,
double latitude)

[Not supported by AnyLogic Cloud] Returns true if the projection of the given point to screen is visible on this map

Parameters:

longitude - the longitude of point, measured in degrees (-180 ... (West) ... 0 ... (East) ... +180)

latitude - the latitude of point, measured in degrees (-90 ... (South) ... 0 ... (North) ... +90)

double convertRotationAngleForward
(double longitude, double latitude, double angle)

[Not supported by AnyLogic Cloud] Creates forward projection of the given rotation angle (direction) at the given point, to screen. Returns the rotation angle measured in radians from model animation point (1, 0) CW around (0, 0) point (as Y-axis is directed downwards).

Parameters:

longitude - the longitude of point, measured in degrees (-180 ... (West) ... 0 ... (East) ... +180)

latitude - the latitude of point, measured in degrees (-90 ... (South) ... 0 ... (North) ... +90)

angle - the rotation angle measured in radians from East CCW (0 is East direction, PI/2 is North direction, etc.)

double convertXForward
(double longitude,
double latitude)

[Not supported by AnyLogic Cloud] Creates forward projection of the given point to screen and returns x-coordinate. Returns the x coordinate of screen-projection of the given point.

Parameters:
longitude - the longitude of point, measured in degrees (-180 ... (West) ... 0 ... (East) ... +180)

latitude - the latitude of point, measured in degrees (-90 ... (South) ... 0 ... (North) ... +90)

double convertYForward
(double longitude,
double latitude)

[Not supported by AnyLogic Cloud] Creates forward projection of the given point to screen and returns y-coordinate. Returns the y coordinate of screen-projection of the given point

Parameters:
longitude - the longitude of point, measured in degrees (-180 ... (West) ... 0 ... (East) ... +180)

latitude - the latitude of point, measured in degrees (-90 ... (South) ... 0 ... (North) ... +90)


Shape position

Function

Description

double getX()

Returns the X coordinate of the shape (namely, the X coordinate of its upper left corner).

double getY()

Returns the Y coordinate of the shape (namely, the Y coordinate of its upper left corner).

void setX(double x)

Sets the X coordinate of the shape.

Parameter:
x - the new value of X coordinate

void setY(double y)

Sets the Y coordinate of the shape.

Parameter:
y - the new value of Y coordinate

void setPos
(double x,
double y)

Sets new coordinates for the shape.

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


Shape size, scaling

Function

Description

double getWidth()

Returns the width of the shape.

double getHeight()

Returns the height of the shape.

void setWidth(double width)

Sets the width of the shape equal to width.

void setHeight(double height)

Sets the height of the shape equal to height.

double getScaleX()

Returns the scale of the shape along X axis.

double getScaleY()

Returns the scale of the shape along Y axis.

void setScaleX(double sx)

Sets the scale of the shape along X axis.

Parameter:
sx - the new value of scale along X axis, 1 = keep original size

void setScaleY(double sy)

Sets the scale of the shape along Y axis.

Parameter:
sy - the new value of scale along Y axis, 1 = keep original size

void setScale(double sx, double sy)

Sets the scales of the shape along both axes.

Parameters:
sx - the new value of scale along X axis, 1 = keep original size
sy - the new value of scale along Y axis, 1 = keep original size

void setScale(double s)

Sets the same scale of the shape along both axes.

Parameter:
s - the new value of scale along both axis, 1 = keep original size

Shape visibility

Function

Description

boolean isVisible()

Checks the visibility of the shape. If the shape is visible, returns true, otherwise returns false.

void setVisible(boolean v)

Sets the visibility of the shape.

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


Working with layers

Function

Description

ShapeGISMap.Layer[] getLayers()

Returns the array of layers used in this GIS Map.
The array shouldn't be modified structurally: only items can be accessed for modification.


Related topics

 GIS tutorial

Navigating a GIS map

           API reference: ShapeGISMap class