Advanced VPS

Introduced in ViroReact 3.1.0, released with ReactVision Spatial 1.4.0, Editor 1.6.0 and StudioGo 1.8.0.

Advanced VPS (visual positioning system) lets your app scan a real place with a phone, then find that place again later, on any iOS or Android device, and pin content to it. ReactVision Spatial turns each scan into a map that devices localise against, and can also build a photoreal mesh, a Gaussian splat, the recorded camera poses and the objects it found in the place.

This section has four pages:

What Advanced VPS is (this page): the pieces, the files a scan builds, where localisation runs, platforms and pricing.
Set up Advanced VPS: plan, billing, project, keys and user tokens, the Expo plugin and depth.
Use Advanced VPS in your app: record and upload scans, then track a place with <ViroVPS> and <ViroVPSAnchor>.
Retrieve your scans with the API: list locations and scans and download their files from your backend, then load the mesh in ViroReact.

How it works

Record. A phone records the place with ViroReact's AR session recorder (startRecording / stopRecording), optionally with the device's depth (LiDAR on iOS, the ARCore Depth API on Android). You can also scan with StudioGo.
Upload. uploadScanRecording() zips the recording on the device and uploads it to ReactVision Spatial as a scan of a location.
Process. ReactVision Spatial builds the map, and whatever else you asked for, from the recording. The map checks itself against its own recording. If it passes, the map is accepted, and the newest accepted scan becomes the location's active map.
Track. <ViroVPS> finds the location (by id, by GPS or from the camera image), localises the device in its map and keeps tracking it. Anything inside <ViroVPSAnchor> sits in the map's frame, so it appears in the same real-world spot on every device and in every session.

Locations, scans and maps

Location: a place, with a name and, optionally, a latitude and longitude. A place without GPS can only be found by id or from the camera image.
Scan: one uploaded recording of a location, and the files built from it. Its status goes awaiting_upload, queued, processing, then succeeded or failed.
Accepted map: a map with at least 500 points that localised at least 70% of its self-check frames with a median position error of 10 cm or less. Only accepted maps are billed and only they become a location's active map.
Later scans of a location are aligned to the active map it had when they were submitted, so their files are built in that map's frame.
Merge: once a location has two accepted scans whose recordings were kept (keepRecording), ReactVision Spatial rebuilds a map from several scans' recordings. A merge appears as a scan with kind: "merge".
Shared or per user: a location made in the Editor, from StudioGo or by your backend without an app user is shared with every user of the project. A location or scan made for one signed-in app user belongs to that user.

What a scan builds

Every scan builds the map. You choose the rest with outputs when you upload (default: the mesh).

File (`kind`)	What it is	Who can download it
`map`	`map.rvmap`, the map devices localise against.	Any key or user token
`world_mesh`	The mesh, untextured and decimated. `<ViroVPS worldMesh>` loads it for occlusion and physics against the real place.	Any key or user token
`semantic`	Detected objects (`semantic.json`): COCO class names such as `chair` or `tv`, with position, bounds and confidence. Needs `mesh`.	Any key or user token
`mesh`	The textured mesh, as binary glTF (`.glb`). Its detail is set by `meshQuality` (`low` builds no HD mesh).	Secret key or user token
`splat`	A 3D Gaussian splat (PLY).	Secret key or user token
`poses`	The camera pose and intrinsics for each recorded frame.	Secret key or user token

Every file is in the map's frame, in metres, with Y up: the same coordinates as the children of <ViroVPSAnchor>. The mesh, splat and poses are a photoreal capture of the place, so a client key cannot download them. See Retrieve your scans with the API.

Each scan also reports its quality: the map's self-check figures and, for a scan with a mesh, mesh_confidence (good, fair or poor, with reasons such as blank walls or a fast sweep). Mesh confidence never decides whether the map is accepted.

Localising on the device or on the server

`localization`	How it works	Best for
`"device"` (default)	The location's map is downloaded and the phone matches the camera against it.	Most apps.
`"server"`	No map is downloaded. The phone sends a camera frame about once a second to the VPS server, which answers with the pose, then one every 10 seconds once converged to correct drift.	Places that change between days, lighting or moved furniture. Needs a paid plan, a map built for server mode and a network round trip per fix.

startTracking() finds the location in one of three ways:

A location id, when your app already knows the place.
"auto": the nearest location with a map, from the device's geospatial pose. Without a GPS fix or a location nearby (indoors, for example) it falls back to "visual".
"visual": image search on the VPS server finds the project's location from what the camera sees. No GPS needed.

Platform support

Capability	iOS	Android	Meta Quest, Apple Vision Pro, web
Record a scan (`startRecording`)	✅	✅	❌
Record depth with the scan	✅ (LiDAR)	✅ (ARCore Depth API)	❌
Upload a scan (`uploadScanRecording`)	✅	✅	❌
Track a place (`<ViroVPS>`, `<ViroVPSAnchor>`)	✅	✅	❌
Open an Editor scene placed in a location	✅	✅	❌

On Apple Vision Pro and the web, <ViroVPS> reports unsupported and <ViroVPSAnchor> renders nothing. On Meta Quest, StudioGo asks the wearer to open a placed scene on a phone. Your backend can call the Advanced VPS API from anywhere.

Pricing

Advanced VPS needs a paid ReactVision plan. It is billed as compute time, from the same monthly pool as environment renders and co-location.

Scan processing: $0.60 a minute, only for scans whose map is accepted. A failed or rejected scan is not billed. A high quality mesh takes about 1.75 times as long to process.
Server-mode localisation: $0.60 a minute by default, the same rate as scan processing.
Not billed: reads, downloads (including the map download for device mode) and image searches.
Included credit: $5 a month on Basic and $15 on Pro. Usage beyond it is invoiced on your plan's renewal date.
Spend limit: owners and admins set a monthly compute spend limit on the team's Usage page in the Editor. The default is $100. Past it, Advanced VPS answers 403 COMPUTE_SPEND_LIMIT_REACHED until the next usage period.
Storage: kept recordings and every file a scan builds count against the team's storage quota.

See Plans, usage and compute billing and Limits.

What Advanced VPS is not

Not the room-scale VPS of ViroReact 3.0. The VPS page's startScan / finishScan host a room scan through the cloud-anchor pipeline. Advanced VPS is a separate workflow with its own maps, API and components.
Not a cloud or geospatial anchor. An anchor is one point. An Advanced VPS location is a mapped place, and you can put any number of objects anywhere in its frame.
Not on headsets or the web. Recording, uploading and tracking run on iOS and Android phones and tablets only.
Not offline. Finding a location and downloading its map needs ReactVision Spatial, and server mode needs the network for every fix. Once a map is loaded, device mode matches on the phone.
Not free. Creating locations and scans and uploading recordings need a paid plan.

In the Editor and StudioGo

From Editor 1.6.0 and StudioGo 1.8.0 (paid plans):

VPS Locations. Each project in the Editor has a VPS Locations page. It shows each scan's processing progress and quality readings, a 3D preview with measuring and the recorded camera views, and every file to download: the textured mesh (GLB), the Gaussian splat (PLY), camera poses and detected objects (chairs, tables and so on, placed on the mesh).
Place scenes in a location. Bind a scene to a location, and the Editor's scene editor shows the place's mesh so you can position content against it. The scene then shows up exactly where you put it, in StudioSceneNavigator. Such a scene needs ViroReact 3.1.0 or later.
Scan with StudioGo. StudioGo on iOS and Android scans a place in a short walk, with an optional mesh quality and object detection, checks a place's map by localising against it, and shows a place's map and mesh in 3D.
Use a scan on its own. You can download a scan's files and use them in your own app or pipeline, without placing any scene.