DeepSight SDK  1.0.2
DeepSight SDK - crowd face analysis
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...
 
DeepSightoperator= (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::Personanalyze (const cv::Mat &image)
 Analyzes an image, tracks and returns the detected faces. More...
 
std::vector< ds::PersonanalyzeSingleImage (const cv::Mat &image)
 Analyzes an image and returns the detected faces without tracking. More...
 
int getLicenseTimeLeft () const
 
int getPeopleCount () const
 Returns the number of tracked bodies. (Beta) More...
 
int getFaceCount () const
 Returns the number of counted faces. More...
 
void resetTracker (bool resetCount)
 Resets the state of the internal tracker. More...
 
void resetPeopleCount ()
 Resets the state of the internal body counter. 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
settingsA 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:

s.neuralNetworksPath = "/path/to/neuralnetworks";
try
{
}
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:

s.neuralNetworksPath = "/path/to/neuralnetworks";
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
imageA 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:

s.neuralNetworksPath = "/path/to/neuralnetworks";
s.licenseKey = "license key";
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;

◆ analyzeSingleImage()

std::vector< ds::Person > ds::DeepSight::analyzeSingleImage ( const cv::Mat &  image)

Analyzes an image and returns the detected faces without tracking.

Parameters
imageA 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:

s.neuralNetworksPath = "/path/to/neuralnetworks";
s.licenseKey = "license key";
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 Sightcorp'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:

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

◆ getFaceCount()

int ds::DeepSight::getFaceCount ( ) 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::getPeopleCount() 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.

◆ getPeopleCount()

int ds::DeepSight::getPeopleCount ( ) const

Returns the number of tracked bodies. (Beta)

Returns
The number of tracked bodies.

If ds::Settings::usePeopleCount is enabled, ds::DeepSight::analyze 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::getFaceCount().

◆ 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::Settings s = ds.getSettings();
// reload networks
s.neuralNetworksPath = "other/path/to/neuralnetworks";
ds.setSettings(s);

◆ 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:

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

◆ resetPeopleCount()

void ds::DeepSight::resetPeopleCount ( )

Resets the state of the internal body counter.

Resets the state of the internal body tracker and the number of tracked bodies.

◆ resetTracker()

void ds::DeepSight::resetTracker ( bool  resetCount)

Resets the state of the internal tracker.

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

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

◆ setSettings()

void ds::DeepSight::setSettings ( const ds::Settings settings)

Set new settings to be used at runtime.

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

Example usage:

// load networks
s.neuralNetworksPath = "/path/to/neuralnetworks";
ds.setSettings( s );