Skip to main content

DeviceTracking

Class

Enables a SceneObject to align with the movements and orientation of the user's device.

  • Available on all platforms
Platform details: Snapchat, SPECS, Camera Kit Web, Camera Kit Mobile fully supported.

Platform details

  • Snapchat — Fully supported.

  • SPECS — Fully supported.

  • Camera Kit Web — Fully supported.

  • Camera Kit Mobile — Fully supported.

Enables a SceneObject to align with the movements and orientation of the user's device. Provides tracking modes such as Surface, Rotation, and World.

Index

Remarks

Usually added to SceneObject with Camera component.

If using Surface tracking mode, adding this to a SceneObject enables surface tracking for the scene, and moves the object to a position and rotation that matches the physical camera's pose in the world. Surface tracking can also be enhanced with native AR by enabling the Use Native AR option in the Inspector panel, or through script by setting the component's SurfaceOptions.enhanceWithNativeAR property.

If using Rotation tracking mode, adding this to a SceneObject will apply the device's real world rotation to the object.

If using World tracking mode, adding this to a SceneObject enables native AR tracking for the scene, and moves the object to a position and rotation that matches the physical camera's pose in the world.

Example

Set the surface tracking target.

//@input Component.DeviceTracking deviceTrackingComponent
function setTrackingTarget()
{
if(script.deviceTrackingComponent)
{
script.deviceTrackingComponent.surfaceTrackingTarget = script.getSceneObject();
}
}
setTrackingTarget();

Extends

Properties

enabled

enabled: boolean

If disabled, the Component will stop enacting its behavior.

Default Value

true

Inherited from

Component.enabled


isBeingDestroyed

readonly isBeingDestroyed: boolean

Returns true if this Component is currently being destroyed. Becomes true as soon as destruction begins via Component#destroy or destruction of its owning SceneObject, before any OnDestroyEvent callbacks fire.

Since

Lens Scripting Version 364

Example

if (!script.isBeingDestroyed) {
// Component is still fully alive
}

Inherited from

Component.isBeingDestroyed


isEnabledInHierarchy

readonly isEnabledInHierarchy: boolean

Returns true if this Component, its SceneObject, and all of that SceneObjects parents are enabled.

Inherited from

Component.isEnabledInHierarchy


rotationOptions

rotationOptions: RotationOptions

Used to access rotation tracking settings.


sceneObject

readonly sceneObject: SceneObject

The SceneObject this component is on.

Inherited from

Component.sceneObject


surfaceOptions

surfaceOptions: SurfaceOptions

Used to access surface tracking settings.


trackingStatus

readonly trackingStatus: TrackingStatus

Access to the TrackingStatus for this Component. Can be used to check if tracking is available and subscribe to events for status changes.


uniqueIdentifier

readonly uniqueIdentifier: string

Since

Lens Scripting Version 176

Inherited from

Component.uniqueIdentifier


worldOptions

worldOptions: WorldOptions

Returns the WorldOptions object of this component, which can be used to control World Tracking settings.


worldTrackingCapabilities

readonly worldTrackingCapabilities: WorldTrackingCapabilities

Returns the World Tracking Capabilities of the current device.

Methods

calculateWorldMeshHistogram()

calculateWorldMeshHistogram(center, radius): TrackedMeshHistogramResult

Calculates a histogram of world mesh surfaces within a sphere at the given world position and radius. Only available when world mesh tracking is supported and enabled.

Parameters

ParameterType
centervec3
radiusnumber

Returns

TrackedMeshHistogramResult


destroy()

destroy(): void

Destroys the component.

Returns

void

Inherited from

Component.destroy


getActualDeviceTrackingMode()

getActualDeviceTrackingMode(): DeviceTrackingMode

Returns the actual DeviceTrackingMode being used. This may be different from the requested DeviceTrackingMode.

Returns

DeviceTrackingMode


getNativeARTrackingState()

getNativeARTrackingState(): NativeARTrackingState

Returns the current NativeARTrackingState of the underlying native AR tracking (SLAM) system. Use this to determine whether tracking is running and whether the poses it produces are currently valid.

Returns

NativeARTrackingState

Since

Lens Scripting Version 377

Example

//@input Component.DeviceTracking deviceTracking
if (script.deviceTracking.getNativeARTrackingState() === NativeARTrackingState.Normal) {
print("Native AR tracking is running normally.");
}

getPointCloud()

getPointCloud(): PointCloud

Exposes user data

Returns the 3D point cloud representing important features visible by the camera.

Returns

PointCloud

Since

Lens Scripting Version 148


getRequestedDeviceTrackingMode()

getRequestedDeviceTrackingMode(): DeviceTrackingMode

Returns the DeviceTrackingMode currently requested to be used. This may be different from the actual DeviceTrackingMode being used.

Returns

DeviceTrackingMode


getSceneObject()

getSceneObject(): SceneObject

Returns the SceneObject the component is attached to.

Returns

SceneObject

Inherited from

Component.getSceneObject


getTransform()

getTransform(): Transform

Returns the Transform this component is attached to.

Returns

Transform

Inherited from

Component.getTransform


getTypeName()

static getTypeName(): TypeName<DeviceTracking>

Returns the fully-qualified JavaScript type name for this class (for example, "Component.Camera"). This is a static accessor (no instance required) and returns the same value as the instance getTypeName().

Returns

TypeName<DeviceTracking>

Overrides

Component.getTypeName


getTypeName()

getTypeName(): string

Returns the name of this object's type.

Returns

string

Inherited from

Component.getTypeName


isDeviceTrackingModeSupported()

isDeviceTrackingModeSupported(mode): boolean

Returns whether the DeviceTrackingMode is supported.

Parameters

ParameterType
modeDeviceTrackingMode

Returns

boolean


isOfType()

isOfType(type): boolean

Returns true if the object matches or derives from the passed in type.

Parameters

ParameterType
typestring

Returns

boolean

Inherited from

Component.isOfType


isSame()

isSame(other): boolean

Returns true if this object is the same as other. Useful for checking if two references point to the same thing.

Parameters

ParameterType
otherScriptObject

Returns

boolean

Inherited from

Component.isSame


requestDeviceTrackingMode()

requestDeviceTrackingMode(val): void

Requests that a DeviceTrackingMode be used. This requested change may not happen immediately.

Parameters

ParameterType
valDeviceTrackingMode

Returns

void


resetTracking()

resetTracking(position): void

Resets the World Tracking origin to the point on the surface plane aligned with the screen position position. Screen positions are represented in the range ([0-1], [0-1]), (0,0) being the top-left of the screen and (1,1) being the bottom-right.

Parameters

ParameterType
positionvec2

Returns

void


setWorldOriginOffset()

setWorldOriginOffset(offset): void

Offsets the default position of the World Tracking surface origin by offset. Avoid using a y value of zero in offset, because it may cause problems with tracking. If used outside of Initialized or TurnOnEvent, you will need to call resetTracking() to apply the offset. Note: calling resetTracking() will overwrite the x and z components of the offset.

Parameters

ParameterType
offsetvec3

Returns

void

See also

Tracking Modes guide for more information.