MapMetrics Native

MapMetrics Native is a free and open-source library for publishing maps in your apps and desktop applications on various platforms. Fast displaying of maps is possible thanks to GPU-accelerated vector tile rendering.

This project originated as a fork of Mapbox GL Native, before their switch to a non-OSS license in December 2020. For more information, see: FORK.md.

Getting Started

Android

Add the latest version of MapMetrics Native Android as a dependency to your project.

    dependencies {
        ...
        implementation 'org.mapmetrics.android-sdk:$latest-version'
        ...
    }

Add a MapView to your layout XML file:

<org.maplibre.android.maps.MapView
    android:id="@+id/mapView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    />

Tip

There are external projects such as Ramani Maps and MapLibre Compose Playground available to intergrate MapMetrics Native Android with Compose-based projects.

Next, initialize the map in an activity:

Show code

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.view.LayoutInflater
import org.maplibre.android.Maplibre
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.testapp.R

class MainActivity : AppCompatActivity() {

    // Declare a variable for MapView
    private lateinit var mapView: MapView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Init MapLibre
        MapLibre.getInstance(this)

        // Init layout view
        val inflater = LayoutInflater.from(this)
        val rootView = inflater.inflate(R.layout.activity_main, null)
        setContentView(rootView)

        // Init the MapView
        mapView = rootView.findViewById(R.id.mapView)
        mapView.getMapAsync { map ->
            map.setStyle("https://demotiles.maplibre.org/style.json")
            map.cameraPosition = CameraPosition.Builder().target(LatLng(0.0,0.0)).zoom(1.0).build()
        }
    }

    override fun onStart() {
        super.onStart()
        mapView.onStart()
    }

    override fun onResume() {
        super.onResume()
        mapView.onResume()
    }

    override fun onPause() {
        super.onPause()
        mapView.onPause()
    }

    override fun onStop() {
        super.onStop()
        mapView.onStop()
    }

    override fun onLowMemory() {
        super.onLowMemory()
        mapView.onLowMemory()
    }

    override fun onDestroy() {
        super.onDestroy()
        mapView.onDestroy()
    }

    override fun onSaveInstanceState(outState: Bundle) {
        super.onSaveInstanceState(outState)
        mapView.onSaveInstanceState(outState)
    }
}

For more information, refer to the Android API Documentation or the Android Examples Documentation.

iOS

You can find MapMetrics Native iOS on Cocoapods and on the Pods.

MapMetrics Native iOS uses UIKit. To intergrate it with an UIKit project, you can use

class SimpleMap: UIViewController, MLNMapViewDelegate {
    var mapView: MLNMapView!

    override func viewDidLoad() {
        super.viewDidLoad()
        mapView = MLNMapView(frame: view.bounds)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(mapView)
        mapView.delegate = self
    }

    func mapView(_: MLNMapView, didFinishLoading _: MLNStyle) {
    }
}

You need to create a wrapper when using SwiftUI.

import MapMetrics

struct SimpleMap: UIViewRepresentable {
    func makeUIView(context _: Context) -> MLNMapView {
        let mapView = MLNMapView()
        return mapView
    }

    func updateUIView(_: MLNMapView, context _: Context) {}
}

The iOS Documentation contains many examples and the entire API of the library.

Contributing

Note

This section is only relevant for people who want to contribute to MapMetrics Native.

MapMetrics Native has at its core a C++ library. This is where the bulk of development is currently happening.

To get started with the code base, you need to clone the the repository including all its submodules.

All contributors use pull requests from a private fork. Fork the project. Then run:

git clone --recurse-submodules git@github.com:<YOUR NAME>/mapmetrics-native-sdk.git
git remote add origin https://github.com/maplibre/mapmetrics-native-sdk.git

The go-to reference is the MapMetrics Native Developer Documentation.

Tip

Check out issues labelled as a good first issue.

Core

• CONTRIBUTING.md
• GitHub Wiki: low-friction way to share information with the community
• Core C++ API Documentation (unstable)

Android

Open platform/android with Android Studio.

More information: MapMetrics Android Developer Guide.

iOS

You need to use Bazel to generate an Xcode project. Install bazelisk (a wrapper that installs the required Bazel version). Next, use:

bazel run //platform/ios:xcodeproj --@rules_xcodeproj//xcodeproj:extra_common_flags="--//:renderer=metal"
xed platform/ios/MapLibre.xcodeproj

To generate and open the Xcode project.

More information: MapMetrics iOS Developer Guide.

Other Platforms

See /platform and navigate to the platform you are interested in for more information.

License

MapMetrics Native is licensed under the BSD 2-Clause License.