Skip to main content

​
Overview

The Open Mobile Maps SDK uses coordinate systems to define positions on the map. When setting up a map, you must specify a coordinate system. The current implementation assumes a uniform, two-dimensional grid.

​
The Coord Type

All map positions within Maps Core are represented by the Coord type: 
struct Coord {
    int32_t systemIdentifier;
    double x;
    double y;
    double z;
};
​
systemIdentifier
int32_t
required
Identifies which coordinate system the position values should be interpreted in
​
x
double
required
X-coordinate in the specified system
​
y
double
required
Y-coordinate in the specified system
​
z
double
required
Z-coordinate (elevation/height)
The systemIdentifier allows the SDK to understand which coordinate system the values should be interpreted in at any given time.

​
Supported Coordinate Systems

The SDK comes with implementations for several prominent coordinate systems:

​
EPSG:3857 - Pseudo-Mercator

WGS 84 / Pseudo-Mercator

The most widely used coordinate system for web mapping
MapCoordinateSystem system = CoordinateSystemFactory::getEpsg3857System();
  • Also known as: Web Mercator
  • Used by: Google Maps, OpenStreetMap, and most tile providers
  • Reference: https://epsg.io/3857

​
EPSG:4326 - WGS 84

WGS 84

Standard geographic coordinate system using latitude and longitude
MapCoordinateSystem system = CoordinateSystemFactory::getEpsg4326System();

​
EPSG:2056 - LV95 (Swiss)

CH1903+ / LV95

Swiss coordinate system (LV03+)
MapCoordinateSystem system = CoordinateSystemFactory::getEpsg2056System();

​
EPSG:21781 - LV03 (Swiss Legacy)

CH1903 / LV03

Legacy Swiss coordinate system
MapCoordinateSystem system = CoordinateSystemFactory::getEpsg21781System();

​
Unit Sphere

Unit Sphere Polar

Spherical coordinate system
MapCoordinateSystem system = CoordinateSystemFactory::getUnitSphereSystem();
  • Format: Phi, theta, radius with reference to Earth as unit sphere

​
CoordinateSystemFactory

The CoordinateSystemFactory provides factory methods to create coordinate systems: 
class CoordinateSystemFactory {
public:
    static MapCoordinateSystem getEpsg2056System();
    static MapCoordinateSystem getEpsg3857System();
    static MapCoordinateSystem getEpsg4326System();
    static MapCoordinateSystem getEpsg21781System();
    static MapCoordinateSystem getUnitSphereSystem();
};

​
MapCoordinateSystem Structure

struct MapCoordinateSystem {
    int32_t identifier;
    RectCoord bounds;
    float unitToScreenMeterFactor;
};
​
identifier
int32_t
The EPSG code or system identifier
​
bounds
RectCoord
The valid bounds for this coordinate system
​
unitToScreenMeterFactor
float
Conversion factor from coordinate units to screen meters

​
Coordinate Conversion

The MapScene holds a CoordinateConversionHelper to transform coordinates between different systems. 
class CoordinateConversionHelperInterface {
public:
    virtual Coord convert(int32_t to, const Coord & coordinate) = 0;
    virtual RectCoord convertRect(int32_t to, const RectCoord & rect) = 0;
    // ...
};

​
Using the Conversion Helper

// Get the conversion helper from the map interface
auto conversionHelper = mapInterface->getCoordinateConverterHelper();

// Convert from EPSG:4326 (lat/lon) to EPSG:3857 (Web Mercator)
Coord wgs84Coord(CoordinateSystemIdentifiers::EPSG4326(), 8.5417, 47.3769, 0.0);
Coord webMercatorCoord = conversionHelper->convert(
    CoordinateSystemIdentifiers::EPSG3857(),
    wgs84Coord
);

​
CoordinateSystemIdentifiers

The CoordinateSystemIdentifiers class provides static methods to access system identifiers: 
class CoordinateSystemIdentifiers {
public:
    static int32_t RENDERSYSTEM();
    static int32_t EPSG3857();  // WGS 84 / Pseudo-Mercator
    static int32_t EPSG4326();  // WGS 84
    static int32_t EPSG2056();  // LV03+
    static int32_t EPSG21781(); // CH1903 / LV03
    static int32_t UnitSphere();
    
    // Parse from string like "urn:ogc:def:crs:EPSG:21781"
    static int32_t fromCrsIdentifier(const std::string & identifier);
    
    // Get conversion factor to meters
    static double unitToMeterFactor(int32_t coordinateSystemIdentifier);
};

​
Example: Parsing CRS Identifiers

// Parse CRS identifier from string
int32_t systemId = CoordinateSystemIdentifiers::fromCrsIdentifier(
    "urn:ogc:def:crs:EPSG:3857"
);

// Get unit to meter conversion factor
double factor = CoordinateSystemIdentifiers::unitToMeterFactor(
    CoordinateSystemIdentifiers::EPSG3857()
);

​
Custom Coordinate Systems

You can register custom coordinate converters with the CoordinateConversionHelper:
1

Define Your Coordinate System

Create a unique identifier for your system
2

Implement Conversion Logic

Create a converter that can transform to/from other systems
3

Register the Converter

Add your converter to the CoordinateConversionHelper
Custom converters allow you to work with any projection or coordinate system your application requires.

​
Best Practices

Use EPSG:3857 for web mapping with standard tile providers. Use EPSG:4326 when working with GPS coordinates directly. Use regional systems (like EPSG:2056) for high-accuracy local applications.
Always specify the correct systemIdentifier when creating Coord objects to avoid misinterpretation.
Cache converted coordinates when possible, as coordinate conversion can be computationally expensive.
Verify that coordinates fall within the valid bounds of your chosen coordinate system.

​
Platform Examples

val coordinateSystem = CoordinateSystemFactory.getEpsg3857System()
val coord = Coord(
    CoordinateSystemIdentifiers.EPSG4326(),
    8.5417,  // longitude
    47.3769, // latitude
    0.0
)

// Convert to Web Mercator
val converted = mapInterface.coordinateConverterHelper.convert(
    CoordinateSystemIdentifiers.EPSG3857(),
    coord
)

Architecture

Learn about the SDK architecture

Camera

Understand how the camera uses coordinates

Build docs developers (and LLMs) love

Get started for freeTalk to us