SixDegreesSDK.h

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

Last Updated: Tuesday, Feb 5, 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 current LoadFromARCloud process.

SixDegreesSDK_CancelSave

Interrupts and cancels the current SaveToARCloud process.

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_GetEAGLBackgroundTexture

Returns the OpenGL texture handle of the camera background.

SixDegreesSDK_GetLoadStatus

Provides information about the current or last LoadFromARCloud process.

SixDegreesSDK_GetLocationId

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

SixDegreesSDK_GetMeshBlockInfo

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

SixDegreesSDK_GetMeshBlocks

Populates the provided buffers with real world mesh information.

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 current or last 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.20.0"

SixDegreesSDK_Initialize

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 AR Cloud.

SixDegreesSDK_SaveToARCloud

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

SixDegreesSDK_Stop

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


SixDegreesSDK_CancelLoad


Interrupts and cancels the current LoadFromARCloud process.

void SixDegreesSDK_CancelLoad(
    void);  

SixDegreesSDK_CancelSave


Interrupts and cancels the current SaveToARCloud process.

void SixDegreesSDK_CancelSave(
    void);  

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_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 current or last LoadFromARCloud process.

void SixDegreesSDK_GetLoadStatus(
    int *stateOut,
    int *errorOut,
    long int *timestampOut);  
Parameters
stateOut

optional pointer to the state value (SixDegreesLoadState).

errorOut

optional pointer to the error value (SixDegreesLoadError).

timestampOut

optional pointer to the timestamp value.

Discussion

Populates stateOut with the current state code of the LoadFromARCloud process,

errorOut with an error code if applicable,

timestampOut with the POSIX timestamp of the last time SixDegreesSDK_LoadFromARCloud() was called.


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_GetMeshBlockInfo


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

int SixDegreesSDK_GetMeshBlockInfo(
    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_GetMeshBlocks() 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 GetMeshBlocks().


SixDegreesSDK_GetMeshBlocks


Populates the provided buffers with real world mesh information.

int SixDegreesSDK_GetMeshBlocks(
    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 contiguous array of floats { x, y, z, nx, ny, nz }, each 6 representing a point in 3D space where x, y, z is the location of the vertex, and nx, ny, nz is the normal vector of the vertex.

faceBuffer

contains a contiguous array of vertex indices { a, b, c }, each 3 representing a triangle.

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_GetMeshBlockInfo() 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_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 current or last SaveToARCloud process.

void SixDegreesSDK_GetSaveStatus(
    int *stateOut,
    int *errorOut,
    long int *timestampOut);  
Parameters
stateOut

optional pointer to the state value (SixDegreesSaveState).

errorOut

optional pointer to the error value (SixDegreesSaveError).

timestampOut

optional pointer to the timestamp value.

Discussion

Populates stateOut with the current state code of the SaveToARCloud process,

errorOut with an error code if applicable,

timestampOut with the POSIX timestamp of the last time SixDegreesSDK_SaveToARCloud() was called.


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.20.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_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.


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 (6D 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 AR Cloud.

void SixDegreesSDK_LoadFromARCloud(
    void);  
Discussion

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


SixDegreesSDK_SaveToARCloud


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

void SixDegreesSDK_SaveToARCloud(
    void);  
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, 
};  
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.


SixDegreesSaveState


State of the SaveToARCloud process.

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

SaveToARCloud() was never called.

SixDegreesSaveStatePositioning

Approximate GPS Position is being requested.

SixDegreesSaveStateUploading

Location map data is being packaged and 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 
};  
Constants
SixDegreesStateStopped

The SDK was not initialized, or was stopped

SixDegreesStateInitializing

The SDK is in the process of initializing

SixDegreesStateRunning

The SDK is intialized and running


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")))