Common errors using the Raspberry Pi camera module

Today’s blog post will take a short diversion from our recent trend of Deep Learning tutorials here on the PyImageSearch blog and instead focus on a topic that I’ve been receiving a ton of emails about lately — common errors when using the Raspberry Pi camera module.

I want to start this post by mentioning Dave Jones, the maintainer and chief contributor to the picamera library. Dave is one of the most active open source contributors that I’ve had the privilege to interact with (and he’s a hell of a nice guy too).

A few months ago, I was using the (at the time) latest picamera==1.11 library and was running in to a few errors. After checking the picamera GitHub, I noticed an Issue had been posted regarding my problem. I confirmed the existence of the bug, which Dave then sought out — and fixed before the day was over, even releasing a new, updated version to the PyPI repository.

It goes without saying that without Dave, computer vision and OpenCV on the Raspberry Pi wouldn’t be nearly as fun — or half as accessible.

Over the past few years I’ve encountered a few “common” errors when using the Raspberry Pi and the picamera library. My goal here today is to document some of these errors so you can easily fix them.

In fact, most of the issues I’m documenting here today are not real “errors” at all — they are simply misunderstandings on how the picamera library works in conjunction with your Raspberry Pi setup.

Common errors using the Raspberry Pi camera module

Before we can look at common errors when using the Raspberry Pi camera module, let’s first discuss how we can simply access the picamera video stream.

How to access your picamera video stream

To start, I am going to assume that you’ve already followed the instructions in Accessing the Raspberry Pi Camera with OpenCV and Python and installed the picamera library on your Pi.

If you haven’t installed picamera , this can be accomplished using pip :

$ pip install "picamera[array]"

We add the [array] portion to the command to ensure we can read frames as NumPy arrays, thus making the module compatible with OpenCV.

After pip has finished installing picamera , you can check the version number using the following command:

$ pip freeze

The reported version of picamera should be at least 1.12.

A quick note on Python virtual environments

If you’re a frequent reader of the PyImageSearch blog, you’ll know that I use Python virtual environments a lot — and because of this, you likely do as well.

Before we continue, take a second to see if you are using Python virtual environments by source ‘ing your ~/.profile file and listing all the available virtual environments on your system:

$ source ~/.profile
$ lsvirtualenv

If you get an error related to the lsvirtualenv command not being found, then you are not utilizing Python virtual environments (or you have potentially made a mistake editing your ~/.profile file). If you’re not using Python virtual environments, then you can skip the next paragraph and move to the next sub-section.

Assuming you are using Python virtual environments, you can execute the workon command to access each of the individual Python virtual environments on your system. In most install tutorials on the PyImageSearch blog, we name our Python virtual environment cv , short for “computer vision”:

$ workon cv

A Python template for accessing your Raspberry Pi camera module

In order to access the picamera video stream, I’ve created a simple, extendible template which I’ll detail for you below.

Open up a new file, name it test_video.py , and insert the following code:

# import the necessary packages
from picamera.array import PiRGBArray
from picamera import PiCamera
import time
import cv2

# initialize the camera and grab a reference to the raw camera capture
camera = PiCamera()
camera.resolution = (640, 480)
camera.framerate = 32
rawCapture = PiRGBArray(camera, size=(640, 480))

# allow the camera to warmup
time.sleep(0.1)

Lines 2-5 handle importing our required Python packages.

We then initialize our camera object on Line 8, which allows us to access the Raspberry Pi camera module. We’ll define the resolution of the video stream to be 640 x 480 with a maximum frame rate of 32 FPS (Lines 9 and 10).

From there, we initialize our PiRGBArray object on Line 11, passing in the original camera object and then explicitly re-stating the resolution as well. This PiRGBArray object allows us to actually read frames from the Raspberry Pi camera module in NumPy format, thereby making the frames compatible with OpenCV.

Finally, we wait 0.1 seconds to allow the Raspberry Pi camera sensor to warmup.

Our next code block handles actually capturing frames from our Raspberry Pi camera sensor:

# capture frames from the camera
for frame in camera.capture_continuous(rawCapture, format="bgr", use_video_port=True):
	# grab the raw NumPy array representing the image - this array
	# will be 3D, representing the width, height, and # of channels
	image = frame.array

	# show the frame
	cv2.imshow("Frame", image)
	key = cv2.waitKey(1) & 0xFF

	# clear the stream in preparation for the next frame
	rawCapture.truncate(0)

	# if the `q` key was pressed, break from the loop
	if key == ord("q"):
		break

On Line 17 we start looping over frames captured from the camera using the capture_continuous function. We pass three parameters into this method.

The first is rawCapture , the format in which we want to read each frame. We then specify the format to be bgr since OpenCV expects image channels to be in BGR order rather than RGB. Finally, the use_video_port boolean indicates that we are treating the stream as video.

Once we have the frame , we can access the raw NumPy array via the .array attribute (Line 20).

We display the frame to our screen on Lines 23 and 24 using OpenCV GUI functions.

But before we can move on to the next frame, we first need to prepare our stream by calling the .truncate method on the rawCapture object. If you do not do this, your Python script will throw an error — the exact error we’ll review later in this guide.

Finally, if the q key is pressed (Lines 30 and 31), we break from the loop.

To execute the test_video.py script, just open up a terminal/command line prompt and execute the following command:

$ python test_video.py

Note: If you’re using Python virtual environments, you’ll want to use the workon command to switch to the Python environment that has your OpenCV + picamera library installed.

If all goes well, you should see the Raspberry Pi video stream displayed to your feed:

Otherwise, if you get an error — keep reading. I’ve detailed the most common error messages that I run in to below.

Can’t connect to your picamera module?

Does the following error message look familiar?

$ python test_video.py 
mmal: mmal_vc_component_create: failed to create component 'vc.ril.camera' (1:ENOMEM)
mmal: mmal_component_create_core: could not create component 'vc.ril.camera' (1)
Traceback (most recent call last):
  File "test_video.py", line 11, in <module>
    camera = PiCamera()
  File "/home/pi/.virtualenvs/cv2/local/lib/python2.7/site-packages/picamera/camera.py", line 488, in __init__
    self.STEREO_MODES[stereo_mode], stereo_decimate)
  File "/home/pi/.virtualenvs/cv2/local/lib/python2.7/site-packages/picamera/camera.py", line 526, in _init_camera
    "Camera is not enabled. Try running 'sudo raspi-config' "
picamera.exc.PiCameraError: Camera is not enabled. Try running 'sudo raspi-config' and ensure that the camera has been enabled.

If you are getting this error message, then you likely forgot to (1) run raspi-config , 92) enable the camera, and (3) reboot your Pi.

If you are still getting an error message after running raspi-config , then your camera is likely installed incorrectly. In this case, I would suggest giving this install video a watch and then trying to install your Raspberry Pi camera module again (be sure to power down your Pi first!)

Truncation problems

Truncation errors are fairly easy to identify since they always end with the text Incorrect buffer length for resolution . An example of such an error message can be found below:

$ python test_video.py 
Traceback (most recent call last):
  File "test_video.py", line 20, in <module>
    for frame in camera.capture_continuous(rawCapture, format="bgr", use_video_port=True):
  File "/home/pi/.virtualenvs/cv/local/lib/python2.7/site-packages/picamera/camera.py", line 1851, in capture_continuous
    if not encoder.wait(self.CAPTURE_TIMEOUT):
  File "/home/pi/.virtualenvs/cv/local/lib/python2.7/site-packages/picamera/encoders.py", line 850, in wait
    self.stop()
  File "/home/pi/.virtualenvs/cv/local/lib/python2.7/site-packages/picamera/encoders.py", line 881, in stop
    self._close_output()
  File "/home/pi/.virtualenvs/cv/local/lib/python2.7/site-packages/picamera/encoders.py", line 795, in _close_output
    output.flush()
  File "/home/pi/.virtualenvs/cv/local/lib/python2.7/site-packages/picamera/array.py", line 285, in flush
    self.array = bytes_to_rgb(self.getvalue(), self.size or self.camera.resolution)
  File "/home/pi/.virtualenvs/cv/local/lib/python2.7/site-packages/picamera/array.py", line 174, in bytes_to_rgb
    'Incorrect buffer length for resolution %dx%d' % (width, height))
picamera.exc.PiCameraValueError: Incorrect buffer length for resolution 640x480

If you are getting this error message, you likely forgot to call .truncate after you were done processing your frame. Line 27 of our test_video.py script above demonstrates how to use the .truncate method.

In short: Go back to your script and ensure you have called .truncate before .capture_continuous is called again.

The picamera==1.11 and Python 3 specific error

The v1.11 release of the picamera library introduced a Python 3 specific error. It was particularly hard to diagnose, but as Dave Jones points out, the issue was due to a mis-configuration in his test suite, leading to no Python 3 tests being performed.

This error is often diagnosed by seeing the text TypeError: startswith first arg must be bytes or a tuple of bytes, not str as the final line in the error message. A full example of this error message is shown below:

$ python test_video.py
Traceback (most recent call last):
  File "test_image.py", line 15, in <module>
    camera.capture(rawCapture, format="bgr")
  File "/home/pi/.virtualenvs/cv/local/lib/python3.4/site-packages/picamera/camera.py", line 1371, in capture
    camera_port, output_port, format, resize, **options)
  File "/home/pi/.virtualenvs/cv/local/lib/python3.4/site-packages/picamera/camera.py", line 652, in _get_image_encoder
    self, camera_port, output_port, format, resize, **options)
  File "/home/pi/.virtualenvs/cv/local/lib/python3.4/site-packages/picamera/encoders.py", line 1049, in __init__
    parent, camera_port, input_port, format, resize, **options)
  File "/home/pi/.virtualenvs/cv/local/lib/python3.4/site-packages/picamera/encoders.py", line 534, in __init__
    if not resize and format != 'yuv' and input_port.name.startswith('vc.ril.video_splitter'):
TypeError: startswith first arg must be bytes or a tuple of bytes, not str

The easiest solution is to either upgrade or downgrade your picamera module by one point version.

To upgrade to v1.12 (or whatever the current version of picamera is), use the following command:

$ pip install --upgrade picamera

To downgrade to v1.10, just use this commands:

$ pip uninstall picamera
$ pip install "picamera[array]"==1.10

Make sure you are being mindful of whether you’re using Python virtual environments or not. If you are, execute the workon command before running pip to ensure picamera is installed in to your virtual environment.

Blank and/or black frame

The blank/black frame is a particularly strange problem — frames are being read from the video stream, they are just not being decoded and displayed properly.

First, run the rpi-update to grab the latest firmware updates for your Raspberry Pi:

$ sudo rpi-update

After your Pi reboots, try re-executing your Python script.

If the frame retrieved by the Raspberry Pi camera is still blank/black, then downgrade your picamera installation to v1.10:

$ pip uninstall picamera
$ pip install "picamera[array]"==1.10

I’ve encountered situations where I’ve only had to run rpi-update  to resolve the issue. And I’ve also needed to both upgrade my firmware and downgrade my picamera  version. I’m not sure what the common underlying thread is (I think it’s related to using the newer version of the Raspberry Pi camera hardware + picamera  versioning, but I haven’t been able to nail that down yet).

Summary

In this blog post, I reviewed common error messages that you may encounter when using your Raspberry Pi camera module and the picamera library.

These errors can be quite frustrating to debug, especially if you’re just getting started. My hope is that this guide helps point you in the right direction if you run in to any of these problems — I’ve certainly had my share of long nights trying to track these errors down!

Finally, I would like to mention again the wonderful work and contribution of Dave Jones, the maintainer and chief contributor to the picamera library. Without him, we wouldn’t be able to have near as much computer vision fun with our Pi’s!