OSMMapper Extension for Offline or Online Map
The OSMMapper extension is designed for working with maps in both online and offline modes, providing a comprehensive solution for displaying and managing geographic data.
In online mode, the extension supports integration with OpenStreetMap (OSM), allowing real-time access to maps without additional configuration.
For offstrong textline use, OSMMapper works with preloaded maps in various supported formats, including:
• ZIP archives – the recommended format for efficient storage and quick access.
• SQLite databases – suitable for handling large volumes of geographic data.
• MBTiles – a popular format for storing raster tile maps.
With support for both online and offline modes, OSMMapper ensures convenient use of maps for navigation and operation without an internet connection.
Objects Displayed on the Map
The OSMMapper extension supports various types of objects that can be displayed on the map, providing extensive capabilities for data visualization.
Available Objects:
• Markers – interactive elements with flexible settings such as image, scale, rotation, transparency, and more. Markers are clickable and can be used to mark points of interest on the map.
• Images – similar to markers in properties but not clickable. They are mainly intended for displaying graphic elements such as icons, photos, or other visual objects.
• Texts – allow text information to be applied directly to the map, useful for labeling places or providing explanatory notes.
• Polylines – used to display routes, boundaries, and linear objects on the map.
• Polygons – allow highlighting areas on the map, such as coverage zones or specific regions.
• Circles – used to visualize radius zones or other circular elements.
Object Identification:
Each object on the map has a unique ID, which allows users to manage its properties. Assigning new values to an existing ID updates the object’s properties without requiring deletion and re-creation, which significantly reduces device resource consumption and enhances application performance.
Coordinate Format:
Coordinates for objects are specified in text format:
“Latitude, Longitude” Example: “52.5200, 13.4050”
This approach ensures convenient data management and compatibility with other mapping services.
The OSMMapper extension provides powerful tools for working with maps, maintaining a balance between performance and customization flexibility.
Comprehensive Mapping Solution
OSMMapper is part of a comprehensive mapping solution, which includes several extensions designed for convenient map management in different modes. This set of tools provides full functionality for both online and offline navigation, as well as advanced geodata processing capabilities.
Solution Components:
• OSMMapper – the core tool for working with maps, allowing users to display objects, manage layers, and interact with geographic data in both online and offline modes.
• MAPManager – an extension designed for offline map management. It provides functions for downloading maps from OpenStreetMap, copying map files from various sources, and checking map availability in the application directory.
• MAPUtil – an auxiliary extension that includes a set of useful functions for working with maps, such as coordinate conversion, distance calculation, finding the nearest points, and other operations to simplify working with geodata.
This comprehensive solution allows applications to be flexibly configured, using only the necessary modules, ensuring efficient map management on resource-limited devices.
-
OSMMapper.
OSMMapper offers a wide range of blocks to efficiently manage maps, objects, and data. Below is a list of key blocks available in the extension
All Blocks:
Map Initialization
To place the map inside a container:
- If online map mode:
Set the Source to null (“”). - If offline map mode:
Set the Source to the name of the resource (folder) inside the .zip file.
The resource name is case-sensitive and must be specified exactly. The file name of the .zip archive itself does not matter.
Example initialization parameters:
• Offline mode:
“MAP1”, false, “Berlin”, “52.52,13.40”, true, true, 14, 1, 18
• Online mode:
“MAP1”, true, “”, “52.52,13.40”, true, true, 14, 1, 18
Parameter explanation:
• “MAP1” – name of the map or map object (e.g., resource name inside the .zip archive).
• false/true – map mode (offline/online).
• “Berlin” or “” – map name or an empty string for online mode.
• “52.52,13.40” – coordinates of the map center.
• The following parameters control zoom level in file, visibility, and the valid zoom range (default from 3 to 18).
Notes:
A map-ready event is triggered after successful initialization. This ensures that objects are displayed correctly and can interact with the map even if some tiles are still loading or temporarily unavailable.
Creating Map Objects:
To create map objects based on the provided list (List):
Data must be in an array and follow the exact order of the object’s properties.
Example array for creating a marker:
[‘Marker’, ‘1’, ‘Title’, ‘Text’, ‘52.7749,15.4194’, ‘icon.png’, true, 45.0, 0.5, 0.5, 1.0]
Types of objects on the map:
(Marker – marker,Image – image,Text – text,Polyline – line,Polygon – polygon, Circle – circle)
Each object type must be correctly defined and follow the parameter order specified in the blocks.
If you have multiple map resources of the same location but with different zoom levels, OSMMapper will display them in the same sequence. This allows you to combine different map visibility settings—for example, a road map for zoom levels 8 to 10, a topographic view for zoom levels 11 to 15, and a satellite view for higher zoom levels. To achieve this, you only need to create different types of maps for different zoom levels and load them once so the data is cached. After that, you can open any of them, and the maps will switch instantly when changing the zoom level.
Adding or Updating a Marker on the Map
• Coordinate format: “lat,lon”
• Rotation: Specified in degrees.
• Anchor values: Ranges from 0.0 to 1.0 (e.g., 0.5 for centering).
When assigning new values to a marker with the same ID, its properties will be updated. This rule applies to all objects on the map, not just markers.
Example:
Adding or updating a marker:
[‘Marker’, ‘1’, ‘Title’, ‘Text’, ‘52.7749,15.4194’, ‘icon.png’, true, 45.0, 0.5, 0.5, 1.0]
Explanation of the properties:
• ‘Marker’ – Object type (marker).
• ‘1’ – Unique ID of the object.
• ‘Title’ – Title of the marker.
• ‘Text’ – Additional text or description for the marker.
• ‘52.7749,15.4194’ – Coordinates of the marker in “lat,lon” format.
• ‘icon.png’ – Path to the marker icon.
• true – allow user to move.
• 45.0 – Rotation angle in degrees.
• 0.5, 0.5 – Anchor values (0.5 indicates the icon is centered horizontally and vertically).
• 1.0 – Scale factor.
This allows dynamic management of map objects, enabling easy updates and adjustments based on the provided object ID.
In general, the operation is similar to working with a standard map element, except that it creates objects dynamically by indexes, allowing for the quick rendering of multiple objects of the same type or different types. Additionally, more settings are available for objects, and the update parameters enable them to be animated.
Example:
2. MAPManager
MAPManager is an extension designed for easy management of offline maps within the application. It enables downloading, copying, and installing maps for use with OSMMapper, automating all necessary processes. With MAPManager, you can easily download tiles from OpenStreetMap or add maps created by third-party tools.
If your application uses only online maps, enabling MAPManager is not required.
Use of Internal Storage
To ensure stable operation and prevent access conflicts, MAPManager uses the device’s internal storage, placing all map files in the following directory:
/data/data/com.yourapp.package/files/Map (referred to as /files/MAP).
The /files/MAP folder is created automatically, so users do not need to manually copy files or create directories—this is handled by the extension.
Key Features of MAPManager
• Downloading maps from the OpenStreetMap service in ZIP format, which is prioritized for use with OSMMapper.
• Copying maps from a specified location on the device (e.g., if the map was created by another application or service) to the /files/MAP folder.
• Importing maps from application resources (assets) directly into the working folder.
• Checking and deleting files in the /files/MAP directory to manage storage efficiently.
Map Downloading
MAPManager automatically downloads and creates a map atlas on the device, placing all files in the directory: android/data/data/com.yourapp.package/files/MAP
Maps are saved in ZIP format, which is recommended for use with OSMMapper due to its convenience and compact storage.
You can:
• Use the built-in map downloader to retrieve maps directly from the OSM server.
• Import pre-generated maps created with MOBAC, SAS.Planet, and other tools.
There is no limit on the number of map downloads, and no access keys are required. However, excessive activity (e.g., attempting to download maps for the entire planet at maximum resolution) is not recommended.
DownloadMapToZip
This block allows downloading map tiles from the OpenStreetMap service and saving them to a ZIP file in the MAP folder, providing easy access to offline maps.
Block parameters:
• zipFileName (text) – The name of the ZIP file to be created.
• NameSource (text) – The name of the map to be used inside the ZIP file.
• topLeftCoordinate (text) – Coordinates of the top-left corner of the area (latitude, longitude).
• bottomRightCoordinate (text) – Coordinates of the bottom-right corner of the area (latitude, longitude).
• minZoom (number) – Minimum zoom level.
• maxZoom (number) – Maximum zoom level.
Example: “MyMap”, “Minsk”, “54.23,27.08”, “53.45,27.97”, “9”, “12”
• If a file with the same name already exists, it will be overwritten.
• If the working folder /files/MAP does not exist, it will be created automatically.
Recommendations for Downloading Maps:
• Avoid downloading maps with high detail levels during testing.
Large maps may contain hundreds of thousands of tiles and occupy hundreds of megabytes of storage. For initial tests, it is recommended to limit zoom levels to 5-9 to assess performance and download speed.
• After testing, you can proceed to download more detailed maps with zoom levels of 12+.
• OpenStreetMap officially supports zoom levels up to 19, although in some regions, detail may reach levels of 22 or higher.
• Map downloads are based on geographic coordinates, not administrative regions (countries, cities). You can specify any area by providing its boundary coordinates.
DownloadProgress
Reports the current progress of downloading and saving map tiles.Download progress percentage (0 to 100). The process is synchronous, combining file downloads and ZIP creation.
DownloadComplete
Triggered after successfully downloading tiles and creating the ZIP archive.
• filePath (text) – Path to the created ZIP file.
• totalFiles (number) – Number of files included in the ZIP.
SaveError
Triggered when an error occurs during ZIP file creation.
• errorMessage (text) – Description of the error.
AssetToMap
This block copies a map file from the application’s resources (assets) to the MAP folder, allowing you to embed offline maps in the app.
Note: Maps can take up a significant amount of storage, so this method is rarely used. However, it is provided for convenience and offline functionality.
FileToMap
This block allows users to manually select and copy a map file to the MAP directory.
The block supports two methods based on the Android version:
• SAF (S*torage Access Framework) – Used on devices with Android 10+, providing secure access to files in restricted storage.
• Classic file system – Used on devices with earlier Android versions, allowing direct access to the file system.
The user selects a map file through a dialog, and the selected file is automatically copied to:
/data/data/com.yourapp.package/files/MAP
The file becomes available for use with OSMMapper. This method allows you to expand the set of offline maps without embedding them in the application in advance.
Events:
CopyFileComplete
Triggered after successfully copying a file to the MAP directory.
• filePath (text) – Full path to the copied file.
CopyFileError
Triggered when an error occurs while copying a file.
• errorMessage (text) – Description of the error.
DeleteFileFromMap
Deletes the specified file from the MAP directory.
• fileName (text) – Name of the file to delete (e.g., “MyMap.zip”).
ListFilesInMap
Returns a list of files in the MAP directory.
• Return value: list – A list of files in the folder (e.g., [“MyMap.zip”, “Kuku.zip”]).
FileExistsInMap
Checks if a file exists in the MAP directory.
• fileName (text) – Name of the file to check (e.g., “Kuku.zip”).
• Return value: boolean – true if the file exists, otherwise false.
Offline Maps: Explanations and Recommendations
The OSMMapper extension supports multiple map formats, providing flexibility and convenience when working with offline data. This enables efficient storage, processing, and viewing of map information without requiring a constant internet connection.
Supported Map Formats:
ZIP (Osmdroid ZIP Archive) – recommended format
The most convenient and compact way to store maps.
Widely used in services like OpenStreetMap, Google Maps, Mapbox, and others.
Maps are stored in a compressed .zip archive with the following structure:file_name.zip
/Source – name of the map layer (e.g., Berlin, Minsk, Village)
*z} – zoom level /{x} – horizontal coordinate (int) /{y}.png – vertical coordinate (int) /{y}.jpg – alternative format
Example structure: MinskMap.zip /Minsk/12/1234/5678.png…5679.png
A single ZIP archive can contain multiple maps with unique layer names.Recommended programs for generation:Mobile Atlas Creator (MOBAC): mobac.sourceforge.io SAS.Planet: sasgis.org (recommended)
SQLite – database format for storing tiles
Maps are stored in the format /z/x/y. Supported by many mapping applications. Generation is possible using MOBAC, OruxMaps, Locus Map, and SAS.Planet.
MBTiles – standard SQLite-based format developed by Mapbox
Suitable for compact storage and transfer of maps between devices.Can be generated using MOBAC and SAS.Planet.
NOTE:
OSMMapper operates based on the map name (Source), not the file name. This means:
• The name of the ZIP file does not matter.
• It is crucial to provide the correct name of the map layer (folder) inside the archive.
• For example, if the archive contains a folder named /Minsk, that name (Minsk) will be used to load the map, not the name of the file minsk_map.zip.
Therefore, as long as the file structure is properly organized inside the archive, OSMMapper will automatically find and use the correct map.
Using offline maps with OSMMapper allows for flexible management of map data, adapting it to the application’s needs, and ensuring smooth operation without internet access.
3. MAPUtil
DemoApk: OSMMapper_Demo.apk (6.1 MB)
MapForTest:
BerlinZoom13.zip (3.6 MB)
Variant MAP mbtiles Type.zip (6.9 MB)(pre-extract the file)
(upload the files to your device. in the demo application, specify the files to copy.)
Price: 20$ for the development of the project
or other ways
:
