# How to Download a Mesh Using the API Source: https://www.nianticspatial.com/docs/nsdk/how-to/vps/mesh_download/?platform=kotlin With the Mesh Download API, you can download and create a mesh of any Site at runtime, allowing you to dynamically create mesh overlays in AR scenes. This feature makes it easier to test AR experiences by allowing you to check that your mesh lines up with the real world without having to leave the test environment. For example, you can download a stored mesh after localizing to see how far offset your localization is and figure out how it needs to change. Mesh downloading also allows developers to place content in scenes and explore environmental interactions without needing to stop testing and set up each mesh they want to try. A Site mesh is delivered as a stream of **chunks** rather than as a single download. Identify the map by the **VPS map asset ID** of the map you localized to. The first request starts the download process, and mesh chunks are received via polling the API. Chunks arrive closest-first relative to a geographic position you supply, so the geometry nearest the user renders while the rest is still downloading. You can cap how much mesh data the request downloads to help with rendering large maps. > **Warning:** > > **Anchor payload mesh download APIs are deprecated** > > The APIs for downloading meshes using a Site's anchor payload are deprecated. > These APIs do not support maps captured by 360 cameras or location-based streaming. > Site IDs and asset IDs are the preferred mechanisms for identifying maps in NSDK. > Use the streaming, asset-based API described on this page instead. > > | Platform | Deprecated API | Migrate To | > | --- | --- | --- | > | Unity | `LocationMeshManager.GetLocationMeshForPayloadAsync` | `LocationMeshManager.GetLocationMeshChunksByVpsMapAssetIdAsync` | > | Swift | `NSDKMeshDownloader.requestLocationMesh(payload:)` | `NSDKMeshDownloader.requestLocationMeshByAsset(vpsMapAssetId:)` | > | Kotlin | `MeshDownloaderSession.download(payload =)` | `MeshDownloaderSession.downloadByAsset(vpsMapAssetId =)` | ## Prerequisites You will need a Kotlin project with NSDK installed and the VPS map asset ID of the map you want a mesh for. For more information, see [Set up the NSDK in Kotlin](https://www.nianticspatial.com/docs/nsdk/setup/#set-up-the-nsdk-in-kotlin) and [Niantic Spatial VPS](https://www.nianticspatial.com/docs/nsdk/features/lightship_vps/). ## Localize and get the VPS map asset ID First, localize to the Site. Then, fetch the Site's assets and get the ID of its production VPS asset. `Vps2LocalizedAsset` contains the asset ID of the VPS map: ```kotlin val vps2Session = nsdkSession.vps2.acquire() vps2Session.localize(siteId = siteId) ``` ```kotlin vps2Session.localizationUpdates .onEach { localization -> val asset = localization.localizedAsset ?: return@onEach startMeshDownload(vpsMapAssetId = asset.assetId) } .launchIn(lifecycleScope) ``` `localizedAsset` is `null` until a visual localization succeeds. If you need the asset ID before localizing, fetch it from the [Sites API](https://www.nianticspatial.com/docs/nsdk/features/sites/) instead: ```kotlin val sitesSession = nsdkSession.sites.acquire() val assets = sitesSession.requestAssetsForSite(siteId) val vpsMapAssetId = assets.assets.firstOrNull { asset -> asset.assetType == AssetType.VPS_INFO && asset.deployment == AssetDeploymentType.PRODUCTION }?.id ``` ## Stream a Site mesh The `MeshDownloaderSession` downloads mesh geometry and textures for Sites at runtime. Create a session from an existing `NSDKSession` instance: ```kotlin val nsdkSession = NSDKSession( accessToken = "YOUR_ACCESS_TOKEN", useLidar = false ) val meshDownloaderSession = nsdkSession.meshDownload.acquire() ``` Call `downloadByAsset()` with the VPS map asset ID and the device's current geographic position. It returns a cold `Flow`, so the download starts when you collect it. The download runs asynchronously, and mesh chunks are received one by one: ```kotlin lifecycleScope.launch { var terminalError: MeshDownloaderError? = null meshDownloaderSession.downloadByAsset( vpsMapAssetId = vpsMapAssetId, latitude = latitude, longitude = longitude, getTexture = true, maxChunks = 0, // Number of nearest chunks to download, default: 0 (no limit) maxSizeKb = 0 // In kilobytes, default: 0 (no cap) ).collect { result -> when (result) { is NSDKResult.Success -> { // Render this chunk (MeshDownloaderData) as soon as it arrives. addMeshChunk(result.value) } is NSDKResult.Error -> terminalError = result.code } } when (terminalError) { null, MeshDownloaderError.NONE -> Log.i("MeshDownload", "Download complete") // A size cap stopped the download. Every chunk that fit under the cap has // already been delivered, so treat this as a successful early stop. MeshDownloaderError.SIZE_LIMIT_REACHED -> Log.i("MeshDownload", "Size limit reached") else -> Log.e("MeshDownload", "Download failed: $terminalError") } } ``` Each `MeshDownloaderData` exposes `meshData` (a `MeshData` with `vertices`, `indices`, `normals`, and `uvs`), `imageData` (the chunk's texture image), and `transform` (the chunk's pose). `latitude` and `longitude` only decide the order the chunks arrive in. They do not affect the position of the mesh itself. Cancelling the collecting coroutine stops the download. ## Position the mesh chunks Chunk vertices are in the chunk's own local space, in meters, and each chunk's `transform` places the chunk relative to the VPS map's own origin. Get the pose of that origin in AR tracking space from `getAssetTrackingData(assetId)` and place the chunks relative to it. Continue polling for tracking data: the pose refines as the device moves, and it's `null` until the asset is fully tracked. ```kotlin val tracking = vps2Session.getAssetTrackingData(vpsMapAssetId) ?: return val assetTransform = FloatArray(16).also { tracking.assetToLocalTrackingTransform.toMatrix(it, 0) } // modelMatrix = assetToLocalTrackingTransform * chunk.transform val modelMatrix = FloatArray(16) Matrix.multiplyMM(modelMatrix, 0, assetTransform, 0, chunk.transform, 0) ``` ### Rendering a downloaded mesh When you build geometry from `meshData`, make two adjustments so each chunk appears in the correct orientation and with the scanned texture: > **Tip:** > > **Convert the coordinate convention** > > VPS mesh coordinates use OpenCV convention (**Y-down, Z-forward**), while ARCore uses OpenGL convention (**Y-up, Z-back**). > Correct the coordinate convention by **negating Y and Z** components of the geometry data (rotating 180 degrees around the X axis) so that the mesh appears upright and stays aligned with the localized Site. > > If you apply the correction as a transform instead of modifying the vertex buffer itself, apply it to the mesh transform, after the asset transform and chunk transform. In other words, use `asset * chunk * correction`, not `correction * asset * chunk`. Apply the correction to the mesh itself rather than to the whole world transform. > **Tip:** > > **Apply the texture** > > To show the scanned texture, do the following: > > 1. Download the mesh with `getTexture = true`. > 2. Decode the chunk's `imageData` into a texture. Some meshes are untextured and return an empty `ByteArray`, so fall back to an untextured material in that case. > 3. Upload `meshData.uvs` and use those UVs when you sample the texture in your shader. > > If the texture appears upside down in a raw OpenGL renderer, flip the V coordinate in the shader with `1.0 - uv.y` because decoded image rows are top-down, while OpenGL texture coordinates are bottom-up. ## Textures and 360 captures Meshes generated from 360 camera captures are served as decimated, **untextured** meshes, so it's recommended to render them with a vertex color or wireframe material to avoid covering the AR camera view with opaque surfaces. Due to the decimation, their level of geometry detail will be lower than the original reconstruction in Scaniverse. ## Known Issues - Some meshes can be quite large. If download size or runtime performance is a concern, limit the number of chunks or set a maximum download size. - A maximum download size is checked after each chunk is delivered, so the chunk that crosses the limit is still delivered, and the total downloaded size can exceed the limit by up to one chunk. ## More Information See [`MeshDownloaderSession`](https://www.nianticspatial.com/docs/api/kotlin/com.nianticspatial.nsdk.mesh.MeshDownloaderSession) in the Kotlin API reference.