RASPBERRY PI CAMERA MODULE

This document describes the use of the three Raspberry Pi camera applications, as of January 8th 2015.

There are three applications provided: raspistill, raspivid, and raspistillyuv. raspistill and raspistillyuv are very similar and are intended for capturing images; raspivid is for capturing video.

All the applications are driven from the command line, and 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.

The applications use up to four OpenMAX (MMAL) components: camera, preview, encoder, and null_sink. All applications use the camera component; raspistilluses the Image Encode component; raspivid uses the Video Encode component; and raspistillyuv doesn't use an encoder, and sends its YUV or RGB output directly from the camera component to file.

The 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. The camera must produce preview frames even if these aren't required for display, as they're used for calculating exposure and white balance settings.

In addition, it's 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.

Command line help is available by typing just the application name in the command line.

Setting up

See Camera Setup.

Troubleshooting

If the Camera Module isn't working correctly, there are number of things to try:

• Is the ribbon cable attached to the Camera Serial Interface (CSI), not the Display Serial Interface (DSI)? The ribbon connector will fit into either port. The Camera port is located near the HDMI connector.

• Are the ribbon connectors all firmly seated, and are they the right way round? They must be straight in their sockets.

• Is the Camera Module connector, between the smaller black Camera Module itself and the PCB, firmly attached? Sometimes this connection can come loose during transit or when putting the Camera Module in a case. Using a fingernail, flip up the connector on the PCB, then reconnect it with gentle pressure. It engages with a very slight click. Don't force it; if it doesn't engage, it's probably slightly misaligned.

• Have sudo apt-get update and sudo apt-get upgrade been run?

• Has raspi-config been run and the Camera Module enabled?

• Is your power supply sufficient? The Camera Module adds about 200-250mA to the power requirements of your Raspberry Pi.

If things are still not working, try the following:

• Error : raspistill/raspivid command not found. This probably means your update/upgrade failed in some way. Try it again.

• Error : ENOMEM. The Camera Module is not starting up. Check all connections again.

• 
Error : ENOMEM. The Camera Module is not starting up. Check all connections again.

• Error : ENOSPC. The Camera Module is probably running out of GPU memory. Check config.txt in the /boot/ folder. The gpu_mem option should be at least 128. Alternatively, use the Memory Split option in the Advanced section of raspi-config to set this.

• If you've checked all the above issues and the Camera Module is still not working, you may need to upgrade the firmware on the Raspberry Pi. Use the following command to get the very latest (but experimental) firmware:

  sudo rpi-update

• If even a firmware update doesn't fix the problem, your Camera Module may be defective, and may need to be replaced.

Common command line options

PREVIEW WINDOW

    --preview,  -p      Preview window settings <'x,y,w,h'>

Allows the user to define the size of the preview window and its location on the screen. Note this will be superimposed over the top of any other windows/graphics.

    --fullscreen,   -f      Fullscreen preview mode

Forces 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.

    --nopreview,    -n      Do not display a preview window

Disables the preview window completely. Note that even though the preview is disabled, the camera will still be producing frames, so will be using power.

    --opacity,  -op     Set preview window opacity

Sets the opacity of the preview windows. 0 = invisible, 255 = fully opaque.

CAMERA CONTROL OPTIONS

    --sharpness,    -sh     Set image sharpness (-100 - 100)

Sets the sharpness of the image. 0 is the default.

    --contrast, -co     Set image contrast (-100 - 100)

Sets the contrast of the image. 0 is the default.

    --brightness,   -br     Set image brightness (0 - 100)

Sets the brightness of the image. 50 is the default. 0 is black, 100 is white.

    --saturation,   -sa     Set image saturation (-100 - 100)

Sets the colour saturation of the image. 0 is the default.

    --ISO,  -ISO        Set capture ISO (100 - 800)

Sets the ISO to be used for captures.

    --vstab,    -vs     Turn on video stabilisation

In video mode only, turns on video stabilisation.

    --ev,   -ev     Set EV compensation (-10 - 10)

Sets the EV compensation of the image. Default is 0.

    --exposure, -ex     Set exposure mode

Possible options are:

• auto: use automatic exposure mode
• night: select setting for night shooting
• nightpreview:
• backlight: select setting for backlit subject
• spotlight:
• sports: select setting for sports (fast shutter etc.)
• snow: select setting optimised for snowy scenery
• beach: select setting optimised for beach
• verylong: select setting for long exposures
• fixedfps: constrain fps to a fixed value
• antishake: antishake mode
• fireworks: select setting optimised for fireworks

Note that not all of these settings may be implemented, depending on camera tuning.

    --awb,  -awb        Set Automatic White Balance (AWB) mode

Modes for which colour temperature ranges (K) are available have these settings in brackets.

• off: turn off white balance calculation
• auto: automatic mode (default)
• sun: sunny mode (between 5000K and 6500K)
• cloud: cloudy mode (between 6500K and 12000K)
• shade: shade mode
• tungsten: tungsten lighting mode (between 2500K and 3500K)
• fluorescent: fluorescent lighting mode (between 2500K and 4500K)
• incandescent: incandescent lighting mode
• flash: flash mode
• horizon: horizon mode

Note that not all of these settings may be implemented, depending on camera type.

    --imxfx,    -ifx        Set image effect

Set an effect to be applied to the image:

• none: no effect (default)
• negative: invert the image colours
• solarise: solarise the image
• posterise: posterise the image
• whiteboard: whiteboard effect
• blackboard: blackboard effect
• sketch: sketch effect
• denoise: denoise the image
• emboss: emboss the image
• oilpaint: oil paint effect
• hatch: hatch sketch effect
• gpen: graphite sketch effect
• pastel: pastel effect
• watercolour: watercolour effect
• film: film grain effect
• blur: blur the image
• saturation: colour saturate the image
• colourswap: not fully implemented
• washedout: not fully implemented
• colourpoint: not fully implemented
• colourbalance: not fully implemented
• cartoon: not fully implemented<