# How to Download a Mesh Using the API Source: https://www.nianticspatial.com/docs/nsdk/how-to/vps/mesh_download/?platform=swift 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 Swift 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 Swift](https://www.nianticspatial.com/docs/nsdk/setup/#set-up-the-nsdk-in-swift) 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: ```swift let vps2Session = nsdkSession.acquireVps2Session() try vps2Session.localize(siteId: siteId) // Alternatively, pass in a lat/long to automatically target nearby sites ``` ```swift vps2Session.$latestLocalization .receive(on: DispatchQueue.main) .sink { [weak self] localization in guard let self, let asset = localization?.localizedAsset else { return } self.startMeshDownload(vpsMapAssetId: asset.assetId) } .store(in: &cancellables) ``` `localizedAsset` is `nil` until a visual localization succeeds. If you need the asset ID before localizing, you can fetch it from the [Sites API](https://www.nianticspatial.com/docs/nsdk/features/sites/) instead: ```swift let sitesSession = nsdkSession.acquireSitesSession() let assets = try await sitesSession.requestAssetsForSite(siteId: siteId) let vpsMapAssetId = assets.assets.first { $0.assetType == .vpsInfo && $0.deployment == .production }?.id ``` ## Stream a Site mesh The `NSDKMeshDownloader` downloads mesh geometry and textures for Sites at runtime. Create an `NSDKMeshDownloader` instance from an existing `NSDKSession`: ```swift let nsdkSession = NSDKSession(accessToken: "YOUR_ACCESS_TOKEN") let meshDownloader = nsdkSession.acquireMeshDownloader() ``` Call `requestLocationMeshByAsset()` with the VPS map asset ID and the device's current geographic position. The download runs asynchronously, and mesh chunks are received sequentially by polling the API. For large maps, set `maxSizeKb` or `maxChunks` to limit the download size and help manage memory usage. Mesh downloading will automatically stop once it reaches either limit. ```swift let stream = meshDownloader.requestLocationMeshByAsset( vpsMapAssetId: vpsMapAssetId, latitude: coordinate?.latitude ?? 0.0, longitude: coordinate?.longitude ?? 0.0, getTexture: true // Optional parameters: // maxChunks -> number of nearest chunks to download, default: 0 (no limit) // maxSizeKb -> in kilobytes, default: 0 (no cap) // pollingInterval -> in seconds, default: 0.1 ) do { for try await chunk in stream { // Render this chunk (MeshDownloaderChunk) as soon as it arrives. addMeshChunk(chunk) } } catch MeshDownloaderResults.Error.sizeLimitReached { // 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. } catch { print("Failed to download mesh: \(error)") } ``` Each `MeshDownloaderChunk` includes geometry data in [`MeshData`](https://www.nianticspatial.com/docs/api/swift/NSDK.class-MeshData), including `verticesPtr`, `indicesPtr`, `normalsPtr`, and `uvsPtr`, the texture image in `imageData`, and the chunk transform in `transform`. `latitude` and `longitude` only decide the order the chunks arrive in. They do not affect the position of the mesh itself. Cancelling the task that iterates the stream 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 `assetTrackingData(assetId:)` and place the chunks under it. Continue polling for tracking data: the pose refines as the device moves, and it's `nil` until the asset is fully tracked. ```swift guard let tracking = vps2Session.assetTrackingData(assetId: vpsMapAssetId) else { return } // Pose the parent entity once, then add each chunk with its own local transform relative to the VPS map origin. assetAnchor.transform = Transform(matrix: tracking.assetToTrackingTransform) ``` ```swift let modelEntity = ModelEntity(mesh: meshResource, materials: [material]) modelEntity.transform = Transform(matrix: chunk.transform) assetMeshRoot.addChild(modelEntity) ``` ### Rendering a downloaded mesh in SceneKit If you use SceneKit to render the mesh, [`MeshData.toSCNGeometry()`](https://www.nianticspatial.com/docs/api/swift/NSDK.MeshData.method-toSCNGeometry) converts the mesh coordinates and texture coordinates for you. You can create an `SCNGeometry` from each chunk and place it in an `SCNNode`. If you want the scanned texture, create an `SCNMaterial` from `imageData` and pass it to `toSCNGeometry(material:)`. ### Rendering a downloaded mesh in RealityKit If you build a RealityKit `MeshResource` or `ModelEntity` from `chunk.meshData`, handle the following NSDK-specific details so that each mesh chunk appears in the expected orientation and with the correct texture mapping. 1. Correct the coordinate convention by **negating Y and Z** components of the geometry data (rotating 180 degrees around the X axis). NSDK mesh coordinates use OpenCV conventions and RealityKit coordinates use OpenGL conventions, so this rotation corrects the mesh's orientation. For example, rotate the mesh entity by `simd_quatf(angle: .pi, axis: [1, 0, 0])`, in addition to applying each chunk's `transform`. 2. Apply the scanned texture. Download with `getTexture: true`, use `meshData.uvsPtr` as the `MeshDescriptor` texture coordinates, and decode `imageData` into a `TextureResource` for the material's base color. `imageData` is empty when the chunk has no texture, so fall back to an untextured material in that case. ## 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 [`NSDKMeshDownloader`](https://www.nianticspatial.com/docs/api/swift/NSDK.class-NSDKMeshDownloader) in the Swift API reference.