How to Install and Use Niantic Wayfarer
Lightship VPS uses Public Locations, which are noteworthy, publicly-accessible locations in the world that you can localize with using VPS. Niantic provides the Niantic Wayfarer app for creating scans for Public Locations and Test Scans.
The Niantic Wayfarer app uses different credentials from the Niantic Wayfarer program and website. The Niantic Wayfarer app is associated with your Lightship.dev account, and not any account you have associated with the Niantic Wayfarer program.
The Niantic Wayfarer app is in beta and functionality may change in a future release. Currently the app has not been fully optimized for lower-end devices.
Installing the Niantic Wayfarer App
You can install Niantic Wayfarer on iOS or Android.
iOS
The Niantic Wayfarer app requires iOS 12 or better and an iPhone 8 or better. A LiDAR-capable device is not required.
To install the Niantic Wayfarer App, go to Testflight for Niantic Wayfarer on your iOS device.
Android (Beta)
The Niantic Wayfarer app requires the ARCore package.
To install the Niantic Wayfarer app, go to Niantic Wayfarer on your Android device.
Using the Niantic Wayfarer app
The Niantic Wayfarer app can be used to view Public Locations, create Test Scans for Private VPS Locations for testing purposes, contribute supplemental scans for Public Locations, and test localization with Public Locations and Private VPS Locations. Each of these is detailed below.
Viewing Public Locations
If you need to understand the spatial distribution of existing Niantic Wayspots, including Public Locations, you can use the Niantic Wayfarer app to view Wayspots in the map view. You can use the VPS toggle button on the top right to view which of these Wayspots are Public Locations.
You can use the app to view Wayspots within about a square kilometer around you by tapping on Load Nearby Wayspots at the bottom of the map. The circle around your device location represents a 40m walking radius for reference. Zooming out will cluster Wayspots to declutter the map.
To view the details of a Wayspot, tap on the Wayspot marker on the map. The selected Wayspot marker will appear enlarged on this map. This will also load the Wayspot title, photos, and VPS activation status. When a wayspot is not VPS-activated, the Test VPS button is greyed out, and "Not VPS-activated" appears under VPS Status.
Select other Wayspot markers on the map to view other Wayspots, or tap the X in the details card to return to the default map view.
Scanning Best Practices
Scanned Public Locations or Test Scans should be no larger than a 10-meter diameter around the location. For example, a typical statue would work as a Public Location. An entire building, however, would not. One face or doorway/entrance into a building might work. We recommend sticking with smaller areas for starters (e.g. a desk, statue, or mural).
Before scanning, be aware of your surroundings and ensure you have the right to access the location you are scanning.
Remember to walk a full circle around the object and not just rotate around a single spot or wave the phone without actually moving. If the mesh that is generated on the device looks good, the 3D map constructed for VPS should be good too. Increasing the number of viewpoints the object is scanned from by moving around will make localization better. When moving as you scan keep in mind the following:
- Stand about 5 feet from your target object that you wish to scan and walk around it for 30s-1m, while keeping the target in view.
- Plan ahead to decide how you’ll move around the object or area that you want to scan. Make sure you have a clear path with as few obstructions as possible.
- Hold the device in Portrait mode. Move smoothly and avoid turning suddenly or bumping your device. This will improve tracking accuracy and reduce motion blur.
- Walk around the object you are scanning instead of standing in one location and moving your phone.
- You can revisit or rescan the same area multiple times, however, ensure your object/location fits into a 10-meter diameter sphere.
- Have your device camera looking straight at the area or object, not from a high or low angle.
Try to scan with optimal environment conditions. This includes:
- Avoid scanning when there are too many people around.
- Make sure your scene is well-lit. If you have to scan in a darker setting, it’s even more important to move slowly and smoothly.
Avoid uploading any scans that look incomplete or not representative of what you’re trying to scan.
The following video demonstrates some of these scanning best practices:
Best Practices for Test Scans
Scan an area which isn’t going to change throughout the day, where objects are not moving around too much. For example, if you scan your desk with your laptop on it and then remove the laptop while attempting a localization, things might fail.
- Before you submit the scan, verify that you’ve marked it as a Test scan.
- Avoid including people in your test scans to ensure the location is scanned accurately
- While saving the scan, select the Upload Later option instead of Upload Now. This option lets you review your test scan once more before uploading it, and/or verify you selected Test and not Public or Private.
You are limited to submitting up to 10 test scans per week.
Creating Test Scans
If you need a location for testing your app with VPS, you can use the Niantic Wayfarer app to upload a Test Scan. This scan will be used to create a location that will only be accessible to you and only localizable within apps that use an API key created with your Lightship.dev developer account.
Test scans, being private, will not be discoverable through the VPS Coverage API.
Test Scans should only be used for development and testing purposes.
Before creating a Test Scan, be sure and review Scanning Best Practices and Best Practices for Test Scans.
To start collecting a Test Scan, make sure you are on the default map view, with no Wayspot marker selected. In the location card below the map, tap on SCAN. This should open up the camera view with a start-recording button at the bottom. Tap on the start button to initiate the scan. Note that scans must be longer than 20s to be saved to your device. Ensure you have at least 1GB of available space on your device.
When you’re finished scanning, press the red stop button and your scan will automatically be saved to your device. You will then be prompted to select whether the scan is Public or Test. Select Test and tap Next.
Scans longer than 1 minute will be split into multiple meshes for VPS. The meshes will all be available in the Lightship.dev developer portal.
When asked if you want to upload now or later, we recommend selecting Upload Later so that you may review your Test Scan once more before uploading it, and/or verify you selected Test and not Public. After selecting Upload Later, tap DONE and then OKAY. Then tap the white back-arrow to exit the camera view.
To upload your saved scans, tap on the Logbook in the bottom menu bar to view any pending scan uploads. To view details of the scan, tap on the scan in the list view. This will display a thumbnail of the scan, the date, size, duration, type, and location.
You can tap the thumbnail to open an interactive view of the pending mesh from your scan. In the scan details card, you can delete or upload your scan.
In the main list view of all your pending scans, you can tap UPLOAD ALL to initiate the upload of all scans, or tap the blue upload button to initiate the upload of individual scans.
The Logbook only shows the scans saved to your device that are pending upload. So once you’ve uploaded your scans, and you leave the Logbook, they will no longer appear in the Logbook when you view it once again.
Once you’ve uploaded your Test Scan, Niantic will turn it into a private 3D mesh within 4 hours. You’ll access and manage your test scans through the Lightship.dev portal where you can check processing status, view generated meshes, and/or delete scans. For more details see How to Manage Test Scans.
Contributing Scans to Niantic Public Locations
If your app is having trouble localizing at a known Wayspot, it may be that the location doesn’t have enough scans to be a Public Location. You can help improve scan quality over time by submitting additional scans of that Public Location.
Before creating a scan, review the Scanning Best Practices.
Once you are next to the Public Location, tap on the Public Location marker in the map and drag up the Wayspot details card. At the top of the card, tap on SCAN to open your device’s camera and initiate the scan. Start scanning as described in Creating Test Scans, but using a Public scan type. Again, we recommend that you select Upload Later.
You can also create a scan from the default map view when a Wayspot marker is not selected. This type of “freeform” scan will allow you to scan, per above, but will then prompt you to associate your scan with a nearby location. We recommend you associate it with the one nearest to your scan location so that the imagery you capture in that scan is properly associated with the 3D mesh of that wayspot.
Testing Localizations
If you need to test the scan quality of a known Public Location or one of your successfully uploaded Test Scans, you may do so using the Niantic Wayfarer app. You’ll need to go to the location and use the TEST VPS feature from the map view. You can test VPS localization as long as you’re within the coverage area for the location. To get the exact boundaries of the coverage area for a location, you’ll need to use the VPS Coverage API.
