localize
Declaration
Summary
Throws
NsdkInvalidArgumentStatusException— ifsiteIdis empty.
Parameters
| Name | Type | Summary |
|---|---|---|
| siteId | String | The identifier of the site to localize to. |
Overload 1
Summary
Requests localization to one VPS map asset of a site.
Like the site-ID localize overload, but assetId narrows it to that single asset of any
deployment, including non-production ones. assetId is the VPS map asset's ID, as a UUID
(32 hex digits, optionally 0x-prefixed, or the canonical 8-4-4-4-12 form). This is not the
ID of the asset group's mesh or splat. An empty string localizes against the site's
production-deployed assets, exactly as the site-ID overload does.
Progress is reported on localizationRequestRecords on the same terms as the site-ID
overload. When the site has no localizable asset with that ID, the request fails with
Vps2LocalizationError.ASSETS_NOT_FOUND. stopLocalize with the site's ID stops it.
Throws
NsdkInvalidArgumentStatusException— ifsiteIdis empty, orassetIdis neither empty nor a UUID.
Parameters
| Name | Type | Summary |
|---|---|---|
| siteId | String | The identifier of the site the asset belongs to. |
| assetId | String | The VPS map asset's ID, or empty for the site's production assets. |
Overload 2
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.
Starts the session if it is not already started.
Note: assets already submitted for localization stay in the localization set until
stopLocalize removes them; stopLocalize for every site also cancels a request still in
progress. Every extra asset 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,radiusMetersis negative, or any argument is not a finite number.
Parameters
| Name | Type | Summary |
|---|---|---|
| latitude | Double | Latitude of the search centre in degrees, in the range [-90, 90]. |
| longitude | Double | Longitude of the search centre in degrees, in the range [-180, 180]. |
| radiusMeters | Double | Search radius in meters. Pass 0.0 (the default) to use the native default of 100 m. Must not be negative. |
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
localizationRequestRecordsas a record of typeVps2LocalizationRequestType.ASSET_INFO—Vps2LocalizationRequestStatus.PENDINGondispatch, then
Vps2LocalizationRequestStatus.COMPLETED, orVps2LocalizationRequestStatus.FAILEDwith the record's error set (e.g.Vps2LocalizationError.SITE_NOT_FOUNDwhen no such site exists, orVps2LocalizationError.ASSETS_NOT_FOUNDwhen the site has nothing localizable in it).COMPLETEDmeans every production-deployed asset in the site was submitted forlocalization, not that localization succeeded — observe
localizationUpdatesfor 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.
Starts the session if it is not already started.
Note: assets already submitted for localization stay in the localization set until
stopLocalizeremoves them;stopLocalizefor the site also cancels a request still inprogress. Each additional site increases the size of every cloud localization request and the per-frame
target-selection cost, so keep the number of sites small.