The purpose of the document is to provide an introduction to how to perform various useful tasks with your Native Raspberry Pi Camera
1.How to Capture Image
- The simplest possible example of capture a still image
raspistill -o photo.jpg
- The example that shows the more commonly used options like size and quality
raspistill -o mypic.jpg --width 2592 --height 1944 --quality 100 --hflip --verbose
The camera module takes pictures at a resolution of 2592 x 1944 which is 5,038,848 pixels or 5 megapixels.
- The example that shows the more commonly used options like ISO and shutter speed
raspistill -t 0 --ISO 1600 --shutter 10000
- More available options:
For a full list of possible options, run raspistill with no arguments.
raspistill
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
2.How to Capture Video
- The simplest possible example of capture a video – H.264 video format
raspivid -o vid.h264
- The simplest possible example of capture a video – MP4 video format
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
- The example that shows the more commonly used options like size, framerate, and timeout
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
- More available options:
For a full list of possible options, run raspivid with no arguments.
raspivid
There is a lot of overlap in the arguments used by ‘raspivid‘ and ‘raspistill‘. Here are some of the ones specific to ‘raspivid‘:
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
3.How to Stream Video Remotely
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, We have 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 ntecat is not encrypted. Also, 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.
4.Using ffmpeg with Native 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=305.Time Lapse Photography
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 speed 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 that work for your situation.
Getting high-quality results in very dark environments (such as 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.
6.More reference
https://blog.robertelder.org/commands-raspberry-pi-camera/
https://www.raspberrypi.org/documentation/usage/camera/raspicam/
https://www.raspberrypi.org/documentation/raspbian/applications/camera.md
