RASPICAM(7)

NAME
raspicam - the Raspberry Pi Camera Module and its utilities

DESCRIPTION
There are four applications provided: raspistill(1), raspivid(1), raspiyuv(1) and raspividyuv(1). raspistill(1) and raspiyuv(1) are very similar and are intended for capturing images; raspivid(1) and raspvidyuv(1) are for recording video. The utilities share many common options, which are documented in the sections HARDWARE OPTIONS, PREVIEW OPTIONS, IMAGE OPTIONS, and STEREOSCOPIC (3D) OPTIONS below. Within each section, options are listed alphabetically (by the long-option's title).

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; raspistill(1) uses the Image Encode component; raspivid(1) uses the Video Encode component; and raspiyuv(1) and raspividyuv(1) don't use an encoder, sending their 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.

GETTING STARTED
Warning: Cameras are sensitive to static. Earth yourself prior to handling the PCB. A sink tap or similar should suffice if you don’t have an earthing strap.

The camera board attaches to the Raspberry Pi via a 15-way ribbon cable. There are only two connections to make: the ribbon cable needs to be attached to the camera PCB, and to the Raspberry Pi itself. You need to get the cable the right way round, or the camera will not work. On the camera PCB, the blue backing on the cable should face away from the PCB, and on the Raspberry Pi it should face towards the Ethernet connection (or where the Ethernet connector would be if you're using a model A+).

Although the connectors on the PCB and the Pi are different, they work in a similar way. On the Raspberry Pi itself, 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 set straight, then gently press down the tabs to clip it into place. The camera PCB connector also requires you to pull the tabs away from the board, gently insert the cable, then push the tabs back. The PCB connector can be a little more awkward than the one on the Pi itself.

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 update and sudo apt full-upgrade been run?

•   Is start_x=1 present in the “config.txt” boot configuration?

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

Try the following in response to specific error messages:

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 : ENOSPC
    The Camera Module is probably running out of GPU memory. Check “config.txt” on the boot partition. The gpu_mem option should be at least 128.

HARDWARE OPTIONS

-cs, --camselect camera
    Selects the camera to use on a multi-camera system (currently only Pi Compute Modules). Use 0 or 1.

-md, --mode mode
    Sets a specified sensor mode, disabling the automatic selection. Possible values depend on the version of the Camera Module being used:

    Version 1.x (OV5647)
    Mode | Size | Aspect | Framerates | FOV | Binning
    0 | --- automatic selection ---
    1 | 1920 x 1080 | 16:9 | 1 - 30fps | Partial | None
    2 | 2592 x 1944 | 4:3 | 1 - 15fps | Full | None
    3 | 2592 x 1944 | 4:3 | 0.1666 - 1fps | Full | None
    4 | 1296 x 972 | 4:3 | 1 - 42fps | Full | 2 x 2
    5 | 1296 x 730 | 16:9 | 1 - 49fps | Full | 2 x 2
    6 | 640 x 480 | 4:3 | 42.1 - 60fps | Full | 2 x 2 + skip
    7 | 640 x 480 | 4:3 | 60.1 - 90fps | Full | 2 x 2 + skip

    Version 2.x (IMX219)
    Mode | Size | Aspect | Framerates | FOV | Binning
    0 | --- automatic selection ---
    1 | 1920 x 1080 | 16:9 | 0.1 - 30fps | Partial | None
    2 | 3280 x 2464 | 4:3 | 0.1 - 15fps | Full | None
    3 | 3280 x 2464 | 4:3 | 0.1 - 15fps | Full | None
    4 | 1640 x 1232 | 4:3 | 0.1 - 40fps | Full | 2 x 2
    5 | 1640 x 922 | 16:9 | 0.1 - 40fps | Full | 2 x 2
    6 | 1280 x 720 | 16:9 | 40 - 90fps | Partial | 2 x 2
    7 | 640 x 480 | 4:3 | 40 - 200fps* | Partial | 2 x 2

    * For frame rates over 120fps, it is necessary to turn off automatic exposure and gain control using -ex off. Doing so should achieve the higher frame rates, but exposure time and gains will need to be set to fixed values supplied by the user.

    HQ Camera (IMX477)
    Mode | Size | Aspect | Framerates | FOV | Binning
    0 | --- automatic selection ---
    1 | 2028 x 1080 | 169:90 | 0.1 - 50fps | Partial | 2 x 2
    2 | 2028 x 1520 | 4:3 | 0.1 - 50fps | Full | 2 x 2
    3 | 4056 x 3040 | 4:3 | 0.005 - 10fps | Full | None
    4 | 1012 x 760 | 4:3 | 50.1 - 120fps | Full | 4 x 4

-gps, --gpsdexif
    Applies real-time EXIF information from any attached GPS dongle (using GSPD) to the image; requires libgps.so to be installed.

PREVIEW OPTIONS

-dn, --dispnum screen
    Specifies which display the camera preview should appear on, using dispmanx / tvservice numbering (see the output of tvservice -l or the display_power command under vcgencmd(1) for more information).

-f, --fullscreen
    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.

-n, --nopreview
    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.

-op, --opacity value
    Sets the opacity of the preview window. 0 = invisible, 255 = fully opaque.

-p, --preview 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.

IMAGE OPTIONS

-a, --annotate flags|text
    Adds some text and/or metadata to the picture.

    Metadata is indicated using a bitmask notation, so add them together to show multiple parameters. For example, 12 will show time (4) and date (8), since 4+8=12.

    Text may include date/time placeholders by using the '%' character, as used by strftime(3).

    -a 4
        Displays the time, "20:09:33"

    -a 8
        Displays the date, "10/28/15"

    -a 16
        Shutter settings

    -a 32
        CAF settings

    -a 64
        Gain settings

    -a 128
        Lens settings

    -a 256
        Motion settings

    -a 512
        Frame number

    -a 1024
        Black background

    -a ABC
        Show the specified text, "ABC"

    -a ABC %Y-%m-%d
        Show the specified text, "ABC %Y-%m-%d"

    -a 4 -a ABC %Y-%m-%d %X
        Displays a formatted timestamp, "ABC 2015-10-28 20:09:33"

    -a 8 -a ABC %Y-%m-%d %X
        Also displays a formatted timestamp, "ABC 2015-10-28 20:09:33"

-ae, --annotateex size,fg,bg
    Specifies annotation size, text color, and background color. Colors are in hex YUV format. Size ranges from 6 - 160; default is 32. Asking for an invalid size should give you the default.

    For example, to obtain size 32 white text on a black background:

        -ae 32,0xff,0x808000 -a "Annotation text"

    Or for size 10 black text on a white background:

        -ae 10,0x00,0x8080FF -a "Annotation text"

-ag, --analoggain value
    Sets the analog gain value directly on the sensor (floating point value from 1.0 to 8.0 for the OV5647 sensor on V1 Camera Module, and 1.0 to 12.0 for the IMX219 sensor on V1 Camera Module and the IMX447 on the HQ Camera).

-awb, --awb mode
    Modes for which color temperature ranges (in Kelvin) 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

    greyworld
        used on the NoIR camera to fix incorrect AWB results due to the lack of the IR filter

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

-awbg, --awbgains blue,red
    Sets blue and red gains (as floating point numbers) to be applied when -awb off is set e.g. -awbg 1.5,1.2

-br, --brightness value
    Sets the brightness of the image, from 0 to 100. 50 is the default.

-cfx, --colfx u:v
    The supplied U and V parameters (range 0 - 255) are applied to the U and Y channels of the image. For example, --colfx 128:128 should result in a monochrome image.

-co, --contrast value
    Sets the contrast of the image, from -100 to 100. 0 is the default.

-dg, --digitalgain value
    Sets the digital gain value applied by the ISP (floating point value from 1.0 to 64.0, but values over about 4.0 will produce overexposed images).

-drc, --drc value
    Dynamic range control (DRC) changes the images by increasing the range of dark areas, and decreasing the brighter areas. This can improve the image in low light areas. Valid values are off (default), low, med, or high.

-ev, --ev value
    Sets the exposure value compensation, from -10 to 10. 0 is the default.

-ex, --exposure mode
    Sets the exposure mode of the camera. Possible options are:

    auto
        use automatic exposure mode (default)

    night
        select setting for night shooting

    nightpreview
        <undocumented>

    backlight
        select setting for backlit subject

    spotlight
        <undocumented>

    sports
        select setting for sports (fast shutter etc.)

    snow
        select setting optimized for snowy scenery

    beach
        select setting optimized for beach

    verylong
        select setting for long exposures

    fixedfps
        constrain fps to a fixed value

    antishake
        select "antishake" mode

    fireworks
        select setting optimized for fireworks

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

-fli, --flicker mode
    Set a mode to compensate for lights flickering at the mains frequency, which can be seen as a dark horizontal band across an image. Flicker avoidance locks the exposure time to a multiple of the mains flicker frequency (8.33ms for 60Hz, or 10ms for 50Hz). This means that images can be noisier as the control algorithm has to increase the gain instead of exposure time should it wish for an intermediate exposure value. auto can be confused by external factors, therefore it is preferable to leave this setting off unless actually required.

    Possible options are:

    off turn off flicker avoidance

    auto
        automatically detect mains frequency

    50hz
        set avoidance at 50Hz

    60hz
        set avoidance at 60Hz

-hf, --hflip
    Flips the preview and saved image horizontally.

-ifx, --imxfx effect
    Set an effect to be applied to the image:

    none
        no effect (default)

    negative
        invert the image colors

    solarise
        solarize the image

    posterise
        posterize 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
        watercolor effect

    film
        film grain effect

    blur
        blur the image

    saturation
        saturate the image color

    colourswap
        not fully implemented

    washedout
        not fully implemented

    colourpoint
        not fully implemented

    colourbalance
        not fully implemented

    cartoon
        not fully implemented

    Note that not all of these settings may be available in all circumstances.

-ISO, --ISO value
    Sets the ISO to be used for captures, from 100 to 800. The default is automatic.

-mm, --metering mode
    Specify the metering mode used for the preview and capture:

    average
        average the whole frame for metering

    spot
        spot metering in the center of the frame

    backlit
        assume a backlit image

    matrix
        matrix metering

-roi, --roi x,y,w,h
    Allows 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, with all values in normalised coordinates (0.0 - 1.0). So, to set a ROI at halfway across and down the sensor, and a width and height of a quarter of the sensor, use:

        -roi 0.5,0.5,0.25,0.25

-rot, --rotation value
    Sets the rotation of the image in the 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.

-sa, --saturation value
    Sets the color saturation of the image, from -100 to 100. 0 is the default.

-set, --settings
    Retrieves the current camera settings and writes them to stdout.

-sh, --sharpness value
    Sets the sharpness of the image, from -100 to 100. 0 is the default.

-ss, --shutter value
    Sets the shutter open time to the specified value (in microseconds). Shutter speed limits are as follows:
    Camera Model | Max (microseconds)
    Version 1.x (OV5647) | 6000000 (6s)
    Version 2.x (IMX219) | 10000000 (10s)
    HQ (IMX477) | 200000000 (200s)

    Using values above these maximums will result in undefined behaviour.

-st, --stats
    Force recomputation of statistics on stills capture pass. Digital gain and AWB are recomputed based on the actual capture frame statistics, rather than the preceding preview frame.

-vf, --vflip
    Flips the preview and saved image horizontally.

-vs, --vstab
    In video mode only, turns on video stabilisation.

STEREOSCOPIC (3D) OPTIONS

-3dswap, --3dswap
    Swaps the camera order used in stereoscopic imaging; NOTE: currently not working.

-dec, --decimate
    Halves the width and height of the stereo image.

-3d, --stereo mode
    Select the specified stereo imaging mode; sbs selects side-by-side mode, tb selects top/bottom mode; off turns off stereo mode (the default).

SEE ALSO
raspistill(1), raspiyuv(1), raspivid(1), raspividyuv(1), vcgencmd(1), [SOURCE]

REFERENCES

[SOURCE]
    https://www.raspberrypi.org/documentation/raspbian/applications/camera.md