IGPSPORT Map Updater

A tool to generate custom map files for IGPSPORT cycling computers from OpenStreetMap data. This project downloads OSM PBF files, filters them based on polygon boundaries, transforms unsupported tags, and generates Mapsforge map files with the specific naming convention required by IGPSPORT GPS devices.

Supported Products

BiNavi
iGS800
iGS630
iGS630S
BSC300T
BSC300

Official support/download page: https://www.igpsport.com/en/support/product

Requirements

Java 17 or higher
Internet connection (for downloading OSM data and dependencies)
Disk space: Several GB depending on the size of the regions being processed

Platform-Specific Requirements

Windows

PowerShell 5.0 or higher (included in Windows 10/11)
Windows 7 or higher

Unix/Linux/macOS

Bash shell
curl (for downloading files)
unzip (for extracting archives)
bc (for mathematical calculations)

Important Notes

Before You Start

⚠️ Use At Your Own Risk: Do it at your own risk; I am not responsible for broken devices.

⚠️ Backup Your Maps: Before using the new maps, make sure to backup your existing maps from your IGPSPORT cycle computer. Store them in a safe location in case you need to revert.

⚠️ Free Up Space: Remove old maps from your cycle computer before transferring new ones. The new maps are significantly larger due to enhanced tags and more detailed information, so you'll need extra storage space.

⚠️ Processing Time: The map conversion process takes several hours to complete, depending on the size of the regions and your computer's performance. Plan accordingly and let the script run without interruption.

Map Size Changes

The generated maps are larger than original IGPSPORT maps because they include:

More detailed road networks
Additional map features (waterways, natural features)
Enhanced tagging information for better routing
Extended geographic data

Tag Configuration

This project uses two XML configuration files to control which OpenStreetMap tags are included in the generated maps:

Supported Tags (tag-igpsport.xml)

The following 21 tags are directly supported by IGPSPORT devices:

Category	Tags	Zoom Level
Major Roads	primary, primary_link, secondary, secondary_link, trunk, trunk_link, tertiary, tertiary_link	13
Minor Roads	cycleway, living_street, pedestrian, residential, road, service, track, unclassified	14
Natural	coastline, water	13
Waterways	canal, dam, drain, river, stream	14

Tag Transformations (tag-igpsport-transform.xml)

The following 12 transformations convert unsupported OSM tags to device-compatible equivalents:

Unsupported Tag	Transformed To	Description
`highway=motorway`	`highway=trunk`	Major highways
`highway=motorway_link`	`highway=trunk_link`	Highway ramps
`highway=footway`	`highway=cycleway`	Pedestrian paths
`highway=path`	`highway=cycleway`	Generic paths
`highway=bridleway`	`highway=cycleway`	Horse trails
`highway=sidewalk`	`highway=cycleway`	Sidewalks
`highway=steps`	`highway=pedestrian`	Stairs
`highway=byway`	`highway=track`	Rural byways
`highway=bus_guideway`	`highway=road`	Guided bus routes
`highway=construction`	`highway=road`	Roads under construction
`highway=raceway`	`highway=road`	Racing circuits
`highway=services`	`highway=service`	Service areas

This means the maps effectively support 33 highway types (21 native + 12 transformed).

See the Mapsforge tag-mapping reference for all available OpenStreetMap tags.

How to Run

Windows

Run the PowerShell script:

.\script.ps1
# Example with custom thread count:
.\script.ps1 -Threads 8

Or right-click script.ps1 and select "Run with PowerShell"

Unix/Linux/macOS

Make the script executable and run it:

chmod +x script.sh
./script.sh
# Example with custom thread count:
./script.sh --threads 8

What the Script Does

Downloads Osmosis (if not present) - OpenStreetMap data processing tool (v0.49.2)
Downloads Mapsforge Writer Plugin (v0.27.0) - Converts OSM data to Mapsforge format
Reads maps.csv - Configuration file with region definitions
Downloads OSM PBF files - Raw OpenStreetMap data from Geofabrik
Downloads Polygon files - Geographic boundary definitions
Transforms tags - Converts unsupported OSM tags to device-compatible equivalents
Generates maps - Creates Mapsforge .map files with proper zoom levels
Renames output - Calculates GEOCODE and applies IGPSPORT filename convention

CSV File Structure

The maps.csv file defines which regions to process. It has three columns:

Column	Description	Example
Original filename	The target IGPSPORT map filename format	`BR01002303102B83FO00N00E.map`
OSM BPF URL	URL to download the OpenStreetMap PBF file	`https://download.geofabrik.de/south-america/brazil-latest.osm.pbf`
Poly URL	URL to download the polygon boundary file	`https://download.openstreetmap.fr/polygons/south-america/brazil/central-west/distrito-federal.poly`

Example CSV Content

Original filename,OSM BPF URL,Poly URL
BR01002303102B83FO00N00E.map,https://download.geofabrik.de/south-america/brazil-latest.osm.pbf,https://download.openstreetmap.fr/polygons/south-america/brazil/central-west/distrito-federal.poly
BR02002303102833DN04O04Q.map,https://download.geofabrik.de/south-america/brazil-latest.osm.pbf,https://download.openstreetmap.fr/polygons/south-america/brazil/central-west/goias.poly

Where to Find Resources

OSM PBF files: Geofabrik Downloads
Polygon files: OpenStreetMap Polygons

Directory Structure

igpsport-map-updater/
├── script.sh                    # Unix/Linux/macOS execution script
├── script.ps1                   # Windows PowerShell execution script
├── maps.csv                     # Configuration file with map definitions
├── tag-igpsport.xml             # Tag configuration for Mapsforge writer
├── tag-igpsport-transform.xml   # Tag transformation rules
├── extract_tags.py              # Utility to extract tags from .map files
├── download/                    # Downloaded OSM PBF and polygon files
│   ├── *.osm.pbf
│   └── *.poly
├── output/                      # Generated map files (final output)
│   └── *.map
├── backup/                      # Store original IGPSPORT maps here
├── tmp/                         # Temporary files during processing
├── misc/                        # Documentation and diagrams
│   ├── filename-structure.svg
│   ├── tile-grid-concept.svg
│   └── compare-2023-to-2026.jpg
└── osmosis-0.49.2/              # Osmosis tool (auto-downloaded)
    ├── bin/
    ├── lib/
    └── script/

Directory Descriptions

download/: Stores downloaded OSM PBF files and polygon boundary files. Files are cached to avoid re-downloading.
output/: Contains the final generated .map files with IGPSPORT-compatible filenames.
backup/: Recommended location to store your original IGPSPORT maps before replacing them.
tmp/: Temporary directory used by Osmosis during processing (can be deleted after completion).
misc/: Contains SVG diagrams explaining the filename structure and tile grid concepts.
osmosis-0.49.2/: Automatically downloaded and extracted Osmosis tool with Mapsforge plugin.

IGPSPORT Filename Structure

The generated map files follow a specific naming convention required by IGPSPORT devices:

Format

[CC][RRRR][YYMMDD][GEOCODE].map

Components

Component	Length	Description	Example
CC	2 chars	Country code	`BR`, `PL`, `US`
RRRR	4 digits	Region/Product code	`0100`, `0200`
YYMMDD	6 digits	Date (Year, Month, Day)	`250317` = March 17, 2025
GEOCODE	12 chars	Geographic boundary encoding	`2B83FO00N00E`

GEOCODE Breakdown (12 characters, Base36 encoding)

The GEOCODE consists of 4 parts, each 3 characters in Base36:

MIN_LON (XXX): Western boundary - minimum longitude as tile X coordinate at zoom 13
MAX_LAT (YYY): Northern boundary - maximum latitude as tile Y coordinate at zoom 13
LON_SPAN (WWW): Width in tiles - 1 (horizontal span)
LAT_SPAN (HHH): Height in tiles - 1 (vertical span)

Example

Filename: BR01002303102B83FO00N00E.map

BR: Brazil
0100: Region code 0100
230310: March 10, 2023
2B8: MIN_LON (tile X at zoom 13)
3FO: MAX_LAT (tile Y at zoom 13)
00N: LON_SPAN (width in tiles)
00E: LAT_SPAN (height in tiles)

For a visual representation of the filename structure, see below:

Viewing and Comparing Maps

Cruiser - Map Viewer

Cruiser is a cross-platform map viewer that supports Mapsforge map files, making it ideal for viewing and comparing the generated maps.

Features

View .map files generated by this tool
Compare different map versions
Test maps before deploying to IGPSPORT devices
Supports multiple map formats including Mapsforge

Download

Visit the Cruiser Wiki page for download links and documentation.

Usage

Open Cruiser
Load your generated .map file from the output/ directory
Compare with other map versions or sources

Comparison Example

Below is a comparison showing the difference between the original IGPSPORT map (left) and the enhanced map (right) with additional features and details:

*Left: Original map (2023) | Right: Enhanced map (2026

Troubleshooting

Java Not Found

Ensure Java 17 or higher is installed:

java -version

Out of Memory Errors

Increase Java heap size by editing the JAVA_OPTS variable in the script:

export JAVA_OPTS="-Xms2g -Xmx16g -Djava.io.tmpdir=$TMP_DIR"

Download Failures

Check your internet connection
Verify the URLs in maps.csv are accessible
Some regions may have updated URLs on Geofabrik

Permission Denied (Unix/Linux)

Make the script executable:

chmod +x script.sh

Technical Details

Processing Pipeline

Read PBF → Load OpenStreetMap binary data
Apply Polygon → Filter data to geographic boundary
Tag Filter → Remove unwanted features, keep roads, waterways, landuse
Used Node → Keep only referenced nodes
Merge → Combine filtered data
Mapfile Writer → Generate Mapsforge .map file
Rename → Calculate GEOCODE and apply IGPSPORT filename

Map Features Included

The script filters OSM data to include:

Roads: highways, paths, tracks (with tag transformation for unsupported types)
Waterways: rivers, streams, canals, dams, drains
Natural features: water bodies, coastlines

All other features (buildings, POIs, amenities, etc.) are filtered out to reduce file size and focus on navigation.

Utilities

GeoJSON to POLY Converter (geojson_to_poly.py)

A Python utility to convert GeoJSON polygons into OSM .poly files for use with Osmosis --bounding-polygon.

Supports:

FeatureCollection, Feature, GeometryCollection
Polygon and MultiPolygon
Interior holes (written as ! rings in .poly)

Usage:

# Basic conversion
python geojson_to_poly.py region.geojson region.poly

# Set polygon name header
python geojson_to_poly.py region.geojson region.poly --name my-region

# Overwrite existing output
python geojson_to_poly.py region.geojson region.poly --overwrite

# Fail on malformed rings instead of skipping
python geojson_to_poly.py region.geojson region.poly --strict

Important:

Coordinates must already be WGS84 lon/lat.
The converter does not reproject coordinates.

Map Tag Extractor (extract_tags_map.py)

A Python utility to extract and analyze tags from Mapsforge .map files. Useful for:

Inspecting what tags are embedded in existing maps
Comparing tags between different map versions
Debugging tag configuration issues

Usage:

# Single file
python extract_tags_map.py output/map.map

# Single file with output
python extract_tags_map.py output/map.map tags.txt

# Process all files in folder
python extract_tags_map.py backup/

# Process folder with output
python extract_tags_map.py backup/ tags_output/

PBF Tag Extractor (extract_tags_pbf.py)

A Python utility to extract and analyze tags from raw OSM PBF files before processing. This tool helps you understand what tags are available in the source data and plan your tag filtering/transformation strategy.

Features:

Extract tags from nodes, ways, and relations separately
Display tag frequency statistics
Export results in multiple formats (text, JSON, CSV)
Process individual files or entire folders
Filter by minimum occurrence count
Requires either pyosmium (faster) or osmium-tool

Installation:

# Option 1: Install pyosmium (recommended - faster)
pip install osmium

# Option 2: Install osmium-tool
# Ubuntu/Debian
sudo apt-get install osmium-tool

# Fedora
sudo dnf install osmium-tool

# macOS
brew install osmium-tool

Usage:

# Single file - display tags in terminal
python extract_tags_pbf.py download/brazil-latest.osm.pbf

# Single file - export to text file
python extract_tags_pbf.py download/sao-paulo.pbf -o tags.txt

# Single file - export to JSON
python extract_tags_pbf.py download/sao-paulo.pbf -o tags.json -f json

# Single file - export to CSV
python extract_tags_pbf.py download/sao-paulo.pbf -o tags.csv -f csv

# Process all .pbf files in folder
python extract_tags_pbf.py download/

# Process folder and export each file
python extract_tags_pbf.py download/ -o output_tags/

# Process with filters
python extract_tags_pbf.py download/ -o output/ -f json -m 10 -d 100

Options:

-o, --output: Output file or folder for extracted tags
-f, --format: Output format - text (default), json, or csv
-m, --min-count: Minimum occurrence count to include (default: 1)
-d, --display: Maximum tags to display in terminal (default: 50)

Use Cases:

Analyze tag distribution in source OSM data
Identify which highway types are present in your region
Determine what tags need transformation for IGPSPORT compatibility
Compare tag usage across different regions
Plan custom tag filtering strategies

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Dependencies and Data

Osmosis: LGPL (GitHub)
Mapsforge: LGPL (GitHub)
OpenStreetMap Data: ODbL (License)

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.vscode		.vscode
misc		misc
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
extract_tags_map.py		extract_tags_map.py
extract_tags_pbf.py		extract_tags_pbf.py
geojson_to_poly.py		geojson_to_poly.py
maps.csv		maps.csv
script.ps1		script.ps1
script.sh		script.sh
tag-igpsport-transform.xml		tag-igpsport-transform.xml
tag-igpsport.xml		tag-igpsport.xml

Folders and files

Latest commit

History

Repository files navigation

IGPSPORT Map Updater

Supported Products

Requirements

Platform-Specific Requirements

Windows

Unix/Linux/macOS

Important Notes

Before You Start

Map Size Changes

Tag Configuration

Supported Tags (tag-igpsport.xml)

Tag Transformations (tag-igpsport-transform.xml)

How to Run

Windows

Unix/Linux/macOS

What the Script Does

CSV File Structure

Example CSV Content

Where to Find Resources

Directory Structure

Directory Descriptions

IGPSPORT Filename Structure

Format

Components

GEOCODE Breakdown (12 characters, Base36 encoding)

Example

Viewing and Comparing Maps

Cruiser - Map Viewer

Features

Download

Usage

Comparison Example

Troubleshooting

Java Not Found

Out of Memory Errors

Download Failures

Permission Denied (Unix/Linux)

Technical Details

Processing Pipeline

Map Features Included

Utilities

GeoJSON to POLY Converter (geojson_to_poly.py)

Map Tag Extractor (extract_tags_map.py)

PBF Tag Extractor (extract_tags_pbf.py)

License

Dependencies and Data

References

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages