documentation

<vlFrameListenerInterface > Protocol Reference

Listener for all callbacks of the visionLib. More...

#import <vlSDK/vlSDK_Apple.h>

Inherits <NSObjectNSObject>.

Instance Methods

(NSMutableData *_Nonnull) - onGetDebugImageBufferWithWidth:andHeight:andBytesPerPixel:
 Retreives the configured Debug Image Use this for setting your own memory location to be the image copied in. More...
 
(void) - onRawDebugImageBuffer:withWidth:andHeight:andBytesPerPixel:
 Retreives the configured Debug Image Overloading this function onGetDebugImageBufferWithWidth should not have been overloaded too. will provide you on every frame with fresh image data. More...
 
(void) - onMetalDebugImageTexture:withRotationMatrix:
 Retreives the configured Debug Image as a metal texture When overloading this function, a metal texture will be passed, when needed to be set or rendered as background texture functions like onGetDebugImageBufferWithWidth and/or onRawImageBuffer will not be called then, even if defined. More...
 
(void) - onCGDebugImageRef:withRotationMatrix:
 Retreives the configured Debug Image as a CGImageRef When overloading this function, a CGImageRef will be passed, when needed to be set or rendered as background texture functions like onGetDebugImageBufferWithWidth and/or onRawImageBuffer will not be called then, even if defined. More...
 
(NSMutableData *_Nonnull) - onGetImageBufferWithWidth:andHeight:andBytesPerPixel:
 Set your own image buffer to copy the image into Use either this for setting your own memory location to be the image copied in. More...
 
(void) - onRawImageBuffer:withWidth:andHeight:andBytesPerPixel:
 Receive a raw image buffer Overloading this function onGetImageBufferWithWidth should not have been overloaded too. will provide you on every frame with fresh image data. More...
 
(void) - onMetalImageTexture:withRotationMatrix:
 Receive a metal image buffer (experimental) When overloading this function, a metal texture will be passed, when needed to be set or rendered as background texture functions like onGetImageBufferWithWidth and/or onRawImageBuffer will not be called then, even if defined. More...
 
(void) - onCGImageRef:withRotationMatrix:
 Receive a CGImageRef image buffer When overloading this function, a CGImageRef will be passed, when needed to be set or rendered as background functions like onGetImageBufferWithWidth and/or onRawImageBuffer will not be called then, even if defined. More...
 
(void) - onTrackerInitialized:
 When the tracker has been initialized Will be called when the tracker has been done loading and is running now or not. It is recommended using the onTrackerInitializedWithWarningIssues:andErrors: function for more precise informations about the state of the tracking pipe. More...
 
(void) - onTrackerInitializedWithWarningIssues:andErrors:
 Will be called when the tracker has been done loading and is running now. Tracking issues are passed separated by errors and warnings. You should take these very serious. You can review a complete list of possible issues in the documentation. More...
 
(void) - onExtrinsicData:isValid:
 Receiving the camera pose Overloading this function will pass a model view matrix for the rendering system. More...
 
(void) - onIntrinsicData:
 Receive the projection matrix Overloading this function will pass a projection matrix regarding the set near and far, width and height value of your screen. More...
 
(void) - onIntrinsicDataWithWidth:height:cx:cy:fx:fy:
 Receive the intrinsic data Overloading this function will pass a projection matrix regarding the set near and far, width and height value of your screen. More...
 
(void) - onLog:
 Receive the internal visionLib Log. Depending on the configured log level you will receive the internal log messages from the visionlib. You might use these messages during development. Anyway it is NOT recommended using them for the end user nor parsing them. Defined issues should be gathered by using onTrackerInitializedWithWarningIssues:andErrors:. More...
 
(void) - onTrackingPaused:
 Receive the pause state. Will be called, when the tracking pause was issued. More...
 
(void) - onSteppedFrame
 Receive the stepped state. Will be called, when the SDK has stepped one frame forward. This can be used in conjunction with stepFrame. More...
 
(void) - onTrackingInformation:
 Receive runtime tracking information on each frame Will pass a dictionary with information about the tracking quality etc into the application only if is tracking. More...
 
(void) - onInitPose:andQ:
 Receive the initial pose as quaternion and translation. Will be called when getInitPose has been issued, it will return the currently set init pose (in openGL compatible system) More...
 
(void) - onInitPoseMatrix:
 Receive the initial pose as matrix. Will be called when getInitPose has been issued, it will return the currently set init pose (in openGL compatible system) More...
 
(void) - onResetTracking:
 Receive the reset state Will be called when a reset has occured (hard or soft) More...
 
(void) - onCalibrationResults:
 Receive the calibration data Will be called with a valid calibration, when getResults has been called. This function will only be called, when using the camera calibration configuration. More...
 
(void) - onGetAttribute:withValue:
 Receive the requested attribute Will be called when an attribute of the pipeline has been requested using getAttributeRequest. More...
 
(void) - onModelProperties:
 
(void) - onModelRemoved:withError:
 
(void) - onRawModelAdded:withError:
 

Detailed Description

Listener for all callbacks of the visionLib.

vlFrameListenerInterface The vlFrameListenerInterface delegate protocol allows you gaining on frame information about the current tracking state.

Method Documentation

◆ onCalibrationResults:()

- (void vlFrameListenerInterface) onCalibrationResults: (NSString *_Nullable)  json
optional

Receive the calibration data Will be called with a valid calibration, when getResults has been called. This function will only be called, when using the camera calibration configuration.

Parameters
jsonA NSString holding a json structure with the calibration data.

◆ onCGDebugImageRef:withRotationMatrix:()

- (void vlFrameListenerInterface) onCGDebugImageRef: (CGImageRef _Nonnull)  texture
withRotationMatrix: (float *_Nonnull)  m 
optional

Retreives the configured Debug Image as a CGImageRef When overloading this function, a CGImageRef will be passed, when needed to be set or rendered as background texture functions like onGetDebugImageBufferWithWidth and/or onRawImageBuffer will not be called then, even if defined.

Parameters
dataMTLTexture object
mA pointer to 16 item matrix holding a rotation matrix of the content to be rotated with

◆ onCGImageRef:withRotationMatrix:()

- (void vlFrameListenerInterface) onCGImageRef: (CGImageRef _Nonnull)  texture
withRotationMatrix: (float *_Nonnull)  m 
optional

Receive a CGImageRef image buffer When overloading this function, a CGImageRef will be passed, when needed to be set or rendered as background functions like onGetImageBufferWithWidth and/or onRawImageBuffer will not be called then, even if defined.

Parameters
dataThe number of bytes occupied per pixel (e.g. 4 for RGBA images)
widthThe width of the image
widthThe height of the image
bytesPerPixelthe number of bytes occupied per pixel (e.g. 4 for RGBA images)

◆ onExtrinsicData:isValid:()

- (void vlFrameListenerInterface) onExtrinsicData: (float *_Nonnull)  data
isValid: (bool)  valid 
optional

Receiving the camera pose Overloading this function will pass a model view matrix for the rendering system.

Parameters
dataA 16 element matrix holding the complete opengl capable model view matrix.
validA boolean flag indicating if the pose is valid.

◆ onGetAttribute:withValue:()

- (void vlFrameListenerInterface) onGetAttribute: (NSString *_Nonnull)  name
withValue: (NSString *_Nonnull)  value 
optional

Receive the requested attribute Will be called when an attribute of the pipeline has been requested using getAttributeRequest.

Parameters
nameA NSString holding the name of the set attribute
valueA NSString holding the value of the set attribute

◆ onGetDebugImageBufferWithWidth:andHeight:andBytesPerPixel:()

- (NSMutableData * _Nonnull vlFrameListenerInterface) onGetDebugImageBufferWithWidth: (int)  width
andHeight: (int)  height
andBytesPerPixel: (int)  bytesPerPixel 
optional

Retreives the configured Debug Image Use this for setting your own memory location to be the image copied in.

Parameters
widththe width of the image
widththe height of the image
bytesPerPixelthe number of bytes occupied per pixel (e.g. 4 for RGBA images)

◆ onGetImageBufferWithWidth:andHeight:andBytesPerPixel:()

- (NSMutableData * _Nonnull vlFrameListenerInterface) onGetImageBufferWithWidth: (int)  width
andHeight: (int)  height
andBytesPerPixel: (int)  bytesPerPixel 
optional

Set your own image buffer to copy the image into Use either this for setting your own memory location to be the image copied in.

Parameters
widththe width of the image
widththe height of the image
bytesPerPixelthe number of bytes occupied per pixel (e.g. 4 for RGBA images)
Returns
NSMutableData object that will be filled upon every arriving image

◆ onInitPose:andQ:()

- (void vlFrameListenerInterface) onInitPose: (float *_Nonnull)  t
andQ: (float *_Nonnull)  q 
optional

Receive the initial pose as quaternion and translation. Will be called when getInitPose has been issued, it will return the currently set init pose (in openGL compatible system)

◆ onInitPoseMatrix:()

- (void vlFrameListenerInterface) onInitPoseMatrix: (float *_Nonnull)  m
optional

Receive the initial pose as matrix. Will be called when getInitPose has been issued, it will return the currently set init pose (in openGL compatible system)

◆ onIntrinsicData:()

- (void vlFrameListenerInterface) onIntrinsicData: (float *_Nonnull)  data
optional

Receive the projection matrix Overloading this function will pass a projection matrix regarding the set near and far, width and height value of your screen.

Parameters
dataA 16 element matrix holding the complete opengl capable projection matrix.

◆ onIntrinsicDataWithWidth:height:cx:cy:fx:fy:()

- (void vlFrameListenerInterface) onIntrinsicDataWithWidth: (float)  width
height: (float)  height
cx: (float)  cx
cy: (float)  cy
fx: (float)  fx
fy: (float)  fy 
optional

Receive the intrinsic data Overloading this function will pass a projection matrix regarding the set near and far, width and height value of your screen.

Parameters
widthWidth in pixels of the original intrinsics
heightHeight in pixels of the original intrinsics
cxNormed horizontal principal point of the intrinsics 0..1
cyNormed vertical principal point of the intrinsics 0..1
fxThe normalized focal length of the intrinsic camera calibration in x direction.
fyThe normalized focal length of the intrinsic camera calibration in y direction.

◆ onLog:()

- (void vlFrameListenerInterface) onLog: (NSString *_Nonnull)  logString
optional

Receive the internal visionLib Log. Depending on the configured log level you will receive the internal log messages from the visionlib. You might use these messages during development. Anyway it is NOT recommended using them for the end user nor parsing them. Defined issues should be gathered by using onTrackerInitializedWithWarningIssues:andErrors:.

Parameters
logStringA NSString holding the message

◆ onMetalDebugImageTexture:withRotationMatrix:()

- (void vlFrameListenerInterface) onMetalDebugImageTexture: (_Nonnull id< MTLTexture >)  texture
withRotationMatrix: (float *_Nonnull)  m 
optional

Retreives the configured Debug Image as a metal texture When overloading this function, a metal texture will be passed, when needed to be set or rendered as background texture functions like onGetDebugImageBufferWithWidth and/or onRawImageBuffer will not be called then, even if defined.

Parameters
dataMTLTexture object
mA pointer to 16 item matrix holding a rotation matrix of the content to be rotated with

◆ onMetalImageTexture:withRotationMatrix:()

- (void vlFrameListenerInterface) onMetalImageTexture: (_Nonnull id< MTLTexture >)  texture
withRotationMatrix: (float *_Nonnull)  m 
optional

Receive a metal image buffer (experimental) When overloading this function, a metal texture will be passed, when needed to be set or rendered as background texture functions like onGetImageBufferWithWidth and/or onRawImageBuffer will not be called then, even if defined.

Parameters
dataThe number of bytes occupied per pixel (e.g. 4 for RGBA images)
widthThe width of the image
widthThe height of the image
bytesPerPixelthe number of bytes occupied per pixel (e.g. 4 for RGBA images)

◆ onModelProperties:()

- (void vlFrameListenerInterface) onModelProperties: (NSArray< vlModelProperties * > *_Nonnull)  info
optional

◆ onModelRemoved:withError:()

- (void vlFrameListenerInterface) onModelRemoved: (NSString *_Nullable)  json
withError: (NSString *_Nullable)  errorJson 
optional

◆ onRawDebugImageBuffer:withWidth:andHeight:andBytesPerPixel:()

- (void vlFrameListenerInterface) onRawDebugImageBuffer: (NSData *_Nonnull)  data
withWidth: (int)  width
andHeight: (int)  height
andBytesPerPixel: (int)  bytesPerPixel 
optional

Retreives the configured Debug Image Overloading this function onGetDebugImageBufferWithWidth should not have been overloaded too. will provide you on every frame with fresh image data.

Parameters
dataThe number of bytes occupied per pixel (e.g. 4 for RGBA images)
widthThe width of the image
widthThe height of the image
bytesPerPixelthe number of bytes occupied per pixel (e.g. 4 for RGBA images)

◆ onRawImageBuffer:withWidth:andHeight:andBytesPerPixel:()

- (void vlFrameListenerInterface) onRawImageBuffer: (NSData *_Nonnull)  data
withWidth: (int)  width
andHeight: (int)  height
andBytesPerPixel: (int)  bytesPerPixel 
optional

Receive a raw image buffer Overloading this function onGetImageBufferWithWidth should not have been overloaded too. will provide you on every frame with fresh image data.

Parameters
dataThe number of bytes occupied per pixel (e.g. 4 for RGBA images)
widthThe width of the image
widthThe height of the image
bytesPerPixelthe number of bytes occupied per pixel (e.g. 4 for RGBA images)

◆ onRawModelAdded:withError:()

- (void vlFrameListenerInterface) onRawModelAdded: (NSString *_Nullable)  json
withError: (NSString *_Nullable)  errorJson 
optional

◆ onResetTracking:()

- (void vlFrameListenerInterface) onResetTracking: (BOOL)  hard
optional

Receive the reset state Will be called when a reset has occured (hard or soft)

Parameters
hardA bool indicating if a hard or soft reset has occured.

◆ onSteppedFrame()

- (void vlFrameListenerInterface) onSteppedFrame
optional

Receive the stepped state. Will be called, when the SDK has stepped one frame forward. This can be used in conjunction with stepFrame.

◆ onTrackerInitialized:()

- (void vlFrameListenerInterface) onTrackerInitialized: (bool)  worked
optional

When the tracker has been initialized Will be called when the tracker has been done loading and is running now or not. It is recommended using the onTrackerInitializedWithWarningIssues:andErrors: function for more precise informations about the state of the tracking pipe.

Parameters
workedtrue or false

◆ onTrackerInitializedWithWarningIssues:andErrors:()

- (void vlFrameListenerInterface) onTrackerInitializedWithWarningIssues: (vlTrackingIssues *_Nullable)  warnings
andErrors: (vlTrackingIssues *_Nullable)  errors 
optional

Will be called when the tracker has been done loading and is running now. Tracking issues are passed separated by errors and warnings. You should take these very serious. You can review a complete list of possible issues in the documentation.

When an error has occured, the tracking will NOT start working in anyway.

Parameters
warningOptional warnings may occured during initialization.
errorsOptional errors may occured during initialization.

◆ onTrackingInformation:()

- (void vlFrameListenerInterface) onTrackingInformation: (NSDictionary *_Nonnull)  info
optional

Receive runtime tracking information on each frame Will pass a dictionary with information about the tracking quality etc into the application only if is tracking.

Parameters
infoA Dictionary holding informations about the tracking

"quality": 0.39441, // maps to tracking inlier ration for now

"state": "tracked", // Can be "tracked", "critical" or "lost"

"_InitInlierRatio": 0.731507, // The inlier ratio that has been present at the moment of initialization

"_InitNumOfCorresp": 365, // The number of correspondences used when initializing

"_TrackingInlierRatio": 0.39441, // The current inliner ratio

"_TrackingNumOfCorresp": 392, // The number of correspondences used actually

"_SFHFrameDist": 466.549, // Actual distance to last key frame

"_NumberOfTemplates": 83 // Number of reinitialization key frames learned

◆ onTrackingPaused:()

- (void vlFrameListenerInterface) onTrackingPaused: (BOOL)  worked
optional

Receive the pause state. Will be called, when the tracking pause was issued.

Parameters
workedA boolean variable stating if the pause command has worked.