ds::DeepSight Class Reference

DeepSight SDK engine class. More...

Public Member Functions
	DeepSight (const ds::Settings &settings)
	ds::DeepSight constructor. More...
	~DeepSight () noexcept
	ds::DeepSight destructor.
	DeepSight (DeepSight &&ds) noexcept
	ds::DeepSight move constructor. More...
DeepSight &	operator= (DeepSight &&ds) noexcept
	ds::DeepSight move assignment operator. More...
void	authenticate ()
	Authenticates the SDK. More...
void	setSettings (const ds::Settings &settings)
	Set new settings to be used at runtime. More...
ds::Settings	getSettings () const
	Returns a copy of the settings object in use. More...
std::vector< ds::Person >	analyze (const cv::Mat &image)
	Analyzes an image, tracks and returns the detected faces. More...
std::vector< ds::Person >	analyzeSingleImage (const cv::Mat &image)
	Analyzes an image and returns the detected faces without tracking. More...
std::vector< ds::Body >	analyzeBodies (const cv::Mat &image)
	Analyzes an image, tracks and returns the detected bodies. More...
std::vector< cv::Rect >	getTrackedBoxes ()
	Returns the bounding boxes tracked by the internal DeepSight tracker. More...
int	getLicenseTimeLeft () const
int	getCountOfFaces () const
	Returns the number of counted faces. More...
int	getCountOfBodies () const
	Returns the number of tracked bodies. More...
void	resetTracker (bool resetCount)
	Resets the state of the internal face tracker. More...
void	resetBodyTracker (bool resetCount)
	Resets the state of the internal body tracker. More...

Detailed Description

DeepSight SDK engine class.

The ds::DeepSight class is the engine of the SDK. By instantiating a ds::DeepSight object the SDK engine is set up and is ready for processing images. The ds::DeepSight class is controlled by the ds::Settings class which holds the external configuration parameters. The main purpose of the ds::DeepSight class is to accept an image and to return a list of ds::Person objects detected in it.

Constructor & Destructor Documentation

DeepSight() [1/2]

ds::DeepSight::DeepSight

(

const ds::Settings &

settings

)

ds::DeepSight constructor.

Parameters

settings

A ds::Settings instance containing the configuration to be used by the DeepSight SDK engine.

Main ds::DeepSight constructor. May throw std::runtime_error exceptions if the neuralNetworksPath specified in the settings does not contain the required networks.

Example usage:

ds::Settings s;
s.neuralNetworksPath = "/path/to/neuralnetworks";
try
{
  ds::DeepSight ds{ s };
}
catch( const std::runtime_error & e )
{
  std::cerr << "Could not construct DeepSight object : " << e.what() << std::endl;
}

DeepSight() [2/2]

ds::DeepSight::DeepSight ( ds::DeepSight &&  ds )

noexcept

ds::DeepSight move constructor.

A ds::DeepSight object cannot be copied, but it can be moved. The move constructor allows for this.

Example usage:

ds::Settings s;
s.neuralNetworksPath = "/path/to/neuralnetworks";
ds::DeepSight ds{ s };
ds::DeepSight ds2 = std::move( ds );

Member Function Documentation

analyze()

std::vector< ds::Person > ds::DeepSight::analyze

(

const cv::Mat &

image

)

Analyzes an image, tracks and returns the detected faces.

Parameters

image

A cv::Mat 3-dimensional array representing a BGR image. Must be non empty.

Returns

An std::vector of ds::Person objects detected in the input image, sorted in descending order of bounding-box area.

This function performs the main SDK task of detecting faces in the input image and performing face analysis on each of them. If the SDK is not already authenticated, the ds::DeepSight::analyze function throws an std::runtime_error exception. Faces detected during the ds::DeepSight::analyze call are tracked in consecutive calls and interpolated such that the ID of each ds::Person is matched among the frames. This allows for assigning the same ID to the same face and smoothing age and gender for more stable estimations.

Example usage:

ds::Settings s;
s.neuralNetworksPath = "/path/to/neuralnetworks";
s.licenseKey = "license key";
ds::DeepSight ds{ s };
 
cv::Mat image = cv::imread( "/path/to/an/image" );
std::vector<ds::Person> people = ds.analyze( image );
for( const ds::Person & person : people )
  std::cout << person.boundingBox << std::endl;

analyzeBodies()

std::vector< ds::Body > ds::DeepSight::analyzeBodies

(

const cv::Mat &

image

)

Analyzes an image, tracks and returns the detected bodies.

Parameters

image

A cv::Mat 3-dimensional array representing a BGR image. Must be non-empty.

Returns

An std::vector of ds::Body objects detected in the input image.

This function performs body detection, tracking and counting. The bodies detected in the current frame are returned. If the SDK is not already authenticated, the ds::DeepSight::analyzeBodies function throws an std::runtime_error exception. Bodies detected during the ds::DeepSight::analyzeBodies call are tracked in consecutive calls and interpolated such that the ID of each ds::Body is matched among the frames. This allows for assigning the same ID to the same body and keeping track of detection duration.

Example usage:

ds::Settings s;
s.neuralNetworksPath = "/path/to/neuralnetworks";
s.licenseKey = "license key";
ds::DeepSight ds{ s };
 
cv::Mat image = cv::imread( "/path/to/an/image" );
std::vector<ds::Body> bodies = ds.analyzeBodies( image );
for( const ds::Body & body : bodies )
  std::cout << body.boundingBox << std::endl;

analyzeSingleImage()

std::vector< ds::Person > ds::DeepSight::analyzeSingleImage

(

const cv::Mat &

image

)

Analyzes an image and returns the detected faces without tracking.

Parameters

image

A cv::Mat 3-dimensional array representing a BGR image. Must be non empty.

Returns

An std::vector of ds::Person objects detected in the input image, sorted in descending order of bounding-box area.

This function is similar to ds::DeepSight::analyze with the exception that the faces detected in the input image are not tracked and therefore not interpolated with previously analyzed frames.

Example usage:

ds::Settings s;
s.neuralNetworksPath = "/path/to/neuralnetworks";
s.licenseKey = "license key";
ds::DeepSight ds{ s };
 
cv::Mat image = cv::imread( "/path/to/an/image" );
std::vector<ds::Person> people = ds.analyzeSingleImage( image );
for( const ds::Person & person : people )
  std::cout << person.boundingBox << std::endl;

authenticate()

void ds::DeepSight::authenticate

(

)

Authenticates the SDK.

Authenticate the DeepSight SDK against Raydiant's licensing servers to allow for its usage. Throws an std::runtime_error if the authentication fails. Before authenticating make sure the ds::Settings::licenseKey (and ds::Settings::lifetimeAuthFile in case of a lifetime release authentication) is properly set.

Example usage:

ds::Settings s;
s.neuralNetworksPath = "/path/to/neuralnetworks";
s.licenseKey = "license key";
ds::DeepSight ds{ s };
try
{
  ds.authenticate();
}
catch( const std::runtime_error & e )
{
  std::cerr << "Could not authenticate the SDK : " << e.what() << std::endl;
}

getCountOfBodies()

int ds::DeepSight::getCountOfBodies

(

)

const

Returns the number of tracked bodies.

Returns

The number of tracked bodies.

If ds::DeepSight::analyzeBodies is used, the SDK internally keeps track of detected bodies and returns the count through this function.

Note

This feature is in beta version and might be subject to changes.

In SDK versions 0.13.0 and earlier, this function was returning the same value of ds::DeepSight::getCountOfFaces().

getCountOfFaces()

int ds::DeepSight::getCountOfFaces

(

)

const

Returns the number of counted faces.

Returns

The number of counted faces.

Returns the number of faces counted by the tracker. Each ds::Person returned by ds::DeepSight::analyze with the same ID is counted once.

Note

This function was ds::DeepSight::getCountOfBodies() in 0.13.0 and earlier versions of the SDK.

getLicenseTimeLeft()

int ds::DeepSight::getLicenseTimeLeft

(

)

const

Returns

The time remaining on a DeepSight license in seconds. This is negative if the license expired, or zero if the SDK did not authenticate.

getSettings()

ds::Settings & ds::DeepSight::getSettings

(

)

const

Returns a copy of the settings object in use.

Returns

A copy of the settings object in use.

Example usage:

ds::DeepSight ds{};
ds::Settings s = ds.getSettings();
// reload networks
s.neuralNetworksPath = "other/path/to/neuralnetworks";
ds.setSettings(s);

getTrackedBoxes()

std::vector< cv::Rect > ds::DeepSight::getTrackedBoxes

(

)

Returns the bounding boxes tracked by the internal DeepSight tracker.

Returns

An std::vector of cv::Rect representing the bounding boxes of faces internally tracked.

When using the ds::DeepSight::analyze() function, each face detected in the frame is passed to an internal tracker. The tracker then interpolates the current face position with the one in the previous frames. Due to occlusion, sometimes a face cannot be found during the detection stage, however the tracker might still be able to find its location given the information collected in the previous frames. This function returns the position of the faces internally tracked, which in some cases differs from the ones detected during the ds::DeepSight::analyze(). This function is particularly usefull when blurring faces, since the detector might fail finding a face when occlusion occurs while the tracker is able to keep track of the face position.

Note

The tracking of a face depends on the detections stage, therefore it is required to call ds::DeepSight::analyze() before calling ds::DeepSight::getTrackedBoxes().

operator=()

ds::DeepSight & ds::DeepSight::operator= ( ds::DeepSight &&  ds )

noexcept

ds::DeepSight move assignment operator.

A ds::DeepSight object cannot be copied, but it can be moved. The move assignment operator allows for this.

Example usage:

ds::Settings s;
s.neuralNetworksPath = "/path/to/neuralnetworks";
ds::DeepSight ds{ s };
ds::DeepSight ds2{ s };
ds2 = std::move( ds );

resetBodyTracker()

void ds::DeepSight::resetBodyTracker

(

bool

resetCount

)

Resets the state of the internal body tracker.

Parameters

resetCount

If true, resets the tracker's body-counter to 0.

Resets the state of the internal tracker and (optionally) the number of tracked bodies.

resetTracker()

void ds::DeepSight::resetTracker

(

bool

resetCount

)

Resets the state of the internal face tracker.

Parameters

resetCount

If true, resets the tracker's person-counter to 0.

Resets the state of the internal tracker and (optionally) the number of tracked faces.

setSettings()

void ds::DeepSight::setSettings

(

const ds::Settings &

settings

)

Set new settings to be used at runtime.

Parameters

settings

A ds::Settings instance containing the new configuration to be used by the DeepSight SDK engine.

Example usage:

ds::Settings s;
ds::DeepSight ds{ s };
// load networks
s.neuralNetworksPath = "/path/to/neuralnetworks";
ds.setSettings( s );