Skip to main content
←API Reference ←com.nianticspatial.nsdk.vps2 ←Vps2Session

localize

Declaration​

fun localize(siteId: String)

Summary​

Requests localization to a site, identified by its site ID.


Localizes against the site's production-deployed VPS assets and only those: an asset that
has not been deployed to production cannot be localized against. This is an asynchronous
operation: progress is reported on localizationRequestRecords as a record of type
Vps2LocalizationRequestType.ASSET_INFO — Vps2LocalizationRequestStatus.PENDING on
dispatch, then Vps2LocalizationRequestStatus.COMPLETED, or
Vps2LocalizationRequestStatus.FAILED with the record's error set (e.g.
Vps2LocalizationError.SITE_NOT_FOUND when no such site exists, or
Vps2LocalizationError.ASSETS_NOT_FOUND when the site has nothing localizable in it).
COMPLETED means every production-deployed asset in the site was submitted for
localization, not that localization succeeded — observe localizationUpdates for the outcome.


Requests are additive: calling this again does not disturb a request already in flight,
and the sites accumulate. Each request produces its own records, but the caller is not
given its record identifier, so records from concurrent requests are distinguishable
only by the order in which they arrive.


May be called before start; requests are deferred and dispatched in order when VPS2
starts.


Note: assets already submitted for localization remain in the localization set for the
lifetime of the session. There is no way to stop localizing against a site once its
assets have been submitted, and no way to cancel a request in progress. Each additional
site permanently increases the size of every cloud localization request and the
per-frame target-selection cost, so keep the number of sites small.

Throws​

  • NsdkInvalidArgumentStatusException — if siteId is empty.

Overload​

fun localize(latitude: Double, longitude: Double, radiusMeters: Double = 0.0)

Summary​

Requests localization near a geographic coordinate.


Looks up every site holding VPS assets within radiusMeters of the coordinate and localizes
against all of their assets. This is an asynchronous operation: progress is reported on
localizationRequestRecords as a record of type Vps2LocalizationRequestType.ASSET_INFO —
Vps2LocalizationRequestStatus.PENDING on dispatch, then
Vps2LocalizationRequestStatus.COMPLETED, or Vps2LocalizationRequestStatus.FAILED with
Vps2LocalizationError.ASSETS_NOT_FOUND when no site fell within the radius or none of the
sites had a localizable asset. COMPLETED means every asset found was submitted for
localization, not that localization succeeded — observe localizationUpdates for the outcome,
and Vps2Localization.localizedAsset for which asset was matched.


The coordinate is supplied by the caller; this does not read the device's GPS.


Requests are additive: calling this again does not disturb a request already in flight, and
the assets accumulate.


May be called before start; requests are deferred and dispatched in order when VPS2 starts.


Note: assets already submitted for localization remain in the localization set for the
lifetime of the session. There is no way to stop localizing against them, and no way to
cancel a request in progress. Every extra asset permanently increases the size of every cloud
localization request and the per-frame target-selection cost, so keep radiusMeters small.

Throws​

  • NsdkInvalidArgumentStatusException — if a coordinate is outside its valid range, radiusMeters is negative, or any argument is not a finite number.