1. Overview[edit | edit source]
This article explains how to use the camera via the libcamera library and its various proposed interfaces to perform use-cases. This article first focuses on a brief description of libcamera and later describes some use-cases and how to achieve them using the interfaces and applications offered by libcamera.
2. Introduction to libcamera[edit | edit source]
"libcamera®[1] is an open source complex camera support library for Linux, Android and ChromeOS. The library interfaces with Linux kernel device drivers and provides an intuitive API to developers in order to simplify the complexity involved in capturing images from complex cameras on Linux systems."
libcamera embeds pipeline handlers and IPA (Image Processing Algorithm) modules in order to perform device-specific configuration/processing. Pipeline handlers are the abstraction layer for device-specific hardware configuration while the IPA modules provide functionality that the pipeline handler can use for image processing.
2.1. System overview[edit | edit source]
For the DCMIPP, a set of dcmipp pipeline handler and IPA modules are available, allowing to configure the pipeline for common use-cases and perform basic image processing.
libcamera can be used in several ways and it is easy to perform a simple camera capture:
- with the provided command line
camapplication (read cam application chapter for more details) - or with the GStreamer
libcamerasrcplugin to perform more complicated use-cases (read GStreamer plugin libcamerasrc chapter for more details)
libcamera introduces notion of StreamRole to define predefined ways an application intends to use a camera. Roles can be either Raw, StillImage, VideoRecording and ViewFinder. In DCMIPP, those roles are mapped to the following formats/resolutions:
- Raw: capture in raw bayer format (identical to the format sent by the sensor)
- ViewFinder: capture at resolution up to 1024x600 in RGB888 format
- VideoRecoding: capture at resolution up to 1920x1080 in NV12 format
- StillCapture: capture at sensor resolution in YUV420 format
3. cam application[edit | edit source]
libcamera provides a command line application named cam which allow to discover capabilities, capture (and optionally display) frames.
3.1. List available cameras[edit | edit source]
cam -l
Available cameras: 1: 'imx335' (/base/soc@0/bus@42080000/i2c@40130000/imx335@1a)
With this command, cam informs that one sensor called imx335 can be used and is numbered 1. The numbering is later on used using the -c argument.
3.2. Capture a single frame to disk in a viewfinder role mode[edit | edit source]
cam -c1 -C1 -s role=viewfinder -F/tmp/
Command above indicates to capture 1 frame using sensor 1, with predefined settings of viewfinder and store the captured frame into the folder /tmp
Using camera /base/soc@0/bus@42080000/i2c@40130000/imx335@1a as cam0 [1:14:11.744971750] [2993] INFO Camera camera.cpp:1183 configuring streams: (0) 1024x600-RGB888 cam0: Capture 1 frames 4451.846024 (0.00 fps) cam0-stream0 seq: 000000 bytesused: 1843200
Upon execution of this command, a file called frame-cam0-stream0-000000.bin is available within the /tmp folder.
3.3. Capture multiple frames to disk in several roles[edit | edit source]
In a similar way as previously and since the DCMIPP allows to capture several frames in parallel, cam can be used to capture several frames at once.
In the example below, cam is used to capture 3 streams (raw / viewfinder / stillcapture).
cam -c1 -C3 -F -s role=viewfinder -s role=raw -s role=still
[0:06:03.774900475] [1539] INFO Camera camera.cpp:1183 configuring streams: (0) 1024x600-RGB888 (1) 2592x1940-SRGGB12 (2) 2592x1940-YUV420 cam0: Capture 3 frames 363.896438 (0.00 fps) cam0-stream1 seq: 000000 bytesused: 10056960 cam0-stream2 seq: 000000 bytesused: 5028480/1257120/1257120 cam0-stream0 seq: 000000 bytesused: 1843200 363.930508 (29.35 fps) cam0-stream1 seq: 000001 bytesused: 10056960 cam0-stream2 seq: 000001 bytesused: 5028480/1257120/1257120 cam0-stream0 seq: 000001 bytesused: 1843200 363.963122 (30.66 fps) cam0-stream1 seq: 000002 bytesused: 10056960 cam0-stream2 seq: 000002 bytesused: 5028480/1257120/1257120 cam0-stream0 seq: 000002 bytesused: 1843200
This leads to availability of 9 files, 3 per streams:
-rw-r--r-- 1 root root 1843200 Feb 27 19:08 frame-cam0-stream0-000000.bin -rw-r--r-- 1 root root 1843200 Feb 27 19:08 frame-cam0-stream0-000001.bin -rw-r--r-- 1 root root 1843200 Feb 27 19:08 frame-cam0-stream0-000002.bin -rw-r--r-- 1 root root 10056960 Feb 27 19:08 frame-cam0-stream1-000000.bin -rw-r--r-- 1 root root 10056960 Feb 27 19:08 frame-cam0-stream1-000001.bin -rw-r--r-- 1 root root 10056960 Feb 27 19:08 frame-cam0-stream1-000002.bin -rw-r--r-- 1 root root 7542720 Feb 27 19:08 frame-cam0-stream2-000000.bin -rw-r--r-- 1 root root 7542720 Feb 27 19:08 frame-cam0-stream2-000001.bin -rw-r--r-- 1 root root 7542720 Feb 27 19:08 frame-cam0-stream2-000002.bin
3.4. Capture & display using DRM/KMS[edit | edit source]
For debug purpose, cam can also be used for capture & display via the DRM/KMS interface. For such situation, Wayland Weston should first be stopped in order to get a direct access to the DRM/KMS resource. To stop Weston, please refer to How to stop and start Weston article.
cam -c1 -C100 -D
4. GStreamer plugin libcamerasrc[edit | edit source]
libcamera also provide a GStreamer element called libcamerasrc, allowing to interface libcamera within a GStreamer pipeline.
Below are few examples of usage of this GStreamer element for some use-cases.
4.1. Capture RAW to disk[edit | edit source]
gst-launch-1.0 libcamerasrc name=cs src::stream-role=raw cs.src ! filesink location=file.raw
4.2. Capture JPEG to disk[edit | edit source]
gst-launch-1.0 libcamerasrc name=cs src::stream-role=still-capture cs.src ! jpegenc ! queue ! filesink location=file.jpeg
4.3. Capture & display[edit | edit source]
gst-launch-1.0 libcamerasrc name=cs src::stream-role=view-finder cs.src ! queue ! autovideosink
5. References[edit | edit source]