documentation

vlSDK Class Reference

Convenient function for using the vlSDK in a simple manner. The vlSDK wrapper uses the C-Interface and prepares the interface in that way, that it is easy accessable by a macOS or iOS application. Please have a look into the tutorials and examples. More...

#import <vlSDK/vlSDK_Apple.h>

Inherits NSObject.

Instance Methods

(id _Nonnull) - initTrackerWithURI:andDelegate:
 Initialize a new tracker Initialize a new tracker with a given URI and the given delegate. More...
 
(id _Nonnull) - initTrackerWithURI:andLicensePath:andDelegate:
 Initialize a new tracker Initialize a new tracker with a given URI and the given delegate. More...
 
(id _Nonnull) - initTrackerWithURI:andLicenseData:andDelegate:
 Initialize a new tracker Initialize a new tracker with a given URI and the given delegate. More...
 
(id _Nonnull) - initTrackerWithURI:andDelegate:withOptions:
 Initialize a new tracker Initialize a new tracker with a given URI and the given delegate. More...
 
(id _Nonnull) - initTrackerWithURI:andLicensePath:andDelegate:withOptions:
 Initialize a new tracker Initialize a new tracker with a given URI and the given delegate. More...
 
(id _Nonnull) - initTrackerWithURI:andLicenseData:andDelegate:withOptions:
 Initialize a new tracker Initialize a new tracker with a given URI and the given delegate. More...
 
(void) - dealloc
 Shut down everything Shut down everything... Please be sure to not call anything in the sdk while calling dealloc. More...
 
(void) - shutDown
 Shut down everything Shut down everything... Please be sure to not call anything in the sdk while calling dealloc. More...
 
(void) - process
 Process one frame This method initiates the processing of the command queue and initiates the resolution of the delegates methode in the same thread as called. More...
 
(void) - step
 Step one frame Usually this methode is not needed when running real time applications. Anyway you might step single frames using this function. More...
 
(BOOL) - isPaused
 Query pause state Ask the SDK if it is paused right now. If you have been calling pause: More...
 
(void) - pause:
 Set pause state Set the actual state to pause. More...
 
(void) - run
 Run the tracking pipeline Run the tracking pipeline when it has been loaded. More...
 
(void) - stop
 Stop the tracking pipeline Stop the tracking pipeline. More...
 
(void) - start
 
(void) - windowResized:
 (macOS only) Set the screen extends of the rendering area to be used. This function should usually be called by a macOS application when a window resize happens. More...
 
(void) - setLogLevel:
 Setting the log level for debugging Set the log level for logging of the visionLib. It is strongly recommended only using the log if you experience rare problems. More...
 
(void) - setFPS:
 Set the frames per second to be processed internally. Set frames per second to process. A value of 0 will make the vlSDK run as fast as it can (not recommended). More...
 
(void) - setNearPlane:andFarPlane:
 Set the near and far plane. Setting the near and far plane will influence the generated intrinsic data (projection matrix) passed to the delegate. You should set this to a useful value, since it defines the frustum. If you cannot see your rendering, please start here! More...
 
(void) - setInitPose:andQ:
 Set initial pose with quaternion and translation Set initial pose in openGL/Metal coordinate system from translation and quaternions. More...
 
(void) - setInitPoseFromMatrix:
 Set initial pose with a matrix Set initial pose in openGL/Metal coordinate system from a model view matrix. More...
 
(void) - configureExtrinsicCameraInverted:
 Treating camera poses Define how the callbacks extrinsic data should be treated. Enabling this option is recommended when working with OpenGL or Metal rendering systems. Like this you can easily directly pass the matrix of onExtrinsic: and onIntrinsic: to the rendering engine. Call this function right after calling the init. More...
 
(void) - resetSoft
 Do a soft reset A soft reset enables the actual poster or model tracker pipe to get back to its initial pose. More...
 
(void) - resetHard
 Do a hard reset A hard reset enables the actual poster or model tracker pipe to get back to its initial pose. It also releases all recorded features helping for reinitialization and stabilization. Use this for starting over with the tracking as nothing happend before. More...
 
(void) - getInitPose
 Trigger to receive an initial pose Trigger to receive an initial pose-. More...
 
(BOOL) - getLastExtrinsic:
 Receive last extrinsic data Receives a matrix with the last valid extrinsic data. More...
 
(void) - applyInitPoseCorrectionWithAxis:andAngle:
 Apply initial pose correction In some cases a initial pose can be corrected by passing axis angle. More...
 
(void) - getInitPoseCorrectionWithAxis:andAngle:
 Retreive actuall initial pose correction In some cases a initial pose can be corrected by passing axis angle. With this function you can receive the actual configured axis angle representation. More...
 
(BOOL) - enableDebugImage
 Enable debug images You might enable receiving of ONE debug image along with the actual view image. In more complex applications this can help debugging. Enable the debug image which will call onGetDebugImageBufferWithWidth and companion methods if implemented in the delegate. More...
 
(BOOL) - disableDebugImage
 Disable debug images. More...
 
(NSImage *_Nullable) - getLastImage
 (macOS) Get last image as NSImage Get the most actual camera image. It is not recommended polling this function for receiving a realtime stream of the image. More...
 
(void) - setAttributeCommand:withFloatValue:
 Set Attribute Set a certain attribute in the pipeline This only works, when the actual pipe has the attribute. More...
 
(void) - setAttributeCommand:withStringValue:
 Set Attribute Set a certain attribute in the pipeline This only works, when the actual pipe has the attribute. More...
 
(void) - getAttributeRequest:
 Request an Attribute Request an attribute from the actual running pipeline This only works, when the actual pipe has the attribute. More...
 
(void) - setCalibrationCommand:
 Send a calibration command Send a calibration command as stated in the documentation. This only works, when the actual pipe is a camera calibration. More...
 
(void) - writeCalibrationDB:
 Write the actual camera calibration to some URI Writes the actual camera calibration to a given URI. This only works, when the actual pipe is a camera calibration. More...
 
(NSString *_Nullable) - getTrackerType
 Get type of tracker The vlSDK uses different pipes for different purposes. When loading a .vl file a certain pipe will be initialized. (e.g. modelTracker, posterTracker etc...) This function will allow you to receive the actual configured pipe name. More...
 
(void) - writeInitData:
 Write recorded init templates to uri While tracking using the modelTracker pipeline init templates are recorded for allowing to reinitialize the scene. It can be useful saving these templates using this function to an uri. More...
 
(void) - readInitData:
 Load recorded init templates from uri While tracking using the modelTracker pipeline init templates are recorded for allowing to reinitialize the scene. It can be useful loading these templates during runtime from an uri. More...
 
(void) - resetInitData
 Reset all init data You might remove statically loaded initialization data. Data which has currently already be recorded will not be deleted. You may call a resetHard in order to remove these as well. More...
 
(void) - setModel:property:state:
 Sets a boolean property of a model (BETA) You might enable/disable, occlude an objects using this function. The general calling mechanism is providing a nameURI which looks like this name:YOUROBJECTNAME. Possible properties are enabled, occluder More...
 
(void) - requestModelProperties
 Request actual scene model properties (BETA) Will call onModelProperties on the delegate. More...
 
(void) - requestModelData:withOptions:
 Request model data of the object (BETA) THIS IS STILL BETA AND IS MATTER OF CHANGE. More...
 
(void) - removeModel:
 Remove a certain model with a name uri (BETA) Use name:YOUROBJECTNAME or id:YOUROBJECTID. This will in return call onModelRemoved. More...
 
(BOOL) - addRawModelWithStruct:andData:
 Add a certain model with raw data (BETA) You can inject model(s) with raw triangles and normals into the visionlib and use them for tracking. More...
 
(void) - pushJsonAndBinaryCommand:andData:
 
(void) - pushJsonCommand:
 
(void) - writeLineModelData:
 
(void) - readLineModelData:
 

Detailed Description

Convenient function for using the vlSDK in a simple manner. The vlSDK wrapper uses the C-Interface and prepares the interface in that way, that it is easy accessable by a macOS or iOS application. Please have a look into the tutorials and examples.

Method Documentation

◆ addRawModelWithStruct:andData:()

- (BOOL) addRawModelWithStruct: (NSString *_Nonnull)  struc
andData: (NSData *_Nonnull)  data 

Add a certain model with raw data (BETA) You can inject model(s) with raw triangles and normals into the visionlib and use them for tracking.

The string to be passed might look like this:

[
{
"name" : "myModel",
"subModels" :
[
{
"binaryOffset" : 0,
"name" : "dummy",
"normalCount" : 4,
"triangleIndexCount" : 6,
"vertexCount" : 4
}
],
"transform" :
{
"s" :
[
0.10000000000000001,
0.10000000000000001,
0.10000000000000001
]
}
}
]

The binary structure might have this format: [vertex Nx3xfloat][triangleIndices: MxUint32][normals: Ox3xfloat]

The function will call onRawModelAdded:withError: NOTE This structure might still change.

Returns
Nothing.

◆ applyInitPoseCorrectionWithAxis:andAngle:()

- (void) applyInitPoseCorrectionWithAxis: (float *_Nonnull)  axis
andAngle: (float)  angle 

Apply initial pose correction In some cases a initial pose can be corrected by passing axis angle.

Parameters
axisAn array of 3 float values representin the axis
angleA float value representing the angle in radians

◆ configureExtrinsicCameraInverted:()

- (void) configureExtrinsicCameraInverted: (BOOL)  invert

Treating camera poses Define how the callbacks extrinsic data should be treated. Enabling this option is recommended when working with OpenGL or Metal rendering systems. Like this you can easily directly pass the matrix of onExtrinsic: and onIntrinsic: to the rendering engine. Call this function right after calling the init.

Parameters
invertSet this to true in order to invert the camera pose automatically for you.

◆ dealloc()

- (void) dealloc

Shut down everything Shut down everything... Please be sure to not call anything in the sdk while calling dealloc.

◆ disableDebugImage()

- (BOOL) disableDebugImage

Disable debug images.

Returns
True if the image could be disabled.

◆ enableDebugImage()

- (BOOL) enableDebugImage

Enable debug images You might enable receiving of ONE debug image along with the actual view image. In more complex applications this can help debugging. Enable the debug image which will call onGetDebugImageBufferWithWidth and companion methods if implemented in the delegate.

Returns
True if the image could be enabled.

◆ getAttributeRequest:()

- (void) getAttributeRequest: (NSString *_Nonnull)  attribute

Request an Attribute Request an attribute from the actual running pipeline This only works, when the actual pipe has the attribute.

Parameters
commandAn NSString holding the attributename.

◆ getInitPose()

- (void) getInitPose

Trigger to receive an initial pose Trigger to receive an initial pose-.

◆ getInitPoseCorrectionWithAxis:andAngle:()

- (void) getInitPoseCorrectionWithAxis: (float *_Nonnull)  axis
andAngle: (float *_Nonnull)  angle 

Retreive actuall initial pose correction In some cases a initial pose can be corrected by passing axis angle. With this function you can receive the actual configured axis angle representation.

Parameters
axisAn array of 3 float values that will be filled
angleA float pointer to a value representing the angle in radians

◆ getLastExtrinsic:()

- (BOOL) getLastExtrinsic: (float *_Nonnull)  m

Receive last extrinsic data Receives a matrix with the last valid extrinsic data.

Parameters
mFills an array with expected 16 float values
Returns
true if the pose has been valid

◆ getLastImage()

- (NSImage * _Nullable) getLastImage

(macOS) Get last image as NSImage Get the most actual camera image. It is not recommended polling this function for receiving a realtime stream of the image.

◆ getTrackerType()

- (NSString * _Nullable) getTrackerType

Get type of tracker The vlSDK uses different pipes for different purposes. When loading a .vl file a certain pipe will be initialized. (e.g. modelTracker, posterTracker etc...) This function will allow you to receive the actual configured pipe name.

Returns
An NSString holding the actual tracker type loaded. Anyway it will pass NULL if no tracker has been loaded yet or it has failed during loading.

◆ initTrackerWithURI:andDelegate:()

- (id _Nonnull) initTrackerWithURI: (NSString *_Nonnull)  uri
andDelegate: ((deprecated("Use functions that also set licensePath or licenseData")))  __attribute 

Initialize a new tracker Initialize a new tracker with a given URI and the given delegate.

Parameters
uriA valid URI pointing to .vl configuration file.
delegatePass a vlFrameListenerInterface
Returns
a vlSDK object id

◆ initTrackerWithURI:andDelegate:withOptions:()

- (id _Nonnull) initTrackerWithURI: (NSString *_Nonnull)  uri
andDelegate: (_Nullable id)  delegate
withOptions: ((deprecated("Use functions that also set licensePath or licenseData")))  __attribute 

Initialize a new tracker Initialize a new tracker with a given URI and the given delegate.

Parameters
uriA valid URI pointing to .vl configuration file.
delegatePass a vlFrameListenerInterface
optionsA dictionary with the following potential options: cameraDatabaseURI: An uri holding your custom cameraCalibration database. targetFPS: An unsigned integer holding the frames per seconds to be used for updates.
Returns
a vlSDK object id

◆ initTrackerWithURI:andLicenseData:andDelegate:()

- (id _Nonnull) initTrackerWithURI: (NSString *_Nonnull)  uri
andLicenseData: (NSString *_Nonnull)  licenseData
andDelegate: (id _Nullable)  delegate 

Initialize a new tracker Initialize a new tracker with a given URI and the given delegate.

Parameters
uriA valid URI pointing to .vl configuration file.
licenseDataThe content of a license file.
delegatePass a vlFrameListenerInterface
Returns
a vlSDK object id

◆ initTrackerWithURI:andLicenseData:andDelegate:withOptions:()

- (id _Nonnull) initTrackerWithURI: (NSString *_Nonnull)  uri
andLicenseData: (NSString *_Nonnull)  licenseData
andDelegate: (_Nullable id)  delegate
withOptions: (NSDictionary *_Nullable)  options 

Initialize a new tracker Initialize a new tracker with a given URI and the given delegate.

Parameters
uriA valid URI pointing to .vl configuration file.
licenseDataThe content of a license file.
delegatePass a vlFrameListenerInterface
optionsA dictionary with the following potential options: cameraDatabaseURI: An uri holding your custom cameraCalibration database. targetFPS: An unsigned integer holding the frames per seconds to be used for updates.
Returns
a vlSDK object id

◆ initTrackerWithURI:andLicensePath:andDelegate:()

- (id _Nonnull) initTrackerWithURI: (NSString *_Nonnull)  uri
andLicensePath: (NSString *_Nonnull)  licensePath
andDelegate: (id _Nullable)  delegate 

Initialize a new tracker Initialize a new tracker with a given URI and the given delegate.

Parameters
uriA valid URI pointing to .vl configuration file.
licensePathA valid URI pointing to license file.
delegatePass a vlFrameListenerInterface
Returns
a vlSDK object id

◆ initTrackerWithURI:andLicensePath:andDelegate:withOptions:()

- (id _Nonnull) initTrackerWithURI: (NSString *_Nonnull)  uri
andLicensePath: (NSString *_Nonnull)  licensePath
andDelegate: (_Nullable id)  delegate
withOptions: (NSDictionary *_Nullable)  options 

Initialize a new tracker Initialize a new tracker with a given URI and the given delegate.

Parameters
uriA valid URI pointing to .vl configuration file.
licensePathA valid URI pointing to license file.
delegatePass a vlFrameListenerInterface
optionsA dictionary with the following potential options: cameraDatabaseURI: An uri holding your custom cameraCalibration database. targetFPS: An unsigned integer holding the frames per seconds to be used for updates.
Returns
a vlSDK object id

◆ isPaused()

- (BOOL) isPaused

Query pause state Ask the SDK if it is paused right now. If you have been calling pause:

Returns
TRUE if paused

◆ pause:()

- (void) pause: (BOOL)  enable

Set pause state Set the actual state to pause.

Parameters
enablepause or not

◆ process()

- (void) process

Process one frame This method initiates the processing of the command queue and initiates the resolution of the delegates methode in the same thread as called.

A common practice is calling this function during the renderloop allowing your delegate methods to be called.

◆ pushJsonAndBinaryCommand:andData:()

- (void) pushJsonAndBinaryCommand: (NSString *_Nonnull)  struc
andData: (NSData *_Nonnull)  data 

◆ pushJsonCommand:()

- (void) pushJsonCommand: (NSString *_Nonnull)  json

◆ readInitData:()

- (void) readInitData: (NSString *_Nonnull)  uri

Load recorded init templates from uri While tracking using the modelTracker pipeline init templates are recorded for allowing to reinitialize the scene. It can be useful loading these templates during runtime from an uri.

Currently the format must be a filename with an ending .binz.

Returns
Nothing.

◆ readLineModelData:()

- (void) readLineModelData: (NSString *_Nonnull)  uri

◆ removeModel:()

- (void) removeModel: (NSString *_Nonnull)  nameURI

Remove a certain model with a name uri (BETA) Use name:YOUROBJECTNAME or id:YOUROBJECTID. This will in return call onModelRemoved.

Returns
Nothing.

◆ requestModelData:withOptions:()

- (void) requestModelData: (NSString *_Nonnull)  name
withOptions: (NSString *_Nonnull)  options 

Request model data of the object (BETA) THIS IS STILL BETA AND IS MATTER OF CHANGE.

Returns
Nothing.

◆ requestModelProperties()

- (void) requestModelProperties

Request actual scene model properties (BETA) Will call onModelProperties on the delegate.

Returns
Nothing.

◆ resetHard()

- (void) resetHard

Do a hard reset A hard reset enables the actual poster or model tracker pipe to get back to its initial pose. It also releases all recorded features helping for reinitialization and stabilization. Use this for starting over with the tracking as nothing happend before.

◆ resetInitData()

- (void) resetInitData

Reset all init data You might remove statically loaded initialization data. Data which has currently already be recorded will not be deleted. You may call a resetHard in order to remove these as well.

Returns
Nothing.

◆ resetSoft()

- (void) resetSoft

Do a soft reset A soft reset enables the actual poster or model tracker pipe to get back to its initial pose.

◆ run()

- (void) run

Run the tracking pipeline Run the tracking pipeline when it has been loaded.

◆ setAttributeCommand:withFloatValue:()

- (void) setAttributeCommand: (NSString *_Nonnull)  attribute
withFloatValue: (float)  value 

Set Attribute Set a certain attribute in the pipeline This only works, when the actual pipe has the attribute.

Parameters
commandA NSString holding the attributename.
valueA float value.

◆ setAttributeCommand:withStringValue:()

- (void) setAttributeCommand: (NSString *_Nonnull)  attribute
withStringValue: (NSString *_Nonnull)  value 

Set Attribute Set a certain attribute in the pipeline This only works, when the actual pipe has the attribute.

Parameters
commandAn NSString holding the attributename.
valueA string value. Note: Also float values can be set and will be converted when needed.

◆ setCalibrationCommand:()

- (void) setCalibrationCommand: (NSString *_Nonnull)  command

Send a calibration command Send a calibration command as stated in the documentation. This only works, when the actual pipe is a camera calibration.

Parameters
commandAn NSString holding the command.

◆ setFPS:()

- (void) setFPS: (unsigned int)  fps

Set the frames per second to be processed internally. Set frames per second to process. A value of 0 will make the vlSDK run as fast as it can (not recommended).

Parameters
fpsinteger holding the frames per second to run with.

◆ setInitPose:andQ:()

- (void) setInitPose: (float *_Nonnull)  t
andQ: (float *_Nonnull)  q 

Set initial pose with quaternion and translation Set initial pose in openGL/Metal coordinate system from translation and quaternions.

Parameters
tTranslation vector
qQuaternion holding the rotation

◆ setInitPoseFromMatrix:()

- (void) setInitPoseFromMatrix: (float *_Nonnull)  m

Set initial pose with a matrix Set initial pose in openGL/Metal coordinate system from a model view matrix.

Parameters
mA matrix holding 16 elements

◆ setLogLevel:()

- (void) setLogLevel: (int)  level

Setting the log level for debugging Set the log level for logging of the visionLib. It is strongly recommended only using the log if you experience rare problems.

Parameters
Theloglevel can be a number from 0-5, while 0 means LOG and 5 is mostly debug.

◆ setModel:property:state:()

- (void) setModel: (NSString *_Nonnull)  name
property: (NSString *_Nonnull)  property
state: (bool)  enable 

Sets a boolean property of a model (BETA) You might enable/disable, occlude an objects using this function. The general calling mechanism is providing a nameURI which looks like this name:YOUROBJECTNAME. Possible properties are enabled, occluder

Returns
Nothing.

◆ setNearPlane:andFarPlane:()

- (void) setNearPlane: (float)  near
andFarPlane: (float)  far 

Set the near and far plane. Setting the near and far plane will influence the generated intrinsic data (projection matrix) passed to the delegate. You should set this to a useful value, since it defines the frustum. If you cannot see your rendering, please start here!

Parameters
nearNear value as float
nearFar value as float

◆ shutDown()

- (void) shutDown

Shut down everything Shut down everything... Please be sure to not call anything in the sdk while calling dealloc.

◆ start()

- (void) start

◆ step()

- (void) step

Step one frame Usually this methode is not needed when running real time applications. Anyway you might step single frames using this function.

◆ stop()

- (void) stop

Stop the tracking pipeline Stop the tracking pipeline.

◆ windowResized:()

- (void) windowResized: (CGSize)  size

(macOS only) Set the screen extends of the rendering area to be used. This function should usually be called by a macOS application when a window resize happens.

◆ writeCalibrationDB:()

- (void) writeCalibrationDB: (NSString *_Nonnull)  uri

Write the actual camera calibration to some URI Writes the actual camera calibration to a given URI. This only works, when the actual pipe is a camera calibration.

Parameters
commandAn NSString holding uri to write to.

◆ writeInitData:()

- (void) writeInitData: (NSString *_Nonnull)  uri

Write recorded init templates to uri While tracking using the modelTracker pipeline init templates are recorded for allowing to reinitialize the scene. It can be useful saving these templates using this function to an uri.

If an empty string is passed, the uri will be local_storage_dir:/VisionLib/InitData_XXXXX.binz, while XXXX depicts a timestamp. You can load the init data as well using either the initDataURI parameter in the tracking configuration file or passing the filename using url parameters, when loading the .vl file.

If you pass a full filename, with .binz at the end. You can explicitly save the init data under this filename. This is the recommended way. You can load the init data again using the loadInitData function

Returns
Nothing.

◆ writeLineModelData:()

- (void) writeLineModelData: (NSString *_Nonnull)  uri