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 and will be saved as 1 min clips. 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 each scan clip will not be merged into one single mesh for VPS. They will be available in the lightship.dev developer portal as individual meshes.
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, and the number of scan clips.
You can tap the thumbnail to open an interactive view of the pending mesh from your scan. In the scan details card, you’ll see a list view of all 20 to 60 second clips associated with a scan session. Tapping EDIT will allow you to delete or upload the individual scan clip.
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 an individual scan collection.
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 localizability 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 localizability 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 app is not available in the Niantic Wayfarer App, you can submit locations to Niantic for consideration to include in Niantic’s Wayspot database. Once your nomination is accepted by Niantic, you can start the VPS-activation process by contributing scans to the Wayspots.
The Wayspot nomination flow is a temporary workflow and will be supported in the Niantic Wayfarer app in the future. This nomination flow is only available to Lightship Developers.
To submit your nominations, gather the required information for your Wayspots (listed below) and navigate to the submission form. Please ensure you use the same email address you’ve used to sign up for Lightship in the lightship.dev portal. All official communication will be sent only to your registered email address.
You’ll need to download the Wayspot nomination template (a CSV file) from the link in the submission form. After you download the CSV file, you will need to open it with a spreadsheet app (e.g. Google Sheets, Microsoft Excel). Then, you will need to provide the following information for each of your requested Wayspots:
Title of the Wayspot: up to 128 characters
Description of the Wayspot: up to 512 characters, will be displayed 20 characters per line
GPS coordinates that best represents the center of the intended VPS experience (see details below). Go to this link for more information on how to get coordinates.
Latitude of the Location (decimal format, 6 decimals)
Longitude of the Location (decimal format, 6 decimals)
Image of the Wayspot. Keep in mind the following image requirements:
Minimum size requirements 512x512 px
Recommended size 800x800 px or higher
Filename should be in the format of
DeveloperName_title.jpeg, no spaces or special characters
You’ll need to provide a URL for each image, to share the image with Niantic. Please note that the image URLs need to be publicly accessible in order to be reviewed. You can verify if the links work by pasting them in an incognito-mode browser window and confirming that the images load.
The image should be one that you have taken yourself, not one you have obtained from another source.
Once you finish filling out Wayspot information, you will need to save the spreadsheet as a CSV file and upload it in the Attachments section of the submission form.
Once your nominations have been reviewed and decided upon by Niantic, you will receive an update from Niantic. Please look for an email from firstname.lastname@example.org. We may provide direct feedback on how to improve the submission if they do not meet Niantic’s quality standards. Nominated Wayspots that Niantic accepts will be viewable in Niantic Wayfarer App within 2 business days of that notice.
Keep in mind the eligibility criteria and rejection criteria listed in the following sections when submitting Wayspots.
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/