Template: RPi Camera Libcamera Guide
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.
Open a terminal and run the following command:
sudo apt install libcamera-apps
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.
The libcamera software stack provides six applications/commands for using cameras.
|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|
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.
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".
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
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:
- 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.
- 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.
- 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.