MappingSession
ClassUsed with the LocatedAtComponent to map the current physical location.
- Available on all platforms
Since Lens Scripting v229
Index
Properties
Methods
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
readonlycanCheckpoint:boolean
Minimum conditions for trigerring onMapped via checkpoint() have been met - ie quality >= 1.
Since
Lens Scripting Version 229
capacityUsed
readonlycapacityUsed: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
readonlyonCapacityUsedAtLimit:event0<void>
Since
Lens Scripting Version 229
onQualityAcceptable
readonlyonQualityAcceptable:event0<void>
Since
Lens Scripting Version 229
quality
readonlyquality: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()
staticgetTypeName():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
getTypeName()
getTypeName():
string
Returns the name of this object's type.
Returns
string
Inherited from
isOfType()
isOfType(
type):boolean
Returns true if the object matches or derives from the passed in type.
Parameters
| Parameter | Type |
|---|---|
type | string |
Returns
boolean
Inherited from
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
| Parameter | Type |
|---|---|
other | ScriptObject |
Returns
boolean
Inherited from
Nested types
Enumerations
| Enumeration | Description |
|---|---|
| MappingScope | Determines what data is included in the checkpoint of the @MappingSession. |
| MappingThrottling | Throttling levels for a MappingSession. |