1.

1: Loading, displaying, and saving images

Every journey starts with the first step.

Go ahead, take off your shoes. Throw your socks aside. Then take a step forward and dip your toes into the vast ocean that is computer vision
and OpenCV.

This journey is certainly not short (and, at times, it won’t be easy). There may even be times where you feel like you’re overwhelmed with content,
or frustrated by trying to master a particular concept. And other times you’ll be coasting through the lessons, knocking them out one right after the
other.

That’s okay. In fact, learning can only take place when we are uncomfortable—when we are right on the edge of our comfort zone, trying to
stretch forward.

The stretch itself hurts a bit and it’s within this stretch that we feel discomfort—but it’s also within this stretch that we better ourselves and our
knowledge.

So why am I telling you all this?

To let you know that the road to computer vision guru may seem challenging at times. You may feel some slight discomfort—you may even get
frustrated.

But I can guarantee you this:

The journey will be worth it.

You’ll come out of this course with a better knowledge of computer vision than you ever thought possible.

Let’s get started, shall we?

Objectives:
The objective of this lesson is for you to dip your toes into the OpenCV library. We’ll be using OpenCV inside the vast majority of lessons in this
course, so you’ll want to familiarize yourself with the library quickly. By the end of this lesson you’ll be able to:

1. Load an image off disk using the cv2.imread function.

2. Display the image on your screen using cv2.imshow .
3. Write your image back to disk in a different image file format using cv2.imwrite .
4. Use the command line to execute Python scripts.

Loading, displaying, and saving images

 FIGURE 1: AN EXAMPLE OF LOADING AN IMAGE FROM DISK AND DISPLAYING IT ON OUR SCREEN.

This lesson is meant to be an introductory, hands on, “get your feet wet” guide to using OpenCV, Python, and the command line.

While the command line can be a bit “scary” if you are not familiar with Unix-based systems (or if you’ve never used the command before), it’s an
absolutely crucial skill to have. Regardless of whether or not you are studying computer vision in school, utilizing it in your day job, or simply
learning for fun, learning how to effectively use the command line is a skill you’ll definitely want to understand (and practice).

We will start slowly with the command line to ease you into it—but be sure to practice using the command line outside of this course. The more
adept you are with the command line, the easier time you will have going through the course.

With that said, let’s not waste any more time! Let’s start writing some code.

First, let’s create a file named load_display_save.py to contain our code. Now we can start writing some code:
load_display_save.py
Python

1 # import the necessary packages

2 import argparse
3 import cv2
4
5 # construct the argument parser and parse the arguments
6 ap = argparse.ArgumentParser()
7 ap.add_argument("-i", "--image", required=True, help="Path to the
8 image")
args = vars(ap.parse_args())

The first thing we are going to do is import the packages we will need for this example. We’ll use argparse to handle parsing our command line
arguments. Then, cv2 is imported— cv2 is our OpenCV library and contains our image processing functions. As you’ll see in future lessons, the
cv2 and argparse packages will be used in almost every topic we cover.

From there, Lines 5-8 handle parsing the command line arguments. The only argument we need is --image : the path to our image on disk.
Finally, we parse the arguments and store them in a dictionary called args .

Let’s take a second and quickly discuss exactly what the --image switch is. The --image “switch” (“switch” is a synonym for “command line
argument” and the terms can be used interchangeably) is a string that we specify at the command line. This switch tells our load_display_save.py
 script where the image we want to load lives on disk. You’ll see why using a command line argument to specify the image path is super convenie
nt in the next example:
load_display_save.py
Python

10 # load the image and show some basic information on it

11 image = cv2.imread(args["image"])
12 print("width: %d pixels" % (image.shape[1]))
13 print("height: %d pixels" % (image.shape[0]))
14 print("channels: %d" % (image.shape[2]))
15
16 # show the image and wait for a keypress
17 cv2.imshow("Image", image)
18 cv2.waitKey(0)

Now that we have the path to the image (via the command line argument), we can load it off disk using the cv2.imread function on Line 11. The cv
2.imread function returns a NumPy array representing the image.

Why is using command line arguments so convenient? Because if we didn’t use command line arguments we would have to hardcode the path to
our image, like this:
Hardcoding the path to your image
Python

1 image = cv2.imread("path/to/your/image.jpg")

While the above line of code is perfectly valid (provided that path/to/your/image.jpg exists), hardcoding paths to files tends to be bad practice. In
real-world situations we either (1) supply command line arguments or (2) utilize some sort of configuration file that details paths to various files.

So while parsing command line arguments can add a few extra lines to your code, it is actually extremely beneficial because it ensures that we
don’t have to update our source code whenever we want to load a new image.

Pretty cool, right?

Anyway, let’s get back to explaining the code.

Lines 12-14 examine the dimensions of the image. Again, since images are represented as NumPy arrays, we can simply use the shape attribute
to examine the width, height, and the number of channels (don’t worry, we’ll discuss exactly what a channel is in the next lesson).

Finally, Lines 17 and 18 handle displaying the actual image on our screen. The first parameter is a string, or the “name” of our window. The
second parameter is a reference to the image we loaded off disk on Line 8. Finally, a call to cv2.waitKey pauses the execution of the script until
we press a key on our keyboard. Using a parameter of “0” indicates that any keypress will un-pause the execution.

The last thing we are going to do is write our image to file in JPEG format:
load_display_save.py
Python

20 # save the image -- OpenCV handles converting filetypes

21 # automatically
22 cv2.imwrite("newimage.jpg", image)

All we are doing here is providing the path to the file (the first argument) and then the image we want to save (the second argument). It’s that
simple. In this case we’ll just hardcode the path to newimage.jpg . For practice, once you have finished this lesson, you should download the code
and update it to utilize a second command line argument to write the image to disk.

To run our script and display our image, we simply open up a terminal window and execute the following command:
load_display_save.py
Shell

1 $ python load_display_save.py --image florida_trip.png

Note: If you are using the PyImageSearch Gurus VM or are using Python virtual environments, you’ll need to use the workon command before
you execute the load_display_save.py Python script. For example, make sure you execute workon gurus before running the command above if
you are using Python virtual environments.

If everything has worked correctly, you should see a picture of me on a trip to Orlando displayed on your screen ( Figure 1). To stop the script from
executing, simply click on the image window and press any key.

Examining the output of the script on your terminal, you should also see some basic information on our image. You’ll note that the image has
width of 600 pixels, a height of 450 pixels, and 3 channels (the Red, Green, Blue [RGB] components of the image). Represented as a NumPy
array, our image has a shape of (450, 600, 3).

Let’s execute our load_display_save.py script again, this time supplying a path to a different image:
load_display_save.py
Python

1 $ python load_display_save.py --image grand_canyon.png

And now you should see a different picture displayed on your screen:

FIGURE 2: THE POWER OF COMMAND LINE ARGUMENTS — OUR CODE HAS NOT CHANGED AT ALL, BUT WE ARE ABLE TO DISPLAY
A DIFFERENT IMAGE TO OUR SCREEN.

Here you can see that instead of a picture of me on a vacation in Orlando, we now have a photo of the Grand Canyon displayed on our screen.

This is just a small example, but it really conveys the power of command line arguments. We did not have to change a single line of code, yet we
were able to display a different image our on screen simply by specifying the path to the image at runtime.

Finally, note the contents of your directory. You’ll see a new file there: newimage.jpg :
 FIGURE 3: OPENCV AUTOMATICALLY HANDLED CONVERTING IMAGE FILE TYPES FOR US AND WROTE OUR NEW IMAGE TO DISK.

OpenCV has automatically converted the PNG image to JPG for us! No further effort is needed on our part to convert between image formats.

Summary:
In this lesson we dipped our toes into the vast world of computer vision. We utilized the OpenCV library to load an image off disk, display it to our
screen, and write it back to file in a different image format.

We also explored how to use our terminal and supply command line arguments. We’ll be using the command line (and command line arguments)
extensively in this course. If you are unfamiliar with the command line, I would suggest using the link at the bottom of this article to download the
source code to this lesson and practice with it until you feel more comfortable. Specifically, you’ll want to practice supplying various paths to
images. I would also suggest adding an extra switch to the script called --output , and then using this output path instead of the hardcoded newim
age.jpg . And if after some practice you still feel like you’re struggling, feel free to reach out and ask for help from some of the more experienced
Unix experts in the PyImageSearch Gurus community.