Create your own offline Pilot Plug map

Install QGIS

Install QGIS 3.44 LTR, 64-bit. Start it once to confirm it opens, then close QGIS before running the kit setup.

Verify the Authoring Kit ZIP

Get-FileHash "D:\Downloads\PilotPlug-UserMap-Authoring-Kit-v1.0.2.zip" -Algorithm SHA256

Expected SHA-256:
4b1fc28a7295694924504cc52d6453167422cd5477e4afb05793da6b514f9a6e

Extract to the recommended folder

Extract the ZIP into C:\PilotPlug\UserMapKit. The ZIP already contains its own versioned top-level folder, so do not create another duplicate folder around it.

Return PowerShell to the kit folder

Set-Location "C:\PilotPlug\UserMapKit\PilotPlug-UserMap-Authoring-Kit-v1.0.2"

Repeat this after reopening PowerShell. Commands beginning with .\ use the current folder.

Unblock and configure QGIS

Get-ChildItem -Filter *.ps1 -Recurse | Unblock-File
powershell -ExecutionPolicy Bypass -File ".\SETUP_AUTHORING_KIT.ps1"

Wait for SETUP AUTHORING KIT RESULT: PASS.

Choose your map bounds

Record West, South, East and North in WGS84 decimal degrees. Leave enough margin for the full operational area. Every point and every line/polygon vertex must stay inside these bounds.

Configure your User Map

powershell -ExecutionPolicy Bypass -File ".\CONFIGURE_USER_MAP.ps1"

Enter Map ID, display name, country code, bounds, and default-view latitude/longitude. The tool creates a visible read-only red dashed User Map Boundary in QGIS.

Wait for CONFIGURE USER MAP RESULT: PASS.

Set up Java and Planetiler

powershell -ExecutionPolicy Bypass -File ".\SETUP_BASEMAP_TOOLS.ps1"

Wait for SETUP BASEMAP TOOLS RESULT: PASS.

Generate the offline basemap

In v1.0.2, a normal user does not need to find or type a Planetiler / Geofabrik area name. The generator reads your configured West/South/East/North bounds and automatically selects the smallest official Geofabrik extract that covers the complete rectangle.

powershell -ExecutionPolicy Bypass -File ".\GENERATE_BASEMAP.ps1"

Before Planetiler starts, the script prints the selected Area ID and name. Wait for GENERATE BASEMAP RESULT: PASS. The accepted basemap is written to build\map.pmtiles.

If automatic selection can only use a continent-scale source such as Europe, the script warns you because that download can be very large. The -Area option remains available only as an expert/manual override.

Add a point

Select Pilot Plug — Points → yellow pencil → Add Point Feature → click the map → choose the Object Type in the form → enter relevant values → save.

Add a line

Select Pilot Plug — Lines → yellow pencil → Add Line Feature → left-click each vertex → right-click once to finish → choose the Object Type → save.

Add an area

Select Pilot Plug — Areas → yellow pencil → Add Polygon Feature → left-click each corner → right-click once to finish → choose the Object Type → save.

Import into Pilot Plug

Copy the completed .ppmap to Android. In Pilot Plug choose MAPS → IMPORT, select the file, then choose the installed User Map from MAPS.

What the Authoring Kit creates

A completed .ppmap contains exactly three files:

• manifest.json — package metadata
• map.pmtiles — offline OpenMapTiles basemap
• user_data.geojson — your QGIS-authored Pilot Plug objects

QGIS is the authoring environment. The Android app supplies the final Pilot Plug symbols and styling. The OpenStreetMap layer visible in QGIS is an online authoring reference only and is not copied into the package.

PowerShell and safe script execution

Authoring Kit v1.0.2 was designed and tested with Windows PowerShell 5.1. Check it with:

$PSVersionTable.PSVersion

PowerShell 7 is optional. You do not need to weaken the machine-wide execution policy. After verifying the release checksum, unblock only the trusted kit scripts:

Get-ChildItem -Filter *.ps1 -Recurse | Unblock-File
Get-ExecutionPolicy -List

Map bounds and configuration rules

Bounds use WGS84 / EPSG:4326 decimal degrees: West, South, East, North. Longitude west of Greenwich is negative; latitude north of the equator is positive. Use a period as the decimal separator.

Leave sensible margin around everything you plan to draw. The default-view latitude and longitude must lie inside the rectangle. Every point and every line/polygon vertex must also stay inside it.

The configuration tool creates config\build_config.json and project\user_map_boundary.geojson. The red dashed boundary is regenerated from the configuration, is read-only, and is never exported to the final map.

Basemap generation details

SETUP_BASEMAP_TOOLS.ps1 downloads and verifies the required Java 21 runtime and the frozen Planetiler 0.10.2 tool. Do not manually upgrade Planetiler for this Authoring Kit release.

With v1.0.2, the normal command is simply:

powershell -ExecutionPolicy Bypass -File ".\GENERATE_BASEMAP.ps1"

The script reads the configured bounds, downloads or reuses the cached official Geofabrik region index, and selects the smallest official extract that fully covers the rectangle. Source data is cached under cache\planetiler-work\. The accepted basemap is build\map.pmtiles.

# Regenerate an existing basemap using automatic source selection
powershell -ExecutionPolicy Bypass -File ".\GENERATE_BASEMAP.ps1" -Force

# Refresh the Geofabrik index and source datasets, then regenerate
powershell -ExecutionPolicy Bypass -File ".\GENERATE_BASEMAP.ps1" -RefreshSources -Force

The -Area parameter is retained for an expert who intentionally wants to force a specific Geofabrik extract, but it is no longer part of the beginner workflow. Judge the build by the final Pilot Plug result: GENERATE BASEMAP RESULT: PASS.

Supported User Map objects

Where applicable, enter Name/Text. For a depth point, enter depth in metres. The template may also offer Show Label, Min Zoom, Max Zoom and Description.

Final build validation

The production build performs headless QGIS export, public taxonomy and geometry validation, bounds checking, PMTiles verification, manifest generation, .ppmap packaging, and independent final-package validation.

The User Map Boundary is deliberately excluded. An empty map is rejected: add and save at least one Pilot Plug feature before building.

Updating an existing User Map

Treat a released .ppmap as immutable. Keep the same Map ID and increase the version, for example 1.0.0 → 1.0.1.

• Only objects changed: save QGIS edits, update the configuration version, then rebuild. Basemap regeneration is normally unnecessary.
• Bounds changed: replace the configuration with the new version and bounds, confirm the refreshed red boundary, regenerate map.pmtiles with -Force, then rebuild.
• Want fresher OSM data: regenerate with -RefreshSources -Force, then rebuild.
• QGIS updated or reinstalled: run SETUP_AUTHORING_KIT.ps1 -Force.

powershell -ExecutionPolicy Bypass -File ".\CONFIGURE_USER_MAP.ps1" -Force `
 -Id "es-las-palmas-approach" `
 -DisplayName "Las Palmas Port Approach" `
 -CountryCode "ES" `
 -Version "1.0.1" `
 -West -15.5 -South 28.05 -East -15.27 -North 28.21 `
 -Latitude 28.13 -Longitude -15.385 -Zoom 11

Important: -Force replaces build_config.json, so re-enter every intended setting carefully.

Updating PC software

• Keep Windows current through Windows Update.
• For Authoring Kit v1.0.2, remain on the QGIS 3.44 LTR line. After updating QGIS, run SETUP_AUTHORING_KIT.ps1 -Force.
• The kit manages Java 21 and Planetiler. Recreate that setup with SETUP_BASEMAP_TOOLS.ps1 -Force.
• Keep future Authoring Kit versions in separate versioned folders rather than overwriting v1.0.2.

Backup and release discipline

Keep the complete editable workspace for every map you maintain. After a successful release, preserve:

• project\PilotPlug_UserMap_v1.qgz
• project\PilotPlug_UserMap_v1.gpkg
• project\user_map_boundary.geojson
• config\build_config.json
• the final build\map.pmtiles
• the final output\*.ppmap
• build/validation reports
• the SHA-256 of the released .ppmap

Use a new semantic version for every changed package. Do not silently replace an already distributed map while retaining the same version number.

Worked example — Las Palmas Port Approach

Revision 3 was acceptance-tested end-to-end using Las Palmas de Gran Canaria. The same map bounds were retained as a regression reference, while v1.0.2 removed the need for the user to type the Geofabrik area name:

Map ID:       es-las-palmas-approach
Display name: Las Palmas Port Approach
Country code: ES
Version:      1.0.0
West:         -15.5000
South:         28.0500
East:         -15.2700
North:         28.2100
Default view:  28.1300, -15.3850
Default zoom:  11
Basemap area:  Automatic → canary-islands

QGIS opened at the configured area with the red dashed read-only boundary. Automatic source selection chose canary-islands from the configured bounds. A test export confirmed the boundary was not exported as user data. The basemap and final package both passed validation, and the .ppmap imported, rendered correctly, and reloaded offline in Pilot Plug.