Skip to main content

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

Platform details

  • Snapchat — Not supported.

  • SPECS — Fully supported.

  • Camera Kit Web — Not supported.

  • Camera Kit Mobile — Not supported.

This page gives a high-level overview of the Navigation Kit package, then details its APIs in the Navigation Kit API reference.

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 from GeoLocationPlace, 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: a CustomLocationPlace whose 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:

ListEach entry createsFields
Manual Geo Placesa GeoLocationPlaceActive, Latitude, Longitude, Label, Icon, Description, Distance To Activate (meters, default 10)
Scene Object Placesa SceneObjectPlaceActive, Scene Object, Label, Icon, Description, Distance To Activate (meters, default 10)
Custom Location Placesa CustomLocationPlaceActive, Located At, Center, Label, Icon, Description, Prompt Image, Distance To Activate (meters, default 10)
Custom Location Group Placesa 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.

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 ARNavigationComponent folder, 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.
The Navigation Kit prefab and the navigation arrow prefab in the Scene Hierarchy, expanded to show the place menu and the arrow

Together these form a working example of how to use the kit.

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.

This section details the functions and properties of the kit's main scripts.

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; 0 for never. Default: 1.
  • Tour Mode: when on, the user visits all places in turn, with completion tracking: onArrivedAtPlace fires for every place reached, and onAllPlacesVisited fires once all have been visited.
SignatureTypeDescription
METHODS
addPlacefunction (place: Place) → voidAdds a place of interest to the guided experience. Throws Null argument. for null.
removePlacefunction (place: Place) → voidRemoves the place from the guided experience.
getUserPositionfunction () → UserPositionReturns the user's position for navigation.
navigateToPlacefunction (place: Place) → voidSelects the place to give directions to and starts the tracking to navigate to it. Adds the place if it isn't registered yet.
stopNavigationfunction () → voidClears the selected place and stops any tracking attached to it.
PROPERTIES
statusNavigationStatusThe status of the navigation component.
placesPlace[]The registered places.
tourModebooleanWhether tour mode is on (the Tour Mode field).
EVENTS
onNavigationStartedPublicApi<Place>Triggered when navigation starts. stopNavigation() triggers it with null.
onPlacesUpdatedPublicApi<void>Triggered when the list of places changes.
onArrivedAtPlacePublicApi<Place>Triggered when the user reaches a place.
onAllPlacesVisitedPublicApi<void>Triggered once when all places have been visited. Fires only with tourMode on.

The example subscribes to onNavigationStarted with add(), selects a place from a menu, and selects the nearest place by distance.

@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
}

The statuses of the navigation component.

NameDescription
LocationNotSelectedNo place is selected: navigation was stopped. Use the navigateToPlace(place: Place) function to select one.
InitializingThe initial status, before any place is selected: the resources for the tracking technology are being initialized.
InProgressDirections to the selected place are being computed as expected, and the user is expected to be following them.
SucceededDirections 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.

SignatureTypeDescription
METHODS
getRelativePositionfunction () → vec3 | nullReturns 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.
getGeoPositionfunction () → GeoPosition | nullReturns the geo-referenced position of this place in the world, as a GeoPosition, with latitude, longitude and altitude among other data.
requestNewGeoPositionfunction (geoPosition: GeoPosition) → booleanRequests a new geo-referenced position for this place. Returns true if accepted, false if rejected. A CustomLocationPlace always rejects it.
getOrientationfunction () → quatReturns the orientation of the place as a quaternion.
PROPERTIES
namestringThe name of the place.
iconTextureAn icon representing this place, for menus.
descriptionstringA description of the place.
visitedbooleanTrue if the user has been to this place in this session.
readybooleanTrue if the place has been initialized and its content is ready for arrival. A CustomLocationPlace is ready once its Custom Location is.
EVENTS
onStatusUpdatedPublicApi<void>Triggered when the internal status changes.

CustomLocationPlace

A CustomLocationPlace adds these members to Place:

SignatureTypeDescription
onNearbyPublicApi<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.
isNearbybooleanTrue while the user is near the place.
isTrackingbooleanTrue while the Custom Location is found and tracked.
changeLocatedAtEnabledbooleanIf true, the place enables its LocatedAtComponent when the user comes near, and disables it when they move away.
setLocatedAtEnabledfunction (enabled: boolean) → voidEnables 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.

SignatureTypeDescription
METHODS
initializeGeoLocationUpdatesfunction (accuracy: GeoLocationAccuracy, updateFrequency: number) → voidInitializes the user position, with the GeoLocationAccuracy to use and the time, in seconds, between updates of the user's position.
getGeoPositionfunction () → GeoPosition | nullThe position of the user in geographic space.
getNorthAlignedOrientationfunction () → quatReturns a quaternion representing the north-aligned orientation of the user.
getBearingfunction () → numberReturns 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.
getRelativeTransformfunction () → TransformReturns the position and orientation of the user relative to the user's position when the session started.
getDistanceTofunction (location: Place) → number | nullReturns the distance, in meters, from the user to the place. Null if it can't be calculated.
getBearingTofunction (location: Place, world: boolean) → number | nullReturns 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
statusUserPositionStatusThe status of the internal location, for debugging.
gpsActivebooleanTrue if GPS is active.
EVENTS
onUserPositionUpdatedPublicApi<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.

/**
* 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())
}

UserPositionStatus

The positioning status, useful for debugging inaccurate or missing location data.

NameDescription
UnknownThe user's position can't be determined.
UnknownErrorNetworkMissingPosition unknown: couldn't connect to any network.
UnknownPoorGPSReceptionPosition unknown because of poor GPS.
GeoLocalizationAvailableWorking and available.
GlobalLocalizationPoorGPSReceptionLocation found, but inaccurate.
ErrorTrackingAssetFailedToDownloadThe necessary assets couldn't be downloaded.
  • Get Started: add Navigation Kit and its prefabs to a project.
  • Custom Locations: the locations CustomLocationPlace and Custom Location Groups are built from.
  • Location: the geoposition behind UserPosition.