Interface DeviceTracking

Description

Moves or rotates the SceneObject to match device orientation.

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.

See the Tracking Modes guide for more information.

Note:* This component was named "WorldTracking" in previous versions of Lens Studio.

Example

Set the surface tracking target.

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

Position an object further ahead on the Device Path every frame. Meant for cases where the Device Path is available, such as Lenses for Spectacles 3. See the Lenses for Spectacles guide for more information.

// Set the script to run on Lens Turned On. Device Path isn't available during the first Initialize event.
// @input Component.DeviceTracking deviceTracking
// @input SceneObject objectToMove

// Get device path information
var devicePath = script.deviceTracking.getDevicePath();

// Bind an event to run every frame
script.createEvent("UpdateEvent").bind(function()
{
    // Get the current frame index
    var currentIndex = script.deviceTracking.getDevicePathIndex();

    // Get the frame index 20 frames in the future (with wrapping)
    var futureIndex = (currentIndex + 20) % devicePath.length;

    // Get the position of the device at the future frame index
    var basicTransform = devicePath[futureIndex];
    var position = basicTransform.getPosition();

    // Move the object to the future path position
    script.objectToMove.getTransform().setWorldPosition(position);
});
interface DeviceTracking {
    enabled: boolean;
    rotationOptions: RotationOptions;
    surfaceOptions: SurfaceOptions;
    surfaceTrackingTarget: SceneObject;
    uniqueIdentifier: string;
    worldOptions: WorldOptions;
    worldTrackingCapabilities: WorldTrackingCapabilities;
    calculateWorldMeshHistogram(center, radius): TrackedMeshHistogramResult;
    createTrackedWorldPoint(worldPos, worldRot): TrackedPoint;
    destroy(): void;
    getActualDeviceTrackingMode(): DeviceTrackingMode;
    getDevicePath(): BasicTransform[];
    getDevicePathIndex(): number;
    getPointCloud(): PointCloud;
    getRequestedDeviceTrackingMode(): DeviceTrackingMode;
    getSceneObject(): SceneObject;
    getTransform(): Transform;
    getTypeName(): string;
    hitTestWorldMesh(screenPos): TrackedMeshHitTestResult[];
    isDeviceTrackingModeSupported(mode): boolean;
    isOfType(type): boolean;
    isSame(other): boolean;
    raycastWorldMesh(from, to): TrackedMeshHitTestResult[];
    requestDeviceTrackingMode(val): void;
    resetTracking(position): void;
    setWorldOriginOffset(offset): void;
}

Hierarchy (view full)

Properties

enabled rotationOptions surfaceOptions surfaceTrackingTarget uniqueIdentifier worldOptions worldTrackingCapabilities

Methods

calculateWorldMeshHistogram createTrackedWorldPoint destroy getActualDeviceTrackingMode getDevicePath getDevicePathIndex getPointCloud getRequestedDeviceTrackingMode getSceneObject getTransform getTypeName hitTestWorldMesh isDeviceTrackingModeSupported isOfType isSame raycastWorldMesh requestDeviceTrackingMode resetTracking setWorldOriginOffset

Properties

enabled

enabled: boolean

Description

If disabled, the Component will stop enacting its behavior.

rotationOptions

rotationOptions: RotationOptions

Description

Used to access rotation tracking settings.

surfaceOptions

surfaceOptions: SurfaceOptions

Description

Used to access surface tracking settings.

surfaceTrackingTarget

surfaceTrackingTarget: SceneObject

Description

Helps to improve surface tracking accuracy while the target SceneObject is being moved.

Readonly uniqueIdentifier

uniqueIdentifier: string

worldOptions

worldOptions: WorldOptions

Description

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

Readonly worldTrackingCapabilities

worldTrackingCapabilities: WorldTrackingCapabilities

Description

Returns the World Tracking Capabilities of the current device.

Methods

calculateWorldMeshHistogram

  • calculateWorldMeshHistogram(center, radius): TrackedMeshHistogramResult

  • Parameters

    • center: vec3
    • radius: number

    Returns TrackedMeshHistogramResult

    Description

    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.

createTrackedWorldPoint

  • createTrackedWorldPoint(worldPos, worldRot): TrackedPoint

  • Parameters

    Returns TrackedPoint

    Description

    Creates a TrackedPoint at world position worldPos and world rotation worldRot.

destroy

  • destroy(): void

  • Returns void

    Description

    Destroys the component.

getActualDeviceTrackingMode

  • getActualDeviceTrackingMode(): DeviceTrackingMode

  • Returns DeviceTrackingMode

    Description

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

getDevicePath

  • getDevicePath(): BasicTransform[]

  • Returns BasicTransform[]

    Description

    Returns an array of BasicTransform objects describing each point that the camera travels through. Each item in the array matches the camera's basic transform in the corresponding frame of the video feed that the Lens is applied to. Only available in some cases, such as in Lenses for Spectacles 3. When not available, it will return an empty array. See the Lenses for Spectacles guide for more information.

getDevicePathIndex

  • getDevicePathIndex(): number

  • Returns number

    Description

    Returns the current frame index of the video feed that the Lens is being applied to. This can be used as an index to access the current BasicTransform in getDevicePath(). Only available in some cases, such as in Lenses for Spectacles 3. When not available, it will return -1. See the Lenses for Spectacles guide for more information.

getPointCloud

  • getPointCloud(): PointCloud

  • Returns PointCloud

    Exposes User Data

    Description

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

getRequestedDeviceTrackingMode

  • getRequestedDeviceTrackingMode(): DeviceTrackingMode

  • Returns DeviceTrackingMode

    Description

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

getSceneObject

getTransform

getTypeName

  • getTypeName(): string

  • Returns string

    Description

    Returns the name of this object's type.

hitTestWorldMesh

  • hitTestWorldMesh(screenPos): TrackedMeshHitTestResult[]

  • Parameters

    Returns TrackedMeshHitTestResult[]

    Description

    Returns an array of TrackedMeshHitTestResult that intersect with a ray cast from screen position screenPos. Only available when world mesh tracking is supported and enabled.

isDeviceTrackingModeSupported

  • isDeviceTrackingModeSupported(mode): boolean

  • Parameters

    Returns boolean

    Description

    Returns whether the DeviceTrackingMode is supported.

isOfType

  • isOfType(type): boolean

  • Parameters

    • type: string

    Returns boolean

    Description

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

isSame

  • isSame(other): boolean

  • Parameters

    Returns boolean

    Description

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

raycastWorldMesh

  • raycastWorldMesh(from, to): TrackedMeshHitTestResult[]

  • Parameters

    Returns TrackedMeshHitTestResult[]

    Description

    Returns an array of TrackedMeshHitTestResult that intersect with a ray cast from the world position from and continuing through the world position to. Only available when world mesh tracking is supported and enabled.

requestDeviceTrackingMode

  • requestDeviceTrackingMode(val): void

  • Parameters

    Returns void

    Description

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

resetTracking

  • resetTracking(position): void

  • Parameters

    Returns void

    Description

    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.

setWorldOriginOffset

  • setWorldOriginOffset(offset): void

  • Parameters

    Returns void

    Description

    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.

Settings

Member Visibility

Theme

On This Page

Generated using TypeDoc