SixDegreesSDK.h

Version: 6D.ai Beta SDK 0.21.0
Includes: <UIKit/UIKit.h>

Last Updated: Tuesday, May 28, 2019

Introduction

This file is part of the 6D.ai Beta SDK and is not licensed for commercial use.

The 6D.ai Beta SDK can not be copied and/or distributed without the express permission of 6degrees.xyz Inc.

Contact developers@6d.ai for licensing requests.



Functions

SixDegreesSDK_CancelLoad

Interrupts and cancels the specified LoadFromARCloud process.

SixDegreesSDK_CancelSave

Interrupts and cancels the specified SaveToARCloud process.

SixDegreesSDK_GetARKitSession

Returns the ARKit Session object managed by the SDK. Optional ARKit features enabled by SixDegreesSDK_InitializeWithConfig() are accessible through this object.

SixDegreesSDK_GetARKitTransform

Populates poseDataOut with a column-major 4x4 matrix describing the transform from ARKit to world coordinates.

SixDegreesSDK_GetBackgroundTexture

Returns the Metal texture pointer of the camera background.

SixDegreesSDK_GetBackgroundTextureSize

Populates widthOut and heightOut with the pixel size of the camera background texture, if available.

SixDegreesSDK_GetBlockMesh

Populates the provided buffers with real world mesh information.

SixDegreesSDK_GetBlockMeshInfo

Returns real world mesh information needed for SixDegreesSDK_GetBlockMesh() calls.

SixDegreesSDK_GetEAGLBackgroundTexture

Returns the OpenGL texture handle of the camera background.

SixDegreesSDK_GetLoadStatus

Provides information about the specified LoadFromARCloud process.

SixDegreesSDK_GetLocationId

Populates locationIdOut with the unique identifier of the location for which the current pose is applicable.

SixDegreesSDK_GetMeshBlockSize

Returns the size of a mesh block.

SixDegreesSDK_GetPose

Populates poseDataOut with a column-major 4x4 matrix describing the position and orientation of the camera in world coordinates.

SixDegreesSDK_GetProjection

Populates projectionDataOut with a column-major 4x4 matrix describing the projection of the camera.

SixDegreesSDK_GetSaveStatus

Provides information about the specified SaveToARCloud process.

SixDegreesSDK_GetState

Returns the internal running state of the SDK.

SixDegreesSDK_GetVersion

Populates versionOut with the current version number of the SDK, e.g. "0.1.0"

SixDegreesSDK_Initialize

Initializes ARKit and the SDK's internal states using the Metal pipeline. Call this first!

SixDegreesSDK_InitializeWithConfig

Initializes ARKit and the SDK's internal states using the Metal pipeline. Call this first!

SixDegreesSDK_InitializeWithEAGL

Initializes ARKit and the SDK's internal states using the OpenGL pipeline. Call this first!

SixDegreesSDK_IsDeviceSupported

Returns whether the device is supported by this SDK.

SixDegreesSDK_IsInitialized

Returns true once the SDK is initialized.

SixDegreesSDK_LoadFromARCloud

Loads the location map data from the 6D.ai AR Cloud.

SixDegreesSDK_RetrySaveToARCloud

Retries uploading a previously failed or cancelled SaveToARCloud process.

SixDegreesSDK_SaveToARCloud

Persists the location map data to the 6D.ai AR Cloud.

SixDegreesSDK_Stop

Shuts down ARKit and the SDK, then releases their memory.


SixDegreesSDK_CancelLoad


Interrupts and cancels the specified LoadFromARCloud process.

void SixDegreesSDK_CancelLoad(
    int64_t loadTimestamp);  
Parameters
loadTimestamp

the timestamp returned by the initial call to SixDegreesSDK_LoadFromARCloud().


SixDegreesSDK_CancelSave


Interrupts and cancels the specified SaveToARCloud process.

void SixDegreesSDK_CancelSave(
    int64_t saveTimestamp);  
Parameters
saveTimestamp

the timestamp returned by the initial call to SixDegreesSDK_SaveToARCloud().


SixDegreesSDK_GetARKitSession


Returns the ARKit Session object managed by the SDK. Optional ARKit features enabled by SixDegreesSDK_InitializeWithConfig() are accessible through this object.

ARSession* SixDegreesSDK_GetARKitSession(
    void);  
Return Value

the ARSession pointer of the object managed by the SDK, null if none available.

Discussion

the ARSession pointer gives access, through the current ARFrame, to ARAnchor objects like planes and images, optionally enabled with SixDegreesSDK_InitializeWithConfig().

Users should not change the delegate object or start and stop the session.

This API call is made available for expert users.


SixDegreesSDK_GetARKitTransform


Populates poseDataOut with a column-major 4x4 matrix describing the transform from ARKit to world coordinates.

void SixDegreesSDK_GetARKitTransform(
    float *transformDataOut,
    int bufferSize);  
Parameters
transformDataOut

pointer to the first element a float array of size 16.

bufferSize

must be 16.

Discussion

Like ARKit, world coordinates assume Y is up (aligned with gravity), X is right and Z towards the user, relatively to the orientation of the device the first time the map was created.

Use the output of this method to transform native ARKit transforms and coordinates (for instance, ARAnchor objects) to 6D.ai world coordinates.

This API call is made available for expert users.


SixDegreesSDK_GetBackgroundTexture


Returns the Metal texture pointer of the camera background.

void* SixDegreesSDK_GetBackgroundTexture(
    void);  
Return Value

the Metal texture pointer of the camera background, null if none available.


SixDegreesSDK_GetBackgroundTextureSize


Populates widthOut and heightOut with the pixel size of the camera background texture, if available.

void SixDegreesSDK_GetBackgroundTextureSize(
    int *widthOut,
    int *heightOut);  
Parameters
widthOut

the pointer to the width value.

heightOut

the pointer to the height value.


SixDegreesSDK_GetBlockMesh


Populates the provided buffers with real world mesh information.

int SixDegreesSDK_GetBlockMesh(
    int *blockBuffer,
    float *vertexBuffer,
    int *faceBuffer,
    int blockBufferSize,
    int vertexBufferSize,
    int faceBufferSize);  
Parameters
blockBuffer

contains a contiguous array of signed integers { x, y, z, vertexCount, faceCount, version } where x, y, z is the location of the block in space.

vertexBuffer

contains a continuous array of floats describing vertices and divided into two parts: vertex positions { x, y, z } are back-to-back at the beginning from index 0 to 3*vertexCount-1; normal vectors { nx, ny, nz } are back-to-back at the end, from index 3*vertexCount to 6*vertexCount-1. vertexCount is equal to vertexBufferSize/6.

faceBuffer

contains a contiguous array of vertex indices { a, b, c }, each 3 representing a triangle. faceCount is equal to faceBufferSize/3.

blockBufferSize

the size of the block buffer, in ints

vertexBufferSize

the size of the vertex buffer, in floats

faceBufferSize

the size of the index buffer, in ints

Return Value

the number of blocks fully populated, or -1 if the mesh is not ready or if at least one of the buffer was too small to accommodate all the mesh data. Use SixDegreesSDK_GetBlockMeshInfo() to get the recommended buffer sizes.

Discussion

All three buffers come with their respective size to prevent the implementation from overflowing, and the function returns the number of blocks fully populated.


SixDegreesSDK_GetBlockMeshInfo


Returns real world mesh information needed for SixDegreesSDK_GetBlockMesh() calls.

int SixDegreesSDK_GetBlockMeshInfo(
    int *blockBufferSizeOut,
    int *vertexBufferSizeOut,
    int *faceBufferSizeOut);  
Parameters
blockBufferSizeOut

optional pointer to the minimum block buffer size in ints.

vertexBufferSizeOut

optional pointer to the minimum vertex buffer size in floats.

faceBufferSizeOut

optional pointer to the minimum face index buffer size in ints.

Return Value

the version number of the mesh, -1 if no mesh is available.

Discussion

The mesh is cut into blocks, which are are cubes which size is obtained with SixDegreesSDK_GetMeshBlockSize(). Blocks provide a reliable way to break down the mesh and track changes between updates.

Block data can be obtained with the SixDegreesSDK_GetBlockMesh() method, which required passing pointers to buffers. This function gives you the minimum size for those buffers.

The returned version number increments every time the mesh changes. You can keep track of the version number to avoid unnecessary calls to GetBlockMesh().


SixDegreesSDK_GetEAGLBackgroundTexture


Returns the OpenGL texture handle of the camera background.

__attribute__((deprecated)) int SixDegreesSDK_GetEAGLBackgroundTexture(
    void);  
Return Value

the OpenGL texture handle of the camera background, 0 if none available.


SixDegreesSDK_GetLoadStatus


Provides information about the specified LoadFromARCloud process.

void SixDegreesSDK_GetLoadStatus(
    int64_t loadTimestamp,
    int *stateOut,
    int *errorOut,
    int64_t *downloadSizeOut,
    float *downloadProgressOut);  
Parameters
loadTimestamp

the timestamp returned by the initial call to SixDegreesSDK_LoadFromARCloud().

stateOut

optional pointer to the state value (SixDegreesLoadState).

errorOut

optional pointer to the error value (SixDegreesLoadError).

downloadSizeOut

optional pointer to the location map data size value.

downloadProgressOut

optional pointer to the download progress percentage value.

Discussion

Populates stateOut with the latest state code of the specified LoadFromARCloud process,

errorOut with an error code if applicable,

downloadSizeOut with the size in bytes of the location map data if applicable,

downloadProgressOut with the percentage progress of the download, from 0 to 100.


SixDegreesSDK_GetLocationId


Populates locationIdOut with the unique identifier of the location for which the current pose is applicable.

void SixDegreesSDK_GetLocationId(
    char *locationIdOut,
    int bufferSize);  
Parameters
locationIdOut

pointer to the first element of a char array of size 16.

bufferSize

must be 16.

Discussion

locationIdOut will be populated with an empty string until:

- location map data was loaded from the AR Cloud AND the device successfully relocalized;

- or the location map data was successfully saved to the AR Cloud.

It will then be populated with a unique location identifier, common to all users and sessions at this location.

It guarantees the consistency of the coordinate system across time and devices, enabling persistence and multiplayer.


SixDegreesSDK_GetMeshBlockSize


Returns the size of a mesh block.

float SixDegreesSDK_GetMeshBlockSize(
    void);  
Return Value

the size of the side of a block in meters.


SixDegreesSDK_GetPose


Populates poseDataOut with a column-major 4x4 matrix describing the position and orientation of the camera in world coordinates.

int SixDegreesSDK_GetPose(
    float *poseDataOut,
    int bufferSize);  
Parameters
poseDataOut

pointer to the first element a float array of size 16.

bufferSize

must be 16.

Return Value

tracking quality (SixDegreesTrackingQuality).

Discussion

World coordinates assume Y is up (aligned with gravity), X is right and Z towards the user, relatively to the orientation of the device the first time the map was created. World coordinates convention is used by ARKit, ARCore, OpenGL, SceneKit and others.


SixDegreesSDK_GetProjection


Populates projectionDataOut with a column-major 4x4 matrix describing the projection of the camera.

void SixDegreesSDK_GetProjection(
    float *projectionDataOut,
    int bufferSize);  
Parameters
projectionDataOut

pointer to the first element float array of size 16.

bufferSize

must be 16.

Discussion

Takes into account the pixel size of the background texture. Clipping planes are at 0.001 and 1000.0.


SixDegreesSDK_GetSaveStatus


Provides information about the specified SaveToARCloud process.

void SixDegreesSDK_GetSaveStatus(
    int64_t saveTimestamp,
    int *stateOut,
    int *errorOut,
    int64_t *uploadSizeOut,
    float *uploadProgressOut);  
Parameters
saveTimestamp

the timestamp returned by the initial call to SixDegreesSDK_SaveToARCloud().

stateOut

optional pointer to the state value (SixDegreesSaveState).

errorOut

optional pointer to the error value (SixDegreesSaveError).

uploadSizeOut

optional pointer to the location map data size value.

uploadProgressOut

optional pointer to the upload progress percentage value.

Discussion

Populates stateOut with the latest state code of the specified SaveToARCloud process,

errorOut with an error code if applicable,

uploadSizeOut with the size in bytes of the location map data if applicable,

uploadProgressOut with the percentage progress of the upload, from 0 to 100.


SixDegreesSDK_GetState


Returns the internal running state of the SDK.

int SixDegreesSDK_GetState(
    void);  
Return Value

the integer value of the current running state (SixDegreesState).


SixDegreesSDK_GetVersion


Populates versionOut with the current version number of the SDK, e.g. "0.1.0"

  void SixDegreesSDK_GetVersion(
    char *versionOut,
    int bufferSize);  
Parameters
versionOut

pointer to a char buffer

bufferSize

size of the char buffer (recommended value: 16)


SixDegreesSDK_Initialize


Initializes ARKit and the SDK's internal states using the Metal pipeline. Call this first!

bool SixDegreesSDK_Initialize(
    void);  
Return Value

true if the SDK is initializing, false if there is a problem (check the logs).

Discussion

Most other API calls in this SDK will not work until you call this. Call only once!

This API call returns early, use SixDegreesSDK_GetState() to monitor initialization progress.

Initialization will fail if the current device is not supported. Use SixDegreesSDK_IsDeviceSupported() to check that the device is supported.


SixDegreesSDK_InitializeWithConfig


Initializes ARKit and the SDK's internal states using the Metal pipeline. Call this first!

bool SixDegreesSDK_InitializeWithConfig(
    ARWorldTrackingConfiguration *configuration);  
Parameters
configuration

optional pointer to the ARWorldTrackingConfiguration object for ARKit. The following configuration options are required: - video format must be a multiple of 16:9 - autofocus must be disabled - world alignment must be ARWorldAlignmentGravity The 6D.ai SDK will use a default configuration if the parameter is null.

Return Value

true if the SDK is initializing, false if there is a problem (check the logs).

Discussion

Most other API calls in this SDK will not work until you call this. Call only once!

This API call returns early, use SixDegreesSDK_GetState() to monitor initialization progress.

Initialization will fail if the current device is not supported. Use SixDegreesSDK_IsDeviceSupported() to check that the device is supported.

This API call is made available for expert users, others should use SixDegreesSDK_Initialize().


SixDegreesSDK_InitializeWithEAGL


Initializes ARKit and the SDK's internal states using the OpenGL pipeline. Call this first!

__attribute__((deprecated)) bool SixDegreesSDK_InitializeWithEAGL(
    void *eaglContext);  
Parameters
eaglContext

optional pointer to the desired EAGLContext handle (The 6D.ai SDK will use the current one or create one if it is null).

Return Value

true if the SDK is initializing, false if there is a problem (check the logs).

Discussion

Most other API calls in this SDK will not work until you call this. Call only once!

This API call returns early, use SixDegreesSDK_IsInitialized() to monitor initialization progress.

Initialization will fail if the current device is not supported. Use SixDegreesSDK_IsDeviceSupported() to check that the device is supported.

This API call is deprecated, we recommend you use Metal instead with SixDegreesSDK_Initialize().


SixDegreesSDK_IsDeviceSupported


Returns whether the device is supported by this SDK.

bool SixDegreesSDK_IsDeviceSupported(
    void);  
Return Value

true if the device is supported, false otherwise.

Discussion

Depth estimation and real world mesh building are resource-intensive processes that are enabled on the most powerful devices only. SixDegreesSDK_Initialize() will fail if this returns false.


SixDegreesSDK_IsInitialized


Returns true once the SDK is initialized.

__attribute__((deprecated)) bool SixDegreesSDK_IsInitialized(
    void);  
Return Value

true when the SDK is initialized and the other methods below are ready to be called.

Discussion

this API call is deprecated and will be removed from the SDK soon. Use SixDegreesSDK_GetState() instead.


SixDegreesSDK_LoadFromARCloud


Loads the location map data from the 6D.ai AR Cloud.

int64_t SixDegreesSDK_LoadFromARCloud(
    void);  
Return Value

load timestamp, to be used in other calls to control and monitor loading progress.

Discussion

This API call returns early, use SixDegreesSDK_GetLoadStatus() to monitor saving progress.


SixDegreesSDK_RetrySaveToARCloud


Retries uploading a previously failed or cancelled SaveToARCloud process.

void SixDegreesSDK_RetrySaveToARCloud(
    int64_t saveTimestamp);  
Parameters
saveTimestamp

the timestamp returned by the initial call to SixDegreesSDK_SaveToARCloud().


SixDegreesSDK_SaveToARCloud


Persists the location map data to the 6D.ai AR Cloud.

int64_t SixDegreesSDK_SaveToARCloud(
    void);  
Return Value

save timestamp, to be used in other calls to control and monitor saving progress.

Discussion

This API call returns early, use SixDegreesSDK_GetSaveStatus() to monitor saving progress.


SixDegreesSDK_Stop


Shuts down ARKit and the SDK, then releases their memory.

bool SixDegreesSDK_Stop(
    void);  
Return Value

true if the SDK is shutting down, false if there is a problem (check the logs).


Enumerated Types

SixDegreesLoadError

Error in the LoadFromARCloud process.

SixDegreesLoadState

State of the LoadFromARCloud process.

SixDegreesSaveError

Error in the SaveToARCloud process.

SixDegreesSaveState

State of the SaveToARCloud process.

SixDegreesState

Running state of the SDK.

SixDegreesTrackingQuality

Quality of the AR pose tracking system.


SixDegreesLoadError


Error in the LoadFromARCloud process.

enum SixDegreesLoadError { 
    SixDegreesLoadErrorNone = 0, 
    SixDegreesLoadErrorUnknown = 1, 
    SixDegreesLoadErrorNotEnoughSpace = 2, 
    SixDegreesLoadErrorOffline = 3, 
    SixDegreesLoadErrorCloudNotAvailable = 4, 
    SixDegreesLoadErrorNotAuthorized = 5, 
    SixDegreesLoadErrorLocationNotAvailable = 6, 
    SixDegreesLoadErrorDataNotAvailable = 7, 
    SixDegreesLoadErrorFailedToRelocalize = 8, 
};  
Constants
SixDegreesLoadErrorNone

LoadFromARCloud() did not produce any errors.

SixDegreesLoadErrorUnknown

Placeholder for unknown and future errors.

SixDegreesLoadErrorNotEnoughSpace

The device file system is too full to download and unpackage the location map data.

SixDegreesLoadErrorOffline

The device is not connected to the Internet.

SixDegreesLoadErrorCloudNotAvailable

The AR Cloud cannot be reached.

SixDegreesLoadErrorNotAuthorized

The AR Cloud rejected the load request.

SixDegreesLoadErrorLocationNotAvailable

The device cannot approximate its location by GPS or Wi-Fi.

SixDegreesLoadErrorDataNotAvailable

The AR Cloud doesn't have map data for this location.

SixDegreesLoadErrorFailedToRelocalize

The device could not relocalize in less than 30 seconds at this location.


SixDegreesLoadState


State of the LoadFromARCloud process.

enum SixDegreesLoadState { 
    SixDegreesLoadStateNone = 0, 
    SixDegreesLoadStatePositioning = 1, 
    SixDegreesLoadStateDownloading = 2, 
    SixDegreesLoadStateRelocalizing = 3, 
    SixDegreesLoadStateDoneSuccess = 4, 
    SixDegreesLoadStateDoneFailed = 5, 
    SixDegreesLoadStateDoneCancelled = 6, 
};  
Constants
SixDegreesLoadStateNone

LoadFromARCloud() was never called.

SixDegreesLoadStatePositioning

Approximate GPS Position is being requested.

SixDegreesLoadStateDownloading

Location map data is being received and unpackaged from the AR Cloud.

SixDegreesLoadStateRelocalizing

Location map data is being used to relocalize the device at this location.

SixDegreesLoadStateDoneSuccess

Location map data was successfully loaded and the device relocalized.

SixDegreesLoadStateDoneFailed

Location map data could not be loaded, or the device could not relocalize, check the error enum for details.

SixDegreesLoadStateDoneCancelled

LoadFromARCloud() was interrupted by a call to CancelLoad().


SixDegreesSaveError


Error in the SaveToARCloud process.

enum SixDegreesSaveError { 
    SixDegreesSaveErrorNone = 0, 
    SixDegreesSaveErrorUnknown = 1, 
    SixDegreesSaveErrorNotEnoughSpace = 2, 
    SixDegreesSaveErrorOffline = 3, 
    SixDegreesSaveErrorCloudNotAvailable = 4, 
    SixDegreesSaveErrorNotAuthorized = 5, 
    SixDegreesSaveErrorLocationNotAvailable = 6, 
    SixDegreesSaveErrorNoLocationMapData = 7, 
};  
Constants
SixDegreesSaveErrorNone

SaveToARCloud() did not produce any errors.

SixDegreesSaveErrorUnknown

Placeholder for unknown and future errors.

SixDegreesSaveErrorNotEnoughSpace

The device file system is too full to package the location map data.

SixDegreesSaveErrorOffline

The device is not connected to the Internet.

SixDegreesSaveErrorCloudNotAvailable

The AR Cloud cannot be reached.

SixDegreesSaveErrorNotAuthorized

The AR Cloud rejected the save request.

SixDegreesSaveErrorLocationNotAvailable

The device cannot approximate its location by GPS or Wi-Fi.

SixDegreesSaveErrorNoLocationMapData

The device has no location map data to send to the AR Cloud.


SixDegreesSaveState


State of the SaveToARCloud process.

enum SixDegreesSaveState { 
    SixDegreesSaveStateNone = 0, 
    SixDegreesSaveStatePositioning = 1, 
    SixDegreesSaveStatePackaging = 2, 
    SixDegreesSaveStateUploading = 3, 
    SixDegreesSaveStateDoneSuccess = 4, 
    SixDegreesSaveStateDoneFailed = 5, 
    SixDegreesSaveStateDoneCancelled = 6, 
};  
Constants
SixDegreesSaveStateNone

SaveToARCloud() was never called.

SixDegreesSaveStatePositioning

Approximate GPS Position is being requested.

SixDegreesSaveStatePackaging

Location map data is being packaged.

SixDegreesSaveStateUploading

Location map data is being transmitted to the AR Cloud.

SixDegreesSaveStateDoneSuccess

Location map data was saved successfully.

SixDegreesSaveStateDoneFailed

Location map data could not be saved, check the error enum for details.

SixDegreesSaveStateDoneCancelled

SaveARCloud() was interrupted by a call to CancelSave().


SixDegreesState


Running state of the SDK.

enum SixDegreesState { 
    SixDegreesStateStopped = 0, 
    SixDegreesStateInitializing = 1, 
    SixDegreesStateRunning = 2, 
    SixDegreesStateDisabled = 3, 
};  
Constants
SixDegreesStateStopped

The SDK was not initialized, or was stopped

SixDegreesStateInitializing

The SDK is in the process of initializing

SixDegreesStateRunning

The SDK is initialized and running

SixDegreesStateDisabled

The SDK is disabled due to permission issues


SixDegreesTrackingQuality


Quality of the AR pose tracking system.

enum SixDegreesTrackingQuality { 
    SixDegreesTrackingQualityNone = 0, 
    SixDegreesTrackingQualityLimited = 1, 
    SixDegreesTrackingQualityGood = 2, 
};  
Constants
SixDegreesTrackingQualityNone

No pose available

SixDegreesTrackingQualityLimited

Pose available, tracking is limited

SixDegreesTrackingQualityGood

Pose available, tracking is good


Macro Definitions

API_METHOD

API_METHOD


 #define API_METHOD FOUNDATION_EXPORT __attribute__((visibility ("default")))