Introduction
In this post we will learn how to get started using dlib with Python. Our tests will consist in reading images from the file system and displaying them in a window.
Dlib is a C++ toolkit containing machine learning algorithms and tools for creating complex software to solve real world problems [1]. Although being a C++ toolkit, dlib also has a Python interface that allows us to use it in our Python programs. Installing it with pip is as easy as sending the following command:
pip install dlib
The example we are going to write also depends on Numpy, which can be installed with the following pip command:
pip install numpy
You can check dlib Python API reference here. For some Python code examples, please check here.
The code was tested using dlib version 19.22.0 and Python version 3.7.2, on Windows 8.1.
Loading and displaying an image
We will start our code by importing the dlib package we have just installed. This will give us access to the functions we need to load an image and display it in a window.
import dlib
After this we will take care of calling the load_rgb_image, to load our image from the file system. This function receives as input a string with the path to the image and returns as output a numpy array containing the image. We will store the output in a variable, so we can use it later.
img = dlib.load_rgb_image("C:/Users/N/Desktop/Test.jpg")
After this we will create an object of class image_window. This class represents a GUI window which will allow us to display the image we have just loaded. There are multiple overloads for the constructor of this class but we will use the signature that allows to pass as input an image, which will be rendered on the window, and a title, which will be assigned to the window.
Naturally, we will pass the image we have just loaded and a “My image” string as title.
win = dlib.image_window(img, "My image")
To ensure that the program doesn’t finish right away and the window is not immediately closed, we will call the wait_until_closed method on our image_window. This will block the execution until the window is explicitly closed.
win.wait_until_closed()
The complete code can be seen in the snippet below.
import dlib
img = dlib.load_rgb_image("C:/Users/N/Desktop/Test.jpg")
win = dlib.image_window(img, "My image")
win.wait_until_closed()
To test the previous code snippet, simply run it in a tool of your choice. In my case I’ll be using PyCharm, a Python IDE. Upon running the code, you should get a result similar to figure 1. As can be seen, the window is displayed with the title we set and with the image we previously loaded.
Setting the image and the window title
In the previous section, we saw how to create the window and set both the title and the image immediately on the instantiation of the object. In this section we will check how to set both the image and the title after the creation of the window. In the particular case of the image being displayed, we will alternate between two images until the user closes the window.
Like before, we start by importing dlib. Additionally, we will import the time package, so we can introduce delays in our program.
import dlib
import time
After this, we will load two images, so we can cycle displaying each other in our window. In my case, I’ll be using the image from figure 1 plus a modified version where I’ve added a green circle on top of it. I’m keeping it simple just to illustrate the concept and to avoid having to worry about resizing images, but you can try with different pictures.
img1 = dlib.load_rgb_image("C:/Users/N/Desktop/Test.jpg")
img2 = dlib.load_rgb_image("C:/Users/N/Desktop/Test2.jpg")
After this we will create a image_window. This time we will use the parameterless constructor, meaning that no image will be rendered in the window and no title will be assigned.
win = dlib.image_window()
Now we will make use of the set_title method on our image_window to set the title we want for our window. This illustrates that we don’t need to do it immediately in the window creation and that we can assign a title later.
win.set_title("My title")
Then we are going to render our images in an infinite loop that will only break when the window is closed. In our case, we can use the is_closed method, which will return true if our window is closed and false otherwise, to decide when to finish the loop.
while win.is_closed() != True:
#display images
Now, to set the image in our window, we can simply call the set_image method, passing as input one of the images we have just loaded. We are going to alternate between both images with a delay of 2 seconds. The complete loop is shown below.
while win.is_closed() != True:
win.set_image(img1)
time.sleep(2)
win.set_image(img2)
time.sleep(2)
The whole code is shown in the snippet below.
import dlib
import time
img1 = dlib.load_rgb_image("C:/Users/N/Desktop/Test.jpg")
img2 = dlib.load_rgb_image("C:/Users/N/Desktop/Test2.jpg")
win = dlib.image_window()
win.set_title("My title")
while win.is_closed() != True:
win.set_image(img1)
time.sleep(2)
win.set_image(img2)
time.sleep(2)
Like in the previous section, simply run the code from the snippet to test it. The result should be similar to figure 2. As can be seen, we are able to alternate the display between two images.
Waiting for key presses
We are now going to check how to keep the dlib window open until the user clicks a specific key. The code on this section will be very similar to the one we have covered in the first code section. The only exception is that, instead of calling the wait_until_closed method on our window, we will instead call the wait_for_keypress method, which will block the execution until the user clicks the given key or closes the window.
As input of this method we need to pass the key we want to wait for. If we want to wait for a char, we need to pass that char as input. We will test with the char ‘a’.
win.wait_for_keypress('a')
print("clicked 'a'")
If we want to use a key that doesn’t map to a character, then we can use the non_printable_keyboard_keys enum values. We are also going to wait for the backspace key.
win.wait_for_keypress(dlib.non_printable_keyboard_keys.KEY_BACKSPACE)
print("clicked 'BACKSPACE'")
The complete code can be seen below. Note that we are calling the wait_for_keypress method twice, meaning that the execution will stop a first time until we click the ‘a’ key, and then a second time until we click the backspace key. Note that if we close the window without clicking any of the keys, both the wait_for_keypress method calls will return immediately and the program will finish the execution.
import dlib
img = dlib.load_rgb_image("C:/Users/N/Desktop/Test.jpg")
win = dlib.image_window(img, "My image")
win.wait_for_keypress('a')
print("clicked 'a'")
win.wait_for_keypress(dlib.non_printable_keyboard_keys.KEY_BACKSPACE)
print("clicked 'BACKSPACE'")
Upon running the code, you should obtain a window with the image. If you click the keys ‘a’ and then the backspace, the program should finish its execution, like shown in figure 3.
Displaying multiple windows
To finalize our tutorial, we will show how to open two windows and display a different image in each of them. The code is basically the same that we covered in the first section but this time we will read two different images and we will create two different image_window instances. The complete code is shown below.
import dlib
img1 = dlib.load_rgb_image("C:/Users/N/Desktop/Test.jpg")
img2 = dlib.load_rgb_image("C:/Users/N/Desktop/Test2.jpg")
win1 = dlib.image_window(img1, "Image 1")
win2 = dlib.image_window(img2, "Image 2")
win1.wait_until_closed()
win2.wait_until_closed()
Upon running the code, you should get a result similar to figure 4.
Suggested readings
References
[1] http://dlib.net/