Difference between revisions of "Template:RPi Camera Libcamera Guide"

From Waveshare Wiki
Jump to: navigation, search
 
(32 intermediate revisions by the same user not shown)
Line 1: Line 1:
==About the Libcamera==
+
=User Guides for libcamera/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.
+
==Introduction==
If you want to use the legacy camera stack (Raspicam), please move to the Raspicam guide.
+
After the Bullseye version of the Raspberry Pi image, the underlying Raspberry Pi driver was switched from Raspicam to libcamera. Libcamera is an open-source software stack (will be called driver later, which is easy to understand), which is convenient for third-party porting and development of their own camera drivers. As of 2021-12-20, there are still many bugs in libcamera, and the current libcamera does not support python, so the Raspberry Pi official still provides a method for installing and downloading Raspicam. For users who are difficult to switch to libcamera but need to use the latest system, please directly refer to the Raspicam instructions. <br />
  
==Installation (optional)==
+
==Call Camera==
Open a terminal and run the following command:
+
The libcamera software stack provides six instructions for users to preview and test the camera interface.
 +
===libcamera-hello===
 +
This is a simple "hello world" program that previews the camera and displays the camera image on the screen.
 +
====Example====
 
<pre>
 
<pre>
sudo apt install libcamera-apps
+
libcamera-hello
 
</pre>
 
</pre>
 
+
This command will preview the camera on the screen for about 5 seconds. The user can use the "-t <duration>" parameter to set the preview time, where the unit of <duration> is milliseconds. If it is set to 0, it will keep previewing all the time. For example:
==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. <br />
 
If you use third-party cameras, the support camera size is as below:
 
{|class="list"
 
! Camera Sensor !! Supported Board !! Configuration
 
|-
 
| OV5647 || A full range of Raspberry Pi boards || Default setting or <br /><font color=gray> dtoverlay=ov5647 </font>
 
|-
 
| IMX219 || Compute Module series only || default setting or <br />  <font color=gray>dtoverlay=imx219</font>
 
|-
 
| IMX290 and IMX327 || A full range of Raspberry Pi Boards
 
| <font color=gray>dtoverlay=imx290,clock-frequency=74250000 </font> or  <br /> <font color=gray>dtoverlay=imx290,clock-frequency=37125000 </font>
 
|-
 
| IMX378 || A full range of Raspberry Pi boards || <font color=gray>dtoverlay=imx378</font>
 
|-
 
| IMX477 ||Compute Module series only|| default setting or <br /> <font color=gray>dtoverlay=imx477</font>
 
|-
 
| OV9281 || A full range of Raspberry Pi boards || <font color=gray>dtoverlay=ov9281</font>
 
|}
 
To override the automatic camera detection, Bullseye users will also need to delete the entry or change it to value 0.
 
 
<pre>
 
<pre>
camera_auto_detect=1
+
libcamerahello -t 0
 
</pre>
 
</pre>
==Using libcamera==
+
 
The libcamera software stack provides six applications/commands for using cameras.
+
====Tune File====
{|class="list"
+
The libcamera driver of the Raspberry Pi will call a tuning file for different camera modules. The tuning file provides various parameters. When calling the camera, libcamera will call the parameters in the tuning file, and process the image in combination with the algorithm. The final output is the preview screen. Since the libcamera driver can only automatically receive the signal of the chip, the final display effect of the camera will also be affected by the entire module. The use of the tuning file is to flexibly handle the cameras of different modules and adjust to improve the image quality. <br />
! Command !! Description
+
If the output image of the camera is not ideal after using the default tuning file, the user can adjust the image by calling the custom tuning file. For example, if you are using the official NOIR version of the camera, the NOIR camera may require different white balance parameters compared with the regular Raspberry Pi Camera V2. In this case, you can switch by calling the tuning file. <br />
|-
 
| [[#libcamera-hello|libcamera-hello]] || "Hello world" application for previewing camera
 
|-
 
| [[#libcamera-jpeg|libcamera-jpeg]] || A simple still image capture application
 
|-
 
| [[#libcamera-still|libcamera-still]] || Still image capture application which feature more funtsion then libcamera-jpeg
 
|-
 
| [[#libcamera-vid|libcamera-vid]] || A video capture application
 
|-
 
| [[#libcamera-raw|libcamera-raw]] || A raw Bayer frames recording application
 
|-
 
| libcamera-detect || -
 
|}
 
===libcamera-hello===
 
This is a "hello world" application for the camera, it starts the camera and displays a preview window.
 
====example====
 
<pre>
 
libcamera-hello -t 0
 
</pre>
 
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.<br />
 
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". <br />
 
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.<br />
 
 
<pre>
 
<pre>
 
libcamera-hello --tuning-file /usr/share/libcamera/ipa/raspberrypi/imx219_noir.json
 
libcamera-hello --tuning-file /usr/share/libcamera/ipa/raspberrypi/imx219_noir.json
 
</pre>
 
</pre>
Uses can copy an existing tuning file and alter it according to their own preferences. <br />
+
Users can copy the default tuning files and modify them according to their needs. <br />
The --tuning-file parameter applies identically across all the libcamera applications.
+
Note: The use of tuning files is applicable to other libcamera commands, and will not be introduced in subsequent commands.<br />
  
 
====Preview Window====
 
====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". <br />
+
Most libcamera commands will display a preview window on the screen. Users can customize the title information of the preview window through the --info-text parameter, and can also call some camera parameters through %directives and display them on the window.<br />
For examples:
+
For example, if you use HQ Camera: You can display the focal length of the camera on the window through --info-txe "%focus".<br />
 
<pre>
 
<pre>
libcamera-hello --info-text "focus %focus"
+
libcamera-hello --info-text "focus %focus".
 
</pre>
 
</pre>
For more information about the option and parameters, please refer to the Command Options part below.
+
Note: For more information on parameter settings, please refer to the following chapters.
  
===libcamera-jpeg===
+
==='''libcamera-jpeg'''===
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.
+
libcamera-jpeg is a simple still picture shooting program, different from the complex functions of libcamera-still, libcamera-jpeg code is more concise, and has many of the same functions to complete picture shooting.
====To capture a full resolution JPEG image use====
+
====Take JPEG image of full pixel====
 
<pre>
 
<pre>
 
libcamera-jpeg -o test.jpg
 
libcamera-jpeg -o test.jpg
 
</pre>
 
</pre>
This command will display a preview for about 5s and then acpture a full resolution JPEG image to the file test.jpg. <br />
+
This shooting command will display a preview serial port for about 5 seconds, and then shoot a full-pixel JPEG image and save it as test.jpg. <br />
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.
+
Users can set the preview time through the -t parameter, and can set the resolution of the captured image through --width and --height. E.g:
 
<pre>
 
<pre>
 
libcamera-jpeg -o test.jpg -t 2000 --width 640 --height 480
 
libcamera-jpeg -o test.jpg -t 2000 --width 640 --height 480
 
</pre>
 
</pre>
 
+
====Exposure control====
====Exposure Control====
+
All libcamera commands allow the user to set the shutter time and gain themselves, such as:
All the libcamera applications allow the user to run the camera with fixed shutter speed and gain. for example:
 
 
<pre>
 
<pre>
 
libcamera-jpeg -o test.jpg -t 2000 --shutter 20000 --gain 1.5
 
libcamera-jpeg -o test.jpg -t 2000 --shutter 20000 --gain 1.5
 
</pre>
 
</pre>
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. <br />
+
This command will capture an image with 20ms exposure and camera gain set to 1.5x. The gain parameter set will first set the analog gain parameter inside the photosensitive chip. If the set gain exceeds the maximum built-in analog gain value of the driver, the maximum analog gain of the chip will be set first, and then the remaining gain multiples will be used as numbers. gain to take effect. <br />
Note: Digital gain is applied by the ISP, note by the sensor. The digital gain will always be very close to 1.p unless:
+
Remarks: The digital gain is realized by ISP (image signal processing), not directly adjusting the built-in register of the chip. Under normal circumstances, the default digital gain is close to 1.0, unless there are the following three situations. <br />
#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.
+
#Overall gain parameter requirements, that is, when the analog gain cannot meet the set gain parameter requirements, digital gain will be needed for compensation.
#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.
+
#One of the color gains is less than 1 (the color gain is achieved by digital gain), in this case, the final gain is stabilized at 1/min(red_gain, blue_gain), that is, a uniform number is actually applied gain, and is the gain value for one of the color channels (not the green channel).
#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.
+
#AEC/AGC was modified. If there is a change in AEC/AGC, the numerical gain will also change to a certain extent, where does it come from to eliminate any fluctuations, but this change will be quickly restored to the "normal" value.
 
+
The Raspberry Pi's AEC/AGX algorithm allows the program to specify exposure compensation, which is to adjust the brightness of the image by setting the aperture value, for example:
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:
 
 
<pre>
 
<pre>
 
libcamera-jpeg --ev -0.5 -o darker.jpg
 
libcamera-jpeg --ev -0.5 -o darker.jpg
Line 104: Line 60:
 
libcamera-jpeg --ev 0.5 -o brighter.jpg
 
libcamera-jpeg --ev 0.5 -o brighter.jpg
 
</pre>
 
</pre>
===libcamera-still===
+
 
libcamera-still is very similar to libcamera-jpeg but supports more of the legacy raspistill options
+
==='''libcamera-still'''===
====example====
+
libcamera-still and libcamera-jpeg are very similar, the difference is that libcamera inherits more functions of raspistill. As before, the user can take a picture with the following command.
 +
====Test Command====
 
<pre>
 
<pre>
 
libcamera-still -o test.jpg
 
libcamera-still -o test.jpg
 
</pre>
 
</pre>
====Encoders====
+
====Encoder====
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.
+
libcamea-still supports image files in different formats, can support png and bmp encoding, and also supports saving binary dumps of RGB or YUV pixels as files without encoding or in any image format. If you save RGB or YUV data directly, the program must understand the pixel arrangement of the file when reading such files.
 
<pre>
 
<pre>
 
libcamera-still -e png -o test.png
 
libcamera-still -e png -o test.png
Line 118: Line 75:
 
libcamera-still -e yuv420 -o test.data
 
libcamera-still -e yuv420 -o test.data
 
</pre>
 
</pre>
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.
+
Note: The format of image saving is controlled by the -e parameter. If the -e parameter is not called, it will be saved in the format of the output file name by default.
====Raw Image Capture====
+
====Raw image capture====
Raw images are the images produced directly by the image sensor before any processing is applied to them either by the ISP or any of the CPU cores. For colour image sensors these are usually Bayer format images. Note that raw images are quite different from the processed but unencoded RGB or YUV images that we saw earlier.
+
The raw image is the image output by the direct image sensor without any ISP or CPU processing. For color camera sensors, the output format of the raw image is generally Bayer. Note that the raw image is different from the bit-encoded RGB and YUV images we said earlier, and RGB and YUV are also ISP-processed images. <br />
 +
Instructions to take a raw image:<br />
 
<pre>
 
<pre>
 
libcamera-still -r -o test.jpg
 
libcamera-still -r -o test.jpg
 
</pre>
 
</pre>
These DNG files contain metadata pertaining to the image capture, including black levels, white balance information and the colour matrix used by the ISP to produce the JPEG. This makes these DNG files much more convenient for later "by hand" raw conversion with some of the aforementioned tools. Using exiftool shows all the metadata encoded into the DNG file:
+
The original image is generally saved in DNG (Adobe Digital Negative) format, which is compatible with most standard programs, such as dcraw or RawTherapee. The original image will be saved as a file of the same name with the .dng suffix, for example, if you run the above command, it will be saved as a test.dng, and generate a jpeg file at the same time. The DNG file contains metadata related to image acquisition, such as white balance data, ISP color matrix, etc. The following is the metadata encoding information displayed by the exiftool tool:<br />
 
<pre>
 
<pre>
File Name                       : test.dng
+
File Name : test.dng
Directory                       : .
+
Directory : .
File Size                       : 24 MB
+
File Size : 24MB
File Modification Date/Time     : 2021:08:17 16:36:18+01:00
+
File Modification Date/Time : 2021:08:17 16:36:18+01:00
File Access Date/Time           : 2021:08:17 16:36:18+01:00
+
File Access Date/Time : 2021:08:17 16:36:18+01:00
File Inode Change Date/Time     : 2021:08:17 16:36:18+01:00
+
File Inode Change Date/Time : 2021:08:17 16:36:18+01:00
File Permissions               : rw-r--r--
+
File Permissions : rw-r--r--
File Type                       : DNG
+
File Type : DNG
File Type Extension             : dng
+
File Type Extension : dng
MIME Type                       : image/x-adobe-dng
+
MIME Type : image/x-adobe-dng
Exif Byte Order                 : Little-endian (Intel, II)
+
Exif Byte Order : Little-endian (Intel, II)
Make                           : Raspberry Pi
+
Make : Raspberry Pi
Camera Model Name               : /base/soc/i2c0mux/[email protected]/[email protected]
+
Camera Model Name : /base/soc/i2c0mux/[email protected]/[email protected]
Orientation                     : Horizontal (normal)
+
Orientation : Horizontal (normal)
Software                       : libcamera-still
+
Software : libcamera-still
Subfile Type                   : Full-resolution Image
+
Subfile Type : Full-resolution Image
Image Width                     : 4056
+
Image Width : 4056
Image Height                   : 3040
+
Image Height : 3040
Bits Per Sample                 : 16
+
Bits Per Sample : 16
Compression                     : Uncompressed
+
Compression : Uncompressed
Photometric Interpretation     : Color Filter Array
+
Photometric Interpretation : Color Filter Array
Samples Per Pixel               : 1
+
Samples Per Pixel : 1
Planar Configuration           : Chunky
+
Planar Configuration : Chunky
CFA Repeat Pattern Dim         : 2 2
+
CFA Repeat Pattern Dim : 2 2
CFA Pattern 2                   : 2 1 1 0
+
CFA Pattern 2 : 2 1 1 0
Black Level Repeat Dim         : 2 2
+
Black Level Repeat Dim : 2 2
Black Level                     : 256 256 256 256
+
Black Level: 256 256 256 256
White Level                     : 4095
+
White Level : 4095
DNG Version                     : 1.1.0.0
+
DNG Version : 1.1.0.0
DNG Backward Version           : 1.0.0.0
+
DNG Backward Version : 1.0.0.0
Unique Camera Model             : /base/soc/i2c0mux/[email protected]/[email protected]
+
Unique Camera Model : /base/soc/i2c0mux/[email protected]/[email protected]
Color Matrix 1                 : 0.8545269369 -0.2382823821 -0.09044229197 -0.1890484985 1.063961506 0.1062747385 -0.01334283455 0.1440163847 0.2593136724
+
Color Matrix 1 : 0.8545269369 -0.2382823821 -0.09044229197 -0.1890484985 1.063961506 0.1062747385 -0.01334283455 0.1440163847 0.2593136724
As Shot Neutral                 : 0.4754476844 1 0.413686484
+
As Shot Neutral : 0.4754476844 1 0.413686484
Calibration Illuminant 1       : D65
+
Calibration Illuminant 1: D65
Strip Offsets                   : 0
+
Strip Offsets : 0
Strip Byte Counts               : 0
+
Strip Byte Counts : 0
Exposure Time                   : 1/20
+
Exposure Time : 1/20
ISO                             : 400
+
ISO : 400
CFA Pattern                     : [Blue,Green][Green,Red]
+
CFA Pattern : [Blue,Green][Green,Red]
Image Size                     : 4056x3040
+
Image Size : 4056x3040
Megapixels                     : 12.3
+
Megapixels : 12.3
Shutter Speed                   : 1/20
+
Shutter Speed ​​: 1/20
 
</pre>
 
</pre>
====Very long exposures====
+
====Long exposure====
To capture very long exposure images, we need to be careful to disable the AEC/AGC and AWB because these algorithms will otherwise force the user to wait for a number of frames while they converge. The way to disable them is to supply explicit values. Additionally, the entire preview phase of the capture can be skipped with the --immediate option.<br />
+
If we want to take a super long exposure picture, we need to disable AEC/AGC and white balance, otherwise these algorithms will cause the picture to wait for a lot of frame data when it converges. Disabling these algorithms requires another explicit value to be set. Additionally, the user can skip the preview process with the --immediate setting. <br />
Capature image and set the exposure time to 100s.
+
Here is the instruction to take an image with an exposure of 100 seconds:<br />
 
<pre>
 
<pre>
 
libcamera-still -o long_exposure.jpg --shutter 100000000 --gain 1 --awbgains 1,1 --immediate
 
libcamera-still -o long_exposure.jpg --shutter 100000000 --gain 1 --awbgains 1,1 --immediate
 
</pre>
 
</pre>
The maximum exposure times of the three official Raspberry Pi cameras are given in the table below.
+
Remarks: Reference table for the longest exposure time of several official cameras.<br />
{|class="wikitable"
+
{| class="wikitable"
! Module !! Max exposure (seconds)
+
! Module !! Maximum exposure time (s)
 
|-
 
|-
| OV5647 || 6
+
|V1(OV5647) || 6
 
|-
 
|-
| IMX219 || 10
+
|V2(IMX219) || 10
 
|-
 
|-
| IMX417 || 230
+
|HQ(IMX477) || 230
 
|}
 
|}
  
===libcamera-vid===
+
==='''libcamera-vid'''===
libcamera-vid is the video capture application. By default, it uses the Raspberry Pi’s hardware H.264 encoder. It will display a preview window and write the encoded bitstream to the specified output. <br />
+
libcamera-vid is a video recording program that uses the Raspberry Pi hardware H.264 encoder by default. After the program runs, a preview window will be displayed on the screen, and the bitstream encoding will be output to the specified file. For example, record a 10s video.
For example, write a 10s video to file:
 
 
<pre>
 
<pre>
 
libcamera-vid -t 10000 -o test.h264
 
libcamera-vid -t 10000 -o test.h264
 
</pre>
 
</pre>
You can use vlc to play the file:
+
If you want to view the video, you can use vlc to play it
 
<pre>
 
<pre>
 
vlc test.h264
 
vlc test.h264
 
</pre>
 
</pre>
Note that this is an unpackaged video bitstream, it is not wrapped in any kind of container format (such as an mp4 file). The --save-pts option can be used to output frame timestamps so that the bitstream can subsequently be converted into an appropriate format
+
Note: The recorded video stream is unpackaged. Users can use --save-pts to set the output timestamp to facilitate subsequent conversion of the bit stream to other video formats.
 
<pre>
 
<pre>
 
libcamera-vid -o test.h264 --save-pts timestamps.txt
 
libcamera-vid -o test.h264 --save-pts timestamps.txt
 
</pre>
 
</pre>
For outputing mkv file:
+
If you want to output the mkv file, you can use the following command:
 
<pre>
 
<pre>
 
mkvmerge -o test.mkv --timecodes 0:timestamps.txt test.h264
 
mkvmerge -o test.mkv --timecodes 0:timestamps.txt test.h264
 
</pre>
 
</pre>
====Encoders====
+
====Encoder====
There is support for motion JPEG, and also for uncompressed and unformatted YUV420
+
Raspberry Pi supports JPEG format and YUV420 without compression and format:
 
<pre>
 
<pre>
 
libcamera-vid -t 10000 --codec mjpeg -o test.mjpeg
 
libcamera-vid -t 10000 --codec mjpeg -o test.mjpeg
 
libcamera-vid -t 10000 --codec yuv420 -o test.data
 
libcamera-vid -t 10000 --codec yuv420 -o test.data
 
</pre>
 
</pre>
The --codec parameter determines the output format, not the extension of the output file. <br />
+
The --codec option sets the output format, not the output file extension. <br />
The --segment parameter breaks output files up into chunks of the segment size (given in milliseconds). This is quite handy for breaking a motion JPEG stream up into individual JPEG files by specifying very short (1 millisecond) segments
+
Use the --segment parameter to split the output file into segments (unit is ms), which is suitable for JPEG files that need to split the JPEG video stream into separate short (about 1ms) JPEG files.
 
<pre>
 
<pre>
 
libcamera-vid -t 10000 --codec mjpeg --segment 1 -o test%05d.jpeg
 
libcamera-vid -t 10000 --codec mjpeg --segment 1 -o test%05d.jpeg
 
</pre>
 
</pre>
  
===libcamera-raw===
+
==='''libcamera-raw'''===
libcamera-raw is like a video recording application except that it records raw Bayer frames directly from the sensor. It does not show a preview window. For a 2 second raw clip use
+
Libcamera-raw is similar to a video recording program. In different places, libcamera-raw records the Bayer format data output by the direct sensor, that is, the original image data. Libcamera-raw doesn't show a preview window. For example, record a 2-second clip of raw data.
 
<pre>
 
<pre>
 
libcamera-raw -t 2000 -o test.raw
 
libcamera-raw -t 2000 -o test.raw
 
</pre>
 
</pre>
The raw frames are dumped with no formatting information at all, one directly after another. The application prints the pixel format and image dimensions to the terminal window so that the user can know how to interpret the pixel data.<br />
+
The program will directly dump the original frame without format information, the program will directly print the pixel format and image size on the terminal, and the user can view the pixel data according to the output data. <br />
By default the raw frames are saved in a single (potentially very large) file. As we saw previously, the --segement option can be used conveniently to direct each to a separate file.
+
By default, the program will save the original frame as a file, the file is usually large, and the user can divide the file by the --segement parameter.
 
<pre>
 
<pre>
 
libcamera-raw -t 2000 --segment 1 -o test%05d.raw
 
libcamera-raw -t 2000 --segment 1 -o test%05d.raw
 
</pre>
 
</pre>
In good conditions (using a fast SSD) libcamera-raw can get close to writing 12MP HQ camera frames (18MB of data each) to disk at 10 frames per second. It writes the raw frames with no formatting in order to achieve these speeds; it has no capability to save them as DNG files (like libcamera-still). If you want to be sure not to drop frames you could reduce the framerate slightly using the --framerate option, for example.
+
If the memory is large (such as using SSD), libcamera-raw can write the official HQ Camera data (about 18MB per frame) to the hard disk at a speed of about 10 frames per second. In order to achieve this speed, the program writes the unformatted raw frames, there is no way to save them as DNG files like libcamera-still does. If you want to ensure that there are no dropped frames, you can use --framerate to reduce the frame rate.
 
<pre>
 
<pre>
 
libcamera-raw -t 5000 --width 4056 --height 3040 -o test.raw --framerate 8
 
libcamera-raw -t 5000 --width 4056 --height 3040 -o test.raw --framerate 8
 
</pre>
 
</pre>
===Common Command Line Options===
+
 
 +
==='''Common command setting options'''===
 +
Common command setting options apply to all libcamera commands:
 +
<pre>
 +
--help, -h
 +
</pre>
 +
Print program help information, you can print the available setting options for each program command, and then exit. <br />
 +
 
 +
<pre>
 +
--version
 +
</pre>
 +
Print software version, print the software version of libcamera and libcamera-app, then exit.<br />
 +
 
 +
<pre>
 +
--timeout, -t
 +
</pre>
 +
The "-t" option sets the running time of the libcamera program. If the video recording command is run, the timeout option sets the recording duration. If the image capture command is run, the timeout sets the preview time before the image is captured and output. <br />
 +
If the timeout is not set when running the libcamera program, the default timeout value is 5000 (5 seconds). If the timeout is set to 0, the program will continue to run. <br />
 +
Example: <font style="color:grey; font-style:italic;">libcamera-hello -t 0</font>
 +
 
 +
<pre>
 +
--preview, -p
 +
</pre>
 +
"-p" sets the size and position of the preview window (the qualified settings are valid in both X and DRM version windows), and the format is --preview <x. y, w, h> where "x, y" sets the preview window coordinate, "w" and "h" set the width and length of the preview window.<br />
 +
The settings of the preview serial port will not affect the resolution and aspect ratio of the camera image preview. The program will scale the preview image to display in the preview window and adapt it according to the original image aspect ratio. <br />
 +
Example: <font style="color:grey; font-style:italic">libcamera-hello -p 100,100,500,500</font>
 +
<pre>
 +
--fullscreen, -f
 +
</pre>
 +
The "-f" option sets the preview window full screen, the preview window, and border in full-screen mode. Like "-p", it does not affect the resolution and aspect ratio, and will automatically adapt. <br />
 +
Example: <font style="color:grey; font-style:italic">libcamera-still -f -o test.jpg</font>
 +
 
 +
<pre>
 +
--qt-preview
 +
</pre>
 +
Using the preview window based on the QT framework, this setting is not recommended under normal circumstances, because the preview program will not use zero-copy buffer sharing and GPU acceleration, which will occupy more resources. The QT preview window supports X forwarding (the default preview program does not).<br />
 +
The Qt preview serial port does not support the "--fullscreen" setting option. If the user wants to use the Qt preview, it is recommended to keep a small preview window to avoid excessive resource usage and affecting the normal operation of the system. <br />
 +
Example: <font style="color:grey; font-style:italic">libcamera-hello --qt-preview</font>
 +
 
 +
<pre>
 +
--nopreview, -n
 +
</pre>
 +
Images are not previewed. This setting will turn off the image preview function.<br />
 +
Example: <font style="color:grey; font-style:italic">libcamera-hello -n</font>
 +
 
 +
<pre>
 +
--info-text
 +
</pre>
 +
Set the title and information display of the preview window (only available in the X graphics window) using the format --info-text <string>. When calling this option, there are multiple parameters that can be set, and the parameters are usually called in the % command format. The program will call the corresponding value in the graphics metadata according to the instruction. <br />
 +
If no window info is specified, the default --info-text is set to <font style="color:grey; font-style:italic"> "#%frame (%fps fps) exp %exp ag %ag dg %dg" </font> <br />
 +
Example: <font style="color:grey; font-style:italic">libcamera-hello --info-test "Focus measure: %focus</font>
 +
Available parameters:<br />
 
{|class="wikitable"
 
{|class="wikitable"
! Option !! Option (abbreviate) !! Description
+
! Instructions !! Instructions
|-
 
| --help
 
| -h
 
| Print help information for the application
 
|-
 
| --version
 
|
 
| Print out a software version number
 
|-
 
| --list-cameras
 
|
 
| List the cameras available for use
 
|-
 
| --camera
 
|
 
| Selects which camera to use <index>
 
|-
 
| --config
 
| -c
 
| Read options from the given file <filename>
 
|-
 
| --timeout
 
| -t
 
| Delay before application stops automatically <milliseconds>
 
|-
 
| --preview
 
| -p
 
| Preview window settings <x,y,w,h>
 
|-
 
| --fullscreen
 
| -f
 
| Fullscreen preview mode
 
|-
 
| --qt-preview
 
|
 
| Use Qt-based preview window
 
|-
 
| --nopreview
 
|
 
| Set window title bar text <string>
 
|-
 
| --width
 
|
 
| Capture image width <width>
 
|-
 
| --height
 
|
 
| Capture image height <height>
 
|-
 
| --viewfinder-width
 
|
 
| Capture image width <width>
 
|-
 
| --viewfinder-height
 
|
 
| Capture image height <height>
 
|-
 
| --rawfull
 
|
 
| Force sensor to capture in full resolution mode
 
|-
 
| --mode
 
|
 
| Specify sensor mode, given as <width>:<height>:<bit-depth>:<packing>
 
|-
 
| --viewfinder-mode
 
|
 
| Specify sensor mode, given as <width>:<height>:<bit-depth>:<packing>
 
|-
 
| --lores-width
 
|
 
| Low resolution image width <width>
 
|-
 
| --lores-height
 
|
 
|Low resolution image height <height>
 
|-
 
| --hflip <br /> --vflip <br /> --rotation
 
|
 
| Read out with horizontal mirror <br />Read out with vertical flip <br /> Use hflip and vflip to create the given rotation <angle>
 
|-
 
| --roi
 
|
 
| Select a crop (region of interest) from the camera <x,y,w,h>
 
|-
 
| --sharpness
 
|
 
| Set image sharpness <number>
 
|-
 
| --contrast
 
|
 
| Set image contrast <number>
 
|-
 
| --brightness
 
|
 
| Set image brightness <number>
 
|-
 
| --saturation
 
|
 
| Set image colour saturation <number>
 
|-
 
| --ev
 
|
 
| Set EV compensation <number>
 
|-
 
| --shutter
 
|
 
| Set the exposure time in microseconds <number>
 
|-
 
| --gain <br />--analoggain
 
|
 
| Sets the combined analogue and digital gains <number> <br />Synonym for --gain
 
|-
 
| --metering
 
|
 
| Set the metering mode <string>
 
 
|-
 
|-
| --exposure
+
| %frame || frame sequence number
|
 
| Set the exposure profile <string>
 
 
|-
 
|-
| --awb
+
| %fps || Instantaneous frame rate
|
 
| Set the AWB mode <string>
 
 
|-
 
|-
| --awbgains
+
| %exp || The shutter speed when capturing the image, in ms
|
 
| Set fixed colour gains <number,number>
 
 
|-
 
|-
| --denoise
+
| %ag || Image analog gain controlled by the sensor chip
|
 
| Set the denoising mode <string>
 
 
|-
 
|-
| --tuning-file
+
| %dg || Image value gain controlled by ISP
|
 
| Specify the camera tuning to use <string>
 
 
|-
 
|-
| --output
+
| %rg || Gain of the red component of each pixel
| -o
 
| Output file name <string>
 
 
|-
 
|-
| --wrap
+
| %bg || The gain of the blue component of each pixel
|
 
| Wrap output file counter at <number>
 
 
|-
 
|-
| --flush
+
| %focus || The corner measurement of the image, the larger the value, the clearer the image
|
 
| Flush output files immediately
 
 
|}
 
|}
  
; Parameter for --info-text option
+
<pre>
 +
--width
 +
--height
 +
</pre>
 +
These two parameters set the width and height of the image, respectively. For libcamera-still, libcamera-jpeg and libcamera-vid commands, these two parameters can set the resolution of the output image/video. <br />
 +
If the libcamera-raw command is used, these two parameters affect the size of the obtained metadata frame. The camera has a 2 x 2 block reading mode. If the set resolution is smaller than the split mode, the camera will obtain the metadata frame according to the 2 x 2 block size. <br />
 +
libcamera-hello cannot specify the resolution.<br />
 +
Example: <br />
 +
<font style="color:grey; font-style:italic">libcamera-vid -o test.h264 --width 1920 --height 1080</font> Record 1080p video <br />
 +
<font style="color:grey; font-style:italic">libcamera-still -r -o test.jpg --width 2028 --height 1520</font> Takes a 2028 x 1520 JPEG image. <br />
 +
 
 +
<pre>
 +
--viewfinder-width
 +
--viewfinder-height
 +
</pre>
 +
This setting option is also used to set the resolution of the image, the difference is only the image size of the preview. It does not affect the final output image or video resolution. The size of the preview image will not affect the size of the preview window and will be adapted according to the window. <br />
 +
Example: <font style="color:grey; font-style:italic"> libcamera-hello --viewfinder-width 640 --viewfinder-height 480 </font>
 +
 
 +
<pre>
 +
--rawfull
 +
</pre>
 +
This setting forces the sensor to use the --width and --height settings to output still images and video in full resolution read mode. This setting libcamera-hello has no effect. <br />
 +
With this setting, the framerate is sacrificed. In full resolution mode, frame reading will be slower. <br />
 +
Example: <font style="color:grey; font-style:italic">libcamera-raw -t 2000 --segment 1 --rawfull -o test%03d.raw</font> The example command captures multiple full resolution images Metadata frame in rate mode. If you are using HQ camera. The size of each frame is 18MB, and if --rawfull is not set, the HQ camera defaults to 2 x 2 mode, and the data size of each frame is only 4.5MB.<br />
 +
 
 +
<pre>
 +
--lores-width
 +
--lores-height
 +
</pre>
 +
These two options set low-resolution images. The low-resolution data stream compresses the image, causing the aspect ratio of the image to change. When using libcamera-vid to record video, if a low resolution is set, functions such as color denoising will be disabled. <br />
 +
Example: <font style="color:grey; font-style:italic">libcamera-hello --lores-width 224 --lores-height 224 </font> Note that low resolution settings are often used in conjunction with image postprocessing , otherwise it has little effect.
 +
 
 +
<pre>
 +
--hflip #Flip the image horizontally
 +
--vflip #Flip the image vertically
 +
--rotation #Flip the image horizontally or vertically according to the given angle <angle>
 +
</pre>
 +
These three options are used to flip the image. The parameters of --rotation currently only support 0 and 180, which are actually equivalent to --hflip and --vflip.<br />
 +
Example: <font style="color:grey; font-style:italic">libcamera-hello --vflip --hflip</font>
 +
 
 +
<pre>
 +
--roi #crop image <x, y, w, h>
 +
</pre>
 +
"--roi" allows the user to crop the image area they want according to the coordinates from the complete image provided by the sensor, that is, digital scaling, pay attention to the coordinate value if it is in the valid range. For example --roi 0, 0, 1, 1 is an invalid instruction. <br />
 +
Example: <font style="color:grey; font-style:italic">libcamera-hello --roi 0.25,0.25,0.5,0.5 </font> <br />The example command will crop 1/4 of the image from the center of the image.
 +
 
 +
<pre>
 +
--sharpness #Set the sharpness of the image <number>
 +
</pre>
 +
Adjust the sharpness of the image by the value of <number>. If set to 0, no sharpening is applied. If you set a value above 1.0, an extra sharpening amount will be used. <br/>
 +
Example: <font style="color:grey; font-style:italic">libcamera-still -o test.jpg --sharpness 2.0</font>
 +
 
 +
<pre>
 +
--contrast #Set image contrast <number>
 +
</pre>
 +
Example: <font style="color:grey; font-style:italic">libcamera-still -o test.jpg --contrast 1.5</font>
 +
 
 +
<pre>
 +
--brightness #Set image brightness <number>
 +
</pre>
 +
The setting range is -1.0 ~ 1.0 <br />
 +
Example: <font style="color:grey; font-style:italic"> libcamera-still -o test.jpg --brightness 0.2 </font>
 +
 
 +
<pre>
 +
--saturation #Set image color saturation <number>
 +
</pre>
 +
Example: <font style="color:grey; font-style:italic">libcamera-still -o test.jpg --saturation 0.8</font>
 +
 
 +
<pre>
 +
--ev #Set EV compensation <number>
 +
</pre>
 +
Set the EV compensation of the image in aperture units, the setting range is -10 ~ 10, the default value is 0. The program works by improving the target method of the AEC/AGC algorithm. <br />
 +
Example: <font style="color:grey; font-style:italic">libcamera-still -o test.jpg --ev 0.3</font>
 +
 
 +
<pre>
 +
--shutter #Set the exposure time, the unit is ms <number>
 +
</pre>
 +
Note: If the frame rate of the camera is too fast, it may not work according to the set shutter time. If this happens, you can try to use --framerate to reduce the frame rate. <br />
 +
Example: <font style="color:grey; font-style:italic">libcamera-hello --shutter 30000 </font>
 +
 
 +
<pre>
 +
--gain #Set gain value (combination of numerical gain and analog gain) <number>
 +
--analoggain #--gain synonym
 +
</pre>
 +
--analoggain is the same as --gain, the use of analoggain is only for compatibility with raspicam programs.
 +
 
 +
<pre>
 +
--metering #Set metering mode <string>
 +
</pre>
 +
Set the metering mode of the AEC/AGC algorithm, the available parameters are: <br />
 +
*centre - Center metering (default)
 +
*spot - spot metering
 +
*average - average or full frame metering
 +
*custom - custom metering mode, can be set via tuning file
 +
Example: <font style="color:grey; font-style:italic">libcamera-still -o test.jpg --metering spot</font>
 +
 
 +
<pre>
 +
--exposure #set exposure profile <string>
 +
</pre>
 +
The exposure mode can be set to normal or sport. The report profile for these two modes does not affect the overall exposure of the image, but in the case of sports mode, the program will shorten the exposure time and increase the justice to achieve the same exposure effect. <br />
 +
Example: <font style="color:grey; font-style:italic">libcamera-still -o test.jpg --exposure sport </font>
 +
 
 +
<pre>
 +
--awb #Set white balance mode <string>
 +
</pre>
 +
Available white balance modes:
 
{|class="wikitable"
 
{|class="wikitable"
!Directive !! Substitution
+
! Mode !! Color temperature
 
|-
 
|-
|%frame || The sequence number of the frame
+
| auto || 2500K ~ 8000K
 
|-
 
|-
|%fps || The instantaneous frame rate
+
|incadescent || 2500K ~ 3000K
 
|-
 
|-
|%exp || The shutter speed used to capture the image, in microseconds
+
|tungsten || 3000K ~3500K
 
|-
 
|-
|%ag || The analogue gain applied to the image in the sensor
+
|fluorescent || 4000K ~ 4700K
 
|-
 
|-
|%dg || The digital gain applied to the image by the ISP
+
|indoor || 3000K ~ 5000K
 
|-
 
|-
|%rg || The gain applied to the red component of each pixel
+
|daylight|| 5500K ~ 6500K
 
|-
 
|-
|%bg || The gain applied to the blue component of each pixel
+
|cloudy|| 7000K ~ 8500K
 
|-
 
|-
|%focus || The focus metric for the image, where a larger value implies a sharper image
+
|custom|| Custom range, set via tuning file
 
|}
 
|}
 +
Example: <font style="color:grey; font-style:italic"> libamera-still -o test.jpg --awb tungsten </font>
 +
 +
<pre>
 +
--awbgains #Set a fixed color gain <number,number>
 +
</pre>
 +
Set red and blue gain. <br />
 +
Example: <font style="color:grey; font-style:italic">libcamera-still -o test.jpg --awbgains 1.5, 2.0</font>
  
; Parameter for --awb option
+
<pre>
{|class="wikitable"
+
--denoise #Set denoising mode <string>
! Mode name !! Colour temperature
+
</pre>
|-
+
Supported denoising modes:
| auto || 2500K to 8000K
+
*auto - default mode, use standard spatial denoising, if it is video, it will use fast color noise reduction and use high-quality color noise reduction when taking still pictures. The preview image will not use any color denoising.
|-
+
*off - turn off spatial denoising and color denoising
| incandescent || 2500K to 3000K
+
*cdn_off - turn off color denoising
|-
+
*cdn_fast - use fast color denoising
| tungsten || 3000K to 3500K
+
*cdn_hq - use high-quality color denoising, not suitable for video recording.
|-
+
Example: <font style="color:grey; font-style:italic">libcamera-vid -o test.h264 --denoise cdn_off</font>
| fluorescent || 4000K to 4700K
+
 
|-
+
<pre>
| indoor || 3000K to 5000K
+
--tuning-file #Specify camera tuning file <string>
|-
+
</pre>
| daylight || 5500K to 5400K
+
For more instructions on tuning files, you can refer to [https://datasheets.raspberrypi.com/camera/raspberry-pi-camera-guide.pdf official tutorial] <br />
|-
+
Example: <font style="color:grey; font-style:italic">libcamera-hello --tuning-file ~/my~camera-tuning.json </font>
| cloudy || 7000K to 8500K
+
 
|}
+
<pre>
 +
--output, -o #output filename <string>
 +
</pre>
 +
Set the filename of the output image or video. In addition to setting the file name, you can also specify the output udp or tcp server address to output the image to the server. If you are interested, you can check the relevant setting instructions of the subsequent tcp and udp. <br />
 +
Example: <font style="color:grey; font-style:italic">libcamera-vid -t 100000 -o test.h264</font>
 +
 
 +
<pre>
 +
--wrap #Wrap the output file counter <number>
 +
</pre>
 +
Example: <font style="color:grey; font-style:italic">libcamera-vid -t 0 --codec mjpeg --segment 1 --wrap 100 -o image%d.jpg </font>
  
===Still Command Line Options===
+
<pre>
{|class="wikitable"
+
--flush # Flush the output file immediately
! Option !! Option (abbreviate) !! Description
+
</pre>
|-
+
--flush will immediately update each frame of the image to the hard disk at the same time as it is written, reducing latency. <br />
| --quality
+
Example: <font style="color:grey; font-style:italic">libcamera-vid -t 10000 --flush -o test.h264</font>
| -q
 
| JPEG quality <number>
 
|-
 
| --exif
 
| -x
 
| Add extra EXIF tags <string>
 
|-
 
| --timelapse
 
|
 
| Time interval between timelapse captures <milliseconds>
 
|-
 
| --framestart
 
|
 
| The starting value for the frame counter <number>
 
|-
 
| --datetime
 
|
 
| Use date format for the output file names
 
|-
 
| --timestamp
 
|
 
| Use system timestamps for the output file names
 
|-
 
| --restart
 
|
 
| Set the JPEG restart interval <number>
 
|-
 
| --keypress
 
| -k
 
| Capture image when Enter pressed
 
|-
 
| --signal
 
| -s
 
| Capture image when SIGUSR1 received
 
|-
 
| --thumb
 
|
 
| Set thumbnail parameters <w:h:q> or none
 
|-
 
| --encoding
 
| -e
 
| Set the still image codec <string>
 
*jpg - JPEG (the default)
 
*png - PNG format
 
*bmp - BMP format
 
*rgb - binary dump of uncompressed RGB pixels
 
*yuv420 - binary dump of uncompressed YUV420 pixels.
 
|-
 
| --raw
 
| -r
 
| Save the raw file
 
|-
 
| --latest
 
|
 
| Make a symbolic link to the latest file saved <string>
 
|}
 
  
===Video Command Line Options===
+
===Still photo shooting setting parameters===
{|class="wikitable"
+
<pre>
! Option !! Option (abbreviate) !! Description
+
--qiality, -q #Set JPEG image quality <0 ~ 100>
|-
+
--exif, -x #Add extra EXIF flags
| --quality
+
--timelapse #Time interval of time-lapse photography, the unit is ms
| -q
+
--framestart #start value of frame count
| JPEG quality <number>
+
--datetime #name output file with date format
|-
+
--timestamp #name the output file with the system timestamp
| --bitrate
+
-- restart #Set the JPEG restart interval
| -b
+
--keypress, -k # Set the enter button photo mode
| H.264 bitrate <number>
+
--signal, -s #Set the signal to trigger the photo
|-
+
--thumb #Set thumbnail parameters <w:h:q>
| --intra
+
--ebcoding, -e #Set the image encoding type. jpg/png/bmp/rgb/yuv420
| -g
+
--raw, -r #Save raw image
| Intra-frame period (H.264 only) <number>
+
--latest #Associate symbols to the latest saved file
|-
+
</pre>
| --profile
+
===Video recording image setting parameters===
|
+
<pre>
| H.264 profile <string>
+
--quality, -q # Set JPEG commands <0 - 100>
|-
+
--bitrate, -b # Set H.264 bitrate
| --level
+
--intra, -g #Set the internal frame period (only supports H.264)
|
+
--profile #Set H.264 configuration
| H.264 level <string>
+
--level #Set H.264 level
|-
+
--codec #Set encoding type h264 / mjpeg / yuv420
| --codec
+
--keypress, -k #Set carriage return to pause and record
|
+
--signal, -s #Set signal pause and record
| Encoder to be used <string>
+
--initial #Start the program in the recording or paused state
*h264 - use H.264 encoder (the default)
+
--split #Split video and save to another file
*mjpeg - use MJPEG encoder
+
--segment #Split video into multiple video segments
*yuv420 - output uncompressed YUV420 frames
+
--circular #Write video to circular buffer
|-
+
--inline #Write header in each I frame (H.264 only)
| --keypress
+
--listen #Wait for a TCP connection
| -k
+
</pre>
| Toggle between recording and pausing
 
|-
 
| --signal
 
| -s
 
| Toggle between recording and pausing when SIGUSR1 received
 
|-
 
| --initial
 
|
 
| Start the application in the recording or paused state <string>
 
|-
 
| --split
 
|
 
| Split multiple recordings into separate files
 
|-
 
| --segment
 
|
 
| Write the video recording into multiple segments <number>
 
|-
 
| --circular
 
|
 
| Write the video recording into a circular buffer of the given <size>
 
|-
 
| --inline
 
|
 
| Write sequence header in every I frame (H.264 only)
 
|-
 
| --listen
 
|
 
| Wait for an incoming TCP connection
 
|-
 
| --frames
 
|
 
| Record exactly this many frames <number>
 
|}
 
  
For more information about the libcamera, please refer to [https://www.raspberrypi.com/documentation/accessories/camera.html Official Document]
+
*For more camera setup instructions, please refer to the official documentation [https://www.raspberrypi.com/documentation/accessories/camera.html#libcamera-and-libcamera-apps Official camera documentation]

Latest revision as of 09:53, 2 September 2022

User Guides for libcamera/libcamera

Introduction

After the Bullseye version of the Raspberry Pi image, the underlying Raspberry Pi driver was switched from Raspicam to libcamera. Libcamera is an open-source software stack (will be called driver later, which is easy to understand), which is convenient for third-party porting and development of their own camera drivers. As of 2021-12-20, there are still many bugs in libcamera, and the current libcamera does not support python, so the Raspberry Pi official still provides a method for installing and downloading Raspicam. For users who are difficult to switch to libcamera but need to use the latest system, please directly refer to the Raspicam instructions.

Call Camera

The libcamera software stack provides six instructions for users to preview and test the camera interface.

libcamera-hello

This is a simple "hello world" program that previews the camera and displays the camera image on the screen.

Example

libcamera-hello

This command will preview the camera on the screen for about 5 seconds. The user can use the "-t <duration>" parameter to set the preview time, where the unit of <duration> is milliseconds. If it is set to 0, it will keep previewing all the time. For example:

libcamerahello -t 0

Tune File

The libcamera driver of the Raspberry Pi will call a tuning file for different camera modules. The tuning file provides various parameters. When calling the camera, libcamera will call the parameters in the tuning file, and process the image in combination with the algorithm. The final output is the preview screen. Since the libcamera driver can only automatically receive the signal of the chip, the final display effect of the camera will also be affected by the entire module. The use of the tuning file is to flexibly handle the cameras of different modules and adjust to improve the image quality.
If the output image of the camera is not ideal after using the default tuning file, the user can adjust the image by calling the custom tuning file. For example, if you are using the official NOIR version of the camera, the NOIR camera may require different white balance parameters compared with the regular Raspberry Pi Camera V2. In this case, you can switch by calling the tuning file.

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

Users can copy the default tuning files and modify them according to their needs.
Note: The use of tuning files is applicable to other libcamera commands, and will not be introduced in subsequent commands.

Preview Window

Most libcamera commands will display a preview window on the screen. Users can customize the title information of the preview window through the --info-text parameter, and can also call some camera parameters through %directives and display them on the window.
For example, if you use HQ Camera: You can display the focal length of the camera on the window through --info-txe "%focus".

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

Note: For more information on parameter settings, please refer to the following chapters.

libcamera-jpeg

libcamera-jpeg is a simple still picture shooting program, different from the complex functions of libcamera-still, libcamera-jpeg code is more concise, and has many of the same functions to complete picture shooting.

Take JPEG image of full pixel

libcamera-jpeg -o test.jpg

This shooting command will display a preview serial port for about 5 seconds, and then shoot a full-pixel JPEG image and save it as test.jpg.
Users can set the preview time through the -t parameter, and can set the resolution of the captured image through --width and --height. E.g:

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

Exposure control

All libcamera commands allow the user to set the shutter time and gain themselves, such as:

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

This command will capture an image with 20ms exposure and camera gain set to 1.5x. The gain parameter set will first set the analog gain parameter inside the photosensitive chip. If the set gain exceeds the maximum built-in analog gain value of the driver, the maximum analog gain of the chip will be set first, and then the remaining gain multiples will be used as numbers. gain to take effect.
Remarks: The digital gain is realized by ISP (image signal processing), not directly adjusting the built-in register of the chip. Under normal circumstances, the default digital gain is close to 1.0, unless there are the following three situations.

  1. Overall gain parameter requirements, that is, when the analog gain cannot meet the set gain parameter requirements, digital gain will be needed for compensation.
  2. One of the color gains is less than 1 (the color gain is achieved by digital gain), in this case, the final gain is stabilized at 1/min(red_gain, blue_gain), that is, a uniform number is actually applied gain, and is the gain value for one of the color channels (not the green channel).
  3. AEC/AGC was modified. If there is a change in AEC/AGC, the numerical gain will also change to a certain extent, where does it come from to eliminate any fluctuations, but this change will be quickly restored to the "normal" value.

The Raspberry Pi's AEC/AGX algorithm allows the program to specify exposure compensation, which is to adjust the brightness of the image by setting the aperture value, 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

libcamera-still and libcamera-jpeg are very similar, the difference is that libcamera inherits more functions of raspistill. As before, the user can take a picture with the following command.

Test Command

libcamera-still -o test.jpg

Encoder

libcamea-still supports image files in different formats, can support png and bmp encoding, and also supports saving binary dumps of RGB or YUV pixels as files without encoding or in any image format. If you save RGB or YUV data directly, the program must understand the pixel arrangement of the file when reading such files.

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: The format of image saving is controlled by the -e parameter. If the -e parameter is not called, it will be saved in the format of the output file name by default.

Raw image capture

The raw image is the image output by the direct image sensor without any ISP or CPU processing. For color camera sensors, the output format of the raw image is generally Bayer. Note that the raw image is different from the bit-encoded RGB and YUV images we said earlier, and RGB and YUV are also ISP-processed images.
Instructions to take a raw image:

libcamera-still -r -o test.jpg

The original image is generally saved in DNG (Adobe Digital Negative) format, which is compatible with most standard programs, such as dcraw or RawTherapee. The original image will be saved as a file of the same name with the .dng suffix, for example, if you run the above command, it will be saved as a test.dng, and generate a jpeg file at the same time. The DNG file contains metadata related to image acquisition, such as white balance data, ISP color matrix, etc. The following is the metadata encoding information displayed by the exiftool tool:

File Name : test.dng
Directory : .
File Size : 24MB
File Modification Date/Time : 2021:08:17 16:36:18+01:00
File Access Date/Time : 2021:08:17 16:36:18+01:00
File Inode Change Date/Time : 2021:08:17 16:36:18+01:00
File Permissions : rw-r--r--
File Type : DNG
File Type Extension : dng
MIME Type : image/x-adobe-dng
Exif Byte Order : Little-endian (Intel, II)
Make : Raspberry Pi
Camera Model Name : /base/soc/i2c0mux/[email protected]/[email protected]
Orientation : Horizontal (normal)
Software : libcamera-still
Subfile Type : Full-resolution Image
Image Width : 4056
Image Height : 3040
Bits Per Sample : 16
Compression : Uncompressed
Photometric Interpretation : Color Filter Array
Samples Per Pixel : 1
Planar Configuration : Chunky
CFA Repeat Pattern Dim : 2 2
CFA Pattern 2 : 2 1 1 0
Black Level Repeat Dim : 2 2
Black Level: 256 256 256 256
White Level : 4095
DNG Version : 1.1.0.0
DNG Backward Version : 1.0.0.0
Unique Camera Model : /base/soc/i2c0mux/[email protected]/[email protected]
Color Matrix 1 : 0.8545269369 -0.2382823821 -0.09044229197 -0.1890484985 1.063961506 0.1062747385 -0.01334283455 0.1440163847 0.2593136724
As Shot Neutral : 0.4754476844 1 0.413686484
Calibration Illuminant 1: D65
Strip Offsets : 0
Strip Byte Counts : 0
Exposure Time : 1/20
ISO : 400
CFA Pattern : [Blue,Green][Green,Red]
Image Size : 4056x3040
Megapixels : 12.3
Shutter Speed ​​: 1/20

Long exposure

If we want to take a super long exposure picture, we need to disable AEC/AGC and white balance, otherwise these algorithms will cause the picture to wait for a lot of frame data when it converges. Disabling these algorithms requires another explicit value to be set. Additionally, the user can skip the preview process with the --immediate setting.
Here is the instruction to take an image with an exposure of 100 seconds:

libcamera-still -o long_exposure.jpg --shutter 100000000 --gain 1 --awbgains 1,1 --immediate

Remarks: Reference table for the longest exposure time of several official cameras.

Module Maximum exposure time (s)
V1(OV5647) 6
V2(IMX219) 10
HQ(IMX477) 230

libcamera-vid

libcamera-vid is a video recording program that uses the Raspberry Pi hardware H.264 encoder by default. After the program runs, a preview window will be displayed on the screen, and the bitstream encoding will be output to the specified file. For example, record a 10s video.

libcamera-vid -t 10000 -o test.h264

If you want to view the video, you can use vlc to play it

vlc test.h264

Note: The recorded video stream is unpackaged. Users can use --save-pts to set the output timestamp to facilitate subsequent conversion of the bit stream to other video formats.

libcamera-vid -o test.h264 --save-pts timestamps.txt

If you want to output the mkv file, you can use the following command:

mkvmerge -o test.mkv --timecodes 0:timestamps.txt test.h264

Encoder

Raspberry Pi supports JPEG format and YUV420 without compression and format:

libcamera-vid -t 10000 --codec mjpeg -o test.mjpeg
libcamera-vid -t 10000 --codec yuv420 -o test.data

The --codec option sets the output format, not the output file extension.
Use the --segment parameter to split the output file into segments (unit is ms), which is suitable for JPEG files that need to split the JPEG video stream into separate short (about 1ms) JPEG files.

libcamera-vid -t 10000 --codec mjpeg --segment 1 -o test%05d.jpeg

libcamera-raw

Libcamera-raw is similar to a video recording program. In different places, libcamera-raw records the Bayer format data output by the direct sensor, that is, the original image data. Libcamera-raw doesn't show a preview window. For example, record a 2-second clip of raw data.

libcamera-raw -t 2000 -o test.raw

The program will directly dump the original frame without format information, the program will directly print the pixel format and image size on the terminal, and the user can view the pixel data according to the output data.
By default, the program will save the original frame as a file, the file is usually large, and the user can divide the file by the --segement parameter.

libcamera-raw -t 2000 --segment 1 -o test%05d.raw

If the memory is large (such as using SSD), libcamera-raw can write the official HQ Camera data (about 18MB per frame) to the hard disk at a speed of about 10 frames per second. In order to achieve this speed, the program writes the unformatted raw frames, there is no way to save them as DNG files like libcamera-still does. If you want to ensure that there are no dropped frames, you can use --framerate to reduce the frame rate.

libcamera-raw -t 5000 --width 4056 --height 3040 -o test.raw --framerate 8

Common command setting options

Common command setting options apply to all libcamera commands:

--help, -h

Print program help information, you can print the available setting options for each program command, and then exit.

--version

Print software version, print the software version of libcamera and libcamera-app, then exit.

--timeout, -t

The "-t" option sets the running time of the libcamera program. If the video recording command is run, the timeout option sets the recording duration. If the image capture command is run, the timeout sets the preview time before the image is captured and output.
If the timeout is not set when running the libcamera program, the default timeout value is 5000 (5 seconds). If the timeout is set to 0, the program will continue to run.
Example: libcamera-hello -t 0

--preview, -p

"-p" sets the size and position of the preview window (the qualified settings are valid in both X and DRM version windows), and the format is --preview <x. y, w, h> where "x, y" sets the preview window coordinate, "w" and "h" set the width and length of the preview window.
The settings of the preview serial port will not affect the resolution and aspect ratio of the camera image preview. The program will scale the preview image to display in the preview window and adapt it according to the original image aspect ratio.
Example: libcamera-hello -p 100,100,500,500

--fullscreen, -f

The "-f" option sets the preview window full screen, the preview window, and border in full-screen mode. Like "-p", it does not affect the resolution and aspect ratio, and will automatically adapt.
Example: libcamera-still -f -o test.jpg

--qt-preview

Using the preview window based on the QT framework, this setting is not recommended under normal circumstances, because the preview program will not use zero-copy buffer sharing and GPU acceleration, which will occupy more resources. The QT preview window supports X forwarding (the default preview program does not).
The Qt preview serial port does not support the "--fullscreen" setting option. If the user wants to use the Qt preview, it is recommended to keep a small preview window to avoid excessive resource usage and affecting the normal operation of the system.
Example: libcamera-hello --qt-preview

--nopreview, -n

Images are not previewed. This setting will turn off the image preview function.
Example: libcamera-hello -n

--info-text

Set the title and information display of the preview window (only available in the X graphics window) using the format --info-text <string>. When calling this option, there are multiple parameters that can be set, and the parameters are usually called in the % command format. The program will call the corresponding value in the graphics metadata according to the instruction.
If no window info is specified, the default --info-text is set to "#%frame (%fps fps) exp %exp ag %ag dg %dg"
Example: libcamera-hello --info-test "Focus measure: %focus Available parameters:

Instructions Instructions
%frame frame sequence number
%fps Instantaneous frame rate
%exp The shutter speed when capturing the image, in ms
%ag Image analog gain controlled by the sensor chip
%dg Image value gain controlled by ISP
%rg Gain of the red component of each pixel
%bg The gain of the blue component of each pixel
%focus The corner measurement of the image, the larger the value, the clearer the image
--width
--height

These two parameters set the width and height of the image, respectively. For libcamera-still, libcamera-jpeg and libcamera-vid commands, these two parameters can set the resolution of the output image/video.
If the libcamera-raw command is used, these two parameters affect the size of the obtained metadata frame. The camera has a 2 x 2 block reading mode. If the set resolution is smaller than the split mode, the camera will obtain the metadata frame according to the 2 x 2 block size.
libcamera-hello cannot specify the resolution.
Example:
libcamera-vid -o test.h264 --width 1920 --height 1080 Record 1080p video
libcamera-still -r -o test.jpg --width 2028 --height 1520 Takes a 2028 x 1520 JPEG image.

--viewfinder-width
--viewfinder-height

This setting option is also used to set the resolution of the image, the difference is only the image size of the preview. It does not affect the final output image or video resolution. The size of the preview image will not affect the size of the preview window and will be adapted according to the window.
Example: libcamera-hello --viewfinder-width 640 --viewfinder-height 480

--rawfull

This setting forces the sensor to use the --width and --height settings to output still images and video in full resolution read mode. This setting libcamera-hello has no effect.
With this setting, the framerate is sacrificed. In full resolution mode, frame reading will be slower.
Example: libcamera-raw -t 2000 --segment 1 --rawfull -o test%03d.raw The example command captures multiple full resolution images Metadata frame in rate mode. If you are using HQ camera. The size of each frame is 18MB, and if --rawfull is not set, the HQ camera defaults to 2 x 2 mode, and the data size of each frame is only 4.5MB.

--lores-width
--lores-height

These two options set low-resolution images. The low-resolution data stream compresses the image, causing the aspect ratio of the image to change. When using libcamera-vid to record video, if a low resolution is set, functions such as color denoising will be disabled.
Example: libcamera-hello --lores-width 224 --lores-height 224 Note that low resolution settings are often used in conjunction with image postprocessing , otherwise it has little effect.

--hflip #Flip the image horizontally
--vflip #Flip the image vertically
--rotation #Flip the image horizontally or vertically according to the given angle <angle>

These three options are used to flip the image. The parameters of --rotation currently only support 0 and 180, which are actually equivalent to --hflip and --vflip.
Example: libcamera-hello --vflip --hflip

--roi #crop image <x, y, w, h>

"--roi" allows the user to crop the image area they want according to the coordinates from the complete image provided by the sensor, that is, digital scaling, pay attention to the coordinate value if it is in the valid range. For example --roi 0, 0, 1, 1 is an invalid instruction.
Example: libcamera-hello --roi 0.25,0.25,0.5,0.5
The example command will crop 1/4 of the image from the center of the image.

--sharpness #Set the sharpness of the image <number>

Adjust the sharpness of the image by the value of <number>. If set to 0, no sharpening is applied. If you set a value above 1.0, an extra sharpening amount will be used.
Example: libcamera-still -o test.jpg --sharpness 2.0

--contrast #Set image contrast <number>

Example: libcamera-still -o test.jpg --contrast 1.5

--brightness #Set image brightness <number>

The setting range is -1.0 ~ 1.0
Example: libcamera-still -o test.jpg --brightness 0.2

--saturation #Set image color saturation <number>

Example: libcamera-still -o test.jpg --saturation 0.8

--ev #Set EV compensation <number>

Set the EV compensation of the image in aperture units, the setting range is -10 ~ 10, the default value is 0. The program works by improving the target method of the AEC/AGC algorithm.
Example: libcamera-still -o test.jpg --ev 0.3

--shutter #Set the exposure time, the unit is ms <number>

Note: If the frame rate of the camera is too fast, it may not work according to the set shutter time. If this happens, you can try to use --framerate to reduce the frame rate.
Example: libcamera-hello --shutter 30000

--gain #Set gain value (combination of numerical gain and analog gain) <number>
--analoggain #--gain synonym

--analoggain is the same as --gain, the use of analoggain is only for compatibility with raspicam programs.

--metering #Set metering mode <string>

Set the metering mode of the AEC/AGC algorithm, the available parameters are:

  • centre - Center metering (default)
  • spot - spot metering
  • average - average or full frame metering
  • custom - custom metering mode, can be set via tuning file

Example: libcamera-still -o test.jpg --metering spot

--exposure #set exposure profile <string>

The exposure mode can be set to normal or sport. The report profile for these two modes does not affect the overall exposure of the image, but in the case of sports mode, the program will shorten the exposure time and increase the justice to achieve the same exposure effect.
Example: libcamera-still -o test.jpg --exposure sport

--awb #Set white balance mode <string>

Available white balance modes:

Mode Color temperature
auto 2500K ~ 8000K
incadescent 2500K ~ 3000K
tungsten 3000K ~3500K
fluorescent 4000K ~ 4700K
indoor 3000K ~ 5000K
daylight 5500K ~ 6500K
cloudy 7000K ~ 8500K
custom Custom range, set via tuning file

Example: libamera-still -o test.jpg --awb tungsten

--awbgains #Set a fixed color gain <number,number>

Set red and blue gain.
Example: libcamera-still -o test.jpg --awbgains 1.5, 2.0

--denoise #Set denoising mode <string>

Supported denoising modes:

  • auto - default mode, use standard spatial denoising, if it is video, it will use fast color noise reduction and use high-quality color noise reduction when taking still pictures. The preview image will not use any color denoising.
  • off - turn off spatial denoising and color denoising
  • cdn_off - turn off color denoising
  • cdn_fast - use fast color denoising
  • cdn_hq - use high-quality color denoising, not suitable for video recording.

Example: libcamera-vid -o test.h264 --denoise cdn_off

--tuning-file #Specify camera tuning file <string>

For more instructions on tuning files, you can refer to official tutorial
Example: libcamera-hello --tuning-file ~/my~camera-tuning.json

--output, -o #output filename <string>

Set the filename of the output image or video. In addition to setting the file name, you can also specify the output udp or tcp server address to output the image to the server. If you are interested, you can check the relevant setting instructions of the subsequent tcp and udp.
Example: libcamera-vid -t 100000 -o test.h264

--wrap #Wrap the output file counter <number>

Example: libcamera-vid -t 0 --codec mjpeg --segment 1 --wrap 100 -o image%d.jpg

--flush # Flush the output file immediately

--flush will immediately update each frame of the image to the hard disk at the same time as it is written, reducing latency.
Example: libcamera-vid -t 10000 --flush -o test.h264

Still photo shooting setting parameters

--qiality, -q #Set JPEG image quality <0 ~ 100>
--exif, -x #Add extra EXIF flags
--timelapse #Time interval of time-lapse photography, the unit is ms
--framestart #start value of frame count
--datetime #name output file with date format
--timestamp #name the output file with the system timestamp
-- restart #Set the JPEG restart interval
--keypress, -k # Set the enter button photo mode
--signal, -s #Set the signal to trigger the photo
--thumb #Set thumbnail parameters <w:h:q>
--ebcoding, -e #Set the image encoding type. jpg/png/bmp/rgb/yuv420
--raw, -r #Save raw image
--latest #Associate symbols to the latest saved file

Video recording image setting parameters

--quality, -q # Set JPEG commands <0 - 100>
--bitrate, -b # Set H.264 bitrate
--intra, -g #Set the internal frame period (only supports H.264)
--profile #Set H.264 configuration
--level #Set H.264 level
--codec #Set encoding type h264 / mjpeg / yuv420
--keypress, -k #Set carriage return to pause and record
--signal, -s #Set signal pause and record
--initial #Start the program in the recording or paused state
--split #Split video and save to another file
--segment #Split video into multiple video segments
--circular #Write video to circular buffer
--inline #Write header in each I frame (H.264 only)
--listen #Wait for a TCP connection