I compiled dlib's Python interface with CUDA enabled, why isn't it using CUDA?

You can check if dlib is compiled to use CUDA by looking at the dlib.DLIB_USE_CUDA boolean. If dlib.DLIB_USE_CUDA is false then you didn't compile it with CUDA enabled, but if it's true then dlib is using all the CUDA it's going to use.

Why is dlib.image_window missing from the Python module?

But since you are reading this you obviously want to use the GUI tools. The solution is to get a copy of dlib and python setup.py install it yourself. It's easy. Note that you might get a warning in the build output about X11 not being installed. Maybe that's why you are getting this error in the first place. READ THAT MESSAGE AND FOLLOW ITS INSTRUCTIONS since it tells you what to do to fix this.

Why is some function missing from the dlib Python module?

How can I cite dlib?

@Article{dlib09,
  author = {Davis E. King},
  title = {Dlib-ml: A Machine Learning Toolkit},
  journal = {Journal of Machine Learning Research},
  year = {2009},
  volume = {10},
  pages = {1755-1758},
}
         

How can I use dlib in Visual Studio?

First, note that you need a version of Visual Studio with decent C++11 support. This means you need Visual Studio 2015 or newer.

cd examples
mkdir build
cd build
del /F /S /Q *
cmake ..
cmake --build . --config Release

How do I install/compile dlib?

How do I set the size of a matrix at runtime?

matrix<double> mat;
mat.set_size(4,5);

matrix<double,0,1> column_vect;
column_vect.set_size(6);

matrix<double,0,1> column_vect2(6);  // give size to constructor

matrix<double,1> row_vect;
row_vect.set_size(5);

How does dlib interface with other libraries/tools?

• BLAS and LAPACK libraries are used by the matrix automatically if you #define DLIB_USE_BLAS and/or DLIB_USE_LAPACK and link against the appropriate library files. Note that the CMakeLists.txt file that comes with dlib will do this for you automatically in many instances.


• Armadillo and Eigen libraries have matrix objects which can be converted into dlib matrix objects by calling dlib::mat() on them.


• OpenCV image objects can be converted into a form usable by dlib routines by using cv_image. You can also convert from a dlib matrix or image to an OpenCV Mat using dlib::toMat().


• Google Protocol Buffers can be serialized by the dlib serialization routines. This means that, for example, you can pass protocol buffer objects through a bridge.


• libpng and libjpeg are used by load_image whenever DLIB_PNG_SUPPORT and DLIB_JPEG_SUPPORT are defined respectively. You must also tell your compiler to link against these libraries to use them. However, CMake will try to link against them automatically if they are installed.


• SQLite is used by the database object. In fact, it is just a wrapper around SQLite's C interface which simplifies its use (e.g. makes resource management use RAII).

It doesn't work?

If you think you found some kind of bug or problem in dlib then feel free to submit a dlib issue on github. But include the version of dlib you are using, what you are trying, what happened, what you expected to have happened instead, etc.

On the other hand, if you haven't found a bug or problem in dlib, but instead are looking for machine learning/computer vision/programming help then post your question to stack overflow with the dlib tag.

Where is the documentation for <object/function>?

A lot of people post questions like "There is no documentation for some_random_function(), how do I use it?", when in reality the function is documented in detail. Between the index, site search, and main website which breaks down functions/classes into topical categories there is no excuse for not being able to find the documentation for a function or class. This is especially true if you know its name because you can jump right to it using the index or even a simple google search. So if you are posting a question like "I don't understand how something works" and obviously haven't read the documentation then you are just going to get referred to this FAQ. So please read the documentation before asking questions.

Why do I get USER_ERROR__inconsistent_build_configuration__see_dlib_faq_1?

For reference, the code that generates this error is: dlib/test_for_odr_violations.h and dlib/test_for_odr_violations.cpp.

Why do I get USER_ERROR__inconsistent_build_configuration__see_dlib_faq_2?

For reference, the code that generates this error is: dlib/test_for_odr_violations.h and dlib/test_for_odr_violations.cpp.

Finally, most users who get this error are using Visual Studio. You probably compiled dlib and then went into Visual Studio's output folder, grabbed the .lib file, and then tried to create a project using that .lib file and dlib's .h files from github. THIS IS WRONG, DO NOT DO THIS. Instead, read the instructions for using dlib and follow them. I promise they are much simpler than any process that involves manually copying files around in the file explorer.

Why is dlib slow?

cd examples
mkdir build
cd build
cmake .. 
cmake-gui .

Why isn't serialization working?

• You are using a file stream and forgot to put it into binary mode. You need to do something like this:

  std::ifstream fin("myfile", std::ios::binary);
  

  or

  std::ofstream fout("myfile", std::ios::binary);
  

  If you don't give std::ios::binary then the iostream will mess with the binary data and cause serialization to not work right.


• The iostream is in a bad state. You can check the state by calling mystream.good(). If it returns false then the stream is in an error state such as end-of-file or maybe it failed to do the I/O. Also note that if you close a file stream and reopen it you might have to call mystream.clear() to clear out the error flags.

Can you give advice on feature generation/kernel selection?

Picking the right kernel all comes down to understanding your data, and obviously this is highly dependent on your problem.

One thing that's sometimes useful is to plot each feature against the target value. You can get an idea of what your overall feature space looks like and maybe tell if a linear kernel is the right solution. But this still hides important information from you. For example, imagine you have two diagonal lines which are very close together and are both the same length. Suppose one line is of the +1 class and the other is the -1 class. Each feature (the x or y coordinate values) by itself tells you almost nothing about which class a point belongs to but together they tell you everything you need to know.

On the other hand, if you know something about the data you are working with then you can also try and generate your own features. So for example, if your data is a bunch of images and you know that one of your classes contains a lot of lines then you can make a feature that attempts to measure the number of lines in an image using a hough transform or sobel edge filter or whatever. Generally, try and think up features which should be highly correlated with your target value. A good way to do this is to try and actually hand code N solutions to the problem using whatever you know about your data or domain. If you do a good job then you will have N really great features and a linear or rbf kernel will probably do very well when using them.

Or you can just try a whole bunch of kernels, kernel parameters, and training algorithm options while using cross validation. I.e. when in doubt, use brute force :) There is an example of that kind of thing in the model selection example program.

How can I define a custom kernel?

Why does my decision_function always give the same output?

So you need to pick the gamma value so that it is scaled reasonably to your data. A good rule of thumb (i.e. not the optimal gamma, just a heuristic guess) is the following:

const double gamma = 1.0/compute_mean_squared_distance(randomly_subsample(samples, 2000));

Why is cross_validate_trainer_threaded() crashing?

For example, you could reduce the amount of data by saying this:

// reduce to only 1000 samples
cross_validate_trainer_threaded(trainer, 
                                randomly_subsample(samples, 1000), 
                                randomly_subsample(labels,  1000), 
                                4,   // num folds
                                4);  // num threads

Why is RVM training is really slow?

You should try kernel ridge regression instead since it also doesn't take any parameters but is always very fast.

Why doesn't the object detector I trained work?

• Not labeling all the objects in each image

  The tools for training object detectors in dlib use the Max-Margin Object Detection loss. This loss optimizes the performance of the detector on the whole image, not on some subset of windows cropped from the training data. That means it counts the number of missed detections and false alarms for each of the training images and tries to find a way to minimize the sum of these two error metrics. For this to be possible, you must label all the objects in each training image. If you leave unannotated objects in some of your training images then the loss will think any detections on these unannotated objects are false alarms, and will therefore try to find a detector that doesn't detect them. If you have enough unannotated objects, the most accurate detector will be the one that never detects anything. That's obviously not what you want. So make sure you annotate all the objects in each image.

  Sometimes annotating all the objects in each image is too onerous, or there are ambiguous objects you don't care about. In these cases you should annotate these objects you don't care about with ignore boxes so that the MMOD loss knows to ignore them. You can do this with dlib's imglab tool by selecting a box and pressing i. Moreover, there are two ways the code treats ignore boxes. When a detector generates a detection it compares it against any ignore boxes and ignores it if the boxes "overlap". Deciding if they overlap is based on either their intersection over union or just basic percent coverage of one by another. You have to think about what mode you want when you annotate things and configure the training code appropriately. The default behavior is to use intersection over union to measure overlap. However, if you wanted to simply mask out large parts of an image you wouldn't want to use intersection over union to measure overlap since small boxes contained entirely within the large ignored region would have small IoU with the big ignore region and thus not "overlap" the ignore region. In this case you should change the settings to reflect this before training. The available configuration options are discussed in great detail in parts of dlib's documentation.

• Using training images that don't look like the testing images

  This should be obvious, but needs to be pointed out. If there is some clear difference between your training and testing images then you have messed up. You need to show the training algorithm real images so it can learn what to do. If instead you only show it images that look obviously different from your testing images don't be surprised if, when you run the detector on the testing images, it doesn't work. As a rule of thumb, a human should not be able to tell if an image came from the training dataset or testing dataset.

  Here are some examples of bad datasets:

  • A training dataset where objects always appear with some specific orientation but the testing images have a diverse set of orientations.
  • A training dataset where objects are tightly cropped, but testing images that are uncropped.
  • A training dataset where objects appear only on a perfectly white background with nothing else present, but testing images where objects appear in a normal environment like living rooms or in natural scenes.

  Another way you can mess this up is when using the random_cropper to jitter your training data, which is common when training a CNN or other deep model. In general, the random_cropper finds images that are more or less centered on your objects of interest and it also scales the images so the object has some user specified minimum size. That's all fine. But what can happen is you train a model that gets 0 training error but when you go and use it it doesn't detect any objects. Why is that? It's probably because all the objects in your normal images, the ones you give to the random_cropper, are really small. Smaller than the min size you told the cropper to make them. So now your testing images are really different from your training images. Moreover, in general object detectors have some minimum size they scan and if objects are smaller than that they will never be found. Another related issue is all your uncropped images might show objects at the very border of the image. But the random_cropper will center the objects in the crops, by padding with zeros if necessary. Again, make your testing images look like the training images. Pad the edges of your images with zeros if needed.

• Using a HOG based detector but not understanding the limits of HOG templates

  The HOG detector is very fast and generally easy to train. However, you have to be aware that HOG detectors are essentially rigid templates that are scanned over an image. So a single HOG detector isn't going to be able to detect objects that appear in a wide range of orientations or undergo complex deformations or have complex articulation.

  For example, a HOG detector isn't going to be able to learn to detect human faces that are upright as well as faces rotated 90 degrees. If you wanted to deal with that you would be best off training 2 detectors. One for upright faces and another for 90 degree rotated faces. You can efficiently run multiple HOG detectors at once using the evaluate_detectors function, so it's not a huge deal to do this. Dlib's imglab tool also has a --cluster option that will help you split a training dataset into clusters that can be detected by a single HOG detector. You will still need to manually review and clean the dataset after applying --cluster, but it makes the process of splitting a dataset into coherent poses, from the point of view of HOG, a lot easier.

  A related issue arises because HOG is a rigid template, which is that the boxes in your training data need to all have essentially the same aspect ratio. For instance, a single HOG filter can't possibly detect objects that are both 100x50 pixels and 50x100 pixels. To do this you would need to split your dataset into two parts, objects with a 2:1 aspect ratio and objects with a 1:2 aspect ratio and then train two separate HOG detectors, one for each aspect ratio.

  However, it should be emphasized that even using multiple HOG detectors will only get you so far. So at some point you should consider using a CNN based detection method since CNNs can generally deal with arbitrary rotations, poses, and deformations with one unified detector.

Why can't I change the network architecture at runtime?

Here is an example of one problem it addresses. Since dlib exposes the entire network architecture to the C++ type system we can get automatic serialization of networks. Without this, we would have to resort to the kind of hacky global layer registry used in other tools that compose networks entirely at runtime.

Another nice feature is that we get to use C++11 alias template statements to create network sub-blocks, which we can then use to easily define very large networks. There are examples of this in this example program. It should also be pointed out that it takes days or even weeks to train one network. So it isn't as if you will be writing a program that loops over large numbers of networks and trains them all. This makes the time needed to recompile a program to change the network irrelevant compared to the entire training time. Moreover, there are plenty of compile time constructs in C++ you can use to enumerate network architectures (e.g. loop over filter widths) if you really wanted to do so.

All that said, if you think you found a compelling use case that isn't supported by the current API feel free to post a github issue.

Why can't I use the DNN module with Visual Studio?

To make this even more complicated, Visual Studio 2017 had regressions in its C++11 support. So all versions of Visual Studio 2017 prior to December 2017 would just hang if you tried to compile the DNN examples. Happily, the newest versions of Visual Studio 2017 appear to have good C++11 support and will compile the DNN codes without any issue. So make sure your Visual Studio is fully updated.

Finally, it should be noted that you should give the -T host=x64 cmake option when generating a Visual Studio project. If you don't do this then you will get the default Visual Studio toolchain, which runs the compiler in 32bit mode, restricting it to 2GB of RAM, leading to compiler crashes due to it running out of RAM in some cases. This isn't the 1990s anymore, so you should probably run your compiler in 64bit mode so it can use your computer's RAM. Giving -T host=x64 will let Visual Studio use as much RAM as it needs.