Components List
Browse the Navigation Kit components, assets and APIs for SPECS Lenses: places, the user's position, the place menu and the navigation arrow.
- Snapchat: not supported
- SPECS: fully supported
- Camera Kit Web: not supported
- Camera Kit Mobile: not supported
- SnapchatNot supported
- SPECSFully supported
- Camera Kit WebNot supported
- Camera Kit MobileNot supported
This page gives a high-level overview of the Navigation Kit package, then details its APIs in the Navigation Kit API reference.
Navigation Kit core components
Navigation Data Component
The NavigationDataComponent holds a list of Places, provides APIs to select a Place for
navigation, and fires events such as onArrivedAtPlace. The other components in the kit subscribe
to its events.
Place
A Place is a location the user can navigate to, with a name, a description, and an icon. These
specialized place types derive from the Place class:
GeoLocationPlace: a place that gets its position from a geoposition.CustomLocationPlace: a place, derived fromGeoLocationPlace, that gets its position from a LocatedAtComponent representing a Custom Location scanned on SPECS. Navigation uses the Custom Location's geoposition, refined by location tracking once the Custom Location is found.OverridableCustomLocationPlace: aCustomLocationPlacewhose position can be overridden; the places of a Custom Location Group use it (see PlacesFromLocationGroup).SceneObjectPlace: a place defined only in virtual space, with no physical location.
UserPosition and EditableUserPosition
EditableUserPosition implements the UserPosition interface and represents the user's position in
both virtual and geographic space. It provides APIs for the distance and bearing to a Place.
Define Navigation Kit places in the Inspector
ManualPlaceList
The ManualPlaceList component defines places in the Inspector and adds them to a
NavigationDataComponent when the Lens starts. The Navigation Kit prefab uses it for its sample
places. Set its Navigation Data Component field, then add places to any of its four lists:
| List | Each entry creates | Fields |
|---|---|---|
| Manual Geo Places | a GeoLocationPlace | Active, Latitude, Longitude, Label, Icon, Description, Distance To Activate (meters, default 10) |
| Scene Object Places | a SceneObjectPlace | Active, Scene Object, Label, Icon, Description, Distance To Activate (meters, default 10) |
| Custom Location Places | a CustomLocationPlace | Active, Located At, Center, Label, Icon, Description, Prompt Image, Distance To Activate (meters, default 10) |
| Custom Location Group Places | a group of places (PlacesFromLocationGroup) | Active, Custom Locations (a list of Custom Location Places) |
- Icon is the texture shown on the default 3D pin and in the compass carousel.
- Distance To Activate is how close, in meters, the user must be to visit the place.
- Prompt Image is an image that helps the user arrive at a Custom Location. The optional
Image Display field (an
IPlaceImageRegister) shows these images.
For a Custom Location Place, ManualPlaceList turns on changeLocatedAtEnabled, so the place
enables its LocatedAtComponent when the user comes near, and when navigation to the place starts.
PlacesFromLocationGroup
PlacesFromLocationGroup maps the members of a Custom Location Group to places. The relative
positions of a group's members are known, so as soon as one member is localized, it updates every
other member's place with an approximate position, which allows indoor navigation. Until then, each
place tracks from its geoposition. Once a member's LocatedAtComponent is localized, that place uses
the tracked position, the most accurate one. Each member's Center must be a child of its
Located At scene object, in the same order; otherwise it throws
Center points and located ats must be in the same order.
Navigation Kit assets
The package contains ready-to-use assets: a menu and two 3D navigation arrows.
- NavigationKit__PLACE_IN_SCENE.prefab, at the package root, is the example: dragging it
into the scene adds NavigationKitDemo, with the Navigation Kit Menu (a selection menu of
places) and AR Navigation (a 3D arrow that points to the selected
Place, with its distance and name). - ARNavigationPrefab [PUT_IN_SCENE], in the
ARNavigationComponentfolder, is the same arrow on its own, for a setup without the example menu. ARNavigation_Camera [PUT_UNDER_CAMERA], in the same folder, is a second arrow prefab that, as its name says, goes under the camera.

Together these form a working example of how to use the kit.
Navigation Kit scripts
These scripts control the assets:
ExampleMenu
A basic example of how to read the Places from the NavigationDataComponent, and how to select a
Place to navigate to. It expects at least 3 places.
ARNavigation
Controls the 3D arrow that guides the user. The script also shows how to subscribe to events from
the NavigationDataComponent, and how to use the orientation and distance functions. Within its
Here Radius (hereRadius, 3 meters by default) of the selected place, the arrow stops showing a
direction.
Navigation Kit API reference
This section details the functions and properties of the kit's main scripts.
NavigationDataComponent
Holds the navigation places and the tracking state, to build a guided experience. On this component
you add the places the user can navigate to, and select the place to navigate to. Its events fire
when navigation starts, when the user arrives at a place, when the list of places changes, and, in
tour mode, when every place has been visited. Each place uses the best tracking it has: a
CustomLocationPlace uses its Custom Location once it's found, and a group of places is updated
when one member is localized.
Inspector fields:
- User Camera: the camera whose transform is the user's position.
- Update Threshold: how often, in seconds, the user's geoposition is requested;
0for never. Default:1. - Tour Mode: when on, the user visits all places in turn, with completion tracking:
onArrivedAtPlacefires for every place reached, andonAllPlacesVisitedfires once all have been visited.
| Signature | Type | Description |
|---|---|---|
| METHODS | ||
addPlace | function (place: Place) → void | Adds a place of interest to the guided experience. Throws Null argument. for null. |
removePlace | function (place: Place) → void | Removes the place from the guided experience. |
getUserPosition | function () → UserPosition | Returns the user's position for navigation. |
navigateToPlace | function (place: Place) → void | Selects the place to give directions to and starts the tracking to navigate to it. Adds the place if it isn't registered yet. |
stopNavigation | function () → void | Clears the selected place and stops any tracking attached to it. |
| PROPERTIES | ||
status | NavigationStatus | The status of the navigation component. |
places | Place[] | The registered places. |
tourMode | boolean | Whether tour mode is on (the Tour Mode field). |
| EVENTS | ||
onNavigationStarted | PublicApi<Place> | Triggered when navigation starts. stopNavigation() triggers it with null. |
onPlacesUpdated | PublicApi<void> | Triggered when the list of places changes. |
onArrivedAtPlace | PublicApi<Place> | Triggered when the user reaches a place. |
onAllPlacesVisited | PublicApi<void> | Triggered once when all places have been visited. Fires only with tourMode on. |
NavigationDataComponent example code
The example subscribes to onNavigationStarted with add(), selects a place from a menu, and
selects the nearest place by distance.
- TypeScript
- JavaScript
@input navigationComponent: NavigationDataComponent
@input menuImage: Image
@input menuTitle: Text
onAwake(): void {
this.createEvent('OnStartEvent').bind(() => {
this.navigationComponent.onNavigationStarted.add((place) =>
this.onNavigationLocationSelected(place)
)
})
}
/*
* Called from a menu of Places that can be selected as the active target.
*/
public navigationLocationSelected(place: Place): void {
this.navigationComponent.navigateToPlace(place)
}
/*
* Selects the nearest Place to navigate to.
*/
public selectNearest(): void {
const userPosition = this.navigationComponent.getUserPosition()
let nearestPlace: Place | null = null
let nearestDistance = Infinity
for (const place of this.navigationComponent.places) {
const distance = userPosition.getDistanceTo(place)
if (distance !== null && distance < nearestDistance) {
nearestPlace = place
nearestDistance = distance
}
}
if (nearestPlace !== null) {
this.navigationComponent.navigateToPlace(nearestPlace)
}
}
/*
* Subscribed to navigationComponent.onNavigationStarted to update the menu.
*/
private onNavigationLocationSelected(place: Place | null): void {
if (place === null) {
this.menuTitle.text = ''
return
}
this.menuImage.mainPass.baseTex = place.icon
this.menuTitle.text = place.name
}
// @input Component.ScriptComponent navigationComponent
// @input Component.Image menuImage
// @input Component.Text menuTitle
script.createEvent('OnStartEvent').bind(function () {
script.navigationComponent.onNavigationStarted.add(onNavigationLocationSelected);
});
/*
* Called from a menu of Places that can be selected as the active target.
*/
function navigationLocationSelected(place) {
script.navigationComponent.navigateToPlace(place);
}
/*
* Selects the nearest Place to navigate to.
*/
function selectNearest() {
var userPosition = script.navigationComponent.getUserPosition();
var nearestPlace = null;
var nearestDistance = Infinity;
script.navigationComponent.places.forEach(function (place) {
var distance = userPosition.getDistanceTo(place);
if (distance !== null && distance < nearestDistance) {
nearestPlace = place;
nearestDistance = distance;
}
});
if (nearestPlace !== null) {
script.navigationComponent.navigateToPlace(nearestPlace);
}
}
/*
* Subscribed to navigationComponent.onNavigationStarted to update the menu.
*/
function onNavigationLocationSelected(place) {
if (place === null) {
script.menuTitle.text = '';
return;
}
script.menuImage.mainPass.baseTex = place.icon;
script.menuTitle.text = place.name;
}
NavigationStatus
The statuses of the navigation component.
| Name | Description |
|---|---|
| LocationNotSelected | No place is selected: navigation was stopped. Use the navigateToPlace(place: Place) function to select one. |
| Initializing | The initial status, before any place is selected: the resources for the tracking technology are being initialized. |
| InProgress | Directions to the selected place are being computed as expected, and the user is expected to be following them. |
| Succeeded | Directions were provided and the user reached the destination. |
Place
A place of interest or a physical location in the world that the user can navigate to, for example a geolocation or a Custom Location.
| Signature | Type | Description |
|---|---|---|
| METHODS | ||
getRelativePosition | function () → vec3 | null | Returns the position of this place relative to the user's position when the session started. This position isn't geo-referenced in the Earth's global coordinate frame: its frame is the world frame set by the DeviceTracking component in World mode. Returns null when the place is geo-referenced and the user's geo-referenced position isn't available. |
getGeoPosition | function () → GeoPosition | null | Returns the geo-referenced position of this place in the world, as a GeoPosition, with latitude, longitude and altitude among other data. |
requestNewGeoPosition | function (geoPosition: GeoPosition) → boolean | Requests a new geo-referenced position for this place. Returns true if accepted, false if rejected. A CustomLocationPlace always rejects it. |
getOrientation | function () → quat | Returns the orientation of the place as a quaternion. |
| PROPERTIES | ||
name | string | The name of the place. |
icon | Texture | An icon representing this place, for menus. |
description | string | A description of the place. |
visited | boolean | True if the user has been to this place in this session. |
ready | boolean | True if the place has been initialized and its content is ready for arrival. A CustomLocationPlace is ready once its Custom Location is. |
| EVENTS | ||
onStatusUpdated | PublicApi<void> | Triggered when the internal status changes. |
CustomLocationPlace
A CustomLocationPlace adds these members to Place:
| Signature | Type | Description |
|---|---|---|
onNearby | PublicApi<boolean> | Triggered with true when the user comes near the place, and with false when they move away. Near means within the place's Distance To Activate plus the accuracy of both geographic positions. |
isNearby | boolean | True while the user is near the place. |
isTracking | boolean | True while the Custom Location is found and tracked. |
changeLocatedAtEnabled | boolean | If true, the place enables its LocatedAtComponent when the user comes near, and disables it when they move away. |
setLocatedAtEnabled | function (enabled: boolean) → void | Enables or disables the place's LocatedAtComponent scene object, when changeLocatedAtEnabled is true. |
UserPosition
The position of the user in both world and geographic space. It updates when new data is received.
| Signature | Type | Description |
|---|---|---|
| METHODS | ||
initializeGeoLocationUpdates | function (accuracy: GeoLocationAccuracy, updateFrequency: number) → void | Initializes the user position, with the GeoLocationAccuracy to use and the time, in seconds, between updates of the user's position. |
getGeoPosition | function () → GeoPosition | null | The position of the user in geographic space. |
getNorthAlignedOrientation | function () → quat | Returns a quaternion representing the north-aligned orientation of the user. |
getBearing | function () → number | Returns the user's north-aligned orientation in radians: how far the device is from heading north. Zero is true north, and the direction is clockwise. |
getRelativeTransform | function () → Transform | Returns the position and orientation of the user relative to the user's position when the session started. |
getDistanceTo | function (location: Place) → number | null | Returns the distance, in meters, from the user to the place. Null if it can't be calculated. |
getBearingTo | function (location: Place, world: boolean) → number | null | Returns the bearing, in radians, from the user's position to the place. If world is true, the user's own bearing isn't taken into account. |
| PROPERTIES | ||
status | UserPositionStatus | The status of the internal location, for debugging. |
gpsActive | boolean | True if GPS is active. |
| EVENTS | ||
onUserPositionUpdated | PublicApi<void> | Triggered when the position has been updated. |
UserPosition example code
The first function is adapted from the kit's GeoLocationPlace, which uses
getPhysicalDistanceBetweenLocations from the kit's NavigationUtils. The second is adapted from
ARNavigation.
- TypeScript
- JavaScript
/**
* Calculates the distance between the user and this place's GeoPosition.
*/
private getPhysicalDistance(userPosition: UserPosition): number | null {
const userGeoPosition = userPosition.getGeoPosition()
if (isNull(userGeoPosition)) {
return null
}
return getPhysicalDistanceBetweenLocations(userGeoPosition, this.getGeoPosition())
}
/**
* Called whenever the user position is updated, to update the target rotation of a scene object pointing the way.
*/
private onUserPositionUpdated(): void {
const angle = this.userPosition.getBearingTo(this.selectedPlace, true)
this.targetRotation = quat.angleAxis(-angle, vec3.up())
}
/**
* Calculates the distance between the user and this place's GeoPosition.
*/
function getPhysicalDistance(userPosition) {
var userGeoPosition = userPosition.getGeoPosition();
if (isNull(userGeoPosition)) {
return null;
}
return getPhysicalDistanceBetweenLocations(userGeoPosition, getGeoPosition());
}
/**
* Called whenever the user position is updated, to update the target rotation of a scene object pointing the way.
*/
function onUserPositionUpdated() {
var angle = userPosition.getBearingTo(selectedPlace, true);
targetRotation = quat.angleAxis(-angle, vec3.up());
}
UserPositionStatus
The positioning status, useful for debugging inaccurate or missing location data.
| Name | Description |
|---|---|
| Unknown | The user's position can't be determined. |
| UnknownErrorNetworkMissing | Position unknown: couldn't connect to any network. |
| UnknownPoorGPSReception | Position unknown because of poor GPS. |
| GeoLocalizationAvailable | Working and available. |
| GlobalLocalizationPoorGPSReception | Location found, but inaccurate. |
| ErrorTrackingAssetFailedToDownload | The necessary assets couldn't be downloaded. |
Related
- Get Started: add Navigation Kit and its prefabs to a project.
- Custom Locations: the
locations
CustomLocationPlaceand Custom Location Groups are built from. - Location: the geoposition behind
UserPosition.