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.

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.