GeoARSDK - Getting started

The WemapGeoARSDK is a library for enabling AR navigation within mobile applications.

Requirements

In addition to common requirement WemapGeoARSDK supports Android SDK 24 and newer.

Installation

Check common installation.

Permissions

WemapGeoARSDK requires camera permission to be able to show camera background for AR. Declare android.permission.CAMERA in your app Manifest as follows:

<uses-permission android:name="android.permission.CAMERA" />

Please request camera permission before creating and presenting GeoARView, because without access to the camera - system can't work. If you don't do it, system will request permission on first access to camera. But if user denied access - black screen will be shown instead of camera background.

private val cameraPermissionHandler =
    registerForActivityResult(ActivityResultContracts.RequestPermission()) { granted ->
        if (!granted) {
            // User denied camera access. show a message explaining how to enable it
            return
        }
        // User granted camera access. Continue with GeoARView
    }

fun requestCameraPermission() {
    // show a model explaining that camera access is crucial for AR
    // then check if it's arealy granted and request if not yet
    if (ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA) == PackageManager.PERMISSION_GRANTED) {
        // User already granted camera access, Continue with GeoARView
    } else {
        requestCameraPermission.launch(Manifest.permission.CAMERA)
    }
}

Add a GeoARView

At first add GeoARView to your layout:

<com.getwemap.sdk.geoar.GeoARView
    android:id="@+id/geoARView"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Then create a session and pass it to the GeoARView via configure. The GeoAR view works with a CoreSession (a MapSession is a CoreSession, so you can share the same session with a map). The session and the (optional) GeoARViewConfig are set once:

lifecycleScope.launch {
    runCatching {
        CoreSession.create(requireContext(), 19158, "GUHTU6TYAWWQHUSR5Z5JZNMXX") // your mapId and token
    }.onSuccess { session ->
        geoARView.configure(session) // pass a GeoARViewConfig() as the second argument to tune AR rendering
    }.onFailure {
        println("Failed to create session with error - $it")
    }
}

Wait for the GeoARView to load

Only once the view has finished loading is it safe to access GeoARView properties. Await loading with the suspending awaitLoaded():

lifecycleScope.launch {
    runCatching {
        geoARView.awaitLoaded()
    }.onSuccess {
        // now it's safe to access GeoARView properties
    }.onFailure { error ->
        println("Failed to load GeoARView with error - $error")
    }
}

Or observe loadPhases — the same StateFlow<LoadPhase> the Map SDK exposes, so both views present one loading surface:

lifecycleScope.launch {
    geoARView.loadPhases.collect { phase ->
        when (phase) {
            LoadPhase.Loading -> showSpinner()
            LoadPhase.Ready -> showScene()
            is LoadPhase.Failed -> showError(phase.error)
        }
    }
}

When you're done with the screen, tear down the session with session.deinit() (from the lifecycle owner that holds it — e.g. onDestroy, or a ViewModel.onCleared() to survive configuration changes).

Using Jetpack Compose? WemapGeoAR ships as a separate artifact — see GeoARSDK with Jetpack Compose.

User Location

Wemap provides various location sources to track the user's location. For more info check positioning docs

There is no default LocationSource embedded into WemapGeoARSDK, so you have to choose one. You can easily do it by taking any WemapPositioningSDK location source — created with the same session — and connecting it to the GeoARView as shown below:

fun setupLocationSource(session: CoreSession) {
    val locationSource = VpsARCoreLocationSource(requireContext(), session) // it can be any LocationSource from WemapPositioningSDK
    geoARView.locationManager.locationSource = locationSource
}

The full example is available in our GitHub repository.

Examples

For additional examples and sample implementations of WemapSDKs, visit the official GitHub repository.

Clone the repository and follow the README instructions to run the sample application.