OpenCV Load Image (cv2.imread)

1. Load an input image from disk
2. Determine the image’s width, height, and number of channels
3. Display the loaded image to our screen
4. Write the image back out to disk as a different image filetype

By the end of this guide, you will have a good understanding of how to load images from disk with OpenCV.

To learn how to load an image from disk using OpenCV and cv2.imread, just keep reading.

OpenCV load image (cv2.imread)

In the first part of this tutorial, we’ll discuss how to load an image from disk using OpenCV and the cv2.imread function.

From there, you’ll learn how to configure your development environment to install OpenCV.

We will then review our project directory structure, followed by implementing load_image_opencv.py, a Python script that will load input images from disk using OpenCV and the cv2.imread function.

We’ll wrap up this tutorial with a discussion of our results.

How do we load images from disk with OpenCV?

The cv2.imread function accepts a single parameter, the path to where your image lives on your disk:

image = cv2.imread("path/to/image.png")

Configuring your development environment

Before digging into image loading with OpenCV, you’ll need to have the library installed on your system.

Luckily, OpenCV is pip-installable:

$ pip install opencv-contrib-python

If you need help configuring your development environment for OpenCV 4.3+, I highly recommend that you read my pip install OpenCV guide — it will have you up and running in a matter of minutes.

Having problems configuring your development environment?

All that said, are you:

• Short on time?
• Learning on your employer’s administratively locked system?
• Wanting to skip the hassle of fighting with the command line, package managers, and virtual environments?
• Ready to run the code right now on your Windows, macOS, or Linux systems?

Then join PyImageSearch Plus today!

Gain access to Jupyter Notebooks for this tutorial and other PyImageSearch guides that are pre-configured to run on Google Colab’s ecosystem right in your web browser! No installation required.

And best of all, these Jupyter Notebooks will run on Windows, macOS, and Linux!

Project structure

Let’s review our project structure. Grab the source code from the “Downloads” section, unzip the content, and navigate to where you saved it:

$ tree . --dirsfirst
.
├── 30th_birthday.png
├── jurassic_park.png
├── load_image_opencv.py
└── newimage.jpg

0 directories, 4 files

Let’s now implement our image-loading Python script using OpenCV!

Implementing our OpenCV image loading script

Let’s get started learning how to load an input image from disk using OpenCV.

Create a Python script named load_image_opencv.py, and insert the following code:

# import the necessary packages
import argparse
import cv2

# construct the argument parser and parse the arguments
ap = argparse.ArgumentParser()
ap.add_argument("-i", "--image", required=True,
	help="path to input image")
args = vars(ap.parse_args())

# load the image from disk via "cv2.imread" and then grab the spatial
# dimensions, including width, height, and number of channels
image = cv2.imread(args["image"])
(h, w, c) = image.shape[:3]

# display the image width, height, and number of channels to our
# terminal
print("width: {} pixels".format(w))
print("height: {}  pixels".format(h))
print("channels: {}".format(c))

We can now print the image dimensions (width, height, and number of channels) to the terminal for review (Lines 18-20).

In a future blog post, we’ll talk about what image channels are, but for now keep in mind that the number of channels will be three for color images, representing the Red, Green, and Blue (RGB) components of pixel colors.

But hey, what good is it having an image in memory if we do not know whether it was read correctly by OpenCV? Let’s display the image on screen for verification:

# show the image and wait for a keypress
cv2.imshow("Image", image)
cv2.waitKey(0)

# save the image back to disk (OpenCV handles converting image
# filetypes automatically)
cv2.imwrite("newimage.jpg", image)

You should now be able to apply OpenCV to:

1. Load an image from disk
2. Display it on screen
3. Write it back to disk

We’ll review some of the results of those operations in the next section.

OpenCV image loading results

Now it’s time to load images from the disk using OpenCV!

Start by accessing the “Downloads” section of this tutorial to retrieve the source code and example images.

From there, open a terminal, and execute the following command:

$ python load_image_opencv.py --image 30th_birthday.png 
width: 720 pixels
height: 764  pixels
channels: 3

For my 30th birthday a couple of years ago, my wife rented a near-replica jeep from Jurassic Park (my favorite movie) for us to drive around for the day.

$ ls
30th_birthday.png	jurassic_park.png	load_image_opencv.py	newimage.jpg

$ python load_image_opencv.py --image jurassic_park.png 
width: 577 pixels
height: 433  pixels
channels: 3

Continuing on with the Jurassic Park theme in this tutorial, here we have a photo of Ray Arnold (played by Samuel L. Jackson).

This image has a width of 577 pixels, a height of 433 pixels, and three channels.

Speaking of that final bullet item, let’s give that a try now …

What happens if we pass an invalid image path to “cv2.imread”?

$ python load_image_opencv.py --image path/does/not/exist.png
Traceback (most recent call last):
  File "load_image_opencv.py", line 17, in <module>
    (h, w, c) = image.shape[:3]
AttributeError: 'NoneType' object has no attribute 'shape'

Here I am purposely providing an image path that does not exist on my disk.

Summary

OpenCV conveniently handles reading and writing a wide variety of image file formats (e.g., JPG, PNG, TIFF). The library also simplifies displaying an image on screen and allowing user interaction with the opened window.

If an image cannot be read by OpenCV, you should carefully check if the input filename was given correctly, as the cv2.imread function returns a NoneType Python object upon failure. The function will fail if the file does not exist or if the image format is unsupported by OpenCV.

We have also printed the image dimensions to the terminal (width, height, and number of channels), based on the values of the underlying NumPy array shape. Our script then saved the image to disk using the JPG format, taking advantage of OpenCV’s ability to automatically convert the image to the desired file type.

In the next tutorial in this series, you will learn about OpenCV image basics, including what a pixel is, an overview of the image coordinate system, and how to access individual pixel values.

To download the source code to this post (and be notified when future tutorials are published here on PyImageSearch), simply enter your email address in the form below!