Skip to main content

MappingSession

Class

Used with the LocatedAtComponent to map the current physical location.

  • 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.

Since Lens Scripting v229

Index

Example

// Have a frame of reference to where
// tracking starting in the session
// LocationAsset returns a label for the co-ordinate frame
var worldOriginLocationAsset = LocationAsset.getAROrigin();

worldOriginLocatedAt = global.scene.createSceneObject("AR Origin").createComponent("LocatedAtComponent");

// LocatedAtComponent
worldOriginLocatedAt.location = worldOriginLocationAsset;

// MAP NEW LOCATION + GET STORE FOR IT

// Start mapping the space of the user
var options = LocatedAtComponent.createMappingOptions();
options.location = worldOriginLocationAsset;

mappingSession = LocatedAtComponent.createMappingSession(options);

mappingSession.onMapped.add((location) => {
// we _can_ use location if we like - it is now a persisted private custom
// location and has the same coordinate frame as worldOriginLocationAsset
currentLocationLocatedAt.location = location;

locationCloudStorageModule.storeLocation(
location,
(locationId) => {
// cloud storage is not associated with locations but can store strings
// locationCloudStorageModule has privacy model for location <-> string.
cloudStorage.putString("previous-location",
locationId);
},
(errorString) => {
print("failed to obtain persistent id for location: " + errorString);
});

var options = LocationCloudStorageOptions.create();
options.location = location;
options.onDiscoveredNearby.add((store) => {
//store code here
});

options.onError.add((error) => {
//error code here
});

// get store and use it
locationCloudStorageModule.getNearbyLocationStores(options);

...

// Mapping will continue; can be cancelled or throttled here
});

...

// Progress towards map being of acceptable quality (ie canCheckpoint going true)
print(mappingSession.quality); // 0 -> 1
print(mappingSession.canCheckpoint); // == (quality >= 1)

// force onMapped to be fired immediately
// can be called 'early' once canCheckpoint goes true
mappingSession.checkpoint(); // error to call with
// canCheckpoint == false

print(mappingSession.capacityUsed); // 0 -> 1
// when ==1 onMapped is fired
// quality guaranteed >=1 at
// that point

...

mappingSession.setThrottling(MappingSession.Auto);
// or (MappingSession.MappingThrottling.Foreground)
// or (MappingSession.MappingThrottling.Background)
// or (MappingSession.MappingThrottling.Off)

... or
mappingSession.cancel();

...

// concurrently with creating a new map

function onPreviousLocationRetrieved(previousLocationAsset) {
// TRACKING PREVIOUS + GETTING STORES FOR PREVIOUS
previousLocationLocatedAt.location = previousLocationAsset;
previousLocationLocatedAt.onFound.add(() => {
// Cancel new location mapping
mappingSession.cancel();

// we could switch to incremental by creating a new mapping session here
// using previousLocationAsset

...

var options = LocationCloudStorageOptions.create();
options.location = previousLocationAsset;
options.onDiscoveredNearby.add((store) => {
//store code here
});

options.onError.add((error) => {
//error code here
});

// get a store for the tracked location
locationCloudStorageModule.getNearbyLocationStores(options);
});
};

function onError(errorString) {
print("could not retrieve previous location: " + errorString);
};

// use some other means of storage to retrieve a previously stored location id
var previousLocationId = cloudStorage.getString("previous-location");

locationCloudStorageModule.retrieveLocation(
previousLocationId,
onPreviousLocationRetrieved,
onError);

Extends

Properties

canCheckpoint

readonly canCheckpoint: boolean

Minimum conditions for trigerring onMapped via checkpoint() have been met - ie quality >= 1.

Since

Lens Scripting Version 229


capacityUsed

readonly capacityUsed: number

Capacity used up for a map, goes from 0 to 1, where 1 will automatically trigger a checkpoint. Capacity will not reach 1.0 while quality <1.0. 1.0 is maximum capacity used, implemented per-device and per-mapping-policy.

Since

Lens Scripting Version 229


handheldMaximumSize

handheldMaximumSize: number

Since

Lens Scripting Version 229

Default Value

50.0

handheldMinimumSize

handheldMinimumSize: number

Since

Lens Scripting Version 229

Default Value

4.0

onCapacityUsedAtLimit

readonly onCapacityUsedAtLimit: event0<void>

Since

Lens Scripting Version 229


onQualityAcceptable

readonly onQualityAcceptable: event0<void>

Since

Lens Scripting Version 229


quality

readonly quality: number

Progress towards an acceptable map, goes from 0 -> 1.0, where 1.0 is defined as 'Acceptable' given a specific mapping policy.

Since

Lens Scripting Version 245


throttling

throttling: MappingThrottling

Current throttling of mapping process, i.e. how much effort the device is putting into it. (planned future extension)

Since

Lens Scripting Version 229

Default Value

MappingSession.MappingThrottling.Auto

wearableAcceptableRawCapacity

wearableAcceptableRawCapacity: number

Since

Lens Scripting Version 229

Default Value

524288.0

wearableAllowEarlyCheckpoint

wearableAllowEarlyCheckpoint: boolean

Since

Lens Scripting Version 229

Default Value

false

wearableMaximumSize

wearableMaximumSize: number

Since

Lens Scripting Version 229

Default Value

52428800.0

wearableMinimumSize

wearableMinimumSize: number

Since

Lens Scripting Version 229

Default Value

67.0

Methods

cancel()

cancel(): void

Stops the current mapping session. No more events will be queued after this is called, although previously queued onMapped events may complete.

Returns

void

Since

Lens Scripting Version 229


checkpoint()

checkpoint(): Promise<LocationAsset>

Require the onMapped event to fire. Fires as soon as minimum quality condition is met. Mapping can be left running and can be called multiple times (Spectacles only).

Returns

Promise<LocationAsset>

A promise that resolves to the LocationAsset when the checkpoint is complete. The onMapped callback will also be triggered for backward compatibility.

Since

Lens Scripting Version 245


getTypeName()

static getTypeName(): TypeName<MappingSession>

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<MappingSession>

Since

Lens Scripting Version 229

Overrides

ScriptObject.getTypeName


getTypeName()

getTypeName(): string

Returns the name of this object's type.

Returns

string

Inherited from

ScriptObject.getTypeName


isOfType()

isOfType(type): boolean

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

Parameters

ParameterType
typestring

Returns

boolean

Inherited from

ScriptObject.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

ScriptObject.isSame

Nested types

Enumerations

EnumerationDescription
MappingScopeDetermines what data is included in the checkpoint of the @MappingSession.
MappingThrottlingThrottling levels for a MappingSession.