Map (Paint Object)

The Map Paint Object enables displaying and working with map data stored as tiles in either the format used by 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. It uses high quality scaling of images.

With the supporting routine operations, portals and networks can be positioned over the map and smoothly updated dynamically as the map view is shifted and zoomed, with minimal supporting model code.

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 does not automatically retrieve map data from the internet. It assumes you have the needed image data in a hierarchy in the same directory as the model or a standalone EXE.  The map can optionally log needed tiles which can assist in acquiring (or generating) your map tile set.

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).

A "fixed zoom" mode is also supported. In this case a zoom factor and centre determine the tile zoom level and area displayed.

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 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

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.

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

A map view can handle pan and zoom and reposition objects at edit time. This facilitates editing map based networks. Existing portals, spatial links, pipes and tracks and their bend points will be updated if they are in a node/bendpoint table, as detailed below.

Note that the CTRL key needs to be pressed when dragging. When zooming, you need to give the view focus first with a CTRL-click, uinless you've just been dragging it.

Objects/links are not shown during dragging of the map since the animation manager is not running during edit mode and it would excessively flicker.

Edit time dragging requires enabling the map option "Handle Drag During Object Edit Mode".

Next the modeller has to provide existing tables populated with the objects/bend points and their long/lat, The names of these tables can be set in the Edit dialog for the map view. The columns expected are as follows:

Node Table: _x, _y, _long, _lat, _location
Bend Table: _x, _y, _long, _lat, _from, _to, _linktype

Note that bend column names, as used with GetBendPoints() and SetBendPoints(), have been updated but the old names (X,Y,Long,Lat,From,To) still work. Its more consistent to use the newer names as that is what the map expects.

Bend Table _linktype Column

The Bend Table supports an optional additional 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 manage bends for different types of links on the one panel.

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.