BGMountains Garmin IMG → OsmAnd OBF (v0.7)

One command builds the C++ IMG converter, emits a reviewed OSM, generates complete custom OsmAnd POI and map type definitions, validates the intermediate source/OSM data, and invokes OsmAndMapCreator to build an OBF.

Unlike v0.6's optional build_obf.sh wrapper, the main script no longer expects you to create any missing XML files. First-time setup requires access to the official OsmAnd resource files and the OsmAndMapCreator Java tool; the script can download both on demand. Java, Python, CMake, libpng, SQLite3 and a C++ compiler must be installed.

One-command full Bulgarian map

sudo apt update
sudo apt install -y build-essential cmake libpng-dev libsqlite3-dev python3 openjdk-21-jre-headless unzip

python3 scripts/build_bgmountains.py \
  --img '/path/to/gmapsupp.img' \
  --out '/path/to/BGMountains-build' \
  --download-creator

If you already have OsmAndMapCreator, use --creator /path/to/OsmAndMapCreator in place of --download-creator. You can also export OSMAND_MAPCREATOR=/path/to/OsmAndMapCreator and omit --creator.

OsmAndMapCreator is ~150 MB and requires extra disk space and Java RAM. By default, the script downloads it only when you request --download-creator; upstream OsmAnd poi_types.xml and rendering_types.xml are downloaded or read from your MapCreator directory automatically, then cached in the output folder. Requires Internet for first use unless you supply existing XML files with --poi-base FILE --rendering-base FILE.

Multithreading remains disabled by default (--jobs 1). Pass --jobs 4 explicitly for the IMG parsing stage. It does not control MapCreator's Java processing.

If the Java process runs out of memory:

python3 scripts/build_bgmountains.py --img gmapsupp.img --out ./BGMountains-build \
  --creator ~/OsmAndMapCreator --jobs 4 \
  --java-opts '-Xms1G -Xmx12G'

The full-country OSM can be large. Allocate substantial disk space for OSM XML, temporary indexing databases, and OBF output. The script retains intermediate files for auditing.

What is generated

BGMountains-build/
  BGMountains.osm                    # converted source, Garmin type and name kept
  source-pois.csv                    # source point audit manifest
  poi-types.csv                      # observed type counts and example coordinates
  validation.json                   # source-to-OSM counts/mismatches
  mismatches.csv
  converter.log
  validator.log
  upstream/poi_types.xml            # official OsmAnd definitions (if downloaded)
  upstream/rendering_types.xml
  osmand-config/
    poi_types.bgmountains.xml        # FULL base OsmAnd POI rules + 1 custom type per observed Garmin code
    rendering_types.bgmountains.xml  # FULL base render encoding + map encoding for each Garmin code
    BGMountains-custom.render.xml    # OPTIONAL visual style for custom icons in OsmAnd
    type-index-summary.json
  mapcreator.log
  *.obf                              # full map (created by OsmAndMapCreator)
  obf-poi-index.txt                  # dump from inspector.sh, if available
  build-manifest.json

For the v0.6 reviewed national catalog: 263 decoded types, 410,563 POIs, 87 types with at least 100 occurrences, 86 with Garmin TYP bitmap extraction. Actual new runs produce their own observed counts. The default threshold is 100; use --threshold 250 to change it.

Three different meanings of 'icon'

Native OsmAnd map icon. Verified type receives proper OSM tags (natural=spring, tourism=hotel, etc.) from config/poi-overrides-all-types.csv. Existing OsmAnd styles choose their built-in symbols.
Custom Garmin type in OBF. Every observed POI receives garmin:type and bgm_poi=type_0xHEX; the generated POI and map type XML preserve those types as a dedicated category. Map-index objects at high-frequency types are stored from zoom 15 by default, rare types from zoom 17 (adjustable by --frequent-zoom, --rare-zoom). Native OsmAnd styles may not draw custom types without a matching style.
Actual Garmin TYP bitmap. Preserved separately as PNG in data/poi-icons/; an OBF does not embed third-party bitmap resources into the app icon set. To display these exact symbols requires changing OsmAnd application resources, not just editing XML. A different installed OsmAnd render style may refer to already available built-in symbols.

Assign additional built-in OsmAnd icons yourself

Edit config/osmand-icons.csv:

code,show_in_custom_style,minzoom,osmand_builtin_icon,...
0x650b,yes,16,information,...

For common unknowns (>=100 occurrences with no verified standard OSM semantic category) the sample config enables a generic built-in information icon in an optional style. For verified classes, show_in_custom_style=no lets the stock OsmAnd map style draw a more meaningful native icon. The file includes one entry for all 263 source types, occurrence counts and sample coordinates. Change the osmand_builtin_icon to a valid icon ID supported by your installed OsmAnd version and set show_in_custom_style=yes to override the default.

After building, install BGMountains-custom.render.xml as a custom OsmAnd rendering style in the application's rendering directory, then select the corresponding map style. It depends on OsmAnd's default style. It is optional and not automatically installed by placing the OBF on the device. Its exact icon rendering has not been device-tested in this release; built-in IDs and application versions may differ. Avoid over-rendering at low zoom because 410k points can be slow.

Test a region first

python3 scripts/build_bgmountains.py --img gmapsupp.img \
 --out ./rila-build --bbox 23.22,42.08,23.47,42.29 \
 --creator ~/OsmAndMapCreator

Alternatively use --prepare-only to stop before Java: this produces the OSM plus generated XML and validation reports.

Rebuild from existing OSM

Only use an OSM generated by v0.7 or later containing bgm_poi tags:

python3 scripts/build_bgmountains.py \
 --osm ./BGMountains-build/BGMountains.osm \
 --catalog ./BGMountains-build/poi-types.csv \
 --creator ~/OsmAndMapCreator \
 --out ./obf-rebuild

Original v0.6 OSM exports lack the bgm_poi classifier. The script rejects those for this path rather than quietly producing an incomplete custom POI index. To reuse old data, rerun the IMG extraction with v0.7.

How POIs are edited

config/poi-overrides-all-types.csv: reviewed original IMG type → semantic OSM tags (five-column CSV). You can override/add rules, preserving provenance. This includes the earlier 67 legend/icon matches.
config/poi-name-fixes.csv: coordinate-specific correction of verified names, never guessed universally.
config/poi-additions.csv: manually add personally verified POIs.
config/osmand-icons.csv: optional on-screen stock OsmAnd symbol selections for custom raw types.
data/BGMountains-unique-poi-types.csv: counts, names, five real sample coordinates per Garmin hex type.
data/poi-icons: 96 extracted TYP bitmaps for reference, not automatically installed into OsmAnd.

Validation

The C++/Python roundtrip test checks extracted source POI manifest against OSM coordinates, names and tags. ctest --test-dir build --output-on-failure runs 5 bundled tests, including checks of full upstream XML augmentation. On the tested source bbox (23.22,42.08,23.47,42.29) a v0.7 extraction produced 3,986 POIs across 60 types and zero source-versus-OSM mismatches. These tests do not assert OBF persistence until MapCreator runs on your machine and obf-poi-index.txt is reviewed.

OsmAnd has separate indexed data for map rendering and POI search, and an additional app-side style/icons component. A successful OBF build does not prove every icon will be visible. To debug OBF use ~/OsmAndMapCreator/inspector.sh -vpoi /path/to/map.obf and compare the categories to osmand-config/type-index-summary.json.

Upstream and redistribution

The repository's C++ converter has its own LICENSE; BGMountains-derived SVG/PNG icons, data, examples and Garmin IMG/OBF remain subject to map licensors' conditions. Do not redistribute the full data release or generated OBF as unrestricted ODbL/CC0 without additional rights clearance. The script downloads official OsmAnd XML into a private build directory rather than repackaging those resource files in this source ZIP.

Official references:

8.6 KiB Raw Permalink Blame History