documentation

vlSDK Class Reference

Convenient function for using the vlSDK in a simple manner. @discussion 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 </Users/local/builds/F-28fkuL/0/visometry/vlSDK/visionlib-documentation/temp/vlSDK/objective_c/vlSDK_Apple.h>

Inherits NSObject.

Instance Methods

(BOOL) - addRawModelWithStruct:andData:
 Add a certain model with raw data (BETA) @discussion You can inject model(s) with raw triangles and normals into the visionlib and use them for tracking. More...
 
(void) - applyInitPoseCorrectionWithAxis:andAngle:
 Apply initial pose correction @discussion In some cases a initial pose can be corrected by passing axis angle. More...
 
(void) - configureExtrinsicCameraInverted:
 Treating camera poses @discussion 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) - dealloc
 Shut down everything @discussion Shut down everything... Please be sure to not call anything in the sdk while calling dealloc.
 
(BOOL) - disableDebugImage
 Disable debug images. More...
 
(BOOL) - enableDebugImage
 Enable debug images @discussion 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...
 
(void) - getAttributeRequest:
 Request an Attribute @discussion Request an attribute from the actual running pipeline This only works, when the actual pipe has the attribute. More...
 
(NSString *_Nullable) - getDeviceType
 Get type of device @discussion The vlSDK can use different image sources. When loading a .vl file a certain image source will be initialized. (e.g. camera, image sequence etc...) This function will allow you to receive the actual configured image source name (device). More...
 
(void) - getInitPose
 Trigger to receive an initial pose @discussion Trigger to receive an initial pose-.
 
(void) - getInitPoseCorrectionWithAxis:andAngle:
 Retreive actuall initial pose correction @discussion 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) - getLastExtrinsic:
 Receive last extrinsic data @discussion Receives a matrix with the last valid extrinsic data. More...
 
(NSImage *_Nullable) - getLastImage
 (macOS) Get last image as NSImage @discussion Get the most actual camera image. It is not recommended polling this function for receiving a realtime stream of the image.
 
(NSString *_Nullable) - getTrackerType
 Get type of tracker @discussion 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...
 
(id _Nonnull) - initTrackerWithURI:andDelegate:
 Initialize a new tracker @discussion Initialize a new tracker with a given URI and the given delegate. More...
 
(id _Nonnull) - initTrackerWithURI:andDelegate:withOptions:
 Initialize a new tracker @discussion Initialize a new tracker with a given URI and the given delegate. More...
 
(id _Nonnull) - initTrackerWithURI:andLicenseData:andDelegate:
 Initialize a new tracker @discussion Initialize a new tracker with a given URI and the given delegate. More...
 
(id _Nonnull) - initTrackerWithURI:andLicenseData:andDelegate:withOptions:
 Initialize a new tracker @discussion Initialize a new tracker with a given URI and the given delegate. More...
 
(id _Nonnull) - initTrackerWithURI:andLicensePath:andDelegate:
 Initialize a new tracker @discussion Initialize a new tracker with a given URI and the given delegate. More...
 
(id _Nonnull) - initTrackerWithURI:andLicensePath:andDelegate:withOptions:
 Initialize a new tracker @discussion Initialize a new tracker with a given URI and the given delegate. More...
 
(BOOL) - isPaused
 Query pause state @discussion Ask the SDK if it is paused right now. If you have been calling pause: More...
 
(void) - pause:
 Set pause state @discussion Set the actual state to pause. More...
 
(void) - process
 Process one frame @discussion 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) - pushJsonAndBinaryCommand:andData:
 
(void) - pushJsonCommand:
 
(void) - readInitData:
 Load recorded init templates from uri @discussion 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) - readLineModelData:
 
(void) - removeModel:
 Remove a certain model with a name uri (BETA) @discussion Use name:YOUROBJECTNAME or id:YOUROBJECTID. This will in return call onModelRemoved.
 
(void) - requestModelData:withOptions:
 Request model data of the object (BETA) @discussion THIS IS STILL BETA AND IS MATTER OF CHANGE.
 
(void) - requestModelProperties
 Request actual scene model properties (BETA) @discussion Will call onModelProperties on the delegate.
 
(void) - resetHard
 Do a hard reset @discussion 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.
 
(void) - resetInitData
 Reset all init data @discussion 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.
 
(void) - resetSoft
 Do a soft reset @discussion A soft reset enables the actual poster or model tracker pipe to get back to its initial pose.
 
(void) - run
 Run the tracking pipeline @discussion Run the tracking pipeline when it has been loaded.
 
(void) - setAttributeCommand:withFloatValue:
 Set Attribute @discussion Set a certain attribute in the pipeline This only works, when the actual pipe has the attribute. More...
 
(void) - setAttributeCommand:withStringValue:
 Set Attribute @discussion Set a certain attribute in the pipeline This only works, when the actual pipe has the attribute. More...
 
(void) - setCalibrationCommand:
 Send a calibration command @discussion Send a calibration command as stated in the documentation. This only works, when the actual pipe is a camera calibration. More...
 
(void) - setFPS:
 Set the frames per second to be processed internally. @discussion Set frames per second to process. A value of 0 will make the vlSDK run as fast as it can (not recommended). More...
 
(void) - setInitPose:andQ:
 Set initial pose with quaternion and translation @discussion Set initial pose in openGL/Metal coordinate system from translation and quaternions. More...
 
(void) - setInitPoseFromMatrix:
 Set initial pose with a matrix @discussion Set initial pose in openGL/Metal coordinate system from a model view matrix. More...
 
(void) - setLogLevel:
 Setting the log level for debugging @discussion Set the log level for logging of the visionLib. It is strongly recommended only using the log if you experience rare problems. More...
 
(void) - setModel:property:state:
 Sets a boolean property of a model (BETA) @discussion 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
 
(void) - setNearPlane:andFarPlane:
 Set the near and far plane. @discussion 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) - shutDown
 Shut down everything @discussion Shut down everything... Please be sure to not call anything in the sdk while calling dealloc.
 
(void) - start
 
(void) - step
 Step one frame @discussion Usually this methode is not needed when running real time applications. Anyway you might step single frames using this function.
 
(void) - stop
 Stop the tracking pipeline @discussion Stop the tracking pipeline.
 
(void) - windowResized:
 (macOS only) Set the screen extends of the rendering area to be used. @discussion This function should usually be called by a macOS application when a window resize happens.
 
(void) - writeCalibrationDB:
 Write the actual camera calibration to some URI @discussion Writes the actual camera calibration to a given URI. This only works, when the actual pipe is a camera calibration. More...
 
(void) - writeInitData:
 Write recorded init templates to uri @discussion 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) - writeLineModelData:
 

Detailed Description

Convenient function for using the vlSDK in a simple manner. @discussion 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) @discussion 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.

◆ applyInitPoseCorrectionWithAxis:andAngle:

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

Apply initial pose correction @discussion 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 @discussion 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.

◆ disableDebugImage

- (BOOL) disableDebugImage

Disable debug images.

Returns
True if the image could be disabled.

◆ enableDebugImage

- (BOOL) enableDebugImage

Enable debug images @discussion 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 @discussion Request an attribute from the actual running pipeline This only works, when the actual pipe has the attribute.

Parameters
attributeAn NSString holding the attributename.

◆ getDeviceType

- (NSString * _Nullable) getDeviceType

Get type of device @discussion The vlSDK can use different image sources. When loading a .vl file a certain image source will be initialized. (e.g. camera, image sequence etc...) This function will allow you to receive the actual configured image source name (device).

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

◆ getInitPoseCorrectionWithAxis:andAngle:

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

Retreive actuall initial pose correction @discussion 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 @discussion 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

◆ getTrackerType

- (NSString * _Nullable) getTrackerType

Get type of tracker @discussion 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 @discussion 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 @discussion 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 @discussion 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 @discussion 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 @discussion 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 @discussion 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 @discussion 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 @discussion Set the actual state to pause.

Parameters
enablepause or not

◆ process

- (void) process

Process one frame @discussion 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.

◆ readInitData:

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

Load recorded init templates from uri @discussion 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.

◆ setAttributeCommand:withFloatValue:

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

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

Parameters
attributeA NSString holding the attributename.
valueA float value.

◆ setAttributeCommand:withStringValue:

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

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

Parameters
attributeAn 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 @discussion 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. @discussion 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 @discussion 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 @discussion 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 @discussion Set the log level for logging of the visionLib. It is strongly recommended only using the log if you experience rare problems.

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

◆ setNearPlane:andFarPlane:

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

Set the near and far plane. @discussion 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
farFar value as float

◆ writeCalibrationDB:

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

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

Parameters
uriAn NSString holding uri to write to.

◆ writeInitData:

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

Write recorded init templates to uri @discussion 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