ds_help.h File Reference

#include "ds_exports.h"
#include "ds_person.h"
#include <chrono>
#include <vector>
#include <opencv2/core/core.hpp>

Go to the source code of this file.

Classes
class	ds::help::Fps
	Helper class to keep track of analyzed frames per second. More...
class	ds::help::SourceHandler
	Helper class to handle different types of video input sources, like webcams, IP cameras or video files. More...

Functions
DS_API cv::Rect	ds::help::padRect (const cv::Rect &rect, float padFactor)
	Pads a cv::Rect by a padding factor. More...
DS_API cv::Rect	ds::help::clipRect (const cv::Rect &rect, const cv::Mat &image)
	Clips the sides of a cv::Rect overflowing the image. More...
DS_API cv::Rect	ds::help::padClipRect (const cv::Rect &rect, float padFactor, const cv::Mat &image)
	Pads a cv::Rect by a padding factor and clips the sides overflowing the image. More...
DS_API void	ds::help::drawHeadpose (cv::Mat &frame, const ds::Person &person)
	Draw the headpose of a given person on a frame. More...
DS_API void	ds::help::drawPerson (const ds::Person &person, cv::Mat &image)
	Draws all attributes of person on top of image. More...
DS_API void	ds::help::drawPersonNoLabel (const ds::Person &person, cv::Mat &image)
	Same as ds::help::drawPerson(), but draws only the bounding-box and headpose-axes. More...
DS_API void	ds::help::drawPersonMinimal (const ds::Person &person, cv::Mat &image)
	Same as ds::help::drawPerson(), but it prints only a subset of the ds::Person data. More...
DS_API void	ds::help::drawPeople (const std::vector< ds::Person > &people, cv::Mat &image)
	Calls ds::help::drawPerson() on each ds::Person contained in people. More...
DS_API void	ds::help::drawPeopleNoLabel (const std::vector< ds::Person > &people, cv::Mat &image)
	Calls ds::help::drawPersonNoLabel() on each ds::Person contained in people. More...
DS_API void	ds::help::drawPeopleMinimal (const std::vector< ds::Person > &people, cv::Mat &image)
	Calls ds::help::drawPersonMinimal() on each ds::Person contained in people. More...
DS_API cv::Mat	ds::help::drawPerson (const ds::Person &person, const cv::Mat &image)
	Same as ds::help::drawPerson() but it draws on the returned copy. More...
DS_API cv::Mat	ds::help::drawPersonNoLabel (const ds::Person &person, const cv::Mat &image)
	Same as ds::help::drawPersonNoLabel() but it draws on the returned copy. More...
DS_API cv::Mat	ds::help::drawPersonMinimal (const ds::Person &person, const cv::Mat &image)
	Same as ds::help::drawPersonMinimal() but it draws on the returned copy. More...
DS_API cv::Mat	ds::help::drawPeople (const std::vector< ds::Person > &people, const cv::Mat &image)
	Same as ds::help::drawPeople() but it draws on the returned copy. More...
DS_API cv::Mat	ds::help::drawPeopleNoLabel (const std::vector< ds::Person > &people, const cv::Mat &image)
	Same as ds::help::drawPeopleNoLabel() but it draws on the returned copy. More...
DS_API cv::Mat	ds::help::drawPeopleMinimal (const std::vector< ds::Person > &people, const cv::Mat &image)
	Same as ds::help::drawPeopleMinimal() but it draws on the returned copy. More...
DS_API void	ds::help::drawBody (const ds::Body &body, cv::Mat &image)
	Draws all attributes of body on top of image. More...
DS_API void	ds::help::drawBodies (const std::vector< ds::Body > &bodies, cv::Mat &image)
	Calls ds::help::drawBody() on each ds::Body contained in bodies. More...
DS_API cv::Mat	ds::help::drawBody (const ds::Body &body, const cv::Mat &image)
	Same as ds::help::drawBody() but it draws on the returned copy. More...
DS_API cv::Mat	ds::help::drawBodies (const std::vector< ds::Body > &bodies, const cv::Mat &image)
	Same as ds::help::drawBodies() but it draws on the returned copy. More...
DS_API void	ds::help::blurPerson (const ds::Person &person, cv::Mat &image)
	Blurs the image region where the person's face is. More...
DS_API void	ds::help::blurPeople (const std::vector< ds::Person > &people, cv::Mat &image)
	Calls ds::help::blurPerson() on each ds::Person contained in people. More...
DS_API void	ds::help::blurBox (const cv::Rect &box, cv::Mat &image)
	Blurs the image region where the bounding box is. More...
DS_API void	ds::help::blurBoxes (const std::vector< cv::Rect > &boxes, cv::Mat &image)
	Calls ds::help::blurBox() on each cv::Rect contained in boxes. More...
DS_API cv::Mat	ds::help::blurPerson (const ds::Person &person, const cv::Mat &image)
	Same as ds::help::blurPerson() but it draws on the returned copy. More...
DS_API cv::Mat	ds::help::blurPeople (const std::vector< ds::Person > &people, const cv::Mat &image)
	Same as ds::help::blurPeople() but it draws on the returned copy. More...
DS_API cv::Mat	ds::help::blurBox (const cv::Rect &box, const cv::Mat &image)
	Same as ds::help::blurBox() but it draws on the returned copy. More...
DS_API cv::Mat	ds::help::blurBoxes (const std::vector< cv::Rect > &boxes, const cv::Mat &image)
	Same as ds::help::blurBoxes() but it draws on the returned copy. More...
DS_API std::string	ds::help::personToCsvHeader ()
	Returns the header string of a ds::Person instance in CSV representation, as in ds::help::personToCsv(). More...
DS_API std::string	ds::help::personToCsv (const ds::Person &person)
	Returns a CSV record representing the input person. More...
DS_API std::vector< std::string >	ds::help::peopleToCsv (const std::vector< ds::Person > &people)
	Returns a vector of CSV records representing the input people. More...
DS_API std::string	ds::help::formatPerson (const std::string &templateStr, const ds::Person &person)
	Returns a formatted string given a template using the FMT format. More...
DS_API std::string	ds::help::aggregatedPersonToCsvHeader ()
	Returns the header string of a ds::AggregatedPerson instance in CSV representation, as in ds::help::aggregatedPersonToCsv(). More...
DS_API std::string	ds::help::aggregatedPersonToCsv (const ds::AggregatedPerson &aggregatedPerson)
	Returns a CSV record representing the input aggregatedPerson. More...
DS_API std::vector< std::string >	ds::help::aggregatedPeopleToCsv (const std::vector< ds::AggregatedPerson > &aggregatedPeople)
	Returns a vector of CSV records representing the input aggregatedPeople. More...
DS_API std::string	ds::help::formatAggregatedPerson (const std::string &templateStr, const ds::AggregatedPerson &aggregatedPerson)
	Returns a formatted string given a template using the FMT format. More...
DS_API std::string	ds::help::bodyToCsvHeader ()
	Returns the header string of a ds::Body instance in CSV representation, as in ds::help::bodyToCsv(). More...
DS_API std::string	ds::help::bodyToCsv (const ds::Body &body)
	Returns a CSV record representing the input body. More...
DS_API std::vector< std::string >	ds::help::bodiesToCsv (const std::vector< ds::Body > &bodies)
	Returns a vector of CSV records representing the input bodies. More...
DS_API std::string	ds::help::formatBody (const std::string &templateStr, const ds::Body &body)
	Returns a formatted string given a template using the FMT format. More...
DS_API std::string	ds::help::aggregatedBodyToCsvHeader ()
	Returns the header string of a ds::AggregatedBody instance in CSV representation, as in ds::help::aggregatedBodyToCsv(). More...
DS_API std::string	ds::help::aggregatedBodyToCsv (const ds::AggregatedBody &aggregatedBody)
	Returns a CSV record representing the input aggregatedBody. More...
DS_API std::vector< std::string >	ds::help::aggregatedBodiesToCsv (const std::vector< ds::AggregatedBody > &aggregatedBodies)
	Returns a vector of CSV records representing the input aggregatedBodies. More...
DS_API std::string	ds::help::formatAggregatedBody (const std::string &templateStr, const ds::AggregatedBody &aggregatedBody)
	Returns a formatted string given a template using the FMT format. More...
DS_API std::string	ds::help::getMachineID (const std::string &licenseKey)
	Returns a unique identifier string for the machine on which the SDK runs. More...
DS_API std::string	ds::help::getOpenCLDebugString ()
	Returns a string containing OpenCL version and device information.

Detailed Description

This module contains support functionality for common tasks like converting a ds::Person to CSV or drawing a face on a frame.

Function Documentation

aggregatedBodiesToCsv()

std::vector< std::string > ds::help::aggregatedBodiesToCsv

(

const std::vector< ds::AggregatedBody > &

aggregatedBodies

)

Returns a vector of CSV records representing the input aggregatedBodies.

Parameters

aggregatedBodies

A vector of ds::AggregatedBody instances to convert to CSV

aggregatedBodyToCsv()

std::string ds::help::aggregatedBodyToCsv

(

const ds::AggregatedBody &

aggregatedBody

)

Returns a CSV record representing the input aggregatedBody.

Parameters

aggregatedBody

ds::AggregatedBody instance to convert to CSV

aggregatedBodyToCsvHeader()

std::string ds::help::aggregatedBodyToCsvHeader

(

)

Returns the header string of a ds::AggregatedBody instance in CSV representation, as in ds::help::aggregatedBodyToCsv().

Returns

A CSV header string

aggregatedPeopleToCsv()

std::vector< std::string > ds::help::aggregatedPeopleToCsv

(

const std::vector< ds::AggregatedPerson > &

aggregatedPeople

)

Returns a vector of CSV records representing the input aggregatedPeople.

Parameters

aggregatedPeople

A vector of ds::AggregatedPerson instances to convert to CSV

aggregatedPersonToCsv()

std::string ds::help::aggregatedPersonToCsv

(

const ds::AggregatedPerson &

aggregatedPerson

)

Returns a CSV record representing the input aggregatedPerson.

Parameters

aggregatedPerson

ds::AggregatedPerson instance to convert to CSV

The resulting CSV string is augmented with two extra fields: viewer and dweller. viewer indicates if the person was ever viewing or not (if viewingSessions > 0), represented by 1 or 0 respectively. dweller indicates if the person was ever dwelling or not (if dwellSessions > 0), represented by 1 or 0 respectively.

aggregatedPersonToCsvHeader()

std::string ds::help::aggregatedPersonToCsvHeader

(

)

Returns the header string of a ds::AggregatedPerson instance in CSV representation, as in ds::help::aggregatedPersonToCsv().

Returns

A CSV header string

The header is augmented with two extra fields: viewer and dweller (see ds::help::aggregatedPersonToCsv() documentation).

blurBox() [1/2]

cv::Mat ds::help::blurBox	(	const cv::Rect &	box,
		const cv::Mat &	image
	)

Same as ds::help::blurBox() but it draws on the returned copy.

Parameters

box	cv::Rect to blur
image	Canvas image to draw on

blurBox() [2/2]

void ds::help::blurBox	(	const cv::Rect &	box,
		cv::Mat &	image
	)

Blurs the image region where the bounding box is.

Parameters

box	cv::Rect to blur
image	Canvas image to draw on

blurBoxes() [1/2]

cv::Mat ds::help::blurBoxes	(	const std::vector< cv::Rect > &	boxes,
		const cv::Mat &	image
	)

Same as ds::help::blurBoxes() but it draws on the returned copy.

Parameters

boxes	The vector of cv::Rect to blur
image	Canvas image to draw on

blurBoxes() [2/2]

void ds::help::blurBoxes	(	const std::vector< cv::Rect > &	boxes,
		cv::Mat &	image
	)

Calls ds::help::blurBox() on each cv::Rect contained in boxes.

Parameters

boxes	The vector of cv::Rect to blur
image	Canvas image to draw on

blurPeople() [1/2]

cv::Mat ds::help::blurPeople	(	const std::vector< ds::Person > &	people,
		const cv::Mat &	image
	)

Same as ds::help::blurPeople() but it draws on the returned copy.

Parameters

people	The vector of ds::Person to blur
image	Canvas image to clone and draw on

blurPeople() [2/2]

void ds::help::blurPeople	(	const std::vector< ds::Person > &	people,
		cv::Mat &	image
	)

Calls ds::help::blurPerson() on each ds::Person contained in people.

Parameters

people	The vector of ds::Person to blur
image	Canvas image to draw on

blurPerson() [1/2]

cv::Mat ds::help::blurPerson	(	const ds::Person &	person,
		const cv::Mat &	image
	)

Same as ds::help::blurPerson() but it draws on the returned copy.

Parameters

person	ds::Person to blur
image	Canvas image to clone and draw on

blurPerson() [2/2]

void ds::help::blurPerson	(	const ds::Person &	person,
		cv::Mat &	image
	)

Blurs the image region where the person's face is.

Parameters

person	ds::Person to blur
image	Canvas image to draw on

bodiesToCsv()

std::vector< std::string > ds::help::bodiesToCsv

(

const std::vector< ds::Body > &

bodies

)

Returns a vector of CSV records representing the input bodies.

Parameters

bodies

A vector of ds::Body instances to convert to CSV

bodyToCsv()

std::string ds::help::bodyToCsv

(

const ds::Body &

body

)

Returns a CSV record representing the input body.

Parameters

body	ds::Body instance to convert to CSV

bodyToCsvHeader()

std::string ds::help::bodyToCsvHeader

(

)

Returns the header string of a ds::Body instance in CSV representation, as in ds::help::bodyToCsv().

Returns

A CSV header string

clipRect()

cv::Rect ds::help::clipRect	(	const cv::Rect &	rect,
		const cv::Mat &	image
	)

Clips the sides of a cv::Rect overflowing the image.

Parameters

rect	Input rectangle to be clipped.
image	The image where the output rectangle should be contained.

Returns

A cv::Rect which is clipped within the image boundaries.

If the input cv::Rect is within the image boundaries, the returned cv::Rect is the same. Otherwise the parts of the cv::Rect that outside the image boundaries are clipped.

drawBodies() [1/2]

cv::Mat ds::help::drawBodies	(	const std::vector< ds::Body > &	bodies,
		const cv::Mat &	image
	)

Same as ds::help::drawBodies() but it draws on the returned copy.

Parameters

bodies	The vector of ds::Body objects to draw
image	Canvas image to clone and draw on

drawBodies() [2/2]

void ds::help::drawBodies	(	const std::vector< ds::Body > &	bodies,
		cv::Mat &	image
	)

Calls ds::help::drawBody() on each ds::Body contained in bodies.

Parameters

bodies	The vector of ds::Body objects to draw
image	Canvas image to draw on

drawBody() [1/2]

cv::Mat ds::help::drawBody	(	const ds::Body &	body,
		const cv::Mat &	image
	)

Same as ds::help::drawBody() but it draws on the returned copy.

Parameters

body	ds::Body object to draw
image	Canvas image to clone and draw on

drawBody() [2/2]

void ds::help::drawBody	(	const ds::Body &	body,
		cv::Mat &	image
	)

Draws all attributes of body on top of image.

Parameters

body	ds::Body object to draw
image	Canvas image to draw on

drawHeadpose()

void ds::help::drawHeadpose	(	cv::Mat &	frame,
		const ds::Person &	person
	)

Draw the headpose of a given person on a frame.

Parameters

frame	Canvas image to draw the headpose on.
person	ds::Person instance containing the headpose to draw.

drawPeople() [1/2]

cv::Mat ds::help::drawPeople	(	const std::vector< ds::Person > &	people,
		const cv::Mat &	image
	)

Same as ds::help::drawPeople() but it draws on the returned copy.

Parameters

people	The vector of ds::Person objects to draw
image	Canvas image to clone and draw on

drawPeople() [2/2]

void ds::help::drawPeople	(	const std::vector< ds::Person > &	people,
		cv::Mat &	image
	)

Calls ds::help::drawPerson() on each ds::Person contained in people.

Parameters

people	The vector of ds::Person objects to draw
image	Canvas image to draw on

drawPeopleMinimal() [1/2]

cv::Mat ds::help::drawPeopleMinimal	(	const std::vector< ds::Person > &	people,
		const cv::Mat &	image
	)

Same as ds::help::drawPeopleMinimal() but it draws on the returned copy.

Parameters

people	The vector of ds::Person objects to draw
image	Canvas image to clone and draw on

drawPeopleMinimal() [2/2]

void ds::help::drawPeopleMinimal	(	const std::vector< ds::Person > &	people,
		cv::Mat &	image
	)

Calls ds::help::drawPersonMinimal() on each ds::Person contained in people.

Parameters

people	The vector of ds::Person objects to draw
image	Canvas image to draw on

drawPeopleNoLabel() [1/2]

cv::Mat ds::help::drawPeopleNoLabel	(	const std::vector< ds::Person > &	people,
		const cv::Mat &	image
	)

Same as ds::help::drawPeopleNoLabel() but it draws on the returned copy.

Parameters

people	The vector of ds::Person objects to draw
image	Canvas image to clone and draw on

drawPeopleNoLabel() [2/2]

void ds::help::drawPeopleNoLabel	(	const std::vector< ds::Person > &	people,
		cv::Mat &	image
	)

Calls ds::help::drawPersonNoLabel() on each ds::Person contained in people.

Parameters

people	The vector of ds::Person objects to draw
image	Canvas image to draw on

drawPerson() [1/2]

cv::Mat ds::help::drawPerson	(	const ds::Person &	person,
		const cv::Mat &	image
	)

Same as ds::help::drawPerson() but it draws on the returned copy.

Parameters

person	ds::Person object to draw
image	Canvas image to clone and draw on

drawPerson() [2/2]

void ds::help::drawPerson	(	const ds::Person &	person,
		cv::Mat &	image
	)

Draws all attributes of person on top of image.

Parameters

person	ds::Person object to draw
image	Canvas image to draw on

Gender is identified by the color of the bounding box: red for female, blue for male.

drawPersonMinimal() [1/2]

cv::Mat ds::help::drawPersonMinimal	(	const ds::Person &	person,
		const cv::Mat &	image
	)

Same as ds::help::drawPersonMinimal() but it draws on the returned copy.

Parameters

person	ds::Person object to draw
image	Canvas image to clone and draw on

The printed attributes are: ID, viewing, age, gender, smile.

drawPersonMinimal() [2/2]

void ds::help::drawPersonMinimal	(	const ds::Person &	person,
		cv::Mat &	image
	)

Same as ds::help::drawPerson(), but it prints only a subset of the ds::Person data.

Parameters

person	ds::Person object to draw
image	Canvas image to draw on

The printed attributes are: ID, viewing, age, gender, smile.

drawPersonNoLabel() [1/2]

cv::Mat ds::help::drawPersonNoLabel	(	const ds::Person &	person,
		const cv::Mat &	image
	)

Same as ds::help::drawPersonNoLabel() but it draws on the returned copy.

Parameters

person	ds::Person object to draw
image	Canvas image to clone and draw on

drawPersonNoLabel() [2/2]

void ds::help::drawPersonNoLabel	(	const ds::Person &	person,
		cv::Mat &	image
	)

Same as ds::help::drawPerson(), but draws only the bounding-box and headpose-axes.

Parameters

person	ds::Person object to draw
image	Canvas image to draw on

formatAggregatedBody()

std::string ds::help::formatAggregatedBody	(	const std::string &	templateStr,
		const ds::AggregatedBody &	aggregatedBody
	)

Returns a formatted string given a template using the FMT format.

Parameters

templateStr	A string containing the template.
aggregatedBody	ds::AggregatedBody instance to fill the template string with.

Given a template string, this function replaces the template variables with the body's attribute values. The template variable names are equal to the ds::AggregatedBody member names.

formatAggregatedPerson()

std::string ds::help::formatAggregatedPerson	(	const std::string &	templateStr,
		const ds::AggregatedPerson &	aggregatedPerson
	)

Returns a formatted string given a template using the FMT format.

Parameters

templateStr	A string containing the template.
aggregatedPerson	ds::AggregatedPerson instance to fill the template string with.

Given a template string, this function replaces the template variables with the person's attribute values. The template variable names are equal to the ds::AggregatedPerson member names. Two extra variables are provided: "viewer" and "dweller" (see ds::help::aggregatedPersonToCsv() documentation).

formatBody()

std::string ds::help::formatBody	(	const std::string &	templateStr,
		const ds::Body &	body
	)

Returns a formatted string given a template using the FMT format.

Parameters

templateStr	A string containing the template.
body	ds::Body instance to fill the template string with.

Given a template string, this function replaces the template variables with the body's attribute values. The template variable names are equal to the ds::Body member names. Sub-fields names prepend a "_" (underscore) to the parent field name (eg. the template variable name for "boundingBox.x" is "bounding_box_x")

Example:

ds::Body b;
b.ID = 1;
b.boundingBox.x = 4;
b.boundingBox.y = 5;
b.boundingBox.width = 6;
b.boundingBox.height = 7;
 
std::string templateStr = "Body ID: {ID}, bounding box (x, y, width, height): {boundingBox_x}, {boundingBox_y}, {boundingBox_width}, {boundingBox_height}";
 
std::cout << ds::help::formatBody( templateStr, b ) << std::endl;
// Prints: Body ID: 1, bounding box (x, y, width, height): 4, 5, 6, 7"

You can create your own template using the available fields in any order to construct for example a JSON string or a CSV row. You can find the full documentation of FMT here.

formatPerson()

std::string ds::help::formatPerson	(	const std::string &	templateStr,
		const ds::Person &	person
	)

Returns a formatted string given a template using the FMT format.

Parameters

templateStr	A string containing the template.
person	ds::Person instance to fill the template string with.

Given a template string, this function replaces the template variables with the person's attribute values. The template variable names are equal to the ds::Person member names. Sub-fields names prepend a "_" (underscore) to the parent field name (eg. the template variable name for "worldPosition.x" is "worldPosition_x")

Example:

ds::Person p;
p.ID = 1;
p.age = 2;
p.gender = 0.3;
p.boundingBox.x = 4;
p.boundingBox.y = 5;
p.boundingBox.width = 6;
p.boundingBox.height = 7;
 
std::string templateStr = "Person ID: {ID}, age: {age}, gender: {gender}, bounding box (x, y, width, height): {boundingBox_x}, {boundingBox_y}, {boundingBox_width}, {boundingBox_height}";
 
std::cout << ds::help::formatPerson( templateStr, p ) << std::endl;
// Prints: Person ID: 1, age: 2, gender: 0.3, bounding box (x, y, width, height): 4, 5, 6, 7"

You can create your own template using the available fields in any order to construct for example a JSON string or a CSV row. You can find the full documentation of FMT here.

getMachineID()

std::string ds::help::getMachineID

(

const std::string &

licenseKey

)

Returns a unique identifier string for the machine on which the SDK runs.

Parameters

licenseKey

License key to be combined with the machine ID.

padClipRect()

cv::Rect ds::help::padClipRect	(	const cv::Rect &	rect,
		float	padFactor,
		const cv::Mat &	image
	)

Pads a cv::Rect by a padding factor and clips the sides overflowing the image.

Parameters

rect	Input rectangle to be padded.
padFactor	The ratio of padding relative to the original size.
image	The image where the output rectangle should be contained.

Returns

A cv::Rect which is a padded version of the input cv::Rect, clipped within the image boundaries.

Same as ds::help::padRect() but if the resulting rectangle overflows the image boundaries, it is clipped.

padRect()

cv::Rect ds::help::padRect	(	const cv::Rect &	rect,
		float	padFactor
	)

Pads a cv::Rect by a padding factor.

Parameters

rect	Input rectangle to be padded.
padFactor	The ratio of padding relative to the original size.

Returns

A cv::Rect which is a padded version of the input cv::Rect.

The input rect is padded by padFactor on each side and returned by the function. The center of the input rectangle is preserved. A padFactor of 0.2 means that a copy if the input rectangle will be padded by 20% on each side and returned as output.

peopleToCsv()

std::vector< std::string > ds::help::peopleToCsv

(

const std::vector< ds::Person > &

people

)

Returns a vector of CSV records representing the input people.

Parameters

people

A vector of ds::Person instances to convert to CSV

personToCsv()

std::string ds::help::personToCsv

(

const ds::Person &

person

)

Returns a CSV record representing the input person.

Parameters

person

ds::Person instance to convert to CSV

personToCsvHeader()

std::string ds::help::personToCsvHeader

(

)

Returns the header string of a ds::Person instance in CSV representation, as in ds::help::personToCsv().

Returns

A CSV header string