1# RaspiCam Documentation 2 3This document describes the use of the four Raspberry Pi camera applications as of February 19th 2018. 4 5There are four applications provided, **raspistill**, **raspivid**, **raspiyuv** and **raspividyuv**. raspistill and raspiyuv are very similar and are intended for capturing images, raspivid and raspividyuv are for capturing video. 6 7All the applications are command line driven, written to take advantage of the mmal API which runs over OpenMAX. The mmal API provides an easier to use system than that presented by OpenMAX. Note that mmal is a Broadcom specific API used only on Videocore 4 systems. 8 9The applications use up to four OpenMAX(mmal) components - camera, preview, encoder and null_sink. All applications use the camera component, raspistill uses the Image Encode component, raspivid uses the Video Encode component and raspiyuv and raspividyuv do not use an encoder, and sends their YUV or RGB output direct from camera component to file. 10 11The preview display is optional, but can be used full screen or directed to a specific rectangular area on the display. If preview is disabled, the null_sink component is used to 'absorb' the preview frames. It is necessary for the camera to produce preview frames even if not required for display, as they are used for calculating exposure and white balance settings. 12 13In addition it is possible to omit the filename option, in which case the preview is displayed but no file is written, or to redirect all output to stdout. 14 15Command line help is available by typing just the application name in on the command line. 16 17## Setting up the Camera hardware 18 19**Warning.** Cameras are static sensitive. Earth yourself prior to handling the PCB, a sink tap/faucet or similar should suffice if you don't have an earthing strap. 20The camera board attaches to the Raspberry Pi via a 15 way ribbon cable. There are only two connections to make, the ribbon cable need to be attached to the camera PCB and the Raspberry Pi itself. You need to get it the right way round or the camera will not work. On the camera PCB, the blue backing on the cable should be away from the PCB, and on the Raspberry Pi it should be towards the Ethernet connection (or where the Ethernet connector would be if you are using a model A). 21 22Although the connectors on the PCB and the Pi are different, they work in a similar way. On the Raspberry Pi, pull up the tabs on each end of the connector. It should slide up easily, and be able to pivot around slightly. Fully insert the ribbon cable into the slot, ensuring it is straight, then gently press down the tabs to clip it into place. The camera PCB itself also requires you to pull the tabs away from the board, gently insert the cable, then push the tabs back. The PCB connector is a little more awkward than the one on the Pi itself. 23 24## Setting up the Camera software 25 26Execute the following instructions on the command line to download and install the latest kernel, GPU firmware and applications. You will need a internet connection for this to work correctly. 27 28 sudo apt-get update 29 sudo apt-get upgrade 30 31Now you need to enable camera support using the raspi-config program you will have used when you first set up your Raspberry Pi. 32 33 sudo raspi-config 34 35Use the cursor keys to move to the camera option and select enable. On exiting raspi-config it will ask to reboot. The enable option will ensure that on reboot the correct GPU firmware will be running (with the camera driver and tuning), and the GPU memory split is sufficient to allow the camera to acquire enough memory to run correctly. 36 37To test that the system is installed and working, try the following command : 38 39 raspistill -v -o test.jpg 40 41The display should show a 5 second preview from the camera and then take a picture, saved to the file test.jpg, whilst display various informational messages. 42 43## Troubleshooting 44 45If the camera is not working correctly, there are number of things to try. 46Are the ribbon connectors all firmly seated and the right way round? They must be straight in their sockets. 47Is the camera module connector firmly attached to the camera PCB? This is the connection from the smaller black camera module itself to the camera PCB. Sometimes this connection can come loose. Using a fingernail, flip up the connector on the PCB, then reseat it with gentle pressure, it engages with a very slight click. 48Have sudo apt-get update, sudo apt-get upgrade been run? 49Has raspi-config been run and the camera enabled? 50Is your power supply sufficient? The camera adds about 200-250mA to the power requirements of the Raspberry Pi. 51 52So, if things are still not working, try the following: 53 54Error : raspistill/raspivid not found. This probably means your update/upgrade failed in some way. Try it again. 55 56Error : ENOMEM displayed. Camera is not starting up. Check all connections again. 57 58Error : ENOSPC displayed. Camera is probably running out of GPU memory. Check config.txt in the /boot/ folder. The gpu_mem option should be at least 128. 59 60If after all the above, the camera is still not working, it may be defective. Try posting on the Raspberry Pi forum (Camera section) to see if there is any more help available there. 61 62## Common Command line Options 63Preview Window 64 65 --preview, -p Preview window settings <'x,y,w,h'> 66 67Allows the user to define the size and location on the screen that the preview window will be placed. Note this will be superimposed over the top of any other windows/graphics. 68 69 --fullscreen, -f Fullscreen preview mode 70 71Forces the preview window to use the whole screen. Note that the aspect ratio of the incoming image will be retained, so there may be bars on some edges. 72 73 --nopreview, -n, Do not display a preview window 74 75Disables the preview window completely. Note that even though the preview is disabled, the camera will still be producing frames, so will be using power. 76 77 --opacity, -op Set preview window opacity 78 79Sets the opacity of the preview windows. 0 = invisible, 255 = fully opaque. 80 81### Camera Control Options 82 83 --sharpness, -sh Set image sharpness (-100 to 100) 84 85Set the sharpness of the image, 0 is the default. 86 87 --contrast, -co Set image contrast (-100 to 100) 88 89Set the contrast of the image, 0 is the default 90 91 --brightness, -br Set image brightness (0 to 100) 92 93Set the brightness of the image, 50 is the default. 0 is black, 100 is white. 94 95 --saturation, -sa Set image saturation (-100 to 100) 96 97set the colour saturation of the image. 0 is the default. 98 99 --ISO, -ISO Set capture ISO 100 101Sets the ISO to be used for captures. Range is 100 to 800. 102 --vstab, -vs Turn on video stabilisation 103 104In video mode only, turn on video stabilisation. 105 106 --ev, -ev Set EV compensation 107 108Set the EV compensation of the image. Range is -10 to +10, default is 0. 109 110 --exposure, -ex Set exposure mode 111 112Possible options are: 113 114auto Use automatic exposure mode 115night Select setting for night shooting 116nightpreview 117backlight Select setting for back lit subject 118spotlight 119sports Select setting for sports (fast shutter etc) 120snow Select setting optimised for snowy scenery 121beach Select setting optimised for beach 122verylong Select setting for long exposures 123fixedfps, Constrain fps to a fixed value 124antishake Antishake mode 125fireworks Select settings 126 127Note that not all of these settings may be implemented, depending on camera tuning. 128 129 --awb, -awb Set Automatic White Balance (AWB) mode 130 131off Turn off white balance calculation 132auto Automatic mode (default) 133sun Sunny mode 134cloud Cloudy mode 135shade Shaded mode 136tungsten Tungsten lighting mode 137fluorescent Fluorescent lighting mode 138incandescent Incandescent lighting mode 139flash Flash mode 140horizon Horizon mode 141 142 --imxfx, -ifx Set image effect 143 144Set an effect to be applied to the image 145 146none NO effect (default) 147negative Negate the image 148solarise Solarise the image 149posterize Posterise the image 150whiteboard Whiteboard effect 151blackboard Blackboard effect 152sketch Sketch style effect 153denoise Denoise the image 154emboss Emboss the image 155oilpaint Apply an oil paint style effect 156hatch Hatch sketch style 157gpen 158pastel A pastel style effect 159watercolour A watercolour style effect 160film Film grain style effect 161blur Blur the image 162saturation Colour saturate the image 163colourswap Not fully implemented 164washedout Not fully implemented 165posterise Not fully implemented 166colourpoint Not fully implemented 167colourbalance Not fully implemented 168cartoon Not fully implemented 169 170 --colfx, -cfx Set colour effect <U:V> 171 172The supplied U and V parameters (range 0 to 255) are applied to the U and Y channels of the image. For example, --colfx 128:128 should result in a monochrome image. 173 174 --metering, -mm Set metering mode 175 176Specify the metering mode used for the preview and capture 177 178average Average the whole frame for metering. 179spot Spot metering 180backlit Assume a backlit image 181matrix Matrix metering 182 183 --rotation, -rot Set image rotation (0-359) 184 185Sets the rotation of the image in viewfinder and resulting image. This can take any value from 0 upwards, but due to hardware constraints only 0, 90, 180 and 270 degree rotations are supported. 186 187 --hflip, -hf Set horizontal flip 188 189Flips the preview and saved image horizontally. 190 191 --vflip, -vf Set vertical flip 192 193Flips the preview and saved image vertically. 194 195 --roi, -roi Set sensor region of interest 196 197Allows the specification of the area of the sensor to be used as the source for the preview and capture. This is defined as x,y for the top left corner, and a width and height, all values in normalised coordinates (0.0-1.0). So to set a ROI at half way across and down the sensor, and an width and height of a quarter of the sensor use : 198 199 -roi 0.5,0.5,0.25,0.25 200 201 --shutter, -ss Set shutter speed 202 203Set the shutter speed to the specified value (in microseconds). There is currently an upper limit of approximately 330000us (330ms, 0.33s) past which operation is undefined. This is being investigated. 204 205 --camselect, -cs Select <camera number> 206 207Select camera number. Default 0 208 209## Application specific settings 210 211### raspistill 212 213--width, -w Set image width <size> 214--height, -h Set image height <size> 215--quality, -q Set jpeg quality <0 to 100> 216 217Quality 100 is almost completely uncompressed. 75 is a good all round value 218 219 --raw, -r Add raw bayer data to jpeg metadata 220 221This option inserts the raw Bayer data from the camera in to the JPEG metadata 222 223 --output -o Output filename <filename>. 224 225Specify the output filename. If not specified, no file is saved. If the filename is '-', then all output is sent to stdout. 226 227 --latest -l Link latest frame to filename <filename> 228 229Make a file system link under this name to the latest frame. 230 231 --verbose, -v Output verbose information during run 232 233Outputs debugging/information messages during the program run. 234 235 --timeout, -t Time before takes picture and shuts down. 236 237The program will run for this length of time, then take the capture (if output is specified). If not specified, this is set to 5 seconds. 238 239 --timelapse, -tl Timelapse mode. 240 241The specific value is the time between shots in milliseconds. Note you should specify %04d at the point in the filename where you want a frame count number to appear. e.g. 242 243 -t 30000 -tl 2000 -o image%04d.jpg 244 245You can also name the files with timestamp (-ts) or datetime(-dt) 246 247 -t 30000 -tl 2000 -ts -o image%d.jpg 248 -t 30000 -tl 2000 -dt -o image2015%10d.jpg 249 250will produce a capture every 2 seconds, over a total period of 30s, named image1.jpg, image0002.jpg..image0015.jpg. Note that the %04d indicates a 4 digit number with leading zero's added to pad to the required number of digits. So, for example, %08d would result in an 8 digit number. 251 252If a timelapse value of 0 is entered, the application will take pictures as fast as possible. Note there is an minimum enforced pause of 30ms between captures to ensure that exposure calculations can be made. 253 254 --thumb, -th Set thumbnail parameters (x:y:quality) 255 256Allows specification of the thumbnail image inserted in to the JPEG file. If not specified, defaults are a size of 64x48 at quality 35. 257 258 --demo, -d Run a demo mode <milliseconds> 259 260This options cycles through range of camera options, no capture is done, the demo will end at the end of the timeout period, irrespective of whether all the options have been cycled. The time between cycles should be specified as a millisecond value. 261 262 --encoding, -e Encoding to use for output file 263 264Valid options are jpg, bmp, gif and png. Note that unaccelerated image types (gif, png, bmp) will take much longer to save than JPG which is hardware accelerated. Also note that the filename suffix is completely ignored when deciding the encoding of a file. 265 266 --exif, -x EXIF tag to apply to captures (format as 'key=value') 267 268Allows the insertion of specific exif tags in to the JPEG image. You can have up to 32 exif tge entries. This is useful for things like adding GPS metadata. For example, to set the Longitude 269 270 --exif GPS.GPSLongitude=5/1,10/1,15/100 271 272would set the Longitude to 5degs, 10 minutes, 15 seconds. See exif documentation for more details on the range of tags available; the supported tags are as follows. 273 274IFD0.< or 275IFD1.< 276ImageWidth, ImageLength, BitsPerSample, Compression, PhotometricInterpretation, ImageDescription, Make, Model, StripOffsets, Orientation, SamplesPerPixel, RowsPerString, StripByteCounts, Xresolution, Yresolution, PlanarConfiguration, ResolutionUnit, TransferFunction, Software, DateTime, Artist, WhitePoint, PrimaryChromaticities, JPEGInterchangeFormat, JPEGInterchangeFormatLength, YcbCrCoefficients, YcbCrSubSampling, YcbCrPositioning, ReferenceBlackWhite, Copyright> 277 278EXIF.< 279ExposureTime, FNumber, ExposureProgram, SpectralSensitivity, a 280ISOSpeedRatings, OECF, ExifVersion, DateTimeOriginal, DateTimeDigitized, ComponentsConfiguration, CompressedBitsPerPixel, ShutterSpeedValue, ApertureValue, BrightnessValue, ExposureBiasValue, MaxApertureValue, SubjectDistance, MeteringMode, LightSource, Flash, FocalLength, SubjectArea, MakerNote, UserComment, SubSecTime, SubSecTimeOriginal, SubSecTimeDigitized, FlashpixVersion, ColorSpace, PixelXDimension, PixelYDimension, RelatedSoundFile, FlashEnergy, SpacialFrequencyResponse, FocalPlaneXResolution, FocalPlaneYResolution, FocalPlaneResolutionUnit, SubjectLocation, ExposureIndex, SensingMethod, FileSource, SceneType, CFAPattern, CustomRendered, ExposureMode, 281WhiteBalance, DigitalZoomRatio, FocalLengthIn35mmFilm, SceneCaptureType, GainControl, Contrast, Saturation, Sharpness, DeviceSettingDescription, SubjectDistanceRange, ImageUniqueID> 282 283GPS.< 284GPSVersionID, GPSLatitudeRef, GPSLatitude, GPSLongitudeRef, GPSLongitude, GPSAltitudeRef, GPSAltitude, GPSTimeStamp, GPSSatellites, GPSStatus, GPSMeasureMode, GPSDOP, GPSSpeedRef, GPSSpeed, GPSTrackRef, GPSTrack, GPSImgDirectionRef, GPSImgDirection, GPSMapDatum, GPSDestLatitudeRef, GPSDestLatitude, GPSDestLongitudeRef, GPSDestLongitude, GPSDestBearingRef, GPSDestBearing, GPSDestDistanceRef, GPSDestDistance, GPSProcessingMethod, GPSAreaInformation, GPSDateStamp, GPSDifferential> 285 286EINT.< 287InteroperabilityIndex, InteroperabilityVersion, RelatedImageFileFormat, RelatedImageWidth, RelatedImageLength> 288 289Note that a small subset of these tags will be set automatically by the camera system, but will be overridden by any exif options on the command line. 290 291 --fullpreview, -fp Full Preview mode 292 293This runs the preview windows using the full resolution capture mode. Maximum frames per second in this mode is 15fps and the preview will have the same field of view as the capture. Captures should happen more quickly as no mode change should be required. This feature is currently under development. 294 295 --keypress -k Keypress mode 296 297The camera is run for the requested time (-t), and a captures can be initiated throughout that by pressing the Enter key. Press X then Enter will exit the application before the timeout is reached. If the timeout is set to 0, the camera will run indefinitely until X then Enter is typed. 298Additional supported keys: 'i', 'o' and 'r'. Press 'i' then Enter will zoom in by 10%. Press 'o' then Enter will zoom out by 10%. Press 'r' then Enter will reset zoom. 299Using the verbose option (-v) will display a prompt asking for user input, otherwise no prompt is displayed. 300 301 --signal -s Signal mode 302 303The camera is run for the requested time (-t), and a captures can be initiated throughout that time by sending a USR1 signal to the camera process. If USR2 signal is received the application makes a capture and exits. This can be done using the kill command. You can find the camera process ID using the 'ps ax' command or using pidof command. 304 305 kill -USR1 <process id of raspistill> 306 kill -USR2 <process id of raspistill> 307 308### raspistillyuv 309 310Many of the options for raspistillyuv are the same as those for raspistill. This section shows the differences. 311 312Unsupported Options: 313 --exif, --encoding, --thumb, --raw, --quality 314 315Extra Options : 316 317 --rgb, -rgb Save uncompressed data as RGB888 318 319This option forces the image to be saved as RGB data with 8 bits per channel, rather than YUV420. 320 321Note that the image buffers saved in raspistillyuv are padded to a horizontal size divisible by 16 (so there may be unused bytes at the end of each line to made the width divisible by 16). Buffers are also padded vertically to be divisible by 16, and in the YUV mode, each plane of Y,U,V is padded in this way. 322 323### raspivid 324 325 --width, -w Set image width <size> 326 327Width of resulting video. This should be between 64 and 1920. 328 329 --height, -h Set image height <size> 330 331Height of resulting video. This should be between 64 and 1080. 332 333 --bitrate, -b Set bitrate. 334 335Use bits per second, so 10MBits/s would be -b 10000000. For H264, 1080p a high quality bitrate would be 15Mbits/s or more. 336 337 --output -o Output filename <filename>. 338 339Specify the output filename. If not specified, no file is saved. If the filename is '-', then all output is sent to stdout. 340 341 --verbose, -v Output verbose information during run 342 343Outputs debugging/information messages during the program run. 344 345 --timeout, -t Time before takes picture and shuts down. 346 347The program will run for this length of time, then take the capture (if output is specified). If not specified, this is set to 5seconds. Setting 0 will mean the application will run continuously until stopped with Ctrl-C. 348 349 --demo, -d Run a demo mode <milliseconds> 350 351This options cycles through range of camera options, no capture is done, the demo will end at the end of the timeout period, irrespective of whether all the options have been cycled. The time between cycles should be specified as a millisecond value. 352 353 --framerate, -fps Specify the frames per second to record 354 355At present, the minimum frame rate allowed is 2fps, the maximum is 30fps. This is likely to change in the future. 356 357 --penc, -e Display preview image *after* encoding 358 359Switch on an option to display the preview after compression. This will show any compression artefacts in the preview window. In normal operation, the preview will show the camera output prior to being compressed. This option is not guaranteed to work in future releases. 360 361 --intra, -g Specify the intra refresh period (key frame rate/GoP) 362 363Sets the intra refresh period (GoP) rate for the recorded video. H264 video uses a complete frame (I-frame) every intra refresh period from which subsequent frames are based. This options specifies the numbers of frames between each I-frame. Larger numbers here will reduce the size of the resulting video, smaller numbers make the stream more robust to error. Setting 0 will produce an initial I-frame and then just P-frames. 364 365 --profile, -pf Specify H264 profile to use for encoding 366 367Sets the H264 profile to be used for the encoding. Options are : baseline, main, high. 368 369Examples 370 371Still captures 372 373By default, captures are done at the highest resolution supported by the sensor. This can be changed using the -w and -h command line options. 374 375Taking a default capture after 2s (note times are specified in milliseconds) on viewfinder, saving in image.jpg 376 377 raspistill -t 2000 -o image.jpg 378 379Take a capture at a different resolution. 380 381 raspistill -t 2000 -o image.jpg -w 640 -h 480 382 383Now reduce the quality considerably to reduce file size 384 385 raspistill -t 2000 -o image.jpg -q 5 386 387Force the preview to appear at coordinate 100,100, with width 300 and height 200 pixels. 388 389 raspistill -t 2000 -o image.jpg -p 100,100,300,200 390 391Disable preview entirely 392 393 raspistill -t 2000 -o image.jpg -n 394 395Save the image as a png file (lossless compression, but slower than JPEG). Note that the filename suffix is ignored when choosing the image encoding. 396 397 raspistill -t 2000 -o image.png -e png 398 399Add some EXIF information to the JPEG. This sets the Artist tag name to Boris, and the GPS altitude to 123.5m. Note that if setting GPS tags you should set as a minimum GPSLatitude, GPSLatitudeRef, GPSLongitude, GPSLongitudeRef, GPSAltitude and GPSAltitudeRef. 400 401 raspistill -t 2000 -o image.jpg -x IFDO.Artist=Boris -x GPS.GPSAltitude=1235/10 402 403Set an emboss style image effect 404 405 raspistill -t 2000 -o image.jpg -ifx emboss 406 407Set the U and V channels of the YUV image to specific values (128:128 produces a greyscale image) 408 409 raspistill -t 2000 -o image.jpg -cfx 128:128 410 411Run preview ONLY for 2s, no saved image. 412 413 raspistill -t 2000 414 415Take timelapse picture, one every 10 seconds for 10 minutes (10 minutes = 600000ms), named image_num_001_today.jpg, image_num_002_today.jpg onwards, with the latest picture also available under the name latest.jpg. 416 417 raspistill -t 600000 -tl 10000 -o image_num_%03d_today.jpg -l latest.jpg 418 419Take a picture and send image data to stdout 420 421 raspistill -t 2000 -o - 422 423Take a picture and send image data to file 424 425 raspistill -t 2000 -o - > my_file.jpg 426 427Run camera forever, taking a picture when Enter is pressed 428 429 raspistill -t 0 -k -o my_pics%02d.jpg 430Video Captures 431 432Image size and preview settings are the same as for stills capture. Default size for video recording is 1080p (1920x1080) 433 434Record a 5s clip with default settings (1080p30) 435 436 raspivid -t 5000 -o video.h264 437 438Record a 5s clip at a specified bitrate (3.5MBits/s) 439 440 raspivid -t 5000 -o video.h264 -b 3500000 441 442Record a 5s clip at a specified framerate (5fps) 443 444 raspivid -t 5000 -o video.h264 -f 5 445 446Encode a 5s camera stream and send image data to stdout 447 448 raspivid -t 5000 -o - 449 450Encode a 5s camera stream and send image data to file 451 452 raspivid -t 5000 -o - > my_file.h264 453 454Shell Error Codes 455 456The applications described here will return a standard error code to the shell on completion. Possible error codes are : 457 458ER_OK 0 Application ran successfully. 459EX_USAGE 64 Bad command line parameter 460ER_SOFTWARE 70 Software or camera error 461 130 Application terminated by ctrl-C. 462 463