dlib C++ Library - Linear Algebra

Linear Algebra

This page documents the core linear algebra tools included in dlib. In particular, the three most important objects in this part of the library are the matrix, vector, and rectangle. All the other tools on this page are functions for manipulating these three objects. A good example and introduction can be found in the matrix example program.

Most of the linear algebra tools deal with dense matrices. However, there is also a limited amount of support for working with sparse matrices and vectors. In particular, the dlib tools represent sparse vectors using the containers in the C++ STL. For details, see the notes at the top of dlib/svm/sparse_vector_abstract.h.

Finally, note that all the dense matrix tools can be obtained by #including `<dlib/matrix.h>` while the sparse vector tools can be obtained by #including `<dlib/sparse_vector.h>`. The geometry tools can be used by #including `<dlib/geometry.h>`.

[top]

# angle_between_lines

This routine returns the angle, in degrees, between two lines. This is a number in the range [0 90].
More Details...
#include <dlib/geometry.h>
[top]

# border_enumerator

This object is an enumerator over the border points of a rectangle.
More Details...
#include <dlib/geometry.h>
[top]

# camera_transform

This object maps 3D points into the image plane of a camera. Therefore, you can use it to compute 2D representations of 3D data from the point of view of some camera in 3D space.
More Details...
#include <dlib/geometry.h>
[top]

# center

Returns the center point of a rectangle.
More Details...
#include <dlib/geometry.h>
[top]

# centered_rect

There are various overloads of this function but the basic idea is that it returns a rectangle with a given width and height and centered about a given point.
More Details...
#include <dlib/geometry.h>
[top]

# clip_line_to_rectangle

This function takes a rectangle and a line segment and returns the part of the line segment that is entirely contained within the rectangle.
More Details...
#include <dlib/geometry.h>
[top]

# count_points_between_lines

This routine takes a pair of lines and an array of points and counts how many points are between the lines.
More Details...
#include <dlib/geometry.h>
[top]

# count_points_on_side_of_line

This routine takes a line and an array of points and counts how many points are on one side of the line. Which side of the line is of interest is selected by the user.
More Details...
#include <dlib/geometry.h>
[top]

# dcenter

Returns the center point of a rectangle. This is a version of center() which returns a double version of the point rather than one which uses integers to represent the result. Therefore, it is slightly more accurate.
More Details...
#include <dlib/geometry.h>
[top]

# distance_to_line

This function takes a line and a point and returns the distance from the line to the point.
More Details...
#include <dlib/geometry.h>
[top]

# distance_to_rect_edge

This function takes a rectangle and a point and returns the Manhattan distance between the rectangle's edge and the point.
More Details...
#include <dlib/geometry.h>
[top]

# dpoint

This object represents a point inside a Cartesian coordinate system. Note that a dpoint is simply a typedef for a vector that is 2D and uses doubles to represent coordinate values.
More Details...
#include <dlib/geometry.h>
[top]

# drectangle

This object represents a rectangular region inside a Cartesian coordinate system. It is very similar to the rectangle except that it uses double variables instead of longs to represent the location of the rectangle. Therefore, it can position rectangles with sub-pixel accuracy.
More Details...
#include <dlib/geometry.h>
[top]

# find_affine_transform

This is a routine that takes in two sets of points and finds the best affine transformation that maps between them.
More Details...
#include <dlib/geometry.h>
[top]

# find_convex_quadrilateral

This routine takes 4 lines as input and determines if their intersections form a convex quadrilateral. If so it returns the 4 corners of this quadrilateral.
More Details...
#include <dlib/geometry.h>
[top]

# find_projective_transform

This is a routine that takes in two sets of points and finds the best projective transformation that maps between them.
More Details...
#include <dlib/geometry.h>
[top]

# find_similarity_transform

This is a routine that takes in two sets of points and finds the best affine transformation that maps between them. However, it considers only rotations, translations, and uniform scale changes in finding the mapping. Therefore, it finds a similarity transformation rather than a general affine transform.
More Details...
#include <dlib/geometry.h>
[top]

# get_rect

This is a simple template function that returns a rectangle representing the size of a 2D container (e.g. matrix or array2d).
More Details...
#include <dlib/geometry.h>
[top]

# grow_rect

This function takes a rectangle object, grows its borders by a given amount, and returns the result.
More Details...
#include <dlib/geometry.h>
[top]

# intersect

This routine finds the point at the intersection of two lines.
More Details...
#include <dlib/geometry.h>
[top]

# is_convex_quadrilateral

This routine tests if 4 points define a convex quadrilateral.
More Details...
#include <dlib/geometry.h>
[top]

# line

This object represents a line in the 2D plane. The line is defined by two points running through it. This object also includes a unit normal vector that is perpendicular to the line.
More Details...
#include <dlib/geometry.h>
[top]

# mat

This is a set of simple functions that take objects like std::vector or array2d and convert them into matrix objects. Note that the conversion is done using template expressions so there is no runtime cost associated with calling mat().
More Details...
#include <dlib/matrix.h>
[top]

# matrix

This is a 2D matrix object that enables you to write code that deals with matrices using a simple syntax similar to what can be written in MATLAB. It is implemented using the expression templates technique which allows it to eliminate the temporary matrix objects that would normally be returned from expressions such as M = A+B+C+D; Normally each invocation of the + operator would construct and return a temporary matrix object but using this technique we can avoid creating all these temporary objects and receive a large speed boost.

This object is also capable of using BLAS and LAPACK libraries such as ATLAS or the Intel MKL when available. To enable BLAS support all you have to do is #define DLIB_USE_BLAS and then make sure you link your application with your BLAS library. Similarly, to enable LAPACK support just #define DLIB_USE_LAPACK and link to your LAPACK library. Finally, the use of BLAS and LAPACK is transparent to the user, that is, the dlib matrix object uses BLAS and LAPACK internally to optimize various operations while still allowing the user to use a simple MATLAB like syntax.

Note that the cmake files that come with dlib will automatically link with ATLAS or the Intel MKL if they are installed. So using cmake makes this easy, but by no means are you required to use cmake or the dlib cmake files.

It is also worth noting that all the preconditions of every function related to the matrix object are checked by DLIB_ASSERT statements and thus can be enabled by #defining ENABLE_ASSERTS or DEBUG. Doing this will cause your program to run slower but should catch any usage errors.

C++ Example Programs: matrix_ex.cpp, matrix_expressions_ex.cpp
More Details...
#include <dlib/matrix.h>

# Extensions to matrix

matrix_la
This extension contains linear algebra functions to calculate QR, LU, Cholesky, eigenvalue, and singular value decompositions. It also contains a few other miscellaneous functions that solve systems of equations or calculate values derived from the above decompositions.
More Details...
matrix_math_functions
This extension contains mathematical functions that operate on each element of a matrix independently.
More Details...
matrix_sub_expressions
This extension contains a number of functions for dealing with sub-matrices.
More Details...
matrix_utilities
This extension contains miscellaneous utility functions for manipulating matrix objects.
More Details...
[top]

# move_rect

This function takes a rectangle and moves it so that it's upper left corner occupies the given location.
More Details...
#include <dlib/geometry.h>
[top]

# nearest_point

This function takes a rectangle and a point and returns the point in the given rectangle that is nearest to the given point.
More Details...
#include <dlib/geometry.h>
[top]

# nearest_rect

This function takes a std::vector<rectangle> and a point and identifies the rectangle that is nearest to the point.
More Details...
#include <dlib/geometry.h>
[top]

# point

This object represents a point inside a Cartesian coordinate system. Note that a point is simply a typedef for a vector that is 2D and uses longs to represent coordinate values.
More Details...
#include <dlib/geometry.h>
[top]

# point_rotator

This is an object that rotates a 2D vector or point object about the origin.
More Details...
#include <dlib/geometry.h>
[top]

# point_transform

This is an object that rotates a 2D vector or point object about the origin and then adds a displacement vector.
More Details...
#include <dlib/geometry.h>
[top]

# point_transform_affine

This is an object that applies a 2D affine transformation to a vector or point. Note that you can use find_affine_transform to easily create affine transforms from sets of point correspondences.
More Details...
#include <dlib/geometry.h>
[top]

# point_transform_affine3d

This is an object that applies a 3D affine transformation to a vector.
More Details...
#include <dlib/geometry.h>
[top]

# point_transform_projective

This is an object that applies a projective transformation to a vector or point. Note that you can use find_projective_transform to easily create projective transforms from sets of point correspondences.
More Details...
#include <dlib/geometry.h>
[top]

# polygon

This class represents a polygon in a 2D coordinate system.
More Details...
#include <dlib/geometry.h>
[top]

# polygon_area

When given a set of points defining the vertices of a polygon this routine returns the area of the polygon.
More Details...
#include <dlib/geometry.h>
[top]

# rectangle

This object represents a rectangular region inside a Cartesian coordinate system. It allows you to easily represent and manipulate rectangles.
More Details...
#include <dlib/geometry.h>
[top]

# rectangle_transform

This is an object that applies a 2D affine transformation to a rectangle or drectangle.
More Details...
#include <dlib/geometry.h>
[top]

# resize_rect

This function takes a rectangle and returns a new rectangle with the given size but with the same upper left corner as the original rectangle.
More Details...
#include <dlib/geometry.h>
[top]

# resize_rect_height

This function takes a rectangle and returns a new rectangle with the given height but otherwise with the same edge points as the original rectangle.
More Details...
#include <dlib/geometry.h>
[top]

# resize_rect_width

This function takes a rectangle and returns a new rectangle with the given width but otherwise with the same edge points as the original rectangle.
More Details...
#include <dlib/geometry.h>
[top]

# reverse

This function returns a line object that represents the same line but with the endpoints and normal vector flipped.
More Details...
#include <dlib/geometry.h>
[top]

# rotate_around_x

This is a method for creating a point_transform_affine3d that rotates points around the x-axis.
More Details...
#include <dlib/geometry.h>
[top]

# rotate_around_y

This is a method for creating a point_transform_affine3d that rotates points around the y-axis.
More Details...
#include <dlib/geometry.h>
[top]

# rotate_around_z

This is a method for creating a point_transform_affine3d that rotates points around the z-axis.
More Details...
#include <dlib/geometry.h>
[top]

# rotate_point

This is a function that rotates a 2D vector or point object about a given point.
More Details...
#include <dlib/geometry.h>
[top]

# rotation_matrix

This is a method for creating 2D rotation matrices.
More Details...
#include <dlib/geometry.h>
[top]

# set_aspect_ratio

This function reshapes a rectangle so that it has a user specified aspect ratio.
More Details...
#include <dlib/geometry.h>
[top]

# set_rect_area

This function reshapes a rectangle so that it has a user specified area.
More Details...
#include <dlib/geometry.h>
[top]

# shrink_rect

This function takes a rectangle object, shrinks its borders by a given amount, and returns the result.
More Details...
#include <dlib/geometry.h>
[top]

# signed_distance_to_line

This function returns how far a point is from a line. This is a signed distance. The sign indicates which side of the line the point is on and the magnitude is the distance.
More Details...
#include <dlib/geometry.h>
[top]

# sparse_to_dense

This is a set of simple functions that take sparse vectors and converts them into equivalent dense vectors.
More Details...
#include <dlib/sparse_vector.h>
[top]

# translate_point

This is a method for creating a point_transform_affine3d that just translates points.
More Details...
#include <dlib/geometry.h>
[top]

# translate_rect

This function takes a rectangle and moves it by a given number of units along the x and y axis relative to where it was before the move.
More Details...
#include <dlib/geometry.h>
[top]

# vector

This object represents a two or three dimensional vector.

If you want to work with general N-dimensional column vectors then you should the matrix object. In particular, you should usually use a matrix with this type: `dlib::matrix<double,0,1>`.

More Details...
#include <dlib/geometry.h>