Helper classes within the gaze library. More...

Classes
struct	Data
	Wraps the data acquired per frame into a single instance. More...

Functions
dlib::rectangle	get_eye_region (int eye, dlib::full_object_detection object_detection)

double	parse_aspect_ratio (std::string aspect_ratio_string)

double	clamp (double value, double min, double max)

void	fill_displacement_tables (dlib::matrix< double > &table_x, dlib::matrix< double > &table_y, int size)

YAML::Node	get_config ()

YAML::Node	get_config (int pipeline_step_number)

dlib::point	cv_to_dlib (const cv::Point &to_convert)

dlib::rectangle	cv_to_dlib (const cv::Rect &to_convert)

cv::Rect	dlib_to_cv (const dlib::rectangle &to_convert)

std::vector< dlib::chip_details >	get_eyes_chip_details (const dlib::full_object_detection object_detection)

template<typename T >
void	normalize_and_threshold_gradients (dlib::matrix< T > &horizontal, dlib::matrix< T > &vertical, double relative_threshold=-1)

std::ostream &	operator<< (std::ostream &ostr, const Data &data)

dlib::point	cv_to_dlib (const cv::Vec3d &to_convert)

template<typename T , int N>
dlib::vector< T, N >	cv_to_dlib (const cv::Vec< T, N > &to_convert)

template<typename T , int N>
cv::Vec< T, N >	dlib_to_cv (const dlib::vector< T, N > &to_convert)

Detailed Description

Helper classes within the gaze library.

This namespace contains a data access class (util::Data).

Function Documentation

double gaze::util::clamp	(	double	value,
		double	min,
		double	max
	)

If value is smaller than min, min is returned. If value is bigger than max, max is returned. Else, the value is returned.

Parameters

value	The value to clamp.
min	The minimum allowed value.
max	The maximum allowed value.

Returns: The clamped value.

Definition at line 36 of file gaze_point_calculation.cpp.

References max(), and min().

Referenced by gaze::pipeline::GazePointCalculation::process().

                                                    {
   if (value < min) {
     return min;
   } else if (value > max) {
     return max;
   }
   return value;
 }

dlib::point gaze::util::cv_to_dlib ( const cv::Point & to_convert )

Converts a cv::Point to a dlib::point.

Parameters

to_convert The point to convert.

Returns: The converted point.

Definition at line 8 of file dlibcv.cpp.

References Point_< int >::x, and Point_< int >::y.

                                                 {
   return {to_convert.x, to_convert.y};
 }

dlib::rectangle gaze::util::cv_to_dlib ( const cv::Rect & to_convert )

Converts a cv::Rect to a dlib::rectangle.

Parameters

to_convert The rectangle to convert.

Returns: The converted rectangle.

Definition at line 12 of file dlibcv.cpp.

References cv::Rect_< _Tp >::height, cv::Rect_< _Tp >::width, cv::Rect_< _Tp >::x, and cv::Rect_< _Tp >::y.

                                                    {
   return {to_convert.x, to_convert.y,
           to_convert.width, to_convert.height};
 }

dlib::point gaze::util::cv_to_dlib ( const cv::Vec3d & to_convert )

Converts a cv::Point to a dlib::point.

Parameters

to_convert The point to convert.

Returns: The converted point.

cv::Rect gaze::util::dlib_to_cv ( const dlib::rectangle & to_convert )

Converts a dlib::rectangle to a cv::Rect.

Parameters

to_convert The rectangle to convert.

Returns: The converted rectangle.

Definition at line 17 of file dlibcv.cpp.

                                                    {
   return cv::Rect(to_convert.left(), to_convert.top(),
                   to_convert.width(), to_convert.height());
 }

void gaze::util::fill_displacement_tables	(	dlib::matrix< double > &	table_x,
		dlib::matrix< double > &	table_y,
		int	size
	)

Filles the displacement table to precalculate values for vector $d_i$ Timm2011.

The function returns without modifying table_x or table_y if size is smaller than the current table size.

The size will always be set to size or size + 1, whichever is odd. This ensures that the center value is 0 as a reference point.

After a call to this function with a sufficiently big size argument, table_x and table_y contain values such that reading from both tables at the same indices yields the respective components for a unit vector geometrically pointing from the center of the matrix to the read position.

A $3 \times 3$ table_x would thus look like this:

$\left( \begin{array}{ccc} -0.707 & 0 & 0.707 \\ -1 & 0 & 1 \\ -0.707 & 0 & 0.707 \end{array} \right)$

And the corresponding $3 \times 3$ table_y would be table_x's transposed version:

$\left( \begin{array}{ccc} -0.707 & -1 & -0.707 \\ 0 & 0 & 0 \\ 0.707 & 1 & 0.707 \end{array} \right)$

Accessing table_x and table_y at (0, 0) yields $(-0.707, -0.707)$ which is a unit length vector pointing from the center (1, 1) to (0, 0).

Parameters

table_x	The x components of .
table_y	The y components of .
size	The size to grow this table to.

Definition at line 23 of file pupil_localization.cpp.

References std::numeric_limits< class >::min(), and std::sqrt().

Referenced by gaze::pipeline::PupilLocalization::process().

               {
   // Ensure size is bigger than the current size (i.e. if an update is needed
   // at all)
   if (size <= table_x.nr()) {
     return;
   }
 
   // Ensure size is odd
   size += (1 - size & 1);
   int half_size = (size - 1) / 2;
 
   // Resize tables
   table_x.set_size(size, size);
   table_y.set_size(size, size);
 
   // Fill with indices
   for (int row = 0; row < table_x.nr(); ++row) {
     dlib::set_rowm(table_x, row) = dlib::range(-half_size, half_size);
   }
   table_y = dlib::trans(table_x);
 
   // Calculate norms and store to table_x, then transpose to table_y
   const double epsilon = std::numeric_limits<double>::min();
   for (int row = 0; row < table_x.nr(); ++row) {
     for (int col = 0; col < table_x.nc(); ++col) {
       table_x(row, col) = table_x(row, col) /
         (std::sqrt(table_x(row, col) * table_x(row, col)
                    + table_y(row, col) * table_y(row, col))
          // Avoid div0
          + epsilon);
     }
   }
   table_y = dlib::trans(table_x);
 }

YAML::Node gaze::util::get_config ( )

Tries to read "gaze_pipeline.yaml" or on failure "gaze_pipeline.default.yaml" and returns the resulting YAML::Node.

Returns: the yaml configuration

Definition at line 12 of file config.in.cpp.

Referenced by gaze::pipeline::FallbackStep::FallbackStep(), gaze::pipeline::HeadPoseEstimation::get_and_maybe_read_distortions(), get_config(), gaze::pipeline::HeadPoseEstimation::read_or_set_camera_matrix(), and gaze::pipeline::SourceCapture::SourceCapture().

                       {
   YAML::Node config;
   try {
     config = YAML::LoadFile("gaze.yaml");
   } catch (YAML::BadFile) {
     config = YAML::Load("@DEFAULT_CONFIGURATION_FILE@");
   }
   return config;
 }

YAML::Node gaze::util::get_config ( int pipeline_step_number )

Calls get_config() and gets the data from

pipeline:
  - ...
  - ...

Where pipeline_step_number is the bullet to read.

Parameters

pipeline_step_number the pipeline step to read

Returns: the sub node for the respective pipeline step.

Definition at line 22 of file config.in.cpp.

References get_config().

                                               {
   return get_config()["pipeline"][pipeline_step_number];
 }

dlib::rectangle gaze::util::get_eye_region	(	int	eye,
		dlib::full_object_detection	object_detection
	)

Returns the bounding box around an eye region. Works for both, the 5 and the 68 landmarks model.

Parameters

eye	0 for left eye, 1 for right eye.
object_detection	The detected face landmarks.

Returns: the bounding box.

Definition at line 239 of file eye_like.cpp.

References get_eye_region(), one(), and rectangle().

Referenced by get_eye_region().

                                                                     {
   int index_ex;
   int index_en;
   if (object_detection.num_parts() == 5) {
     if (eye == 0) {
       index_ex = 0;
       index_en = 1;
     } else {
       index_ex = 2;
       index_en = 3;
     }
   } else {
     if (eye == 0) {
       index_ex = 45;
       index_en = 42;
     } else {
       index_ex = 36;
       index_en = 39;
     }
   }
 
   auto get_rectangle = [](dlib::point one, dlib::point two)
     -> dlib::rectangle {
       dlib::rectangle result(one, two);
       double scale = (one - two).length() * 1.5;
       return dlib::centered_rect(result, scale, scale);
     };
 
   return get_rectangle(object_detection.part(index_ex),
                        object_detection.part(index_en));
 }

std::vector< dlib::chip_details > gaze::util::get_eyes_chip_details ( const dlib::full_object_detection object_detection )

Determines a bounding box around the eyes from a given object detection. This function is designed to work with 5 feature landmarks.

Parameters

object_detection A full object detecetion as acquired from a dlib::shape_predictor.

Returns: a vector of dlib::chip_details to use with dlib::extract_image_chips.

Definition at line 12 of file pipeline_utils.cpp.

References one(), std::vector< _Tp, _Alloc >::push_back(), and rectangle().

Referenced by gaze::pipeline::GazeCapture::process(), gaze::pipeline::PupilLocalization::process(), gaze::pipeline::GazePointCalculation::process(), and gaze::pipeline::PupilLocalization::visualize().

                                                       {
   std::vector<dlib::chip_details> details;
   if (object_detection.num_parts() < 5) {
     return details;
   }
 
   auto get_rectangle = [](dlib::point one, dlib::point two)
     -> dlib::rectangle {
       dlib::rectangle result(one, two);
       double scale = (one - two).length() * 1.5;
       return dlib::centered_rect(result, scale, scale);
     };
 
   int index_ex_left;
   int index_en_left;
   int index_ex_right;
   int index_en_right;
   if (object_detection.num_parts() == 5) {
     index_ex_left = 2;
     index_en_left = 3;
     index_ex_right = 0;
     index_en_right = 1;
   } else {  // 68 landmarks
     index_ex_left = 45;
     index_en_left = 42;
     index_ex_right = 36;
     index_en_right = 39;
   }
 
   details.push_back(dlib::chip_details(
         get_rectangle(object_detection.part(index_ex_right),
                       object_detection.part(index_en_right))));
   details.push_back(dlib::chip_details(
         get_rectangle(object_detection.part(index_ex_left),
                       object_detection.part(index_en_left))));
 
   return details;
 }

template<typename T >

void gaze::util::normalize_and_threshold_gradients	(	dlib::matrix< T > &	horizontal,
		dlib::matrix< T > &	vertical,
		double	relative_threshold = `-1`
	)

Normalizes a horizontal and a vertical gradient matrix to unit length vectors.

If a relative threshold is provided, all values where the gradient magnitude $ M $ is lower than $\theta \max M$ are set to 0.

Parameters

horizontal	A gradient, e.g. from dlib::sobel_edge_detector
vertical	A gradient, e.g. from dlib::sobel_edge_detector
relative_threshold	optional threshold to set small values to 0.

Definition at line 79 of file pupil_localization.h.

References magnitude(), mean(), sqrt(), and threshold().

Referenced by gaze::pipeline::PupilLocalization::process().

                                     {
   dlib::matrix<T> magnitude;
   magnitude = dlib::sqrt(dlib::squared(horizontal) +
                          dlib::squared(vertical));
 
   // Thresholding
   if (relative_threshold >= 0) {
     T threshold = dlib::mean(magnitude)
                 + dlib::stddev(magnitude) * relative_threshold;
     for (int row = 0; row < horizontal.nr(); ++row) {
       for (int col = 0; col < horizontal.nc(); ++col) {
         if (magnitude(row, col) < threshold) {
           horizontal(row, col) = 0;
           vertical(row, col) = 0;
         }
       }
     }
   }
 
   // Normalization
   horizontal = dlib::pointwise_multiply(
       horizontal, dlib::reciprocal(magnitude));
   vertical = dlib::pointwise_multiply(
       vertical, dlib::reciprocal(magnitude));
 }

std::ostream& gaze::util::operator<<	(	std::ostream &	ostr,
		const Data &	data
	)

inline

Prints a human readable short information about the data object to the stream.

Parameters

ostr	the stream.
data	the data object.

Returns: the stream.

Definition at line 130 of file data.h.

References std::endl(), gaze::util::Data::eyes, gaze::util::Data::image, gaze::util::Data::landmarks, cv::Mat::size, and gaze::util::Data::source_image.

                                                   {
   ostr << "Source image size: " << data.source_image.size() << std::endl
        << "dlib image size: " << data.image.size() << std::endl
        << "Face: " << data.landmarks.get_rect() << std::endl
        << "Eyes detected: " << data.eyes.size() << std::endl;
   return ostr;
 }

double gaze::util::parse_aspect_ratio ( std::string aspect_ratio_string )

Parses a string representing an aspect ratio. If the string contains : or /, it is split there and the aspect ratio is the quotient between the values left and right: a:b is equal to a/b. If non of the tokens is present, the string is parsed as a double.

Parameters

aspect_ratio_string The string to parse.

Returns: the parsed aspect ratio.

Definition at line 20 of file gaze_point_calculation.cpp.

References basic_string< char >::find(), and basic_string< char >::substr().

                                                          {
   double aspect_ratio;
   int delim = aspect_ratio_string.find(":");
   if (delim < 0) {
     delim = aspect_ratio_string.find("/");
   }
   if (delim > 0) {
     double width_rate = std::stod(aspect_ratio_string.substr(0, delim));
     double height_rate = std::stod(aspect_ratio_string.substr(delim + 1));
     aspect_ratio = width_rate / height_rate;
   } else {
     aspect_ratio = std::stod(aspect_ratio_string);
   }
   return aspect_ratio;
 }

Classes

Functions

Detailed Description

Function Documentation