Map (Paint Object)
The Map Paint Object enables displaying and interacting with geographic maps stored as many small tile images which are combined automatically.
Two formats of map data are supported, Slippy and Open Street Maps or TMS format as used in OpenLayers, MapTiler and TileCache.
The map paint object features automatic combination of tiles at different resolutions to achieve the best view possible and high quality scaling of images.
With the supporting table and routine operations, Planimate track/spatial link/pipe networks can be positioned over the map and smoothly updated dynamically as the map view is panned and zoomed. Very little supporting model code is required.
Map Data
Map data consists of 256x256 PNG image tiles stored in a hierarchy in the form:
(model directory) / map-name / level of zoom / x axis / y image.png
The level of zoom determines the number and map resolution of the tiles within. The top level, "0" is just one tile for the whole world. Level "1" is 4 tiles, "2" is 16 tiles and so on. As you progress to higher levels it quickly gets impractical having tiles for the whole world on a PC. Instead you would have tiles for region(s) of interest up to the needed resolution.
Planimate normally does not retrieve map data from the internet. It assumes you have the needed image data in a hierarchy starting with a named directory in the same directory as the model or a standalone EXE.
Advanced uses can configure Planimate to access a tile server which can assist in populating a tileset. Be aware this is experimental and there are usage conditions on public servers - this option is intended for users with their own servers.
Map data can be downloaded using the mobile atlas creator tool.
Co-ordinate System
The map has two modes of operation.
In the default automatic zoom mode, the map uses a longitude and latitude range to determine its display. This is specified in degrees and can be set at edit time and changed dynamically at runtime. The top left limit of the map is (-180,85) (180W,85N). The bottom right limit is (180,-85) (180E,85S).
In the alternate "fixed zoom" mode. you set a oom factor and centre co-ordinate. The map then starts at tiles at the given zoom level and determines the longitude/latitude range based on the space available in the view.
Used together with Anchoring options, the map will dynamically resize as the panel it is on is resized. In automatic zoom mode the map will scale its image as its view area is resized. In fixed mode, the zoom stays the same and the extent that is visible will change.
Options (Map Specific)
Auto Latitude Range
Default: ON
With this option on the map automatically determines the best latitude range given the longitude specified. This maintains the aspect ratio of the display and enforces proper clipping when near the edge of the map.
With this "on", you should set the minimum and maximum latitudes so their average is the centre of the region you want (they can be equal). Planimate will then update the range to the values actually used.
Don't Upscale Lower Resolution TIles
Default: OFF
By default the map will automatically use lower resolution tiles and upscale (stretch) them to ensure the user has always something to look at. The minimum you could get away with is a single zoom level 0 tile, which corresponds to the whole world.
Turning this option off prevents the upscaling and makes it much more obvious where optimal resolution tile data is not available for a given view.
Given a simulation model will involve a specific part of the world at high resolution, this option can assist in acquiring the relevant data as it clearly highlights when map data at the preferred zoom is not present.
Disable Anti-Alias For Downscaled Tiles
Default: ON
This disables anti-alias smoothing for tiles which are being reduced in size. This improves redraw speed but tiles which are being shrunk will not be as smooth. Tiles which are being expanded
in size are not affected by this option.
Disable Anti-Alias For Upscaled Tiles
Default: OFF
This disables anti-alias smoothing for tiles which are being expanded in size. It will improve redraw speed further when tile image data is not available at a given resolution so coarser tiles
are upscaled. It would normally only be used if the option for downscaled tiles is also enabled in cases where speed comes before image quality.
Log Tile Request Failures
Default: OFF
When selected, Planimate will log failed tile requests to PLANIMAT.DBG to assist in data collection. You will need to run Planimate with the /DEBUGFILE command line option to enable creation of the debug log file.
This option should be turned off when not in use as it will slow down display.
It is recommended that the "Don't Upscale Lower Resolution TIles" option be off when you use this option, it makes missing tiles more obvious visually.
Cache Tiles In Memory
Default: OFF
In cases where there is ample system memory and a limited number of map tiles, turning this option on will make redrawing the map (especially when scrolling/zooming) faster.
At this stage there is no management for running out of memory or releasing cache memory so use this option with care.
Fixed Map Zoom
Default: OFF
With this option selected the map changes to fixed zoom mode. The longitude and latitude ranges are used to specify a centre. A zoom factor then determines which tile set to use. Zoom factor zero uses the entire world, 1 = quarter tiles, 2 = 1/16th tiles etc.
Fractional zoom factor is supported, in this case the tileset used is the next integer larger than the zoom value and it will be downscaled to achieve the desired reduction.
TMS Map Tile Format
Default: OFF
This option enables the use of TMS format tile data. Tiles are virtually identical to OpenStreetMaps format tiles except the Y axis is numbered with 0 at the bottom instead of 0 at the top.
Log Successful Tile Request
Default: OFF
When selected, Planimate will log successful tile requests to PLANIMAT.DBG. You will need to run Planimate with the /DEBUGFILE command line option to enable creation of the debug log file.
The log of used tiles can assist in deriving a sub tile set that a model actually needs, avoiding shipping unnecessary tiles when you already have a
This option should be turned off when not in use as it will slow down display.
It is recommended that the "Don't Upscale Lower Resolution TIles" option be off when you use this option, it makes missing tiles more obvious visually.
Progressively Fade Upscaled Tiles
Default: OFF
When selected, Planimate will successively fade tiles that it has had to upscale because tiles at the desired resolution are not available. The more Planimate upscales a tile, the more it is faded.
This achieves an indication to the developer of regions where tiles are not available and also highlights to an end user that they are viewing a region which is not relevant to their model.
In automatic zoom mode, it is important to remember that a user's screen resolution / window size may result in Planimate selecting a tile zoom level higher than on a lower resolution display / smaller window. Anticipate the window size in preparing the tileset otherwise end users may experience faded tiles if this option is selected.
Handle Drag During Object Edit Mode
Default: OFF
This option enables edit time positioning of objects by the map view and is described below.
Runtime Attributes
The map's display can be set dynamically using the SetPaintProperty() routine operation and these properties (which are in the _paint_properties label list).
"LongitudeFrom", "LatitudeFrom" set the top left corner and "LongitudeTo", "LatitudeTo" set the bottom right corner. Note that LatitudeFrom and LatitudeTo can be set to the centre and they will be calculated automatically according to the longitude range and shape of the map object.
If the Fixed Map Zoom option is selected then the centre of LongitudeFrom/LongitudeTo is used for the longitude to center around and the latitude works as if the Auto Latitude Range option is on.
The "TileZoomLevel" property can be read if the map does not have the Fixed Map Zoom option on. If the option is on then this property sets the zoom level. If set to an integer it correponds to the tile set zoom level to use. If its a fraction, the tile set used will be the next integer greater than the fraction.
After changing the co-ordinate range/zoom a repaint will refresh the map display. Before doing the repaint you may want to reposition objects.
Object Positioning
The map uses a mercator projection. Together with clipping and automatic latitude range, determining the mapping between panel pixels and map co-ordinates is not trivial. The map provides a translation service enabling you to translate between panel and map co-ordinates.
This is provided using two new routine operations.
LongLatToXY() and XYToLongLat(). These both take 2 parameters, a paint object label (the map) and a table. The table must contain the columns "_long","_lat","_x" and "_y". Other columns can be present and will be left untouched. This table is typically the Node Table and Bend Table as described below.
For each row in the table, LongLatToXY translates the _long/_lat columns to the closest corresponding pixel on the panel with the paint object. XYToLongLat does the reverse. Be careful when you use it since if the map is zoomed out you will lose precision in the long/lat co-ordinates.
Edit Time Object Updating
When a Map Paint Object is used together with an overlaid network, the map will determine which objects are visible. It will typically be the case that only some of the objects will be visible at any given time, especially if objects at a finer level of detail are hidden as you zoom out.
To make editing of such models easier, a mechanism exists where the map can re-position Portals and Bend Points (on tracks, spatial links and pipes) without the model running.
Enabling Edit Time Map Dragging/Zooming
The Map Paint Object has an option "Handle Drag During Object Edit Mode". When enabled, the map view can be panned by dragging it with the CTRL key held down and zoomed by giving the map focus (CTRL-click or CTRL-drag) and then turning the mouse scroll wheel. The CTRL key prevents accidental changes to the map whilst editing objects.
Note that the Planimate network is not shown during dragging of the map when Planimate is in edit mode. It is shown when the drag is released.
The next section describes the tables that need to be in place in order for the Planimate network to track the map.
Node Table and Bend Table
In order for a Map Paint Object to update the position of Portals and Bend Points in edit mode, it needs to be provided with tables which contain the precise longitude and latitude of these objects, The same tables are used during run with the LongLatToXY() and XYToLongLat() operations, so they only need to be defined once.
In the Map's "Edit" dialog you can set the names for these tables. The tables differ in structure and need to have column names as follows:
Node Table: _x, _y, _long, _lat, _location
Bend Table: _x, _y, _long, _lat, _from, _to, _linktype
The columns are used as follows:
_x and _y are the current screen pixel centre of the portal or bend point. This changes often as the map is panned and zoomed.
_long and _lat are the map co-ordinate of the centre of the object. This wont change once the network is created and the object's position on the map is established.
_location, _from and _to are Object Labels and identify the Portal for the Node Table or the endpoint Portals for the Bend Table.
_linktype specifies the kind of link a bend point is on, see below.
Note that bend column names are compatible with routine operations GetBendPoints() and SetBendPoints().
Updating Node and Bend Tables
The Node Table and Bend Table are the primary source of information on where Portals and Bend Points are positioned. The Map Paint Object uses the Longitude and Latitude values to calculate the X/Y for each object.
In edit mode, when you move or add a Portal or Bend Point, you will need to update the tables. This isn't fully automatic in order to give the modeller some degree of flexibility in working with objects while editing.
The modeller can trigger updating of the node/bend tables using new context menu options in the Portal and Map object edit menus as described below.
It is important to do this before using the map to shift the view OR running the model.
Updating Portal and Bend Point Positions
Portals on a panel with:
- A map view configured with Node and Bend tables
- An Object Label set (ie: in the Object Label List)
will have a new option in their edit context menu, "Update Map Co-ordinates".
Selecting this option will:
- Update the Node Table with the longitude/latitude corresponding to the portal's screen position. A row for the portal is added if none is present.
- Update the Bend Table for all bend points on any type of link (track, spatial or pipe) which starts or ends at the portal.
It is important to use this option after repositioning a portal or adding/editing/deleting bend points otherwise the changes will be lost next time the map does the update.
You can use the object either side of a link to update changes to bend points..
Make sure the map resolution is zoomed in sufficiently for the object's position to be accurately calculated. Updating the position with the map zoomed out will result in the object shifting when the map is zoomed back in.
Handling Portal Deletion
After portals are deleted the Node and Bend Tables will be left with rows with node indicies which are no longer used. These can be automatically removed by using the "Clean Node/Bend Tables" menu option in the Paint Map Object edit context menu.
Selecting this option will remove any rows in the Node and Bend Tables which refer to an object that no longer exists.
Note that when a bend point is deleted, the Update Map Co-ordinates option, as described above, needs to be used, the option here only applies to deleted portals.
Bend Table _linktype Column
The Bend Table expects a column "_linktype"
(format for label list _link_types). It is necessary when the map view is repositioning the bend points so it knows the type of link.
This enables the one bend table to store bends for all types of links.
Routine operation GetBendPoints() will fetch all bend points on a panel if the _linktype column is present and a link type value of 0 is passed to the routine operation. Likewise SetBendPoints() will use the _linktype column if present.
Tile Server Access
The paint map edit dialog has a field "WGET URL" which is normally empty.
Using this and the WGET.EXE command line utility, you can make Planimate populate a local map tileset from an OSM compatible web server. Tiles will be fetched and saved locally as you navigate the map.
This is experimental and intended for advanced users working with private/local tile servers.
This field is not saved with the model (to avoid it being left "on").
With a tile server running locally on 192.168.0.151 and serving tiles from a URL directory of "tiles", the URL would be:
"http://192.168.0.151/tiles"
(any trailing slash is removed if present).
The Planimate debug log file (if enabled with /DEBUGFILE on the Planimate command line) will log the wget commands being issued. It is assumed the root directory of the
tileset (as named in the File option of the Map Paint Object) already exists and that "wget.exe" is either in the model's directory or in a directory in the user's PATH environment variable.
For the URL above, these logs will look like:
wget.exe http://192.168.0.151/tiles/9/415/299.png -O tiles_Australia\9\415\299.png
wget.exe http://192.168.0.151/tiles/9/410/300.png -O tiles_Australia\9\410\300.png
etc
