visageSDK
Instance Methods | List of all members
VisageTracker Class Reference

Objective-C wrapper of the native VisageSDK::VisageTracker class. More...

#import <objc_VisageTracker.h>

Inherits NSObject.

Instance Methods

(VisageTracker *) - init:
 Constructor. More...
 
(int *) - track:withFrameHeight:withImageData:withFaceDataCollection:withFormat:withOrigin:withWidthStep:withTimeStamp:withMaxFaces:
 Performs face tracking (one or more faces) in the given image and returns tracking results and status. More...
 
(void) - setTrackerConfiguration:withAuFittingDisabled:withMeshFittingDisabled:
 Sets tracking configuration. More...
 
(void) - setIPD:
 Sets the inter pupillary distance. More...
 
(float) - getIPD
 Returns the current inter pupillary distance (IPD) setting. More...
 
(void) - stop
 
(void) - reset
 Reset tracking. More...
 
(NSString *) - getSDKVersion
 Returns visageSDK version and revision number.
 

Detailed Description

Objective-C wrapper of the native VisageSDK::VisageTracker class.

Definition at line 30 of file objc_VisageTracker.h.

Method Documentation

◆ getIPD()

- (float) getIPD

Returns the current inter pupillary distance (IPD) setting.

IPD setting is used by the tracker to estimate the distance of the face from the camera. See setIPD() for further details.

Returns
current setting of inter pupillary distance (IPD) in meters.
See also
setIPD()

◆ init:()

- (VisageTracker *) init: (NSString *)  trackerConfigFile

Constructor.

Parameters
trackerConfigFilethe name of the tracker configuration file (.cfg)

◆ reset()

- (void) reset

Reset tracking.

Resets the tracker. Tracker will reinitialise.

◆ setIPD:()

- (void) setIPD: (float)  value

Sets the inter pupillary distance.

Inter pupillary distance (IPD) is used by the tracker to estimate the distance of the face from the camera. By default, IPD is set to 0.065 (65 millimeters) which is considered average. If the actual IPD of the tracked person is known, this function can be used to set this IPD. As a result, the calculated distance from the camera will be accurate (as long as the camera focal lenght is also set correctly). This is important for applications that require accurate distance. For example, in Augmented Reality applications objects such as virtual eyeglasses can be rendered at appropriate distance and will thus appear in the image with real-life scale.

IMPORTANT NOTE: In case of multitracking, same IPD will be set for all tracked faces!

Parameters
valuethe inter pupillary distance (IPD) in meters.
See also
- getIPD

◆ setTrackerConfiguration:withAuFittingDisabled:withMeshFittingDisabled:()

- (void) setTrackerConfiguration: (NSString *)  trackerConfigFile
withAuFittingDisabled: (bool)  au_fitting_disabled
withMeshFittingDisabled: (bool)  mesh_fitting_disabled 

Sets tracking configuration.

The tracker configuration file name and other configuration parameters are set and will be used for the next tracking session (i.e. when track() is called). Default configuration files (.cfg) are provided in Samples/data folder. Please refer to the VisageTracker Configuration Manual for further details on using the configuration files and all configurable options. Also, please read the section on automatic device-specific configuration selection.

Parameters
trackerConfigFilethe name of the tracker configuration file.
au_fitting_disableddisables the use of the 3D model used to estimate action units (au_fitting_model configuration parameter). If set to true, estimation of action units shall not be performed, and action units related data in the returned FaceData structure will not be available (FaceData::ActionUnits etc.). Disabling will result in a small performance gain.
mesh_fitting_disableddisables the use of the fine 3D mesh (mesh_fitting_model configuration parameter). If set to true, the 3D mesh shall not be fitted and the related information shall not be available in the returned FaceData structure (FaceData::FaceModelVertices etc.). Disabling will result in a small performance gain.

◆ stop()

- (void) stop
Deprecated:
Stops the tracker.

◆ track:withFrameHeight:withImageData:withFaceDataCollection:withFormat:withOrigin:withWidthStep:withTimeStamp:withMaxFaces:()

- (int *) track: (NSInteger)  frameWidth
withFrameHeight: (NSInteger)  frameHeight
withImageData: (const unsigned char *)  imageData
withFaceDataCollection: (FaceDataCollection *)  faceData
withFormat: (int)  format
withOrigin: (int)  origin
withWidthStep: (NSInteger)  widthStep
withTimeStamp: (long)  timeStamp
withMaxFaces: (NSInteger)  maxFaces 

Performs face tracking (one or more faces) in the given image and returns tracking results and status.

This function should be called repeatedly on a series of images in order to perform continuous tracking.

If the tracker needs to be initialized, this will be done automatically before tracking is performed on the given image. Initialization means loading the tracker configuration file, required data files and allocating various data buffers to the given image size. This operation may take several seconds. This happens in the following cases:

  • In the first frame (first call to track() function).
  • When frameWidth or frameHeight are changed, i.e. when they are different from the ones used in the last call to track() function.
  • If setTrackerConfiguration() function was called after the last call to track() function.
  • When maxFaces is changed, i.e. when it its different from the one used in the last call to track() function.

The tracker results are returned in a FaceDataCollection array containing one FaceData object for each tracked face. Contents of each FaceData element depend on the corresponding tracker status (tracker statuses are returned as return value from the function).

The tracking of multiple faces is performed in parallel ( using Dispatch Framework) and performance (speed) may vary depending on the number of CPU cores, the number of faces in the current image and the value of maxFaces argument.

Example:

if let testImagePath = Bundle.main.path(forResource: "image", ofType: "jpg")
{
let image = UIImage(contentsOfFile: testImagePath)
let width = NSInteger(image!.size.width)
let height = NSInteger(image!.size.height)
var trackStatus = UnsafeMutablePointer<Int32>.init(nil)
let faceData = FaceDataCollection(maxFaces: 4)
let maxFaces = 4
let rawData = image?.cgImage?.dataProvider?.data as Data?
let array = [UInt8](rawData!)
trackStatus = tracker!.track(width, withFrameHeight: height, withImageData: array, with: faceData, withFormat: VISAGE_FRAMEGRABBER_FMT_RGBA, withOrigin: VISAGE_FRAMEGRABBER_ORIGIN_TL, withWidthStep: 0, withTimeStamp: -1, withMaxFaces: maxFaces)
}
Parameters
frameWidthWidth of the frame
frameHeightHeight of the frame
imageDataPointer to image pixel data; size of the array must correspond to frameWidth and frameHeight
faceDataAllocated FaceDataCollection object that will receive the tracking results. No tracking results will be returned if NULL pointer is passed. On first call of this function, the memory for the required member variables of the passed array of FaceData objects will be allocated and initialized automatically. The FaceData array must have the size equal to maxFaces argument.
formatFormat of input images passed in p_imageData. It can not change during tracking. Format can be one of the following:
  • VISAGE_FRAMEGRABBER_FMT_RGB: each pixel of the image is represented by three bytes representing red, green and blue channels, respectively.
  • VISAGE_FRAMEGRABBER_FMT_BGR: each pixel of the image is represented by three bytes representing blue, green and red channels, respectively.
  • VISAGE_FRAMEGRABBER_FMT_RGBA: each pixel of the image is represented by four bytes representing red, green, blue and alpha (ignored) channels, respectively.
  • VISAGE_FRAMEGRABBER_FMT_BGRA: each pixel of the image is represented by four bytes representing blue, green, red and alpha (ignored) channels, respectively.
  • VISAGE_FRAMEGRABBER_FMT_LUMINANCE: each pixel of the image is represented by one byte representing the luminance (gray level) of the image.
originNo longer used, therefore, passed value will not have an effect on this function. However, the parameter is left to avoid API changes.
widthStepWidth of the image data buffer, in bytes.
timeStampThe timestamp of the the input frame in milliseconds. The passed value will be returned with the tracking data for that frame (FaceData::timeStamp). Alternatively, the value of -1 can be passed, in which case the tracker will return time, in milliseconds, measured from the moment when tracking started.
maxFacesThe maximum number of faces that will be tracked (tracker currently supports up to 20 faces).
Returns
array of tracking statuses for each of the tracked faces (TRACK_STAT_OFF, TRACK_STAT_OK, TRACK_STAT_RECOVERING and TRACK_STAT_INIT, see FaceData for more details).

The documentation for this class was generated from the following file: