Map (Paint Object)

The Map Paint Object enables displaying and working with map data stored as tiles in the format used by Slippy and Open Street Maps.

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 new supporting routine operations, portals and networks can be positioned over the map and smoothly updated dynamically as the map view is shifted, 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.

Options (Map Specific)

Auto Latitude Range

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

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 be assist in acquiring the relevant data.

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

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

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

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) extremely fast and smooth.

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

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.

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.