Template: RPi Camera Libcamera Guide

From Waveshare Wiki
Revision as of 11:42, 24 January 2022 by Waveshare-eng11 (talk | contribs) (Created page with "==About the Libcamera== Raspberry Pi is transitioning from a legacy camera software stack based on proprietary Broadcom GPU code to an open-source stack based on libcamera. Ra...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

About the Libcamera

Raspberry Pi is transitioning from a legacy camera software stack based on proprietary Broadcom GPU code to an open-source stack based on libcamera. Raspberry Pi OS images from Bullseye onwards will contain only the libcamera-based stack. If you use the newest Bullseye Raspberry Pi OS, the libcamera is pre-installed. If you want to use the legacy camera stack (Raspicam), please move to the Raspicam guide.

Installation (optional)

Open a terminal and run the following command:

sudo apt install libcamera-apps

Camera configuration

If you use the official V1 camera (ov5647), V2 camera (IMX219), and the HQ camera (IMX477), you can just plug in the camera and play.
If you use third-party cameras, the support camera size is as below:

Camera Sensor Supported Board Configuration
OV5647 A full range of Raspberry Pi boards Default setting or
IMX219 Compute Module series only default setting or
IMX290 and IMX327 A full range of Raspberry Pi Boards dtoverlay=imx290,clock-frequency=74250000 or
IMX378 A full range of Raspberry Pi boards dtoverlay=imx378
IMX477 Compute Module series only default setting or
OV9281 A full range of Raspberry Pi boards dtoverlay=ov9281

To override the automatic camera detection, Bullseye users will also need to delete the entry or change it to value 0.


Using libcamera

The libcamera software stack provides six applications/commands for using cameras.

Command Description
libcamera-hello "Hello world" application for previewing camera
libcamera-jpeg A simple still image capture application
libcamera-still Still image capture application which feature more funtsion then libcamera-jpeg
libcamera-vid A video capture application
libcamera-raw A raw Bayer frames recording application
libcamera-detect -


This is a "hello world" application for the camera, it starts the camera and displays a preview window.


libcamera-hello -t 0

This command should dispay a preview window for about 5 seconds. The -t <duration> option lets the user select how long the window is displayed. if you set the duration value to 0, it runs the preview indefinitely.
The preview can be halted either by clicking the window’s close button or using Ctrl-C in the terminal.

The Tuning File

Raspberry Pi’s libcamera implementation includes a tuning file for each different type of camera module. This is a file that describes or "tunes" the parameters that will be passed to the algorithms and hardware to produce the best image quality. libcamera is only able to determine automatically the image sensor being used, not the module as a whole - even though the whole module affects the "tuning".
For example, the NOIR (no IR-filter) versions of sensors require different AWB settings to the standard versions, so the IMX219 NOIR should be run using.

libcamera-hello --tuning-file /usr/share/libcamera/ipa/raspberrypi/imx219_noir.json

Uses can copy an existing tuning file and alter it according to their own preferences.
The --tuning-file parameter applies identically across all the libcamera applications.

Preview Window

Most of the libcamera applications display a preview image in a window, users can use --info-text parameter to display certain helpful image information on the window title bar using "% directives".
For examples:

libcamera-hello --info-text "focus %focus"

For more information about the option and parameters, please refer to the Command Options part below.


libcamera-jpeg is a simple still image capture application. It deliberately avoids some of the additional features of libcamera-still which attempts to emulate raspistill more fully. As such the code is significantly easier to understand, and in practice still provides many of the same features.

To capture a full resolution JPEG image use

libcamera-jpeg -o test.jpg

This command will display a preview for about 5s and then acpture a full resolution JPEG image to the file test.jpg.
The -t <duration> option can be used to alter the length of time the preview shows, and the --width and --height options will change the resolution of the captured still image. For example.

libcamera-jpeg -o test.jpg -t 2000 --width 640 --height 480

Exposure Control

All the libcamera applications allow the user to run the camera with fixed shutter speed and gain. for example:

libcamera-jpeg -o test.jpg -t 2000 --shutter 20000 --gain 1.5

This comamnd would capture an image with an exposure of 20ms and a gain of 1.5x. The the gain will be applied as analogue gain within the sensor up until it reaches the maximum analogue gain permitted by the kernel sensor driver, after which the remainder will be applied as digital gain.
Note: Digital gain is applied by the ISP, note by the sensor. The digital gain will always be very close to 1.p unless:

  1. The total gain requested (either by the --gain option, or by the exposure profile in the camera tuning) exceeds that which can be applied as analogue gain within the sensor. Only the extra gain required will be applied as digital gain.
  2. One of the colour gains is less than 1 (note that colour gains are applied as digital gain too). In this case the advertised digital gain will settle to 1 / min(red_gain, blue_gain). This actually means that one of the colour channels - just not the green one - is having unity digital gain applied to it.
  3. The AEC/AGC is changing. When the AEC/AGC is moving the digital gain will typically vary to some extent to try and smooth out any fluctuations, but it will quickly settle back to its "normal" value.

Raspberry Pi’s AEC/AGC algorithm allows applications to specify exposure compensation, that is, the ability to make images darker or brighter by a given number of stops. For example:

libcamera-jpeg --ev -0.5 -o darker.jpg
libcamera-jpeg --ev 0 -o normal.jpg
libcamera-jpeg --ev 0.5 -o brighter.jpg


libcamera-still is very similar to libcamera-jpeg but supports more of the legacy raspistill options


libcamera-still -o test.jpg


libcamera-still allows files to be saved in a number of different formats. It supports both png and bmp encoding. It also allows files to be saved as a binary dump of RGB or YUV pixels with no encoding or file format at all. In these latter cases, the application reading the files will have to understand the pixel arrangement for itself.

libcamera-still -e png -o test.png
libcamera-still -e bmp -o test.bmp
libcamera-still -e rgb -o test.data
libcamera-still -e yuv420 -o test.data

Note that the format in which the image is saved depends on the -e option and is not selected automatically based on the output file name.

Raw Image Capture