Generating Scans for VPS
Lightship VPS uses VPS-activated Wayspots, 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 Wayspots.
Before you start using the Niantic Wayfarer app to scan objects or locations, make sure you understand the concepts behind Wayspots and Lightship VPS. In particular, you’ll need to understand concepts like VPS-activated Wayspots and Private VPS Locations.
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
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.
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 Niantic Wayspots, create Private Scans for Private VPS Locations for testing purposes, contribute additional scans for VPS-activated Wayspots, and test localization with VPS-activated Wayspots and Private VPS Locations. Each of these is detailed below.
Viewing Niantic Wayspots
If you need to understand the spatial distribution of existing Niantic Wayspots, including VPS-activated Wayspots, you can use the Niantic Wayfarer app to view Wayspots in the map view. The app lets you see nearby Niantic Wayspots. You can use the VPS toggle button on the top left to view which of these Wayspots are VPS-activated.
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 pink 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.
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.
Reporting a Wayspot
If you feel that a Wayspot does not meet Niantic’s Wayspot criteria (as described in “Eligibility Criteria” below), tap on REPORT THIS WAYSPOT at the bottom of the Wayspot details card, select a report reason, and tap Submit.
Creating Private VPS Locations
If you need a Private VPS location for testing your app with VPS, you can use the Niantic Wayfarer app to upload a Private Scan. This scan will be used to create a Private VPS-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. Note that private scans, being private, will not be discoverable through the VPS Coverage API.
Private Scans should only be used for development and testing purposes.
Before creating a Private Scan, be sure and review “Scanning Best Practices” and “Best Practices for Private Scans” below.
To start collecting a Private 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’ll then be prompted to select whether the scan is Public or Private. Select Private and tap Next. Note that 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 Private Scan once more before uploading it, and/or verify you selected Private 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.
Note 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 Private Scan, Niantic will turn it into a private 3D mesh within 4 hours. You’ll access and manage your Private VPS Locations through the Lightship.dev portal where you can check processing status, view generated meshes, and/or delete scans. For more details see Managing Private Scans.
Contributing Scans to Niantic Wayspots
If your app is having trouble localizing at a known Wayspot, it may be that the Wayspot doesn’t have enough scans to be VPS-activated. You can help improve scan quality over time by submitting additional scans of that Wayspot, and even at existing VPS-activated Wayspots.
Before creating a scan, be sure and review “Scanning Best Practices” below.
Once you are next to the Wayspot, tap on the Wayspot 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 Private VPS Locations” above, 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 Wayspot. 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.
If you need to test the scan quality of a known VPS-activated Wayspot or one of your successfully uploaded Private VPS Locations, you may do so using the Niantic Wayfarer app. You’ll need to go to the VPS-activated Wayspot location or Private VPS 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 VPS-activated Wayspot. To get the exact boundaries of the coverage area for a VPS-activated Wayspot, you’ll need to use the VPS Coverage API.
Scanning Best Practices
Scanned VPS-activated Wayspots or Private VPS Locations should be no larger than a 10-meter diameter around the location. For example, a typical statue would work as a VPS-activated Wayspot. 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 Private 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 Private scan.
Avoid including people in your private 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 Private Scan once more before uploading it, and/or verify you selected Private and not Public.
Note that you are limited to submitting up to 10 private scans per week.
Nominating New Wayspots
If the location you’d like to use in your VPS experience does not currently exist on the Niantic Map, you can nominate it as a new Wayspot with the Wayfarer App. Once you’ve downloaded and installed the app, you can enter the Wayspot nomination flow from the map view. After entering the workflow, you will be prompted to submit a title, description, and photo, and confirm the location of the new Wayspot. Your nomination will appear on the map and be ready for scanning within five minutes of submission.
In order to be selected as a Wayspot, nominations must:
Meet at least one of the three eligibility criteria
A great place for exploration
A great place for exercise
A great place to be social with others
Be a permanent physical, tangible, and identifiable place or object, or object that placemarks an area
Be safe and publicly accessible by pedestrians (indoor or outdoor)
Contain accurate information in the title, description, and photo
In order for a Wayspot to work well on Lightship VPS, it should meet the following criteria:
Have a clear focal point that fits within a 10m diameter sphere. Statues, murals, and building facades are all great candidates.
Have features that are distinct and consistent in appearance. A sandy beach, or a crowded patio space with moveable furniture will not work well.
Have minimal features that are reflective or transparent. Areas dominated by large plate glass windows or mirrors will not work well.
For a list of rejection criteria for Wayspots, see Rejection Criteria
For issues using the Niantic Wayfarer app, or issues with the scan submission process, please visit our developer forums at https://community.lightship.dev/