TileMapViewer.pbi is a PureBasic module that provides an interactive, multi-layer map viewer with support for online tile servers (see here https://www.strasis.com/documentation/limelight-xe/reference/tile-map-servers), precipitation overlays, caching, zooming, panning, and a customizable home marker. Precipitation tiles are optional; if enabled, the module can display real-time weather overlays from OpenWeather, which requires a free API key available after registration. The viewer features smooth navigation, threaded tile downloads, and is ideal for embedding dynamic maps in PureBasic applications.
Download
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
TileMapViewer() Procedure Parameters
| Parameter Name | Type | Description | Example Value |
|---|---|---|---|
CanvasGadget | Integer | The gadget ID of the canvas where the map will be drawn. | gCanvas |
homeLat | Double | Latitude (in degrees) for the “home” marker (centered on double-click or reset). | 49.5750583 |
homeLon | Double | Longitude (in degrees) for the “home” marker. | 17.4841983 |
defaultZoom | Integer | Initial zoom level (typically 0–19, higher is more zoomed in). | 4 |
baseTileServer$ | String | URL template for the base map tile server. Use {z}, {x}, {y} as placeholders for zoom/x/y. | "https://server.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Base/MapServer/tile/{z}/{y}/{x}.jpg" |
poolSize | Integer | Number of concurrent download threads for tile fetching. | 50 |
cacheDir$ | String | Directory path for cached map tiles. | "mycache" |
markerDiameter | Integer | Diameter (in pixels) of the home marker. | 8 |
markerBorderColor | Integer | RGBA color value for the home marker border. | RGBA(255,0,0,255) |
markerFillColor | Integer | RGBA color value for the home marker fill. | RGBA(255,0,0,255) |
showPrecip | Boolean | #True to enable precipitation overlay, #False to disable. | #True |
precipTileServer$ | String | URL template for the precipitation tile server. Use {z}, {x}, {y}, {APIKEY} as placeholders. | "https://tile.openweathermap.org/map/precipitation_new/{z}/{x}/{y}.png?appid={APIKEY}" |
precipApiKey$ | String | API key for the precipitation tile server. | "YOU API KEY" |
precipRefreshInterval | Integer | Precipitation overlay refresh interval (in seconds). | 60 |
Usage Example
TileMapViewer(gCanvas, 49.5750583, 17.4841983, 4,
"https://server.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Base/MapServer/tile/{z}/{y}/{x}.jpg",
50, "mycache",
8, RGBA(255,0,0,255), RGBA(255,0,0,255),
#True,
"https://tile.openweathermap.org/map/precipitation_new/{z}/{x}/{y}.png?appid={APIKEY}",
"xxxxxxxxxxxxxxxxxxxxxxx",
60)UpdateMap(CanvasGadget)
| Variable | Type | Description |
|---|---|---|
| w, h | Integer | Width and height of the canvas gadget. |
| t | Integer | Tile size in pixels (from gTileSize). |
| tilesX, tilesY | Integer | Number of tiles horizontally/vertically needed to fill the canvas. |
| grid | Integer | Number of tiles in the grid (from gGrid). |
| halfGrid | Integer | Half the grid size (for centering). |
| maxTile | Integer | Maximum tile index at current zoom. |
| x, y | Integer | Loop counters for tile grid. |
| tileX, tileY | Integer | Tile X/Y indices for each tile in the grid. |
| cacheDir$ | String | Directory path for tile cache. |
| cachePath$ | String | Full file path for cached tile. |
| baseUrl$ | String | URL for the base map tile. |
| baseExt$ | String | File extension for the base map tile. |
| precipKey$ | String | Key for precipitation overlay cache/maps. |
| expired | Boolean | Whether the precipitation overlay is expired and needs refresh. |
| precipUrl$ | String | URL for the precipitation tile. |
DrawMap(CanvasGadget)
| Variable | Type | Description |
|---|---|---|
| gCanvasW, gCanvasH | Integer | Width and height of the canvas gadget. |
| grid, halfGrid | Integer | Grid size and half grid size. |
| tilePx | Integer | Tile size in pixels. |
| centerScreenX, centerScreenY | Integer | Center of the canvas in pixels. |
| x, y | Integer | Loop counters for jobs. |
| dx, dy | Integer | Pixel offset for each tile from the center. |
| img | Integer | Image handle for base map tile. |
| precipImg | Integer | Image handle for precipitation overlay. |
| homeTileX, homeTileY | Double | Tile X/Y for the home marker. |
| pixelOffsetX, pixelOffsetY | Double | Pixel offset for the home marker. |
| markerScreenX, markerScreenY | Integer | Screen position for the home marker. |
| markerRadius | Integer | Radius of the home marker. |
| cx, cy | Integer | Center of the canvas (for spinner). |
| radius, spokeLength, spokeWidth, spokes | Integer | Spinner parameters. |
| angleDeg, angleRad | Float | Spinner spoke angle in degrees/radians. |
| xStart, yStart, xEnd, yEnd | Float | Spinner spoke start/end coordinates. |
| perpX, perpY | Float | Perpendicular vector for spinner spoke thickness. |
| length | Float | Length for normalizing vectors. |
| timeStr$ | String | Text for last precipitation update. |
| scaleBarLengthPx | Integer | Length of the scale bar in pixels. |
| scaleBarLengthM | Integer | Length of the scale bar in meters. |
| scaleLabel$ | String | Label for the scale bar (e.g., “2 km”). |
| barX, barY | Integer | X and Y position for the scale bar. |
| barHeight | Integer | Height (thickness) of the scale bar. |
| endMarkHeight | Integer | Height of the vertical end marks for the scale bar. |
| endMarkWidth | Integer | Width of the vertical end marks for the scale bar. |
| bottomMargin | Integer | Margin from the bottom of the canvas for the scale bar. |
StartTileDownloads(CanvasGadget)
| Variable | Type | Description |
|---|---|---|
| activeThreads | Integer | Number of currently active download threads. |
| idx | Integer | Index for thread array. |
| *job | Pointer | Pointer to a TileJob structure. |
| allDone | Boolean | Whether all jobs are finished. |
| totalSize | Quad | Total size of all jobs. |
| totalProgress | Quad | Total progress of all jobs. |
TileMapViewer_HandleEvent(CanvasGadget, EventType)
| Variable | Type | Description |
|---|---|---|
| now | Integer | Current time in ms (for double-click detection). |
| dx, dy | Float | Pan offset in tiles after drag. |
Scale Bar Variables (in DrawMap)
| Variable | Type | Description |
|---|---|---|
| earthCircumference | Double | Earth’s circumference in meters. |
| latRad | Double | Center latitude in radians. |
| metersPerPixel | Double | Meters per pixel at current zoom and latitude. |
| scaleLengths() | Array | Array of possible scale bar lengths (in meters). |
| maxBarPx | Integer | Maximum allowed width of the scale bar in pixels. |