GeoAR+PositioningSDK - Getting started

Installation

Before you start developing your application with WemapSDKs, you need to configure your credentials and add the SDK as a dependency.

info

The code examples below demonstrate how to configure the WemapPositioningSDK to work with the WemapGeoARSDK, but it can also be used independently. Instructions are available here.

Adding the Dependency

To add WemapSDKs to your app:

1. In your module-level Gradle file (usually project/module/build.gradle.kts or project/module/build.gradle), add the dependency for the WemapGeoARSDK library for Android:

   dependencies {
       // Add the dependency for the WemapMapSDK library
       implementation "com.getwemap.sdk:geo-ar:<version>"
   
       // Add the dependency for the WemapPositioningSDK library
       implementation "com.getwemap.sdk.positioning:wemap-vps-arcore:<version>" // Wemap VPS ARCore Location Source
       implementation "com.getwemap.sdk.positioning:android-fused-adaptive:<version>" // Adaptive Fused Location Source (Google or system)
   }

2. Ensure that your project's minSdkVersion is set to API 24 or higher:

   android {
       ...
       defaultConfig {
           minSdkVersion 24
       }
   }

3. Since you've modified your Gradle files, Android Studio will prompt you to sync the Gradle files. Proceed with syncing.

Add a GeoARView

Open the fragment where you want to add a GeoARView and use the code below.

To make it work, you need to provide a mapID and token in the mapData request.

class DemoFragment: Fragment() {

    private val disposeBag = CompositeDisposable()
    private val geoARView get() = binding.geoSceneView

    private var _binding: FragmentDemoBinding? = null
    private val binding get() = _binding!!

    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
        _binding = FragmentDemoBinding.inflate(inflater, container, false)
        return binding.root
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        ServiceFactory
            .getMapService()
            .mapById(22418, "GUHTU6TYAWWQHUSR5Z5JZNMXX")
            .observeOn(AndroidSchedulers.mainThread())
            .subscribe({ mapData ->
                geoARView.mapData = mapData
            }, {
                println("Failed to get map data with error - $it")
            })
            .disposedBy(disposeBag)

        geoARView.getARViewAsync { _, _ ->
            // check permissions before setup location source
            setupLocationSource()
        }
    }

    private fun setupLocationSource() {
        // setup location source. examples below
    }
}

Location Sources

Wemap provides various location sources to track the user's location. There is no default Location Source embedded into WemapGeoARSDK, so you have to choose one.

To use any location source, you must have a mapID and token. For more details, please contact the Wemap team.

To set a specific location source, you need to:

• Add the relevant WemapPositioningSDK library to your project dependencies.
• Fetch MapData using your mapID and token.
• Create a LocationSource using MapData.
• Assign the location source to GeoARView. Examples are given below.

Wemap VPS ARCore location source

Setting Up the VPS ARCore Location Source

Once you have the MapData, create a WemapVPSARCoreLocationSource instance, add vpsListener, and assign it to the GeoARView:

fun setupLocationSource(mapData: MapData) {
    vpsLocationSource = WemapVPSARCoreLocationSource(requireContext(), mapData)
    vpsLocationSource.vpsListeners.add(vpsListener)
    geoARView.locationManager.locationSource = source
}

Handling Location Source State Changes

You must handle state changes in WemapVPSARCoreLocationSourceListener, as users may need to scan their environment.

private val vpsListener by lazy {
    object : WemapVPSARCoreLocationSourceListener {

        override fun onStateChanged(state: WemapVPSARCoreLocationSource.State) {
            // Handle state changes
        }

        override fun onScanStatusChanged(status: WemapVPSARCoreLocationSource.ScanStatus) {
            // Handle scan status changes
        }
    }
}

Scanning the Environment

To start tracking the user’s location, you need to allow the user to scan their environment:

fun startScan() {
    vpsLocationSource.startScan()
}

Once the system successfully recognizes the user’s location, it will report the ACCURATE_POSITIONING state to WemapVPSARCoreLocationSourceListener. Shortly afterward, the VPS system will start updating the user’s location indicator on the map.

The VPS system will also report:

• NOT_POSITIONING – indicates that the system hasn't yet recognized the environment and a VPS scan is required. At this point, you should present the camera view to the user to allow them to scan using vpsLocationSource.startScan().
• DEGRADED_POSITIONING – indicates that user location tracking is limited. A scan is recommended, but not mandatory, to restore the ACCURATE_POSITIONING state. We suggest a subtle UI indication when this state occurs, such as a location icon warning or a small toast message prompting the user to rescan.

Android Fused Adaptive location source

This Location Source combines Google’s Fused Location Provider with the System Fused/GPS Location Provider. If Google’s Fused Location Provider is available, it will be used first. If it is not available, the system will fall back to the System Fused Location Provider. If that is also unavailable, the GPS Location Provider will be used.

Once you have the MapData, create a AndroidFusedAdaptiveLocationSource instance and assign it to GeoARView.

Setting Up the Fused Location Source

fun setupLocationSource(mapData: MapData) {
    val source = AndroidFusedAdaptiveLocationSource(requireContext(), mapData)
    geoARView.locationManager.locationSource = source
}

The full example is available in our GitHub repository.

Itinerary generation

To know how to compute itineraries and start navigation check this doc

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.

🔗 GeoAR+Positioning sample