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

Planimate does not automatically retrieve map data from the internet. It assumes you have the needed data in a hierarchy in the same directory as the model or a standalone EXE.

Co-ordinate System

All the map needs is a longitude and latitude range to 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).

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.

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.

After changing the co-ordinate range 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.