# Creating Device Maps Source: https://www.nianticspatial.com/docs/nsdk/how-to/vps/creating_device_maps/?platform=kotlin # How to Create a Device Map Before you can use a device map in your AR application, you will need to create and save it. In this tutorial, we will go over how to create and save a device map in your Kotlin project, as well as some tips for how to get the most out of device mapping. ## Prerequisites Ensure your Kotlin project is set up for Niantic SDK use. For more information, see [Set up the NSDK in Kotlin](https://www.nianticspatial.com/docs/nsdk/setup/#set-up-the-nsdk-in-kotlin). This example also assumes you are familiar with how to set up a VPS session (see [Getting Started with VPS](https://www.nianticspatial.com/docs/nsdk/how-to/vps/adding_vps/)). ## Creating a Device Map Before you can begin creating a device map, you will need to set up and configure the VPS session, as well as acquiring an instance of the `DeviceMappingSession` and `MappingStorageSession` from the NsdkSession. The VPS session must be configured to enable Device Map Localization in order to actually create a Device Map. ```kotlin // Acquire the NSDK sessions we will need val nsdkSession = NSDKSession(apiKey = "your-api-key") val vpsSession = nsdkSession.vps.acquire() val mappingSession = nsdkSession.mapping.acquire() val mapStoreSession = nsdkSession.mapStore.acquire() // Variables to store the data for the root map anchor, which you will need in order to place content within a Device Map var rootAnchorBase64 by mutableStateOf(null) var vpsRootAnchorId by mutableStateOf(null) // Example config, see documentation for all possible config options. // The important setting here is enableDeviceMapLocalization = true val config = VPSConfig( enableContinuousLocalization = true, enableDeviceMapLocalization = true ) try { vpsSession.configure(config) } catch (e: NsdkStatusException) { Log.e("DeviceMapping", "Configuration failed: ${e.message}") } // Lastly, start the mapping session mappingSession.start() ``` Now you can begin the recording by calling `mappingSession.startCreating()`, and end the recording by calling `mappingSession.stopCreating()`. > **Note:** > > Each time you want to record a new Device Map, remember to reset the VPS session. This will ensure the VPS anchors are localizing to the current map data. > > Additionally, it takes a few frames for the VPS session to begin successfully tracking the mapped space, so you will need to confirm the root anchor has been created before the map can be used. This coroutine will begin mapping, record for 10 seconds, then automatically stop: ```kotlin lifecycleScope.launch { // Begin the actual recording of the Device Map data mappingSession.startCreating() // Wait for the root anchor to be set up, and VPS tracking to succeed while(rootAnchorBase64 == null) { rootAnchorBase64 = mapStoreSession.createRootAnchor() if (rootAnchorBase64 == null) continue vpsSession.start() try { vpsRootAnchorId = vpsSession.trackAnchor(rootAnchorBase64!!) Log.i("DeviceMapping", "Started tracking anchor: ${vpsRootAnchorId}") } catch (e: NsdkStatusException) { Log.e("DeviceMapping", "Failed to track anchor ($e)") } } // Delay to allow the mapping session to record for 10 seconds delay(10000) // Stop the recording mappingSession.stopCreating() // Reset VPS and clear the root anchor data for the next recording vpsRootAnchorId?.let { vpsSession.removeAnchor(it) } vpsSession.stop() vpsRootAnchorId = null rootAnchorBase64 = null } ``` Once you are finished with your mapping session, be sure to clean up both the Mapping and VPS sessions by stopping and closing them: ```kotlin mappingSession.stop() mappingSession.close() vpsSession.stop() vpsSession.close() ``` ## Saving Device Maps Once you have finished recording, Device Map data in the `MappingStorageSession` can be saved to disk, which can be re-loaded at a later time or shared to other devices. To save this data, make sure you are not currently scanning, and use `mapStoreSession.getData()` to get the current Device Map data as a ByteArray, which can then be written to a file. The following function will save the map to a file with provided file name: ```kotlin // Saves the Device Map data to the application's default file directory. Note that fileName should include the extension if any is needed. fun saveMapToDisk(context: Context, fileName: String): Boolean { val mapData = mapStoreSession.getData() if (mapData == null) { Log.e("DeviceMapping", "Tried to save map but map has no data.") return false } try { val file = File(context.filesDir, fileName) FileOutputStream(file).use { output -> output.write(mapData) } Log.i("DeviceMapping", "Map (${mapData.size} bytes) saved successfully to: ${file.absolutePath}") return true } catch (e: Exception) { errorMessage = Log.e("DeviceMapping", "Failed to save map: ${e.message}") return false } } ``` ## Device Mapping Tips - Because device mapping relies on a single scan, localization and tracking accuracy depend heavily on how well you scan the area. If you remember one tip, let it be this: **if you are having localization issues, don't be afraid to re-scan!** - Lighting matters a lot when scanning an area. If the lighting during localization doesn't match the scan, you will need to re-scan. (This includes both outdoor and indoor lighting!) - For best results, follow these guidelines when scanning: - Focus on distinctive objects in the area that are unlikely to move between scanning and localization, such as furniture, household fixtures, or statues. - Avoid looking primarily at flat surfaces without color variation, such as the ground, grass, walls, and floors. - Move around while scanning! The more viewpoints you see an object from, the better the map of it will be. ## Next Steps Once you have created and saved a device map, move on to [How to Place Real-World Content Using a Device Map](https://www.nianticspatial.com/docs/nsdk/how-to/vps/using_device_maps/).