An Overview of How to Do Everything with Raspberry Pi Cameras

2019-05-28 - By Robert Elder

The purpose of this article is to provide an overview of how to perform various useful tasks with your Raspberry Pi Camera. An emphasis will be made on providing copy and paste examples rather than detailed explanations.

How to Setup & Install Raspberry Pi Camera

#  Make sure you system is up to date first
sudo apt-get update
sudo apt-get upgrade
#  Then select 'Interfacing Options' and 'Camera', then reboot.
sudo raspi-config

Here is a video guide of the camera installation process:

How to Take Still Images On Raspberry Pi

Here is the simplest possible example of capturing a still image:

raspistill -o photo.jpg

Here is an example that shows more commonly used options:

raspistill -o mypic.jpg --width 2592 --height 1944 --quality 100 --hflip --verbose

If you run the command 'raspistill' with no parameters:

raspistill

you'll see a full printout of all available options. Here's what my version shows (it may be different for you):

"raspistill" Camera App (commit 7cbfbd38d982 Tainted)

Runs camera for specific time, and take JPG capture at end if requested

usage: raspistill [options]

Image parameter commands

-q, --quality	: Set jpeg quality <0 to 100>
-r, --raw	: Add raw bayer data to jpeg metadata
-l, --latest	: Link latest complete image to filename <filename>
-t, --timeout	: Time (in ms) before takes picture and shuts down (if not specified, set to 5s)
-th, --thumb	: Set thumbnail parameters (x:y:quality) or none
-d, --demo	: Run a demo mode (cycle through range of camera options, no capture)
-e, --encoding	: Encoding to use for output file (jpg, bmp, gif, png)
-x, --exif	: EXIF tag to apply to captures (format as 'key=value') or none
-tl, --timelapse	: Timelapse mode. Takes a picture every <t>ms. %d == frame number (Try: -o img_%04d.jpg)
-fp, --fullpreview	: Run the preview using the still capture resolution (may reduce preview fps)
-k, --keypress	: Wait between captures for a ENTER, X then ENTER to exit
-s, --signal	: Wait between captures for a SIGUSR1 or SIGUSR2 from another process
-g, --gl	: Draw preview to texture instead of using video render component
-gc, --glcapture	: Capture the GL frame-buffer instead of the camera image
-bm, --burst	: Enable 'burst capture mode'
-dt, --datetime	: Replace output pattern (%d) with DateTime (MonthDayHourMinSec)
-ts, --timestamp	: Replace output pattern (%d) with unix timestamp (seconds since 1970)
-fs, --framestart	: Starting frame number in output pattern(%d)
-rs, --restart	: JPEG Restart interval (default of 0 for none)

GL parameter commands

-gs, --glscene	: GL scene square,teapot,mirror,yuv,sobel,vcsm_square
-gw, --glwin	: GL window settings <'x,y,w,h'>

Common Settings commands

-?, --help	: This help information
-w, --width	: Set image width <size>
-h, --height	: Set image height <size>
-o, --output	: Output filename <filename> (to write to stdout, use '-o -'). If not specified, no file is saved
-v, --verbose	: Output verbose information during run
-cs, --camselect	: Select camera <number>. Default 0
-md, --mode	: Force sensor mode. 0=auto. See docs for other modes available
-gps, --gpsdexif	: Apply real-time GPS information to output (e.g. EXIF in JPG, annotation in video (requires libgps.so.22)

Preview parameter commands

-p, --preview	: Preview window settings <'x,y,w,h'>
-f, --fullscreen	: Fullscreen preview mode
-op, --opacity	: Preview window opacity (0-255)
-n, --nopreview	: Do not display a preview window

Image parameter commands

-sh, --sharpness	: Set image sharpness (-100 to 100)
-co, --contrast	: Set image contrast (-100 to 100)
-br, --brightness	: Set image brightness (0 to 100)
-sa, --saturation	: Set image saturation (-100 to 100)
-ISO, --ISO	: Set capture ISO
-vs, --vstab	: Turn on video stabilisation
-ev, --ev	: Set EV compensation - steps of 1/6 stop
-ex, --exposure	: Set exposure mode (see Notes)
-fli, --flicker	: Set flicker avoid mode (see Notes)
-awb, --awb	: Set AWB mode (see Notes)
-ifx, --imxfx	: Set image effect (see Notes)
-cfx, --colfx	: Set colour effect (U:V)
-mm, --metering	: Set metering mode (see Notes)
-rot, --rotation	: Set image rotation (0-359)
-hf, --hflip	: Set horizontal flip
-vf, --vflip	: Set vertical flip
-roi, --roi	: Set region of interest (x,y,w,d as normalised coordinates [0.0-1.0])
-ss, --shutter	: Set shutter speed in microseconds
-awbg, --awbgains	: Set AWB gains - AWB mode must be off
-drc, --drc	: Set DRC Level (see Notes)
-st, --stats	: Force recomputation of statistics on stills capture pass
-a, --annotate	: Enable/Set annotate flags or text
-3d, --stereo	: Select stereoscopic mode
-dec, --decimate	: Half width/height of stereo image
-3dswap, --3dswap	: Swap camera order for stereoscopic
-ae, --annotateex	: Set extra annotation parameters (text size, text colour(hex YUV), bg colour(hex YUV), justify, x, y)
-ag, --analoggain	: Set the analog gain (floating point)
-dg, --digitalgain	: Set the digital gain (floating point)
-set, --settings	: Retrieve camera settings and write to stdout


Notes

Exposure mode options :
off,auto,night,nightpreview,backlight,spotlight,sports,snow,beach,verylong,fixedfps,antishake,fireworks

Flicker avoid mode options :
off,auto,50hz,60hz

AWB mode options :
off,auto,sun,cloud,shade,tungsten,fluorescent,incandescent,flash,horizon

Image Effect mode options :
none,negative,solarise,sketch,denoise,emboss,oilpaint,hatch,gpen,pastel,watercolour,film,blur,saturation,colourswap,washedout,posterise,colourpoint,colourbalance,cartoon

Metering Mode options :
average,spot,backlit,matrix

Dynamic Range Compression (DRC) options :
off,low,med,high

How to Record Video On Raspberry Pi

Here is the simplest possible example of recording a video:

#  Capture 5 seconds of video as raw .h264
raspivid -o myvideo.h264

The above command will use 'raspivid' to capture raw .h264 video with no container. Many media players may not play this raw .h264 file correctly, so you can package it into a .mp4 file using this command on the Raspberry Pi:

#  Run this only one time to install the 'MP4Box' tool.
sudo apt-get install gpac
#  Package it inside an MP4 container
MP4Box -add myvideo.h264 myvideo.mp4

Here are few examples of other commonly used options for raspivid:

raspivid -o myvideo.h264 --width 1280 --height 1024 --framerate 40 --timeout 10000

You may need to explicitly include some options like framerate when packaging with MP4Box:

MP4Box -add  myvideo.h264 -fps 40 myvideo.mp4

For a full list of all options you can use with 'raspivid' run it without any arugments:

raspivid

There is a lot of overlap in the arguments used by 'raspivid' and 'raspistill'. Here are some of the ones specific to 'raspivid':

"raspivid" Camera App (commit 7cbfbd38d982 Tainted)

Display camera output to display, and optionally saves an H264 capture at requested bitrate


usage: raspivid [options]

Image parameter commands

-b, --bitrate	: Set bitrate. Use bits per second (e.g. 10MBits/s would be -b 10000000)
-t, --timeout	: Time (in ms) to capture for. If not specified, set to 5s. Zero to disable
-d, --demo	: Run a demo mode (cycle through range of camera options, no capture)
-fps, --framerate	: Specify the frames per second to record
-e, --penc	: Display preview image *after* encoding (shows compression artifacts)
-g, --intra	: Specify the intra refresh period (key frame rate/GoP size). Zero to produce an initial I-frame and then just P-frames.
-pf, --profile	: Specify H264 profile to use for encoding
-td, --timed	: Cycle between capture and pause. -cycle on,off where on is record time and off is pause time in ms
-s, --signal	: Cycle between capture and pause on Signal
-k, --keypress	: Cycle between capture and pause on ENTER
-i, --initial	: Initial state. Use 'record' or 'pause'. Default 'record'
-qp, --qp	: Quantisation parameter. Use approximately 10-40. Default 0 (off)
-ih, --inline	: Insert inline headers (SPS, PPS) to stream
-sg, --segment	: Segment output file in to multiple files at specified interval <ms>
-wr, --wrap	: In segment mode, wrap any numbered filename back to 1 when reach number
-sn, --start	: In segment mode, start with specified segment number
-sp, --split	: In wait mode, create new output file for each start event
-c, --circular	: Run encoded data through circular buffer until triggered then save
-x, --vectors	: Output filename <filename> for inline motion vectors
-if, --irefresh	: Set intra refresh type
-fl, --flush	: Flush buffers in order to decrease latency
-pts, --save-pts	: Save Timestamps to file for mkvmerge
-cd, --codec	: Specify the codec to use - H264 (default) or MJPEG
-lev, --level	: Specify H264 level to use for encoding
-r, --raw	: Output filename <filename> for raw video
-rf, --raw-format	: Specify output format for raw video. Default is yuv
-l, --listen	: Listen on a TCP socket
-stm, --spstimings	: Add in h.264 sps timings
-sl, --slices	: Horizontal slices per frame. Default 1 (off)


H264 Profile options :
baseline,main,high

H264 Level options :
4,4.1,4.2

H264 Intra refresh options :
cyclic,adaptive,both,cyclicrows

Raw output format options :
yuv,rgb,gray

How to Stream Video Remotely From Raspberry Pi

A commonly-requested feature is to be able to stream video data from your Raspberry Pi over the local network and view it on another computer. After having experimented with a number of different techniques for real-time video streaming from the Pi, I've found that the following method yields the lowest latency. Run this command on your laptop/desktop computer:

nc -l 2222 | mplayer -fps 25 -demuxer h264es -

and run this command on your Raspberry Pi:

raspivid -t 0 -fps 25 -w 640 -h 480 -o - | nc REPLACE_WITH_YOUR_IP 2222

Replace the 'REPLACE_WITH_YOUR_IP' part with the LAN IP address of your laptop/desktop computer where you want to view the stream. The above solution uses the 'raspivid' command to read directly from the Raspberry Pi Camera and then forward the data directly over the network using netcat using the 'nc' command. This option works well if you have only one client that needs to view the stream. It's worth noting that the data forwarded over the network by netcat is not encrypted. Also, the port 2222 is just an example. You can use any port you want as long as it's not already in use on your machine and you must make sure both port references match.

This technique can also be extended to one that will work over the internet using port forwarding rules and a proxy server technique just as described in Using SSH to Connect to Your Raspberry Pi Over The Internet.

Using ffmpeg With Your Raspberry Pi Camera and /dev/video0

In order to record from your Raspberry Pi camera, you need to make sure that the '/dev/video0' device is available. Use this command to check:

ls /dev/video0

If you see anything other than 'file not found', then it's available. By default, it's usually not and you need to enable 'bcm2835-v4l2' kernel module to make it appear:

sudo modprobe bcm2835-v4l2

Running the above command will enable the kernel module immediately, but it won't automatically load it on every boot. To do that, you can use this command:

sudo sh -c 'grep "bcm2835-v4l2" /etc/modules || echo "bcm2835-v4l2" >> /etc/modules'

Now you should be able to verify that '/dev/video0' is available. Once you've verified that it is, you can use ffmpeg to record directly from your Raspberry Pi camera:

ffmpeg -f v4l2 -s 320x240 -r 25 -i /dev/video0 test.avi

You may find it necessary in some situations to modify/view/edit parameters through the 'v42l' API before recording video through it. You can use 'v4l2-ctl' to view and modify video recording related options through this driver:

v42l-ctl

For example, you can use this command:

v4l2-ctl --list-formats-ext

to see what video recording formats are supported through 'v4l2'. 'v4l2' offers a higher-level more standardized API than the MMAL API (which is used directly by raspivid and raspistill). Here is another command you can use to see what other controls 'v4l2' has:

v4l2-ctl --list-ctrls

and here is the output:

User Controls

                     brightness (int)    : min=0 max=100 step=1 default=50 value=50 flags=slider
                       contrast (int)    : min=-100 max=100 step=1 default=0 value=0 flags=slider
                     saturation (int)    : min=-100 max=100 step=1 default=0 value=0 flags=slider
                    red_balance (int)    : min=1 max=7999 step=1 default=1000 value=1000 flags=slider
                   blue_balance (int)    : min=1 max=7999 step=1 default=1000 value=1000 flags=slider
                horizontal_flip (bool)   : default=0 value=0
                  vertical_flip (bool)   : default=0 value=0
           power_line_frequency (menu)   : min=0 max=3 default=1 value=1
                      sharpness (int)    : min=-100 max=100 step=1 default=0 value=0 flags=slider
                  color_effects (menu)   : min=0 max=15 default=0 value=0
                         rotate (int)    : min=0 max=360 step=90 default=0 value=0 flags=00000400
             color_effects_cbcr (int)    : min=0 max=65535 step=1 default=32896 value=32896

Codec Controls

             video_bitrate_mode (menu)   : min=0 max=1 default=0 value=0 flags=update
                  video_bitrate (int)    : min=25000 max=25000000 step=25000 default=10000000 value=10000000
         repeat_sequence_header (bool)   : default=0 value=0
            h264_i_frame_period (int)    : min=0 max=2147483647 step=1 default=60 value=60
                     h264_level (menu)   : min=0 max=11 default=11 value=11
                   h264_profile (menu)   : min=0 max=4 default=4 value=4

Camera Controls

                  auto_exposure (menu)   : min=0 max=3 default=0 value=0
         exposure_time_absolute (int)    : min=1 max=10000 step=1 default=1000 value=1000
     exposure_dynamic_framerate (bool)   : default=0 value=0
             auto_exposure_bias (intmenu): min=0 max=24 default=12 value=12
      white_balance_auto_preset (menu)   : min=0 max=9 default=1 value=1
            image_stabilization (bool)   : default=0 value=0
                iso_sensitivity (intmenu): min=0 max=4 default=0 value=0
           iso_sensitivity_auto (menu)   : min=0 max=1 default=1 value=1
         exposure_metering_mode (menu)   : min=0 max=2 default=0 value=0
                     scene_mode (menu)   : min=0 max=13 default=0 value=0

JPEG Compression Controls

            compression_quality (int)    : min=1 max=100 step=1 default=30 value=30

Extracting Raw Bayer Data & Slow Motion High FPS Photography

There is an unofficial tool called 'raspiraw' similar to raspistill or raspivid that has been developed by several third-part individuals. This tool allows you to extra raw un-processed bayer data from the image sensor before it has been processed heavily by software. This is useful for people doing novel photography experiments such as pushing the FPS limit as high as it will go with these cameras. Here are several sources that you might find interesting on this topic:

Check out the guide A Guide to Recording 660FPS Video On A $6 Raspberry Pi Camera for even more details on this subject.

Time Lapse Photography on Raspberry Pi

You can do time lapse photography by keeping the shutter open for long periods of time. Here is a simple example that I've used that works for taking a picture in a very dark room:

raspistill -w 2592 -h 1944 -ISO 800 --shutter 6000000 --timelapse 20000 -o img_%04d.jpg

This command will run with a shutter speet of 6 seconds (6000000 microseconds) and run the timelapse for 20 seconds (20000 milliseconds). The 'img_%04d.jpg' part specifies that each file name will be uniquely numbered with '%04' being replaced with a 4 digit number identifying that image in the timelapse sequence. The shutter speed and time lapse time specified don't seem to work very predictably, so you'll have to experiment to find values work for your situation.

Getting high quality results in very dark environments (such as for astrophotography) is tricky and may require more advanced techniques than simply keeping the shutter open for a long time. You can use this command to 'average' out the images and reduce noise:

convert img_*.jpg -evaluate-sequence median avg.jpg

The above won't be sufficient for astrophotography since you'll need to modify the tonality curve which the 'convert' command doesn't directly support without doing a lot of math to identify the curve polynomial. See the Imagemagick docs on 'Curves' Adjustments for more info.

Disabling Colored LEDs for Time Lapse Photography

One problem you'll encounter with time-lapse photography on the Pi is that light pollution from the Raspberry Pi itself will actually have a significant effect for long exposures taken in very dark rooms. Here are some steps you can take to disable all of the LEDs so they don't affect your image. The steps below were tested on a Raspberry Pi model 3 B.

Disabling Raspberry Pi Camera LED

In order to disable the red LED on the Raspberry Pi camera, edit the file at '/boot/config.txt'.

sudo nano /boot/config.txt

and make sure the following line is present:

disable_camera_led=1

either by modifying it if it's already there but enabled, or by adding it. You'll need to reboot for the change to take effect.

Disabling Raspberry Pi Power Status LED

Use this command to disable the power status LED on your Raspberry Pi:

echo 0 | sudo tee /sys/class/leds/led1/brightness

The change should take effect immediately, but only lasts until a reboot.

Disabling Raspberry Pi Network Status LED

Use this command to disable the network status LED on your Raspberry Pi:

echo 0 | sudo tee /sys/class/leds/led0/brightness

The change should take effect immediately, but only lasts until a reboot.

A Guide to Recording 660FPS Video On A $6 Raspberry Pi Camera Published 2019-08-01	$1.00 CAD Terminal Block Mining Simulation Game	Using SSH to Connect to Your Raspberry Pi Over The Internet Published 2019-04-22	DS18B20 Raspberry Pi Setup - What's The Deal With That Pullup Resistor? Published 2019-06-12
A Beginners Guide to Securing A Raspberry Pi Published 2019-04-22	Using SSH and Raspberry Pi for Self-Hosted Backups Published 2019-04-22	Pump Room Leak & Temperature Monitoring With Raspberry Pi Published 2019-06-20	A Surprisingly Common Mistake Involving Wildcards & The Find Command Published 2020-01-21

Why Bother Subscribing?

Free Software/Engineering Content. I publish all of my educational content publicly for free so everybody can make use of it. Why bother signing up for a paid 'course', when you can just sign up for this email list?
Read about cool new products that I'm building. How do I make money? Glad you asked! You'll get some emails with examples of things that I sell. You might even get some business ideas of your own :)
People actually like this email list. I know that sounds crazy, because who actually subscribes to email lists these days, right? Well, some do, and if you end up not liking it, I give you permission to unsubscribe and mark it as spam.