From 088c3c1d99364c6b5da34629f2feec116bd06069 Mon Sep 17 00:00:00 2001 From: Naushir Patuck Date: Mon, 13 Nov 2023 10:54:44 +0000 Subject: [PATCH] camera: Rename libcamera-* to rpicam-* This change reflects the new naming from libcamera-apps to rpicam-apps. All documentation, examples, files are updated to reflect this renaming. --- .../accessories/camera/external_trigger.adoc | 4 +- .../camera/synchronous_cameras.adoc | 8 +- .../computers/camera/camera_usage.adoc | 2 +- .../asciidoc/computers/camera/gstreamer.adoc | 12 +-- .../camera/libcamera_apps_packages.adoc | 31 ------- .../camera/libcamera_differences.adoc | 8 +- .../camera/libcamera_known_issues.adoc | 2 +- .../computers/camera/libcamera_python.adoc | 2 +- .../computers/camera/libcamera_raw.adoc | 23 ----- .../asciidoc/computers/camera/qt.adoc | 4 +- ...uilding.adoc => rpicam_apps_building.adoc} | 34 +++---- ...elp.adoc => rpicam_apps_getting_help.adoc} | 6 +- ....adoc => rpicam_apps_getting_started.adoc} | 4 +- ...apps_intro.adoc => rpicam_apps_intro.adoc} | 22 ++--- ...apps_libav.adoc => rpicam_apps_libav.adoc} | 14 +-- ...ulticam.adoc => rpicam_apps_multicam.adoc} | 2 +- .../camera/rpicam_apps_packages.adoc | 31 +++++++ ....adoc => rpicam_apps_post_processing.adoc} | 22 ++--- ...> rpicam_apps_post_processing_opencv.adoc} | 2 +- ...> rpicam_apps_post_processing_tflite.adoc} | 10 +-- ... rpicam_apps_post_processing_writing.adoc} | 2 +- ..._writing.adoc => rpicam_apps_writing.adoc} | 22 ++--- ...bcamera_detect.adoc => rpicam_detect.adoc} | 6 +- ...libcamera_hello.adoc => rpicam_hello.adoc} | 22 ++--- .../{libcamera_jpeg.adoc => rpicam_jpeg.adoc} | 18 ++-- ...common.adoc => rpicam_options_common.adoc} | 90 +++++++++---------- ...s_still.adoc => rpicam_options_still.adoc} | 42 ++++----- ...tions_vid.adoc => rpicam_options_vid.adoc} | 42 ++++----- .../asciidoc/computers/camera/rpicam_raw.adoc | 23 +++++ ...libcamera_still.adoc => rpicam_still.adoc} | 22 ++--- .../{libcamera_vid.adoc => rpicam_vid.adoc} | 26 +++--- .../asciidoc/computers/camera/timelapse.adoc | 8 +- .../asciidoc/computers/camera_software.adoc | 44 +++++---- .../computers/compute-module/cmio-camera.adoc | 14 +-- 34 files changed, 311 insertions(+), 313 deletions(-) delete mode 100644 documentation/asciidoc/computers/camera/libcamera_apps_packages.adoc delete mode 100644 documentation/asciidoc/computers/camera/libcamera_raw.adoc rename documentation/asciidoc/computers/camera/{libcamera_apps_building.adoc => rpicam_apps_building.adoc} (77%) rename documentation/asciidoc/computers/camera/{libcamera_apps_getting_help.adoc => rpicam_apps_getting_help.adoc} (58%) rename documentation/asciidoc/computers/camera/{libcamera_apps_getting_started.adoc => rpicam_apps_getting_started.adoc} (94%) rename documentation/asciidoc/computers/camera/{libcamera_apps_intro.adoc => rpicam_apps_intro.adoc} (61%) rename documentation/asciidoc/computers/camera/{libcamera_apps_libav.adoc => rpicam_apps_libav.adoc} (77%) rename documentation/asciidoc/computers/camera/{libcamera_apps_multicam.adoc => rpicam_apps_multicam.adoc} (89%) create mode 100644 documentation/asciidoc/computers/camera/rpicam_apps_packages.adoc rename documentation/asciidoc/computers/camera/{libcamera_apps_post_processing.adoc => rpicam_apps_post_processing.adoc} (84%) rename documentation/asciidoc/computers/camera/{libcamera_apps_post_processing_opencv.adoc => rpicam_apps_post_processing_opencv.adoc} (94%) rename documentation/asciidoc/computers/camera/{libcamera_apps_post_processing_tflite.adoc => rpicam_apps_post_processing_tflite.adoc} (91%) rename documentation/asciidoc/computers/camera/{libcamera_apps_post_processing_writing.adoc => rpicam_apps_post_processing_writing.adoc} (95%) rename documentation/asciidoc/computers/camera/{libcamera_apps_writing.adoc => rpicam_apps_writing.adoc} (61%) rename documentation/asciidoc/computers/camera/{libcamera_detect.adoc => rpicam_detect.adoc} (68%) rename documentation/asciidoc/computers/camera/{libcamera_hello.adoc => rpicam_hello.adoc} (66%) rename documentation/asciidoc/computers/camera/{libcamera_jpeg.adoc => rpicam_jpeg.adoc} (73%) rename documentation/asciidoc/computers/camera/{libcamera_options_common.adoc => rpicam_options_common.adoc} (83%) rename documentation/asciidoc/computers/camera/{libcamera_options_still.adoc => rpicam_options_still.adoc} (68%) rename documentation/asciidoc/computers/camera/{libcamera_options_vid.adoc => rpicam_options_vid.adoc} (64%) create mode 100644 documentation/asciidoc/computers/camera/rpicam_raw.adoc rename documentation/asciidoc/computers/camera/{libcamera_still.adoc => rpicam_still.adoc} (83%) rename documentation/asciidoc/computers/camera/{libcamera_vid.adoc => rpicam_vid.adoc} (76%) diff --git a/documentation/asciidoc/accessories/camera/external_trigger.adoc b/documentation/asciidoc/accessories/camera/external_trigger.adoc index fa804c4acd..5f210415ce 100644 --- a/documentation/asciidoc/accessories/camera/external_trigger.adoc +++ b/documentation/asciidoc/accessories/camera/external_trigger.adoc @@ -59,10 +59,10 @@ Run the code on the Pico, and set the camera running: [,bash] ---- -libcamera-hello -t 0 --qt-preview --shutter 3000 +rpicam-hello -t 0 --qt-preview --shutter 3000 ---- A frame should now be generated every time that the Pico pulses the pin. Variable framerate is acceptable, and can be controlled by simply -varying the duration between pulses. No options need to be passed to libcamera-apps to enable external trigger. +varying the duration between pulses. No options need to be passed to rpicam-apps to enable external trigger. NOTE: When running libcamera apps, you will need to specify a fixed shutter duration (the value does not matter). This will ensure the AGC does not try adjusting camera's shutter speed, which is controlled by the external trigger pulse. \ No newline at end of file diff --git a/documentation/asciidoc/accessories/camera/synchronous_cameras.adoc b/documentation/asciidoc/accessories/camera/synchronous_cameras.adoc index 77a1a45ca7..2697f7ccce 100644 --- a/documentation/asciidoc/accessories/camera/synchronous_cameras.adoc +++ b/documentation/asciidoc/accessories/camera/synchronous_cameras.adoc @@ -40,13 +40,13 @@ exit Start the sink running: [,bash] ---- -libcamera-vid --frames 300 --qt-preview -o sink.h264 +rpicam-vid --frames 300 --qt-preview -o sink.h264 ---- Start the source running [,bash] ---- -libcamera-vid --frames 300 --qt-preview -o source.h264 +rpicam-vid --frames 300 --qt-preview -o source.h264 ---- Frames should be synchronous. Use `--frames` to ensure the same number of frames are captured, and that the recordings are exactly the same length. @@ -75,14 +75,14 @@ On the boards that you wish to act as sinks, solder the two halves of the MAS pa Start the sink running: [,bash] ---- -libcamera-vid --frames 300 -o sync.h264 +rpicam-vid --frames 300 -o sync.h264 ---- Allow a delay before you start the source running (see note below). Needs to be roughly > 2 seconds. Start the source running: [,bash] ---- -libcamera-vid --frames 299 -o sync.h264 +rpicam-vid --frames 299 -o sync.h264 ---- [NOTE] diff --git a/documentation/asciidoc/computers/camera/camera_usage.adoc b/documentation/asciidoc/computers/camera/camera_usage.adoc index 229111b82c..774d74085f 100644 --- a/documentation/asciidoc/computers/camera/camera_usage.adoc +++ b/documentation/asciidoc/computers/camera/camera_usage.adoc @@ -10,4 +10,4 @@ Further details on the camera modules can be found in the xref:../accessories/ca All Raspberry Pi cameras are capable of taking high-resolution photographs, along with full HD 1080p video, and can be fully controlled programmatically. This documentation describes how to use the camera in various scenarios, and how to use the various software tools. -Once you've xref:../accessories/camera.adoc#installing-a-raspberry-pi-camera[installed your camera module], there are various ways the cameras can be used. The simplest option is to use one of the provided camera applications, such as `libcamera-still` or `libcamera-vid`. +Once you've xref:../accessories/camera.adoc#installing-a-raspberry-pi-camera[installed your camera module], there are various ways the cameras can be used. The simplest option is to use one of the provided camera applications, such as `rpicam-still` or `rpicam-vid`. diff --git a/documentation/asciidoc/computers/camera/gstreamer.adoc b/documentation/asciidoc/computers/camera/gstreamer.adoc index deba30250f..39d9e1ba6a 100644 --- a/documentation/asciidoc/computers/camera/gstreamer.adoc +++ b/documentation/asciidoc/computers/camera/gstreamer.adoc @@ -1,12 +1,12 @@ === Using Gstreamer -_Gstreamer_ is a Linux framework for reading, processing and playing multimedia files. There is a lot of information and many tutorials at the https://gstreamer.freedesktop.org/[_gstreamer_ website]. Here we show how `libcamera-vid` can be used to stream video over a network. +_Gstreamer_ is a Linux framework for reading, processing and playing multimedia files. There is a lot of information and many tutorials at the https://gstreamer.freedesktop.org/[_gstreamer_ website]. Here we show how `rpicam-vid` can be used to stream video over a network. -On the server we need `libcamera-vid` to output an encoded h.264 bitstream to _stdout_ and can use the _gstreamer_ `fdsrc` element to receive it. Then extra _gstreamer_ elements can send this over the network. As an example we can simply send and receive the stream on the same device over a UDP link. On the server: +On the server we need `rpicam-vid` to output an encoded h.264 bitstream to _stdout_ and can use the _gstreamer_ `fdsrc` element to receive it. Then extra _gstreamer_ elements can send this over the network. As an example we can simply send and receive the stream on the same device over a UDP link. On the server: [,bash] ---- -libcamera-vid -t 0 -n --inline -o - | gst-launch-1.0 fdsrc fd=0 ! udpsink host=localhost port=5000 +rpicam-vid -t 0 -n --inline -o - | gst-launch-1.0 fdsrc fd=0 ! udpsink host=localhost port=5000 ---- For the client (type this into another console window) we can use: @@ -22,7 +22,7 @@ To stream using the RTP protocol, on the server you could use: [,bash] ---- -libcamera-vid -t 0 -n --inline -o - | gst-launch-1.0 fdsrc fd=0 ! h264parse ! rtph264pay ! udpsink host=localhost port=5000 +rpicam-vid -t 0 -n --inline -o - | gst-launch-1.0 fdsrc fd=0 ! h264parse ! rtph264pay ! udpsink host=localhost port=5000 ---- And in the client window: @@ -36,7 +36,7 @@ We conclude with an example that streams from one machine to another. Let us ass [,bash] ---- -libcamera-vid -t 0 -n --inline -o - | gst-launch-1.0 fdsrc fd=0 ! h264parse ! rtph264pay ! udpsink host=192.168.0.3 port=5000 +rpicam-vid -t 0 -n --inline -o - | gst-launch-1.0 fdsrc fd=0 ! h264parse ! rtph264pay ! udpsink host=192.168.0.3 port=5000 ---- If the client is not a Raspberry Pi it may have different _gstreamer_ elements available. For a Linux PC we might use: @@ -48,7 +48,7 @@ gst-launch-1.0 udpsrc address=192.168.0.3 port=5000 caps=application/x-rtp ! rtp ==== The `libcamerasrc` element -`libcamera` provides a `libcamerasrc` _gstreamer_ element which can be used directly instead of `libcamera-vid`. On the server you could use: +`libcamera` provides a `libcamerasrc` _gstreamer_ element which can be used directly instead of `rpicam-vid`. On the server you could use: [,bash] ---- diff --git a/documentation/asciidoc/computers/camera/libcamera_apps_packages.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_packages.adoc deleted file mode 100644 index 61d77c4fde..0000000000 --- a/documentation/asciidoc/computers/camera/libcamera_apps_packages.adoc +++ /dev/null @@ -1,31 +0,0 @@ -=== `libcamera` and `libcamera-apps` Packages - -A number of `apt` packages are provided for convenience. In order to access them, we recommend keeping your OS up to date xref:../computers/os.adoc#using-apt[in the usual way]. - -==== Binary Packages - -There are two `libcamera-apps` packages available, that contain the necessary executables: - -* `libcamera-apps` contains the full applications with support for previews using a desktop environment. This package is pre-installed in Raspberry Pi OS. - -* `libcamera-apps-lite` omits desktop environment support and only the DRM preview is available. This package is pre-installed in Raspberry Pi OS Lite. - -==== Dependencies - -These applications depend on a number of library packages which are named _library-name_ where __ is a version number (actually the ABI, or Application Binary Interface, version), and which stands at zero at the time of writing. Thus we have the following: - -* The package `libcamera0` contains the `libcamera` libraries. - -* The package `libepoxy0` contains the `libepoxy` libraries. - -These will be installed automatically when needed. - -==== Dev Packages - -`libcamera-apps` can be rebuilt on their own without installing and building `libcamera` and `libepoxy` from scratch. To enable this, the following packages should be installed: - -* `libcamera-dev` contains the necessary `libcamera` header files and resources. - -* `libepoxy-dev` contains the necessary `libepoxy` header files and resources. You will only need this if you want support for the GLES/EGL preview window. - -Subsequently `libcamera-apps` can be xref:camera_software.adoc#building-libcamera-apps-without-rebuilding-libcamera[checked out from GitHub and rebuilt]. diff --git a/documentation/asciidoc/computers/camera/libcamera_differences.adoc b/documentation/asciidoc/computers/camera/libcamera_differences.adoc index 85506f56a3..da96139abc 100644 --- a/documentation/asciidoc/computers/camera/libcamera_differences.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_differences.adoc @@ -1,10 +1,10 @@ === Differences compared to _Raspicam_ Apps -Whilst the `libcamera-apps` attempt to emulate most features of the legacy _Raspicam_ applications, there are some differences. Here we list the principal ones that users are likely to notice. +Whilst the `rpicam-apps` attempt to emulate most features of the legacy _Raspicam_ applications, there are some differences. Here we list the principal ones that users are likely to notice. * The use of Boost `program_options` doesn't allow multi-character short versions of options, so where these were present they have had to be dropped. The long form options are named the same, and any single character short forms are preserved. -* `libcamera-still` and `libcamera-jpeg` do not show the capture image in the preview window. +* `rpicam-still` and `rpicam-jpeg` do not show the capture image in the preview window. * `libcamera` performs its own camera mode selection, so the `--mode` option is not supported. It deduces camera modes from the resolutions requested. There is still work ongoing in this area. @@ -25,7 +25,7 @@ Whilst the `libcamera-apps` attempt to emulate most features of the legacy _Rasp * There are some differences in the metering, exposure and AWB options. In particular the legacy apps conflate metering (by which we mean the "metering mode") and the exposure (by which we now mean the "exposure profile"). With regards to AWB, to turn it off you have to set a pair of colour gains (e.g. `--awbgains 1.0,1.0`). -* `libcamera` has no mechanism to set the AWB into "grey world" mode, which is useful for "NOIR" camera modules. However, tuning files are supplied which switch the AWB into the correct mode, so for example, you could use `libcamera-hello --tuning-file /usr/share/libcamera/ipa/rpi/vc4/imx219_noir.json` (for Pi 4 and earlier devices) or `libcamera-hello --tuning-file /usr/share/libcamera/ipa/rpi/pisp/imx219_noir.json` (Pi 5 and later devices). +* `libcamera` has no mechanism to set the AWB into "grey world" mode, which is useful for "NOIR" camera modules. However, tuning files are supplied which switch the AWB into the correct mode, so for example, you could use `rpicam-hello --tuning-file /usr/share/libcamera/ipa/rpi/vc4/imx219_noir.json` (for Pi 4 and earlier devices) or `rpicam-hello --tuning-file /usr/share/libcamera/ipa/rpi/pisp/imx219_noir.json` (Pi 5 and later devices). * There is support for setting the exposure time (`--shutter`) and analogue gain (`--analoggain` or just `--gain`). There is no explicit control of the digital gain; you get this if the gain requested is larger than the analogue gain can deliver by itself. @@ -33,7 +33,7 @@ Whilst the `libcamera-apps` attempt to emulate most features of the legacy _Rasp * There is no support for setting the flicker period yet. -* `libcamera-still` does not support burst capture. In fact, because the JPEG encoding is not multi-threaded and pipelined it would produce quite poor framerates. Instead, users are advised to consider using `libcamera-vid` in MJPEG mode instead (and `--segment 1` can be used to force each frame into a separate JPEG file). +* `rpicam-still` does not support burst capture. In fact, because the JPEG encoding is not multi-threaded and pipelined it would produce quite poor framerates. Instead, users are advised to consider using `rpicam-vid` in MJPEG mode instead (and `--segment 1` can be used to force each frame into a separate JPEG file). * `libcamera` uses open source drivers for all the image sensors, so the mechanism for enabling or disabling on-sensor DPC (Defective Pixel Correction) is different. The imx477 (HQ cam) driver enables on-sensor DPC by default; to disable it the user should, as root, enter diff --git a/documentation/asciidoc/computers/camera/libcamera_known_issues.adoc b/documentation/asciidoc/computers/camera/libcamera_known_issues.adoc index 8f8ec7690f..e19223d5f5 100644 --- a/documentation/asciidoc/computers/camera/libcamera_known_issues.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_known_issues.adoc @@ -1,6 +1,6 @@ === Known Issues -We are aware of the following issues in `libcamera` and `libcamera-apps`. +We are aware of the following issues in `libcamera` and `rpicam-apps`. * On Raspberry Pi 3 (and earlier devices) the graphics hardware can only support images up to 2048x2048 pixels which places a limit on the camera images that can be resized into the preview window. In practice this means that video encoding of images larger than 2048 pixels across (which would necessarily be using a codec other than h.264) will not support, or will produce corrupted, preview images. For Raspberry Pi 4 the limit is 4096 pixels. We would recommend using the `-n` (no preview) option for the time being. diff --git a/documentation/asciidoc/computers/camera/libcamera_python.adoc b/documentation/asciidoc/computers/camera/libcamera_python.adoc index a5c14cbfcc..b2dc7fad7e 100644 --- a/documentation/asciidoc/computers/camera/libcamera_python.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_python.adoc @@ -1,6 +1,6 @@ === Python Bindings for `libcamera` -The https://github.com/raspberrypi/picamera2[Picamera2 library] is a libcamera-based replacement for Picamera, which was a Python interface to Raspberry Pi's legacy camera stack. Picamera2 presents an easy to use Python API. +The https://github.com/raspberrypi/picamera2[Picamera2 library] is a rpicam-based replacement for Picamera, which was a Python interface to Raspberry Pi's legacy camera stack. Picamera2 presents an easy to use Python API. Documentation about Picamera2 is available https://github.com/raspberrypi/picamera2[on Github] and in the https://datasheets.raspberrypi.com/camera/picamera2-manual.pdf[Picamera2 Manual]. diff --git a/documentation/asciidoc/computers/camera/libcamera_raw.adoc b/documentation/asciidoc/computers/camera/libcamera_raw.adoc deleted file mode 100644 index c372f89db7..0000000000 --- a/documentation/asciidoc/computers/camera/libcamera_raw.adoc +++ /dev/null @@ -1,23 +0,0 @@ -=== `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 - -[,bash] ----- -libcamera-raw -t 2000 -o test.raw ----- - -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. - -By default the raw frames are saved in a single (potentially very large) file. As we saw previously, the `--segment` option can be used conveniently to direct each to a separate file. -[,bash] ----- -libcamera-raw -t 2000 --segment 1 -o test%05d.raw ----- - -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 - -[,bash] ----- -libcamera-raw -t 5000 --width 4056 --height 3040 -o test.raw --framerate 8 ----- diff --git a/documentation/asciidoc/computers/camera/qt.adoc b/documentation/asciidoc/computers/camera/qt.adoc index 9c7fa346a2..aeb31b9b6c 100644 --- a/documentation/asciidoc/computers/camera/qt.adoc +++ b/documentation/asciidoc/computers/camera/qt.adoc @@ -1,10 +1,10 @@ === Using _libcamera_ and _Qt_ together -_Qt_ is a popular application framework and GUI toolkit, and indeed _libcamera-apps_ optionally makes use of it to implement a camera preview window. +_Qt_ is a popular application framework and GUI toolkit, and indeed _rpicam-apps_ optionally makes use of it to implement a camera preview window. However, _Qt_ defines certain symbols as macros in the global namespace (such as `slot` and `emit`) and this causes errors when including _libcamera_ files. The problem is common to all platforms trying to use both _Qt_ and _libcamera_ and not specific to Raspberry Pi. Nonetheless we suggest that developers experiencing difficulties try the following workarounds. -1. _libcamera_ include files, or files that include _libcamera_ files (such as _libcamera-apps_ files), should be listed before any _Qt_ header files where possible. +1. _libcamera_ include files, or files that include _libcamera_ files (such as _rpicam-apps_ files), should be listed before any _Qt_ header files where possible. 2. If you do need to mix your Qt application files with libcamera includes, replace `signals:` with `Q_SIGNALS:`, `slots:` with `Q_SLOTS:`, `emit` with `Q_EMIT` and `foreach` with `Q_FOREACH`. diff --git a/documentation/asciidoc/computers/camera/libcamera_apps_building.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_building.adoc similarity index 77% rename from documentation/asciidoc/computers/camera/libcamera_apps_building.adoc rename to documentation/asciidoc/computers/camera/rpicam_apps_building.adoc index 7a1228e69d..65d6aa822a 100644 --- a/documentation/asciidoc/computers/camera/libcamera_apps_building.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_apps_building.adoc @@ -1,29 +1,29 @@ -=== Building `libcamera` and `libcamera-apps` +=== Building `libcamera` and `rpicam-apps` -Building `libcamera` and `libcamera-apps` for yourself can bring the following benefits. +Building `libcamera` and `rpicam-apps` for yourself can bring the following benefits. * You can pick up the latest enhancements and features. -* `libcamera-apps` can be compiled with extra optimisation for Raspberry Pi 3 and Raspberry Pi 4 devices running a 32-bit OS. +* `rpicam-apps` can be compiled with extra optimisation for Raspberry Pi 3 and Raspberry Pi 4 devices running a 32-bit OS. * You can include the various optional OpenCV and/or TFLite post-processing stages (or add your own). -* You can customise or add your own applications derived from `libcamera-apps`. +* You can customise or add your own applications derived from `rpicam-apps`. NOTE: When building on a Raspberry Pi with 1GB or less of RAM, there is a risk that the device may run out of swap and fail. We recommend either increasing the amount of swap, or building with fewer threads (the `-j` option to `ninja` and to `make`). -==== Building `libcamera-apps` without rebuilding `libcamera` +==== Building `rpicam-apps` without rebuilding `libcamera` -You can rebuild `libcamera-apps` _without_ first rebuilding the whole of `libcamera` and `libepoxy`. If you do not need support for the GLES/EGL preview window then `libepoxy` can be omitted entirely. Mostly this will include Raspberry Pi OS Lite users, and they must be sure to use `-Denable_egl=false` when running `meson setup` later. These users should run: +You can rebuild `rpicam-apps` _without_ first rebuilding the whole of `libcamera` and `libepoxy`. If you do not need support for the GLES/EGL preview window then `libepoxy` can be omitted entirely. Mostly this will include Raspberry Pi OS Lite users, and they must be sure to use `-Denable_egl=false` when running `meson setup` later. These users should run: ---- -sudo apt install -y libcamera-dev libjpeg-dev libtiff5-dev +sudo apt install -y rpicam-dev libjpeg-dev libtiff5-dev ---- All other users should execute: ---- -sudo apt install -y libcamera-dev libepoxy-dev libjpeg-dev libtiff5-dev +sudo apt install -y rpicam-dev libepoxy-dev libjpeg-dev libtiff5-dev ---- If you want to use the Qt preview window, please also execute @@ -32,13 +32,13 @@ If you want to use the Qt preview window, please also execute sudo apt install -y qtbase5-dev libqt5core5a libqt5gui5 libqt5widgets5 ---- -If you want xref:camera_software.adoc#libav-integration-with-libcamera-vid[libav] support in `libcamera-vid`, additional libraries must be installed: +If you want xref:camera_software.adoc#libav-integration-with-rpicam-vid[libav] support in `rpicam-vid`, additional libraries must be installed: ---- sudo apt install libavcodec-dev libavdevice-dev libavformat-dev libswresample-dev ---- -Now proceed directly to the instructions for xref:camera_software.adoc#building-libcamera-apps[building `libcamera-apps`]. Raspberry Pi OS Lite users should check that _git_ is installed first (`sudo apt install -y git`). +Now proceed directly to the instructions for xref:camera_software.adoc#building-rpicam-apps[building `rpicam-apps`]. Raspberry Pi OS Lite users should check that _git_ is installed first (`sudo apt install -y git`). ==== Building `libcamera` @@ -89,7 +89,7 @@ ninja -C build # use -j 2 on Raspberry Pi 3 or earlier devices sudo ninja -C build install ---- -NOTE: At the time of writing `libcamera` does not yet have a stable binary interface. Therefore, if you have rebuilt `libcamera` we recommend continuing and rebuilding `libcamera-apps` from scratch too. +NOTE: At the time of writing `libcamera` does not yet have a stable binary interface. Therefore, if you have rebuilt `libcamera` we recommend continuing and rebuilding `rpicam-apps` from scratch too. ==== Building `libepoxy` @@ -114,21 +114,21 @@ ninja sudo ninja install ---- -==== Building `libcamera-apps` +==== Building `rpicam-apps` -First fetch the necessary dependencies for `libcamera-apps`. +First fetch the necessary dependencies for `rpicam-apps`. ---- sudo apt install -y cmake libboost-program-options-dev libdrm-dev libexif-dev sudo apt install -y meson ninja-build ---- -The `libcamera-apps` build process begins with the following: +The `rpicam-apps` build process begins with the following: ---- cd -git clone https://github.com/raspberrypi/libcamera-apps.git -cd libcamera-apps +git clone https://github.com/raspberrypi/rpicam-apps.git +cd rpicam-apps ---- At this point you will need to run `meson setup` after deciding what extra flags to pass it. The valid flags are: @@ -169,6 +169,6 @@ sudo meson install -C build sudo ldconfig # this is only necessary on the first build ---- -NOTE: If you are using an image where `libcamera-apps` have been previously installed as an `apt` package, and you want to run the new `libcamera-apps` executables from the same terminal window where you have just built and installed them, you may need to run `hash -r` to be sure to pick up the new ones over the system supplied ones. +NOTE: If you are using an image where `rpicam-apps` have been previously installed as an `apt` package, and you want to run the new `rpicam-apps` executables from the same terminal window where you have just built and installed them, you may need to run `hash -r` to be sure to pick up the new ones over the system supplied ones. Finally, if you have not already done so, please be sure to follow the `dtoverlay` and display driver instructions in the xref:camera_software.adoc#getting-started[Getting Started section] (and rebooting if you changed anything there). diff --git a/documentation/asciidoc/computers/camera/libcamera_apps_getting_help.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_getting_help.adoc similarity index 58% rename from documentation/asciidoc/computers/camera/libcamera_apps_getting_help.adoc rename to documentation/asciidoc/computers/camera/rpicam_apps_getting_help.adoc index 3237ef2303..74d200ecb4 100644 --- a/documentation/asciidoc/computers/camera/libcamera_apps_getting_help.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_apps_getting_help.adoc @@ -1,10 +1,10 @@ === Getting Help -For further help with `libcamera` and the `libcamera-apps`, the first port of call will usually be the https://forums.raspberrypi.com/viewforum.php?f=43[Raspberry Pi Camera Forum]. Before posting, it's helpful to: +For further help with `libcamera` and the `rpicam-apps`, the first port of call will usually be the https://forums.raspberrypi.com/viewforum.php?f=43[Raspberry Pi Camera Forum]. Before posting, it's helpful to: * Make a note of your operating system version (`uname -a`). -* Make a note of your `libcamera` and `libcamera-apps` versions (`libcamera-hello --version`). +* Make a note of your `libcamera` and `rpicam-apps` versions (`rpicam-hello --version`). * Please report the make and model of the camera module you are using. Note that when third party camera module vendors supply their own software then we are normally unable to offer any support and all queries should be directed back to the vendor. @@ -12,4 +12,4 @@ For further help with `libcamera` and the `libcamera-apps`, the first port of ca * If it seems like it might be relevant, please include any excerpts from the application's console output. -When it seems likely that there are specific problems in the camera software (such as crashes) then it may be more appropriate to https://github.com/raspberrypi/libcamera-apps[create an issue in the `libcamera-apps` Github repository]. Again, please include all the helpful details that you can. +When it seems likely that there are specific problems in the camera software (such as crashes) then it may be more appropriate to https://github.com/raspberrypi/rpicam-apps[create an issue in the `rpicam-apps` Github repository]. Again, please include all the helpful details that you can. diff --git a/documentation/asciidoc/computers/camera/libcamera_apps_getting_started.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_getting_started.adoc similarity index 94% rename from documentation/asciidoc/computers/camera/libcamera_apps_getting_started.adoc rename to documentation/asciidoc/computers/camera/rpicam_apps_getting_started.adoc index 48b4106e97..8b0460e8dc 100644 --- a/documentation/asciidoc/computers/camera/libcamera_apps_getting_started.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_apps_getting_started.adoc @@ -4,13 +4,13 @@ NOTE: On Raspberry Pi 3 and earlier devices running _Bullseye_ you need to re-enable _Glamor_ in order to make the X Windows hardware accelerated preview window work. To do this enter `sudo raspi-config` at a terminal window and then choose `Advanced Options`, `Glamor` and `Yes`. Finally quit `raspi-config` and let it reboot your Raspberry Pi. -When running a recent version of Raspberry Pi OS, the 5 basic `libcamera-apps` are already installed. In this case, official Raspberry Pi cameras will also be detected and enabled automatically. +When running a recent version of Raspberry Pi OS, the 5 basic `rpicam-apps` are already installed. In this case, official Raspberry Pi cameras will also be detected and enabled automatically. You can check that everything is working by entering: [,bash] ---- -libcamera-hello +rpicam-hello ---- You should see a camera preview window for about 5 seconds. diff --git a/documentation/asciidoc/computers/camera/libcamera_apps_intro.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_intro.adoc similarity index 61% rename from documentation/asciidoc/computers/camera/libcamera_apps_intro.adoc rename to documentation/asciidoc/computers/camera/rpicam_apps_intro.adoc index b9b8c1ef20..51f3661a4a 100644 --- a/documentation/asciidoc/computers/camera/libcamera_apps_intro.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_apps_intro.adoc @@ -1,8 +1,8 @@ -== `libcamera` and `libcamera-apps` +== `libcamera` and `rpicam-apps` -[IMPORTANT] +[WARNING] ==== -Raspberry Pi has transitioned from a legacy camera software stack based on proprietary Broadcom GPU code to an open-source stack based on `libcamera`. As such, the old _Raspicam_ stack (`raspistill`, `raspivid`, etc.) is no longer supported. +`rpicam-apps` applications have been renamed from `libcamera-\*` to `rpicam-*`. Symbolic links are installed to allow users to keep using the old application names, but these will be deprecated soon. Users are encouraged to adopt the new application names as soon as possible. ==== === Introduction @@ -11,16 +11,16 @@ Raspberry Pi has transitioned from a legacy camera software stack based on propr `libcamera` presents a {cpp} API to applications and works at the level of configuring the camera and then allowing an application to request image frames. These image buffers reside in system memory and can be passed directly to still image encoders (such as JPEG) or to video encoders (such as h.264), though such ancillary functions as encoding images or displaying them are strictly beyond the purview of `libcamera` itself. -For this reason Raspberry Pi supplies a small set of example `libcamera-apps`. These are simple applications, built on top of `libcamera`, and are designed largely to emulate the function of the legacy stack built on Broadcom's proprietary GPU code (some users will recognise these legacy applications as `raspistill` and `raspivid`). The applications we provide are: +For this reason Raspberry Pi supplies a small set of example `rpicam-apps`. These are simple applications, built on top of `libcamera`, and are designed largely to emulate the function of the legacy stack built on Broadcom's proprietary GPU code (some users will recognise these legacy applications as `raspistill` and `raspivid`). The applications we provide are: -* _libcamera-hello_ A simple "hello world" application which starts a camera preview stream and displays it on the screen. -* _libcamera-jpeg_ A simple application to run a preview window and then capture high resolution still images. -* _libcamera-still_ A more complex still image capture application which emulates more of the features of the original `raspistill` application. -* _libcamera-vid_ A video capture application. -* _libcamera-raw_ A basic application for capturing raw (unprocessed Bayer) frames directly from the sensor. -* _libcamera-detect_ This application is not built by default, but users can build it if they have TensorFlow Lite installed on their Raspberry Pi. It captures JPEG images when certain objects are detected. +* _rpicam-hello_ A simple "hello world" application which starts a camera preview stream and displays it on the screen. +* _rpicam-jpeg_ A simple application to run a preview window and then capture high resolution still images. +* _rpicam-still_ A more complex still image capture application which emulates more of the features of the original `raspistill` application. +* _rpicam-vid_ A video capture application. +* _rpicam-raw_ A basic application for capturing raw (unprocessed Bayer) frames directly from the sensor. +* _rpicam-detect_ This application is not built by default, but users can build it if they have TensorFlow Lite installed on their Raspberry Pi. It captures JPEG images when certain objects are detected. -Raspberry Pi's `libcamera-apps` are not only command line applications that make it easy to capture images and video from the camera, they are also examples of how users can create their own libcamera-based applications with custom functionality to suit their own requirements. The source code for the `libcamera-apps` is freely available under a BSD 2-Clause licence at https://github.com/raspberrypi/libcamera-apps[]. +Raspberry Pi's `rpicam-apps` are not only command line applications that make it easy to capture images and video from the camera, they are also examples of how users can create their own rpicam-based applications with custom functionality to suit their own requirements. The source code for the `rpicam-apps` is freely available under a BSD 2-Clause licence at https://github.com/raspberrypi/rpicam-apps[]. ==== More about `libcamera` diff --git a/documentation/asciidoc/computers/camera/libcamera_apps_libav.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_libav.adoc similarity index 77% rename from documentation/asciidoc/computers/camera/libcamera_apps_libav.adoc rename to documentation/asciidoc/computers/camera/rpicam_apps_libav.adoc index 6607cad180..1127ae25a2 100644 --- a/documentation/asciidoc/computers/camera/libcamera_apps_libav.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_apps_libav.adoc @@ -1,6 +1,6 @@ -=== libav integration with libcamera-vid +=== libav integration with rpicam-vid -`libcamera-vid` can use the ffmpeg/libav codec backend to encode audio and video streams and either save to a local file or stream over the network. At present, video is encoded through the hardware H.264 encoder, and audio is encoded by a number of available software encoders. To list the available output formats, use the `ffmpeg -formats` command. +`rpicam-vid` can use the ffmpeg/libav codec backend to encode audio and video streams and either save to a local file or stream over the network. At present, video is encoded through the hardware H.264 encoder, and audio is encoded by a number of available software encoders. To list the available output formats, use the `ffmpeg -formats` command. To enable the libav backend, use the `--codec libav` command line option. Once enabled, the following configuration options are available: @@ -13,8 +13,8 @@ Set the libav output format to use. These output formats can be specified as con Example: To save a video in an mkv container, the following commands are equivalent: ---- -libcamera-vid --codec libav -o test.mkv -libcamera-vid --codec libav --libav-format mkv -o test.raw +rpicam-vid --codec libav -o test.mkv +rpicam-vid --codec libav --libav-format mkv -o test.raw ---- ---- @@ -35,7 +35,7 @@ Selects which software audio codec is used for encoding. By default `aac` is use Sets the audio encoding bitrate in bits per second. -Example: To record audio at 16 kilobits/sec with the mp2 codec use `libcamera-vid --codec libav -o test.mp4 --audio_codec mp2 --audio-bitrate 16384` +Example: To record audio at 16 kilobits/sec with the mp2 codec use `rpicam-vid --codec libav -o test.mp4 --audio_codec mp2 --audio-bitrate 16384` ---- --audio-samplerate, Set the audio sampling rate @@ -68,10 +68,10 @@ It is possible to use the libav backend as a network streaming source for audio/ To stream audio/video using TCP ---- -libcamera-vid -t 0 --codec libav --libav-format mpegts --libav-audio -o "tcp://0.0.0.0:1234?listen=1" +rpicam-vid -t 0 --codec libav --libav-format mpegts --libav-audio -o "tcp://0.0.0.0:1234?listen=1" ---- To stream audio/video using UDP ---- -libcamera-vid -t 0 --codec libav --libav-format mpegts --libav-audio -o "udp://:" +rpicam-vid -t 0 --codec libav --libav-format mpegts --libav-audio -o "udp://:" ---- diff --git a/documentation/asciidoc/computers/camera/libcamera_apps_multicam.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_multicam.adoc similarity index 89% rename from documentation/asciidoc/computers/camera/libcamera_apps_multicam.adoc rename to documentation/asciidoc/computers/camera/rpicam_apps_multicam.adoc index 2c8e64874e..94cfe06f34 100644 --- a/documentation/asciidoc/computers/camera/libcamera_apps_multicam.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_apps_multicam.adoc @@ -1,6 +1,6 @@ === Multiple Cameras Usage -Basic support for multiple cameras is available within `libcamera-apps`. Multiple cameras may be attached to a Raspberry Pi in the following ways: +Basic support for multiple cameras is available within `rpicam-apps`. Multiple cameras may be attached to a Raspberry Pi in the following ways: * Two cameras connected directly to a Raspberry Pi Compute Module board, see the xref:../computers/compute-module.adoc#attach-a-raspberry-pi-camera-module[Compute Module documentation] for further details. * Two or more cameras attached to a non-compute Raspberry Pi board using a Video Mux board, like https://www.arducam.com/product/multi-camera-v2-1-adapter-raspberry-pi/[this 3rd party product]. diff --git a/documentation/asciidoc/computers/camera/rpicam_apps_packages.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_packages.adoc new file mode 100644 index 0000000000..56453eb32f --- /dev/null +++ b/documentation/asciidoc/computers/camera/rpicam_apps_packages.adoc @@ -0,0 +1,31 @@ +=== `libcamera` and `rpicam-apps` Packages + +A number of `apt` packages are provided for convenience. In order to access them, we recommend keeping your OS up to date xref:../computers/os.adoc#using-apt[in the usual way]. + +==== Binary Packages + +There are two `rpicam-apps` packages available, that contain the necessary executables: + +* `rpicam-apps` contains the full applications with support for previews using a desktop environment. This package is pre-installed in Raspberry Pi OS. + +* `rpicam-apps-lite` omits desktop environment support and only the DRM preview is available. This package is pre-installed in Raspberry Pi OS Lite. + +==== Dependencies + +These applications depend on a number of library packages which are named _library-name_ where __ is a version number (actually the ABI, or Application Binary Interface, version), and which stands at zero at the time of writing. Thus we have the following: + +* The package `libcamera0` contains the `libcamera` libraries. + +* The package `libepoxy0` contains the `libepoxy` libraries. + +These will be installed automatically when needed. + +==== Dev Packages + +`rpicam-apps` can be rebuilt on their own without installing and building `libcamera` and `libepoxy` from scratch. To enable this, the following packages should be installed: + +* `rpicam-dev` contains the necessary `libcamera` header files and resources. + +* `libepoxy-dev` contains the necessary `libepoxy` header files and resources. You will only need this if you want support for the GLES/EGL preview window. + +Subsequently `rpicam-apps` can be xref:camera_software.adoc#building-rpicam-apps-without-rebuilding-libcamera[checked out from GitHub and rebuilt]. diff --git a/documentation/asciidoc/computers/camera/libcamera_apps_post_processing.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_post_processing.adoc similarity index 84% rename from documentation/asciidoc/computers/camera/libcamera_apps_post_processing.adoc rename to documentation/asciidoc/computers/camera/rpicam_apps_post_processing.adoc index fcc0a17f0e..0e9dd65848 100644 --- a/documentation/asciidoc/computers/camera/libcamera_apps_post_processing.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_apps_post_processing.adoc @@ -1,12 +1,12 @@ === Post-Processing -`libcamera-apps` share a common post-processing framework. This allows them to pass the images received from the camera system through a number of custom image processing and image analysis routines. Each such routine is known as a _post-processing stage_ and the description of exactly which stages should be run, and what configuration they may have, is supplied in a JSON file. Every stage, along with its source code, is supplied with a short example JSON file showing how to enable it. +`rpicam-apps` share a common post-processing framework. This allows them to pass the images received from the camera system through a number of custom image processing and image analysis routines. Each such routine is known as a _post-processing stage_ and the description of exactly which stages should be run, and what configuration they may have, is supplied in a JSON file. Every stage, along with its source code, is supplied with a short example JSON file showing how to enable it. For example, the simple _negate_ stage (which "negates" all the pixels in an image, turning light pixels dark and vice versa) is supplied with a `negate.json` file that configures the post-processing pipeline to run it: -`libcamera-hello --post-process-file /path/to/negate.json` +`rpicam-hello --post-process-file /path/to/negate.json` -TIP: Example JSON files can be found in the `assets` folder of the `libcamera-apps` repository at https://github.com/raspberrypi/libcamera-apps/tree/main/assets[]. +TIP: Example JSON files can be found in the `assets` folder of the `rpicam-apps` repository at https://github.com/raspberrypi/rpicam-apps/tree/main/assets[]. The negate stage is particularly trivial and has no configuration parameters of its own, therefore the JSON file merely has to name the stage, with no further information, and it will be run. Thus `negate.json` contains @@ -38,17 +38,17 @@ image::images/sobel_negate.jpg[Image with Sobel and negate] Some stages actually alter the image in some way, and this is their primary function (such as _negate_). Others are primarily for image analysis, and while they may indicate something on the image, all they really do is generate useful information. For this reason we also have a very flexible form of _metadata_ that can be populated by the post-processing stages, and this will get passed all the way through to the application itself. -Image analysis stages often prefer to work on reduced resolution images. `libcamera-apps` are able to supply applications with a ready-made low resolution image provided directly by the ISP hardware, and this can be helpful in improving performance. +Image analysis stages often prefer to work on reduced resolution images. `rpicam-apps` are able to supply applications with a ready-made low resolution image provided directly by the ISP hardware, and this can be helpful in improving performance. -Furthermore, with the post-processing framework being completely open, Raspberry Pi welcomes the contribution of new and interesting stages from the community and would be happy to host them in our `libcamera-apps` repository. The stages that are currently available are documented below. +Furthermore, with the post-processing framework being completely open, Raspberry Pi welcomes the contribution of new and interesting stages from the community and would be happy to host them in our `rpicam-apps` repository. The stages that are currently available are documented below. -NOTE: The `libcamera-apps` supplied with the operating system will be built without any optional 3rd party libraries (such as OpenCV or TensorFlow Lite), meaning that certain post-processing stages that rely on them will not be enabled. To use these stages, please follow the instructions for xref:camera_software.adoc#building-libcamera-and-libcamera-apps[building `libcamera-apps` for yourself]. +NOTE: The `rpicam-apps` supplied with the operating system will be built without any optional 3rd party libraries (such as OpenCV or TensorFlow Lite), meaning that certain post-processing stages that rely on them will not be enabled. To use these stages, please follow the instructions for xref:camera_software.adoc#building-libcamera-and-rpicam-apps[building `rpicam-apps` for yourself]. ==== `negate` stage The `negate` stage requires no 3rd party libraries. -On a Raspberry Pi 3 device or a Raspberry Pi 4 running a 32-bit OS, it may execute more quickly if recompiled using `-DENABLE_COMPILE_FLAGS_FOR_TARGET=armv8-neon`. (Please see the xref:camera_software.adoc#building-libcamera-and-libcamera-apps[build instructions].) +On a Raspberry Pi 3 device or a Raspberry Pi 4 running a 32-bit OS, it may execute more quickly if recompiled using `-DENABLE_COMPILE_FLAGS_FOR_TARGET=armv8-neon`. (Please see the xref:camera_software.adoc#building-libcamera-and-rpicam-apps[build instructions].) The `negate` stage has no user-configurable parameters. @@ -70,7 +70,7 @@ image::images/negate.jpg[Image with negate] The `hdr` stage implements both HDR (high dynamic range) imaging and DRC (dynamic range compression). The terminology that we use here regards DRC as operating on single images, and HDR works by accumulating multiple under-exposed images and then performing the same algorithm as DRC. -The `hdr` stage has no dependencies on 3rd party libraries, but (like some other stages) may execute more quickly on Raspberry Pi 3 or Raspberry Pi 4 devices running a 32-bit OS if recompiled using `-DENABLE_COMPILE_FLAGS_FOR_TARGET=armv8-neon` (please see the xref:camera_software.adoc#building-libcamera-and-libcamera-apps[build instructions]). Specifically, the image accumulation stage will run quicker and result in fewer frame drops, though the tonemapping part of the process is unchanged. +The `hdr` stage has no dependencies on 3rd party libraries, but (like some other stages) may execute more quickly on Raspberry Pi 3 or Raspberry Pi 4 devices running a 32-bit OS if recompiled using `-DENABLE_COMPILE_FLAGS_FOR_TARGET=armv8-neon` (please see the xref:camera_software.adoc#building-libcamera-and-rpicam-apps[build instructions]). Specifically, the image accumulation stage will run quicker and result in fewer frame drops, though the tonemapping part of the process is unchanged. The basic procedure is that we take the image (which in the case of HDR may be multiple images accumulated together) and apply an edge-preserving smoothing filter to generate a low pass (LP) image. We define the high pass (HP) image to be the difference between the LP image and the original. Next we apply a global tonemap to the LP image and add back the HP image. This procedure, in contrast to applying the tonemap directly to the original image, prevents us from squashing and losing all the local contrast in the resulting image. @@ -125,7 +125,7 @@ Without DRC: image::images/nodrc.jpg[Image without DRC processing] -With full-strength DRC: (use `libcamera-still -o test.jpg --post-process-file drc.json`) +With full-strength DRC: (use `rpicam-still -o test.jpg --post-process-file drc.json`) image::images/drc.jpg[Image with DRC processing] @@ -159,7 +159,7 @@ Without HDR: image::images/nohdr.jpg[Image without HDR processing] -With HDR: (use `libcamera-still -o test.jpg --ev -2 --denoise cdn_off --post-process-file hdr.json`) +With HDR: (use `rpicam-still -o test.jpg --ev -2 --denoise cdn_off --post-process-file hdr.json`) image::images/hdr.jpg[Image with DRC processing] @@ -213,4 +213,4 @@ If the amount of computation needs to be reduced (perhaps you have other stages To use the `motion_detect` stage you might enter the following example command: -`libcamera-hello --lores-width 128 --lores-height 96 --post-process-file motion_detect.json` +`rpicam-hello --lores-width 128 --lores-height 96 --post-process-file motion_detect.json` diff --git a/documentation/asciidoc/computers/camera/libcamera_apps_post_processing_opencv.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_post_processing_opencv.adoc similarity index 94% rename from documentation/asciidoc/computers/camera/libcamera_apps_post_processing_opencv.adoc rename to documentation/asciidoc/computers/camera/rpicam_apps_post_processing_opencv.adoc index 1d9adc48f6..24ac245475 100644 --- a/documentation/asciidoc/computers/camera/libcamera_apps_post_processing_opencv.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_apps_post_processing_opencv.adoc @@ -1,6 +1,6 @@ === Post-Processing with OpenCV -NOTE: These stages all require OpenCV to be installed on your system. You may also need to rebuild `libcamera-apps` with OpenCV support - please see the instructions for xref:camera_software.adoc#building-libcamera-and-libcamera-apps[building `libcamera-apps` for yourself]. +NOTE: These stages all require OpenCV to be installed on your system. You may also need to rebuild `rpicam-apps` with OpenCV support - please see the instructions for xref:camera_software.adoc#building-libcamera-and-rpicam-apps[building `rpicam-apps` for yourself]. ==== `sobel_cv` stage diff --git a/documentation/asciidoc/computers/camera/libcamera_apps_post_processing_tflite.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_post_processing_tflite.adoc similarity index 91% rename from documentation/asciidoc/computers/camera/libcamera_apps_post_processing_tflite.adoc rename to documentation/asciidoc/computers/camera/rpicam_apps_post_processing_tflite.adoc index 3797622818..ddeb9bc3a5 100644 --- a/documentation/asciidoc/computers/camera/libcamera_apps_post_processing_tflite.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_apps_post_processing_tflite.adoc @@ -1,6 +1,6 @@ === Post-Processing with TensorFlow Lite -NOTE: These stages require TensorFlow Lite (TFLite) libraries to be installed that export the {cpp} API. Unfortunately the TFLite libraries are not normally distributed conveniently in this form, however, one place where they can be downloaded is https://lindevs.com/install-precompiled-tensorflow-lite-on-raspberry-pi/[lindevs.com]. Please follow the installation instructions given on that page. Subsequently you may need to recompile `libcamera-apps` with TensorFlow Lite support - please follow the instructions for xref:camera_software.adoc#building-libcamera-and-libcamera-apps[building `libcamera-apps` for yourself]. +NOTE: These stages require TensorFlow Lite (TFLite) libraries to be installed that export the {cpp} API. Unfortunately the TFLite libraries are not normally distributed conveniently in this form, however, one place where they can be downloaded is https://lindevs.com/install-precompiled-tensorflow-lite-on-raspberry-pi/[lindevs.com]. Please follow the installation instructions given on that page. Subsequently you may need to recompile `rpicam-apps` with TensorFlow Lite support - please follow the instructions for xref:camera_software.adoc#building-libcamera-and-rpicam-apps[building `rpicam-apps` for yourself]. ==== `object_classify_tf` stage @@ -48,7 +48,7 @@ Example `object_classify_tf.json` file: The stage operates on a low resolution stream image of size 224x224, so it could be used as follows: -`libcamera-hello --post-process-file object_classify_tf.json --lores-width 224 --lores-height 224` +`rpicam-hello --post-process-file object_classify_tf.json --lores-width 224 --lores-height 224` image::images/classify.jpg[Image showing object classifier results] @@ -90,7 +90,7 @@ Example `pose_estimation_tf.json` file: The stage operates on a low resolution stream image of size 257x257 (but which must be rounded up to 258x258 for YUV420 images), so it could be used as follows: -`libcamera-hello --post-process-file pose_estimation_tf.json --lores-width 258 --lores-height 258` +`rpicam-hello --post-process-file pose_estimation_tf.json --lores-width 258 --lores-height 258` image::images/pose.jpg[Image showing pose estimation results] @@ -141,7 +141,7 @@ Example `object_detect_tf.json` file: The stage operates on a low resolution stream image of size 300x300. The following example would pass a 300x300 crop to the detector from the centre of the 400x300 low resolution image. -`libcamera-hello --post-process-file object_detect_tf.json --lores-width 400 --lores-height 300` +`rpicam-hello --post-process-file object_detect_tf.json --lores-width 400 --lores-height 300` image::images/detection.jpg[Image showing detected objects] @@ -181,6 +181,6 @@ Example `segmentation_tf.json` file: This example takes a square camera image and reduces it to 258x258 pixels in size. In fact the stage also works well when non-square images are squashed unequally down to 258x258 pixels without cropping. The image below shows the segmentation map in the bottom right hand corner. -`libcamera-hello --post-process-file segmentation_tf.json --lores-width 258 --lores-height 258 --viewfinder-width 1024 --viewfinder-height 1024` +`rpicam-hello --post-process-file segmentation_tf.json --lores-width 258 --lores-height 258 --viewfinder-width 1024 --viewfinder-height 1024` image::images/segmentation.jpg[Image showing segmentation in the bottom right corner] diff --git a/documentation/asciidoc/computers/camera/libcamera_apps_post_processing_writing.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_post_processing_writing.adoc similarity index 95% rename from documentation/asciidoc/computers/camera/libcamera_apps_post_processing_writing.adoc rename to documentation/asciidoc/computers/camera/rpicam_apps_post_processing_writing.adoc index cda7ec2cc6..8b48d0a660 100644 --- a/documentation/asciidoc/computers/camera/libcamera_apps_post_processing_writing.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_apps_post_processing_writing.adoc @@ -1,6 +1,6 @@ === Writing your own Post-Processing Stages -The `libcamera-apps` _post-processing framework_ is not only very flexible but is meant to make it easy for users to create their own custom post-processing stages. It is easy to include algorithms and routines that are already available both in OpenCV and TensorFlow Lite. +The `rpicam-apps` _post-processing framework_ is not only very flexible but is meant to make it easy for users to create their own custom post-processing stages. It is easy to include algorithms and routines that are already available both in OpenCV and TensorFlow Lite. We are keen to accept and distribute interesting post-processing stages contributed by our users. diff --git a/documentation/asciidoc/computers/camera/libcamera_apps_writing.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_writing.adoc similarity index 61% rename from documentation/asciidoc/computers/camera/libcamera_apps_writing.adoc rename to documentation/asciidoc/computers/camera/rpicam_apps_writing.adoc index c923481e35..158e191586 100644 --- a/documentation/asciidoc/computers/camera/libcamera_apps_writing.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_apps_writing.adoc @@ -1,12 +1,12 @@ === Understanding and Writing your own Apps -`libcamera-apps` are not supposed to be a full set of all the applications with all the features that anyone could ever need. Instead, they are supposed to be easy to understand, such that users who require slightly different behaviour can implement it for themselves. +`rpicam-apps` are not supposed to be a full set of all the applications with all the features that anyone could ever need. Instead, they are supposed to be easy to understand, such that users who require slightly different behaviour can implement it for themselves. All the applications work by having a simple event loop which receives a message with a new set of frames from the camera system. This set of frames is called a `CompletedRequest`. It contains all the images that have been derived from that single camera frame (so perhaps a low resolution image in addition to the full size output), as well as metadata from the camera system and further metadata from the post-processing system. -==== `libcamera-hello` +==== `rpicam-hello` -`libcamera-hello` is much the easiest application to understand. The only thing it does with the camera images is extract the `CompletedRequestPtr` (a shared pointer to the `CompletedRequest`) from the message: +`rpicam-hello` is much the easiest application to understand. The only thing it does with the camera images is extract the `CompletedRequestPtr` (a shared pointer to the `CompletedRequest`) from the message: ---- CompletedRequestPtr &completed_request = std::get(msg.payload); @@ -20,15 +20,15 @@ and forward it to the preview window: One important thing to note is that every `CompletedRequest` must be recycled back to the camera system so that the buffers can be reused, otherwise it will simply run out of buffers in which to receive new camera frames. This recycling process happens automatically when all references to the `CompletedRequest` are dropped, using {cpp}'s _shared pointer_ and _custom deleter_ mechanisms. -In `libcamera-hello` therefore, two things must happen for the `CompletedRequest` to be returned to the camera. +In `rpicam-hello` therefore, two things must happen for the `CompletedRequest` to be returned to the camera. 1. The event loop must go round again so that the message (`msg` in the code), which is holding a reference to the shared pointer, is dropped. 2. The preview thread, which takes another reference to the `CompletedRequest` when `ShowPreview` is called, must be called again with a new `CompletedRequest`, causing the previous one to be dropped. -==== `libcamera-vid` +==== `rpicam-vid` -`libcamera-vid` is not unlike `libcamera-hello`, but it adds a codec to the event loop and the preview. Before the event loop starts, we must configure that encoder with a callback which says what happens to the buffer containing the encoded image data. +`rpicam-vid` is not unlike `rpicam-hello`, but it adds a codec to the event loop and the preview. Before the event loop starts, we must configure that encoder with a callback which says what happens to the buffer containing the encoded image data. ---- app.SetEncodeOutputReadyCallback(std::bind(&Output::OutputReady, output.get(), _1, _2, _3, _4)); @@ -38,19 +38,19 @@ Here we send the buffer to the `Output` object which may write it to a file, or The encoder also takes a new reference to the `CompletedRequest`, so once the event loop, the preview window and the encoder all drop their references, the `CompletedRequest` will be recycled automatically back to the camera system. -==== `libcamera-raw` +==== `rpicam-raw` -`libcamera-raw` is not so very different from `libcamera-vid`. It too uses an encoder, although this time it is a "dummy" encoder called the `NullEncoder`. This just treats the input image directly as the output buffer and is careful not to drop its reference to the input until the output callback has dealt with it first. +`rpicam-raw` is not so very different from `rpicam-vid`. It too uses an encoder, although this time it is a "dummy" encoder called the `NullEncoder`. This just treats the input image directly as the output buffer and is careful not to drop its reference to the input until the output callback has dealt with it first. This time, however, we do not forward anything to the preview window, though we could have displayed the (processed) video stream if we had wanted. The use of the `NullEncoder` is possibly overkill in this application, as we could probably just send the image straight to the `Output` object. However, it serves to underline the general principle that it is normally a bad idea to do too much work directly in the event loop, and time-consuming processes are often better left to other threads. -==== `libcamera-jpeg` +==== `rpicam-jpeg` -We discuss `libcamera-jpeg` rather than `libcamera-still` as the basic idea (that of switching the camera from preview into capture mode) is the same, and `libcamera-jpeg` has far fewer additional options (such as timelapse capture) that serve to distract from the basic function. +We discuss `rpicam-jpeg` rather than `rpicam-still` as the basic idea (that of switching the camera from preview into capture mode) is the same, and `rpicam-jpeg` has far fewer additional options (such as timelapse capture) that serve to distract from the basic function. -`libcamera-jpeg` starts the camera in preview mode in the usual way, but at the appropriate moment stops it and switches to still capture: +`rpicam-jpeg` starts the camera in preview mode in the usual way, but at the appropriate moment stops it and switches to still capture: ---- app.StopCamera(); diff --git a/documentation/asciidoc/computers/camera/libcamera_detect.adoc b/documentation/asciidoc/computers/camera/rpicam_detect.adoc similarity index 68% rename from documentation/asciidoc/computers/camera/libcamera_detect.adoc rename to documentation/asciidoc/computers/camera/rpicam_detect.adoc index e6168a89f9..50e068cb0c 100644 --- a/documentation/asciidoc/computers/camera/libcamera_detect.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_detect.adoc @@ -1,6 +1,6 @@ -=== `libcamera-detect` +=== `rpicam-detect` -`libcamera-detect` is not supplied by default in any Raspberry Pi OS distribution, but can be built by users who have xref:camera_software.adoc#post-processing-with-tensorflow-lite[installed TensorFlow Lite]. In this case, please refer to the xref:camera_software.adoc#building-libcamera-and-libcamera-apps[`libcamera-apps` build instructions]. You will need to run `cmake` with `-DENABLE_TFLITE=1`. +`rpicam-detect` is not supplied by default in any Raspberry Pi OS distribution, but can be built by users who have xref:camera_software.adoc#post-processing-with-tensorflow-lite[installed TensorFlow Lite]. In this case, please refer to the xref:camera_software.adoc#building-libcamera-and-rpicam-apps[`rpicam-apps` build instructions]. You will need to run `cmake` with `-DENABLE_TFLITE=1`. This application runs a preview window and monitors the contents using a Google MobileNet v1 SSD (Single Shot Detector) neural network that has been trained to identify about 80 classes of objects using the Coco dataset. It should recognise people, cars, cats and many other objects. @@ -18,5 +18,5 @@ Please refer to the xref:camera_software.adoc#object_detect_tf-stage[TensorFlow [,bash] ---- -libcamera-detect -t 0 -o cat%04d.jpg --lores-width 400 --lores-height 300 --post-process-file object_detect_tf.json --object cat +rpicam-detect -t 0 -o cat%04d.jpg --lores-width 400 --lores-height 300 --post-process-file object_detect_tf.json --object cat ---- diff --git a/documentation/asciidoc/computers/camera/libcamera_hello.adoc b/documentation/asciidoc/computers/camera/rpicam_hello.adoc similarity index 66% rename from documentation/asciidoc/computers/camera/libcamera_hello.adoc rename to documentation/asciidoc/computers/camera/rpicam_hello.adoc index 45ce7da99f..9ad569395e 100644 --- a/documentation/asciidoc/computers/camera/libcamera_hello.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_hello.adoc @@ -1,23 +1,23 @@ -=== `libcamera-hello` +=== `rpicam-hello` -`libcamera-hello` is the equivalent of a "hello world" application for the camera. It starts the camera, displays a preview window, and does nothing else. For example +`rpicam-hello` is the equivalent of a "hello world" application for the camera. It starts the camera, displays a preview window, and does nothing else. For example [,bash] ---- -libcamera-hello +rpicam-hello ---- should display a preview window for about 5 seconds. The `-t ` option lets the user select how long the window is displayed, where `` is given in milliseconds. To run the preview indefinitely, use: [,bash] ---- -libcamera-hello -t 0 +rpicam-hello -t 0 ---- The preview can be halted either by clicking the window's close button, or using `Ctrl-C` in the terminal. ==== Options -`libcamera-apps` uses a 3rd party library to interpret command line options. This includes _long form_ options where the option name consists of more than one character preceded by `--`, and _short form_ options which can only be a single character preceded by a single `-`. For the most part option names are chosen to match those used by the legacy `raspicam` applications with the exception that we can no longer handle multi-character option names with a single `-`. Any such legacy options have been dropped and the long form with `--` must be used instead. +`rpicam-apps` uses a 3rd party library to interpret command line options. This includes _long form_ options where the option name consists of more than one character preceded by `--`, and _short form_ options which can only be a single character preceded by a single `-`. For the most part option names are chosen to match those used by the legacy `raspicam` applications with the exception that we can no longer handle multi-character option names with a single `-`. Any such legacy options have been dropped and the long form with `--` must be used instead. The options are classified broadly into 3 groups, namely those that are common, those that are specific to still images, and those that are for video encoding. They are supported in an identical manner across all the applications where they apply. @@ -33,30 +33,30 @@ For example, the NOIR (no IR-filter) versions of sensors require different AWB s [,bash] ---- -libcamera-hello --tuning-file /usr/share/libcamera/ipa/rpi/vc4/imx219_noir.json +rpicam-hello --tuning-file /usr/share/libcamera/ipa/rpi/vc4/imx219_noir.json ---- Pi 5 (or later devices) use a different tuning file in a different folder, so here you would use [,bash] ---- -libcamera-hello --tuning-file /usr/share/libcamera/ipa/rpi/pisp/imx219_noir.json +rpicam-hello --tuning-file /usr/share/libcamera/ipa/rpi/pisp/imx219_noir.json ---- If you are using a Soho Enterprises SE327M12 module with a Pi 4 you would use [,bash] ---- -libcamera-hello --tuning-file /usr/share/libcamera/ipa/rpi/vc4/se327m12.json +rpicam-hello --tuning-file /usr/share/libcamera/ipa/rpi/vc4/se327m12.json ---- Notice how this also means that users can copy an existing tuning file and alter it according to their own preferences, so long as the `--tuning-file` parameter is pointed to the new version. -Finally, the `--tuning-file` parameter, in common with other `libcamera-hello` command line options, applies identically across all the `libcamera-apps`. +Finally, the `--tuning-file` parameter, in common with other `rpicam-hello` command line options, applies identically across all the `rpicam-apps`. ==== Preview Window -Most of the `libcamera-apps` display a preview image in a window. If there is no active desktop environment, it will draw directly to the display using Linux DRM (Direct Rendering Manager), otherwise it will attempt to use the desktop environment. Both paths use zero-copy buffer sharing with the GPU, and a consequence of this is that X forwarding is _not_ supported. +Most of the `rpicam-apps` display a preview image in a window. If there is no active desktop environment, it will draw directly to the display using Linux DRM (Direct Rendering Manager), otherwise it will attempt to use the desktop environment. Both paths use zero-copy buffer sharing with the GPU, and a consequence of this is that X forwarding is _not_ supported. For this reason there is a third kind of preview window which does support X forwarding, and can be requested with the `--qt-preview` option. This implementation does not benefit from zero-copy buffer sharing nor from 3D acceleration which makes it computationally expensive (especially for large previews), and so is not normally recommended. @@ -68,7 +68,7 @@ The `--info-text` option allows the user to request that certain helpful image i [,bash] ---- -libcamera-hello --info-text "red gain %rg, blue gain %bg" +rpicam-hello --info-text "red gain %rg, blue gain %bg" ---- will display the current red and blue gain values. diff --git a/documentation/asciidoc/computers/camera/libcamera_jpeg.adoc b/documentation/asciidoc/computers/camera/rpicam_jpeg.adoc similarity index 73% rename from documentation/asciidoc/computers/camera/libcamera_jpeg.adoc rename to documentation/asciidoc/computers/camera/rpicam_jpeg.adoc index 145fb24fe9..64dab71b80 100644 --- a/documentation/asciidoc/computers/camera/libcamera_jpeg.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_jpeg.adoc @@ -1,12 +1,12 @@ -=== `libcamera-jpeg` +=== `rpicam-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. +`rpicam-jpeg` is a simple still image capture application. It deliberately avoids some of the additional features of `rpicam-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 [,bash] ---- -libcamera-jpeg -o test.jpg +rpicam-jpeg -o test.jpg ---- which will display a preview for about 5 seconds, and then capture a full resolution JPEG image to the file `test.jpg`. @@ -14,17 +14,17 @@ The `-t ` option can be used to alter the length of time the preview s [,bash] ---- -libcamera-jpeg -o test.jpg -t 2000 --width 640 --height 480 +rpicam-jpeg -o test.jpg -t 2000 --width 640 --height 480 ---- will capture a VGA sized image. ==== Exposure Control -All the `libcamera-apps` allow the user to run the camera with fixed shutter speed and gain. For example +All the `rpicam-apps` allow the user to run the camera with fixed shutter speed and gain. For example [,bash] ---- -libcamera-jpeg -o test.jpg -t 2000 --shutter 20000 --gain 1.5 +rpicam-jpeg -o test.jpg -t 2000 --shutter 20000 --gain 1.5 ---- would capture an image with an exposure of 20ms and a gain of 1.5x. Note that 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. @@ -32,9 +32,9 @@ Raspberry Pi's AEC/AGC algorithm allows applications to specify _exposure compen [,bash] ---- -libcamera-jpeg --ev -0.5 -o darker.jpg -libcamera-jpeg --ev 0 -o normal.jpg -libcamera-jpeg --ev 0.5 -o brighter.jpg +rpicam-jpeg --ev -0.5 -o darker.jpg +rpicam-jpeg --ev 0 -o normal.jpg +rpicam-jpeg --ev 0.5 -o brighter.jpg ---- ===== Further remarks on Digital Gain diff --git a/documentation/asciidoc/computers/camera/libcamera_options_common.adoc b/documentation/asciidoc/computers/camera/rpicam_options_common.adoc similarity index 83% rename from documentation/asciidoc/computers/camera/libcamera_options_common.adoc rename to documentation/asciidoc/computers/camera/rpicam_options_common.adoc index d76db91b68..84bfae0f24 100644 --- a/documentation/asciidoc/computers/camera/libcamera_options_common.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_options_common.adoc @@ -1,6 +1,6 @@ === Common Command Line Options -The following options apply across all the `libcamera-apps` with similar or identical semantics, unless noted otherwise. +The following options apply across all the `rpicam-apps` with similar or identical semantics, unless noted otherwise. ---- --help, -h Print help information for the application @@ -12,10 +12,10 @@ The `--help` option causes every application to print its full set of command li --version Print out a software version number ---- -All `libcamera-apps` will, when they see the `--version` option, print out a version string both for `libcamera` and `libcamera-apps` and then quit, for example: +All `rpicam-apps` will, when they see the `--version` option, print out a version string both for `libcamera` and `rpicam-apps` and then quit, for example: ---- -libcamera-apps build: ca559f46a97a 27-09-2021 (14:10:24) +rpicam-apps build: ca559f46a97a 27-09-2021 (14:10:24) libcamera build: v0.0.0+3058-c29143f7 ---- @@ -62,7 +62,7 @@ The `--camera` option will select which camera to use from the supplied Normally options are read from the command line, but in case multiple options are required it may be more convenient to keep them in a file. -Example: `libcamera-hello -c config.txt` +Example: `rpicam-hello -c config.txt` This is a text file containing individual lines of `key=value` pairs, for example: @@ -81,7 +81,7 @@ The `--timeout` option specifies how long the application runs before it stops, If unspecified, the default value is 5000 (5 seconds). The value zero causes the application to run indefinitely. -Example: `libcamera-hello -t 0` +Example: `rpicam-hello -t 0` ==== Preview window @@ -91,7 +91,7 @@ Example: `libcamera-hello -t 0` Sets the size and location of the preview window (both desktop and DRM versions). It does not affect the resolution or aspect ratio of images being requested from the camera. The camera images will be scaled to the size of the preview window for display, and will be pillar/letter-boxed to fit. -Example: `libcamera-hello -p 100,100,500,500` +Example: `rpicam-hello -p 100,100,500,500` image::images/preview_window.jpg[Letterboxed preview image] @@ -101,7 +101,7 @@ image::images/preview_window.jpg[Letterboxed preview image] Forces the preview window to use the whole screen, and the window will have no border or title bar. Again the image may be pillar/letter-boxed. -Example `libcamera-still -f -o test.jpg` +Example `rpicam-still -f -o test.jpg` ---- --qt-preview Use Qt-based preview window @@ -111,7 +111,7 @@ The preview window is switched to use the Qt-based implementation. This option i The Qt preview window does not support the `--fullscreen` option. Generally it is advised to try and keep the preview window small. -Example `libcamera-hello --qt-preview` +Example `rpicam-hello --qt-preview` ---- --nopreview, -n Do not display a preview window @@ -119,7 +119,7 @@ Example `libcamera-hello --qt-preview` The preview window is suppressed entirely. -Example `libcamera-still -n -o test.jpg` +Example `rpicam-still -n -o test.jpg` ---- --info-text Set window title bar text @@ -163,7 +163,7 @@ The supplied string is set as the title of the preview window (when running on a When not provided, the `--info-text` string defaults to `"#%frame (%fps fps) exp %exp ag %ag dg %dg"`. -Example: `libcamera-hello --info-text "Focus measure: %focus"` +Example: `rpicam-hello --info-text "Focus measure: %focus"` image::images/focus.jpg[Image showing focus measure] @@ -174,36 +174,36 @@ image::images/focus.jpg[Image showing focus measure] --height Capture image height ---- -These numbers specify the output resolution of the camera images captured by `libcamera-still`, `libcamera-jpeg` and `libcamera-vid`. +These numbers specify the output resolution of the camera images captured by `rpicam-still`, `rpicam-jpeg` and `rpicam-vid`. -For `libcamera-raw`, it affects the size of the raw frames captured. Where a camera has a 2x2 binned readout mode, specifying a resolution not larger than this binned mode will result in the capture of 2x2 binned raw frames. +For `rpicam-raw`, it affects the size of the raw frames captured. Where a camera has a 2x2 binned readout mode, specifying a resolution not larger than this binned mode will result in the capture of 2x2 binned raw frames. -For `libcamera-hello` these parameters have no effect. +For `rpicam-hello` these parameters have no effect. Examples: -`libcamera-vid -o test.h264 --width 1920 --height 1080` will capture 1080p video. +`rpicam-vid -o test.h264 --width 1920 --height 1080` will capture 1080p video. -`libcamera-still -r -o test.jpg --width 2028 --height 1520` will capture a 2028x1520 resolution JPEG. When using the HQ camera the sensor will be driven in its 2x2 binned mode so the raw file - captured in `test.dng` - will contain a 2028x1520 raw Bayer image. +`rpicam-still -r -o test.jpg --width 2028 --height 1520` will capture a 2028x1520 resolution JPEG. When using the HQ camera the sensor will be driven in its 2x2 binned mode so the raw file - captured in `test.dng` - will contain a 2028x1520 raw Bayer image. ---- --viewfinder-width Capture image width --viewfinder-height Capture image height ---- -These options affect only the preview (meaning both `libcamera-hello` and the preview phase of `libcamera-jpeg` and `libcamera-still`), and specify the image size that will be requested from the camera for the preview window. They have no effect on captured still images or videos. Nor do they affect the preview window as the images are resized to fit. +These options affect only the preview (meaning both `rpicam-hello` and the preview phase of `rpicam-jpeg` and `rpicam-still`), and specify the image size that will be requested from the camera for the preview window. They have no effect on captured still images or videos. Nor do they affect the preview window as the images are resized to fit. -Example: `libcamera-hello --viewfinder-width 640 --viewfinder-height 480` +Example: `rpicam-hello --viewfinder-width 640 --viewfinder-height 480` ---- --rawfull Force sensor to capture in full resolution mode ---- -This option forces the sensor to be driven in its full resolution readout mode for still and video capture, irrespective of the requested output resolution (given by `--width` and `--height`). It has no effect for `libcamera-hello`. +This option forces the sensor to be driven in its full resolution readout mode for still and video capture, irrespective of the requested output resolution (given by `--width` and `--height`). It has no effect for `rpicam-hello`. Using this option often incurs a frame rate penalty, as larger resolution frames are slower to read out. -Example: `libcamera-raw -t 2000 --segment 1 --rawfull -o test%03d.raw` will cause multiple full resolution raw frames to be captured. On the HQ camera each frame will be about 18MB in size. Without the `--rawfull` option the default video output resolution would have caused the 2x2 binned mode to be selected, resulting in 4.5MB raw frames. +Example: `rpicam-raw -t 2000 --segment 1 --rawfull -o test%03d.raw` will cause multiple full resolution raw frames to be captured. On the HQ camera each frame will be about 18MB in size. Without the `--rawfull` option the default video output resolution would have caused the 2x2 binned mode to be selected, resulting in 4.5MB raw frames. ---- --mode Specify sensor mode, given as ::: @@ -222,20 +222,20 @@ The `--mode` option affects the mode choice for video recording and stills captu --viewfinder-mode Specify sensor mode, given as ::: ---- -This option is identical to the `--mode` option except that it applies only during the preview phase of stills capture (also used by the `libcamera-hello` application). +This option is identical to the `--mode` option except that it applies only during the preview phase of stills capture (also used by the `rpicam-hello` application). ---- --lores-width Low resolution image width --lores-height Low resolution image height ---- -`libcamera` allows the possibility of delivering a second lower resolution image stream from the camera system to the application. This stream is available in both the preview and the video modes (i.e. `libcamera-hello` and the preview phase of `libcamera-still`, and `libcamera-vid`), and can be used, among other things, for image analysis. For stills captures, the low resolution image stream is not available. +`libcamera` allows the possibility of delivering a second lower resolution image stream from the camera system to the application. This stream is available in both the preview and the video modes (i.e. `rpicam-hello` and the preview phase of `rpicam-still`, and `rpicam-vid`), and can be used, among other things, for image analysis. For stills captures, the low resolution image stream is not available. The low resolution stream has the same field of view as the other image streams. If a different aspect ratio is specified for the low resolution stream, then those images will be squashed so that the pixels are no longer square. -During video recording (`libcamera-vid`), specifying a low resolution stream will disable some extra colour denoise processing that would normally occur. +During video recording (`rpicam-vid`), specifying a low resolution stream will disable some extra colour denoise processing that would normally occur. -Example: `libcamera-hello --lores-width 224 --lores-height 224` +Example: `rpicam-hello --lores-width 224 --lores-height 224` Note that the low resolution stream is not particularly useful unless used in conjunction with xref:camera_software.adoc#post-processing[image post-processing]. @@ -247,7 +247,7 @@ Note that the low resolution stream is not particularly useful unless used in co These options affect the order of read-out from the sensor, and can be used to mirror the image horizontally, and/or flip it vertically. The `--rotation` option permits only the value 0 or 180, so note that 90 or 270 degree rotations are not supported. Moreover, `--rotation 180` is identical to `--hflip --vflip`. -Example: `libcamera-hello --vflip --hflip` +Example: `rpicam-hello --vflip --hflip` ---- --roi Select a crop (region of interest) from the camera @@ -257,7 +257,7 @@ The `--roi` (region of interest) option allows the user to select a particular c The `--roi` parameter implements what is commonly referred to as "digital zoom". -Example `libcamera-hello --roi 0.25,0.25,0.5,0.5` will select exactly a quarter of the total number of pixels cropped from the centre of the image. +Example `rpicam-hello --roi 0.25,0.25,0.5,0.5` will select exactly a quarter of the total number of pixels cropped from the centre of the image. ---- --hdr Run the camera in HDR mode @@ -269,9 +269,9 @@ The `--hdr` option causes the camera to be run in the HDR (High Dynamic Range) m * `auto` - If the sensor supports HDR, then the on-sensor HDR mode is enabled. Otherwise, on Pi 5 devices, the Pi 5's on-chip HDR mode will be enabled. On a Pi 4 or earlier device, HDR will be disabled if the sensor does not support it. This mode will be applied if the `--hdr` option is supplied without a `` value. * `single-exp` - On a Pi 5, the on-chip HDR mode will be enabled, even if the sensor itself supports HDR. On earlier devices, HDR (even on-sensor HDR) will be disabled. -Example: `libcamera-still --hdr -o hdr.jpg` for capturing a still image, or `libcamera-vid --hdr -o hdr.h264` to capture a video. +Example: `rpicam-still --hdr -o hdr.jpg` for capturing a still image, or `rpicam-vid --hdr -o hdr.h264` to capture a video. -When sensors support on-sensor HDR, use of the that option may generally cause different camera modes to be available, and this can be checked by comparing the output of `libcamera-hello --list-cameras` with `libcamera-hello --hdr sensor --list-cameras`. +When sensors support on-sensor HDR, use of the that option may generally cause different camera modes to be available, and this can be checked by comparing the output of `rpicam-hello --list-cameras` with `rpicam-hello --hdr sensor --list-cameras`. NOTE: For the _Raspberry Pi Camera Module 3_, the non-HDR modes include the usual full resolution (12MP) mode as well as its half resolution 2x2 binned (3MP) equivalent. In the case of HDR, only a single half resolution (3MP) mode is available, and it is not possible to switch between HDR and non-HDR modes without restarting the camera application. @@ -285,7 +285,7 @@ The following options affect the image processing and control algorithms that af The given `` adjusts the image sharpness. The value zero means that no sharpening is applied, the value 1.0 uses the default amount of sharpening, and values greater than 1.0 use extra sharpening. -Example: `libcamera-still -o test.jpg --sharpness 2.0` +Example: `rpicam-still -o test.jpg --sharpness 2.0` ---- --contrast Set image contrast @@ -293,7 +293,7 @@ Example: `libcamera-still -o test.jpg --sharpness 2.0` The given `` adjusts the image contrast. The value zero produces minimum contrast, the value 1.0 uses the default amount of contrast, and values greater than 1.0 apply extra contrast. -Example: `libcamera-still -o test.jpg --contrast 1.5` +Example: `rpicam-still -o test.jpg --contrast 1.5` ---- --brightness Set image brightness @@ -303,7 +303,7 @@ The given `` adjusts the image brightness. The value -1.0 produces an (a Note that the brightness parameter adds (or subtracts) an offset from all pixels in the output image. The `--ev` option is often more appropriate. -Example: `libcamera-still -o test.jpg --brightness 0.2` +Example: `rpicam-still -o test.jpg --brightness 0.2` ---- --saturation Set image colour saturation @@ -311,7 +311,7 @@ Example: `libcamera-still -o test.jpg --brightness 0.2` The given `` adjusts the colour saturation. The value zero produces a greyscale image, the value 1.0 uses the default amount of sautration, and values greater than 1.0 apply extra colour saturation. -Example: `libcamera-still -o test.jpg --saturation 0.8` +Example: `rpicam-still -o test.jpg --saturation 0.8` ---- --ev Set EV compensation @@ -319,7 +319,7 @@ Example: `libcamera-still -o test.jpg --saturation 0.8` Sets the EV compensation of the image in units of _stops_, in the range -10 to 10. Default is 0. It works by raising or lowering the target values the AEC/AGC algorithm is attempting to match. -Example: `libcamera-still -o test.jpg --ev 0.3` +Example: `rpicam-still -o test.jpg --ev 0.3` ---- --shutter Set the exposure time in microseconds @@ -331,7 +331,7 @@ Note that this shutter time may not be achieved if the camera is running at a fr Using values above these maximums will result in undefined behaviour. Cameras will also have different minimum shutter times, though in practice this is not important as they are all low enough to expose bright scenes appropriately. -Example: `libcamera-hello --shutter 30000` +Example: `rpicam-hello --shutter 30000` ---- --gain Sets the combined analogue and digital gains @@ -358,7 +358,7 @@ Sets the metering mode of the AEC/AGC algorithm. This may one of the following v For more information on defining a custom metering mode, and also on how to adjust the region weights in the existing metering modes, please refer to the https://datasheets.raspberrypi.com/camera/raspberry-pi-camera-guide.pdf[Tuning guide for the Raspberry Pi cameras and libcamera]. -Example: `libcamera-still -o test.jpg --metering spot` +Example: `rpicam-still -o test.jpg --metering spot` ---- --exposure Set the exposure profile @@ -368,7 +368,7 @@ The exposure profile may be either `normal`, `sport` or `long`. Changing the exp Exposure profiles can be edited in the camera tuning file. Please refer to the https://datasheets.raspberrypi.com/camera/raspberry-pi-camera-guide.pdf[Tuning guide for the Raspberry Pi cameras and libcamera] for more information. -Example: `libcamera-still -o test.jpg --exposure sport` +Example: `rpicam-still -o test.jpg --exposure sport` ---- --awb Set the AWB mode @@ -410,7 +410,7 @@ Note that these values are only approximate, the values could vary according to For more information on AWB modes and how to define a custom one, please refer to the https://datasheets.raspberrypi.com/camera/raspberry-pi-camera-guide.pdf[Tuning guide for the Raspberry Pi cameras and libcamera]. -Example: `libcamera-still -o test.jpg --awb tungsten` +Example: `rpicam-still -o test.jpg --awb tungsten` ---- --awbgains Set fixed colour gains @@ -418,7 +418,7 @@ Example: `libcamera-still -o test.jpg --awb tungsten` This option accepts a red and a blue gain value and uses them directly in place of running the AWB algorithm. Setting non-zero values here has the effect of disabling the AWB calculation. -Example: `libcamera-still -o test.jpg --awbgains 1.5,2.0` +Example: `rpicam-still -o test.jpg --awbgains 1.5,2.0` ---- --denoise Set the denoising mode @@ -438,7 +438,7 @@ The following denoise modes are supported: Note that even the use of fast colour denoise can result in lower framerates. The high quality colour denoise will normally result in much lower framerates. -Example: `libcamera-vid -o test.h264 --denoise cdn_off` +Example: `rpicam-vid -o test.h264 --denoise cdn_off` ---- --tuning-file Specify the camera tuning to use @@ -448,7 +448,7 @@ This identifies the name of the JSON format tuning file that should be used. The For more information on the camera tuning file, please consult the https://datasheets.raspberrypi.com/camera/raspberry-pi-camera-guide.pdf[Tuning guide for the Raspberry Pi cameras and libcamera]. -Example: `libcamera-hello --tuning-file ~/my-camera-tuning.json` +Example: `rpicam-hello --tuning-file ~/my-camera-tuning.json` ---- --autofocus-mode Specify the autofocus mode @@ -458,7 +458,7 @@ Specifies the autofocus mode to use, which may be one of * `default` (also the default if the option is omitted) - normally puts the camera into continuous autofocus mode, except if either `--lens-position` or `--autofocus-on-capture` is given, in which case manual mode is chosen instead * `manual` - do not move the lens at all, but it can be set with the `--lens-position` option -* `auto` - does not move the lens except for an autofocus sweep when the camera starts (and for `libcamera-still`, just before capture if `--autofocus-on-capture` is given) +* `auto` - does not move the lens except for an autofocus sweep when the camera starts (and for `rpicam-still`, just before capture if `--autofocus-on-capture` is given) * `continuous` - adjusts the lens position automatically as the scene changes. This option is only supported for certain camera modules (such as the _Raspberry Pi Camera Module 3_). @@ -526,9 +526,9 @@ This option is only supported for certain camera modules (such as the _Raspberry Examples: -`libcamera-vid -t 100000 --segment 10000 -o chunk%04d.h264` records a 100 second file in 10 second segments, where each file is named `chunk.h264` but with the inclusion of an incrementing counter. Note that `%04d` writes the count to a string, but padded up to a total width of at least 4 characters by adding leading zeroes. +`rpicam-vid -t 100000 --segment 10000 -o chunk%04d.h264` records a 100 second file in 10 second segments, where each file is named `chunk.h264` but with the inclusion of an incrementing counter. Note that `%04d` writes the count to a string, but padded up to a total width of at least 4 characters by adding leading zeroes. -`libcamera-vid -t 0 --inline -o udp://192.168.1.13:5000` stream H.264 video to network address 192.168.1.13 on port 5000. +`rpicam-vid -t 0 --inline -o udp://192.168.1.13:5000` stream H.264 video to network address 192.168.1.13 on port 5000. ---- --wrap Wrap output file counter at @@ -536,7 +536,7 @@ Examples: When outputting to files with an incrementing counter (e.g. `%d` in the output file name), wrap the counter back to zero when it reaches this value. -Example: `libcamera-vid -t 0 --codec mjpeg --segment 1 --wrap 100 -o image%d.jpg` +Example: `rpicam-vid -t 0 --codec mjpeg --segment 1 --wrap 100 -o image%d.jpg` ---- --flush Flush output files immediately @@ -544,7 +544,7 @@ Example: `libcamera-vid -t 0 --codec mjpeg --segment 1 --wrap 100 -o image%d.jpg `--flush` causes output files to be flushed to disk as soon as every frame is written, rather than waiting for the system to do it. -Example: `libcamera-vid -t 10000 --flush -o test.h264` +Example: `rpicam-vid -t 10000 --flush -o test.h264` ==== Post Processing Options @@ -552,6 +552,6 @@ The `--post-process-file` option specifies a JSON file that configures the post- Post-processing is a large topic and admits the use of 3rd party software like OpenCV and TensorFlowLite to analyse and manipulate images. For more information, please refer to the section on xref:camera_software.adoc#post-processing[post-processing]. -Example: `libcamera-hello --post-process-file negate.json` +Example: `rpicam-hello --post-process-file negate.json` This might apply a "negate" effect to an image, if the file `negate.json` is appropriately configured. diff --git a/documentation/asciidoc/computers/camera/libcamera_options_still.adoc b/documentation/asciidoc/computers/camera/rpicam_options_still.adoc similarity index 68% rename from documentation/asciidoc/computers/camera/libcamera_options_still.adoc rename to documentation/asciidoc/computers/camera/rpicam_options_still.adoc index 62a74249eb..fddb156251 100644 --- a/documentation/asciidoc/computers/camera/libcamera_options_still.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_options_still.adoc @@ -6,7 +6,7 @@ Set the JPEG quality. 100 is maximum quality and 93 is the default. Only applies when saving JPEG files. -Example: `libcamera-jpeg -o test.jpg -q 80` +Example: `rpicam-jpeg -o test.jpg -q 80` ---- --exif, -x Add extra EXIF tags @@ -18,15 +18,15 @@ EXIF is supported using the `libexif` library and so there are some associated l Clearly the application needs to supply EXIF tags that contain specific camera data (like the exposure time). But for other tags that have nothing to do with the camera, a reasonable workaround would simply be to add them _post facto_, using something like `exiftool`. -Example: `libcamera-still -o test.jpg --exif IDO0.Artist=Someone` +Example: `rpicam-still -o test.jpg --exif IDO0.Artist=Someone` ---- --timelapse Time interval between timelapse captures ---- -This puts `libcamera-still` into timelapse mode where it runs according to the timeout (`--timeout` or `-t`) that has been set, and for that period will capture repeated images at the interval specified here. (`libcamera-still` only.) +This puts `rpicam-still` into timelapse mode where it runs according to the timeout (`--timeout` or `-t`) that has been set, and for that period will capture repeated images at the interval specified here. (`rpicam-still` only.) -Example: `libcamera-still -t 100000 -o test%d.jpg --timelapse 10000` captures an image every 10s for about 100s. +Example: `rpicam-still -t 100000 -o test%d.jpg --timelapse 10000` captures an image every 10s for about 100s. ---- --framestart The starting value for the frame counter @@ -34,23 +34,23 @@ Example: `libcamera-still -t 100000 -o test%d.jpg --timelapse 10000` captures an When writing counter values into the output file name, this specifies the starting value for the counter. -Example: `libcamera-still -t 100000 -o test%d.jpg --timelapse 10000 --framestart 1` captures an image every 10s for about 100s, starting at 1 rather than 0. (`libcamera-still` only.) +Example: `rpicam-still -t 100000 -o test%d.jpg --timelapse 10000 --framestart 1` captures an image every 10s for about 100s, starting at 1 rather than 0. (`rpicam-still` only.) ---- --datetime Use date format for the output file names ---- -Use the current date and time to construct the output file name, in the form MMDDhhmmss.jpg, where MM = 2-digit month number, DD = 2-digit day number, hh = 2-digit 24-hour hour number, mm = 2-digit minute number, ss = 2-digit second number. (`libcamera-still` only.) +Use the current date and time to construct the output file name, in the form MMDDhhmmss.jpg, where MM = 2-digit month number, DD = 2-digit day number, hh = 2-digit 24-hour hour number, mm = 2-digit minute number, ss = 2-digit second number. (`rpicam-still` only.) -Example: `libcamera-still --datetime` +Example: `rpicam-still --datetime` ---- --timestamp Use system timestamps for the output file names ---- -Uses the current system timestamp (the number of seconds since the start of 1970) as the output file name. (`libcamera-still` only.) +Uses the current system timestamp (the number of seconds since the start of 1970) as the output file name. (`rpicam-still` only.) -Example: `libcamera-still --timestamp` +Example: `rpicam-still --timestamp` ---- --restart Set the JPEG restart interval @@ -58,25 +58,25 @@ Example: `libcamera-still --timestamp` Sets the JPEG restart interval to the given value. Default is zero. -Example: `libcamera-still -o test.jpg --restart 20` +Example: `rpicam-still -o test.jpg --restart 20` ---- --keypress, -k Capture image when Enter pressed ---- -This switches `libcamera-still` into keypress mode. It will capture a still image either when the timeout expires or the Enter key is pressed in the terminal window. Typing `x` and Enter causes `libcamera-still` to quit without capturing. +This switches `rpicam-still` into keypress mode. It will capture a still image either when the timeout expires or the Enter key is pressed in the terminal window. Typing `x` and Enter causes `rpicam-still` to quit without capturing. -Example: `libcamera-still -t 0 -o test.jpg -k` +Example: `rpicam-still -t 0 -o test.jpg -k` ---- --signal, -s Capture image when SIGUSR1 received ---- -This switches `libcamera-still` into signal mode. It will capture a still image either when the timeout expires or a SIGUSR1 is received. SIGUSR2 will cause `libcamera-still` to quit without capturing. +This switches `rpicam-still` into signal mode. It will capture a still image either when the timeout expires or a SIGUSR1 is received. SIGUSR2 will cause `rpicam-still` to quit without capturing. Example: -`libcamera-still -t 0 -o test.jpg -s &` +`rpicam-still -t 0 -o test.jpg -s &` then @@ -88,7 +88,7 @@ then Sets the dimensions and quality parameter of the associated thumbnail image. The defaults are size 320x240 and quality 70. -Example: `libcamera-still -o test.jpg --thumb 640:480:80` +Example: `rpicam-still -o test.jpg --thumb 640:480:80` The value `none` may be given, in which case no thumbnail is saved in the image at all. @@ -104,15 +104,15 @@ Select the still image encoding to be used. Valid encoders are: * `rgb` - binary dump of uncompressed RGB pixels * `yuv420` - binary dump of uncompressed YUV420 pixels. -Note that this option determines the encoding and that the extension of the output file name is ignored for this purpose. However, for the `--datetime` and `--timestamp` options, the file extension is taken from the encoder name listed above. (`libcamera-still` only.) +Note that this option determines the encoding and that the extension of the output file name is ignored for this purpose. However, for the `--datetime` and `--timestamp` options, the file extension is taken from the encoder name listed above. (`rpicam-still` only.) -Example: `libcamera-still -e png -o test.png` +Example: `rpicam-still -e png -o test.png` ---- --raw, -r Save raw file ---- -Save a raw Bayer file in DNG format alongside the usual output image. The file name is given by replacing the output file name extension by `.dng`. These are standard DNG files, and can be processed with standard tools like _dcraw_ or _RawTherapee_, among others. (`libcamera-still` only.) +Save a raw Bayer file in DNG format alongside the usual output image. The file name is given by replacing the output file name extension by `.dng`. These are standard DNG files, and can be processed with standard tools like _dcraw_ or _RawTherapee_, among others. (`rpicam-still` only.) The image data in the raw file is exactly what came out of the sensor, with no processing whatsoever either by the ISP or anything else. The EXIF data saved in the file, among other things, includes: @@ -125,9 +125,9 @@ The image data in the raw file is exactly what came out of the sensor, with no p --latest Make symbolic link to latest file saved ---- -This causes `libcamera-still` to make a symbolic link to the most recently saved file, thereby making it easier to identify. (`libcamera-still` only.) +This causes `rpicam-still` to make a symbolic link to the most recently saved file, thereby making it easier to identify. (`rpicam-still` only.) -Example: `libcamera-still -t 100000 --timelapse 10000 -o test%d.jpg --latest latest.jpg` +Example: `rpicam-still -t 100000 --timelapse 10000 -o test%d.jpg --latest latest.jpg` ---- --autofocus-on-capture Whether to run an autofocus cycle before capture @@ -143,6 +143,6 @@ If `--autofocus-mode` was set to `continuous`, this option will be ignored. You can also use `--autofocus-on-capture 1` in place of `--autofocus-on-capture`, and `--autofocus-on-capture 0` as an alternative to omitting the parameter entirely. -Example: `libcamera-still --autofocus-on-capture -o test.jpg` +Example: `rpicam-still --autofocus-on-capture -o test.jpg` This option is only supported for certain camera modules (such as the _Raspberry Pi Camera Module 3_). diff --git a/documentation/asciidoc/computers/camera/libcamera_options_vid.adoc b/documentation/asciidoc/computers/camera/rpicam_options_vid.adoc similarity index 64% rename from documentation/asciidoc/computers/camera/libcamera_options_vid.adoc rename to documentation/asciidoc/computers/camera/rpicam_options_vid.adoc index 14c664f377..26e739523f 100644 --- a/documentation/asciidoc/computers/camera/libcamera_options_vid.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_options_vid.adoc @@ -6,7 +6,7 @@ Set the JPEG quality. 100 is maximum quality and 50 is the default. Only applies when saving in MJPEG format. -Example: `libcamera-vid --codec mjpeg -o test.mjpeg -q 80` +Example: `rpicam-vid --codec mjpeg -o test.mjpeg -q 80` ---- --bitrate, -b H.264 bitrate @@ -14,7 +14,7 @@ Example: `libcamera-vid --codec mjpeg -o test.mjpeg -q 80` Set the target bitrate for the H.264 encoder, in _bits per second_. Only applies when encoding in H.264 format. -Example: `libcamera-vid -b 10000000 --width 1920 --height 1080 -o test.h264` +Example: `rpicam-vid -b 10000000 --width 1920 --height 1080 -o test.h264` ---- --intra, -g Intra-frame period (H.264 only) @@ -22,7 +22,7 @@ Example: `libcamera-vid -b 10000000 --width 1920 --height 1080 -o test.h264` Sets the frequency of I (Intra) frames in the H.264 bitstream, as a number of frames. The default value is 60. -Example: `libcamera-vid --intra 30 --width 1920 --height 1080 -o test.h264` +Example: `rpicam-vid --intra 30 --width 1920 --height 1080 -o test.h264` ---- --profile H.264 profile @@ -30,7 +30,7 @@ Example: `libcamera-vid --intra 30 --width 1920 --height 1080 -o test.h264` Set the H.264 profile. The value may be `baseline`, `main` or `high`. -Example: `libcamera-vid --width 1920 --height 1080 --profile main -o test.h264` +Example: `rpicam-vid --width 1920 --height 1080 --profile main -o test.h264` ---- --level H.264 level @@ -38,7 +38,7 @@ Example: `libcamera-vid --width 1920 --height 1080 --profile main -o test.h264` Set the H.264 level. The value may be `4`, `4.1` or `4.2`. -Example: `libcamera-vid --width 1920 --height 1080 --level 4.1 -o test.h264` +Example: `rpicam-vid --width 1920 --height 1080 --level 4.1 -o test.h264` ---- --codec Encoder to be used @@ -49,31 +49,31 @@ This can select how the video frames are encoded. Valid options are: * h264 - use H.264 encoder (the default) * mjpeg - use MJPEG encoder * yuv420 - output uncompressed YUV420 frames. -* libav - use the libav backend to encode audio and video (see the xref:camera_software.adoc#libav-integration-with-libcamera-vid[libav section] for further details). +* libav - use the libav backend to encode audio and video (see the xref:camera_software.adoc#libav-integration-with-rpicam-vid[libav section] for further details). Examples: -`libcamera-vid -t 10000 --codec mjpeg -o test.mjpeg` +`rpicam-vid -t 10000 --codec mjpeg -o test.mjpeg` -`libcamera-vid -t 10000 --codec yuv420 -o test.data` +`rpicam-vid -t 10000 --codec yuv420 -o test.data` ---- --keypress, -k Toggle between recording and pausing ---- -Pressing Enter will toggle `libcamera-vid` between recording the video stream and not recording it (i.e. discarding it). The application starts off in the recording state, unless the `--initial` option specifies otherwise. Typing `x` and Enter causes `libcamera-vid` to quit. +Pressing Enter will toggle `rpicam-vid` between recording the video stream and not recording it (i.e. discarding it). The application starts off in the recording state, unless the `--initial` option specifies otherwise. Typing `x` and Enter causes `rpicam-vid` to quit. -Example: `libcamera-vid -t 0 -o test.h264 -k` +Example: `rpicam-vid -t 0 -o test.h264 -k` ---- --signal, -s Toggle between recording and pausing when SIGUSR1 received ---- -The SIGUSR1 signal will toggle `libcamera-vid` between recording the video stream and not recording it (i.e. discarding it). The application starts off in the recording state, unless the `--initial` option specifies otherwise. SIGUSR2 causes `libcamera-vid` to quit. +The SIGUSR1 signal will toggle `rpicam-vid` between recording the video stream and not recording it (i.e. discarding it). The application starts off in the recording state, unless the `--initial` option specifies otherwise. SIGUSR2 causes `rpicam-vid` to quit. Example: -`libcamera-vid -t 0 -o test.h264 -s` +`rpicam-vid -t 0 -o test.h264 -s` then @@ -85,7 +85,7 @@ then The value passed may be `record` or `pause` to start the application in, respectively, the recording or the paused state. This option should be used in conjunction with either `--keypress` or `--signal` to toggle between the two states. -Example: `libcamera-vid -t 0 -o test.h264 -k --initial pause` +Example: `rpicam-vid -t 0 -o test.h264 -k --initial pause` ---- --split Split multiple recordings into separate files @@ -93,7 +93,7 @@ Example: `libcamera-vid -t 0 -o test.h264 -k --initial pause` This option should be used in conjunction with `--keypress` or `--signal` and causes each recording session (in between the pauses) to be written to a separate file. -Example: `libcamera-vid -t 0 --keypress --split --initial pause -o test%04d.h264` +Example: `rpicam-vid -t 0 --keypress --split --initial pause -o test%04d.h264` ---- --segment Write the video recording into multiple segments @@ -101,9 +101,9 @@ Example: `libcamera-vid -t 0 --keypress --split --initial pause -o test%04d.h264 This option causes the video recording to be split across multiple files where the parameter gives the approximate duration of each file in milliseconds. -One convenient little trick is to pass a very small duration parameter (namely, `--segment 1`) which will result in each frame being written to a separate output file. This makes it easy to do "burst" JPEG capture (using the MJPEG codec), or "burst" raw frame capture (using `libcamera-raw`). +One convenient little trick is to pass a very small duration parameter (namely, `--segment 1`) which will result in each frame being written to a separate output file. This makes it easy to do "burst" JPEG capture (using the MJPEG codec), or "burst" raw frame capture (using `rpicam-raw`). -Example: `libcamera-vid -t 100000 --segment 10000 -o test%04d.h264` +Example: `rpicam-vid -t 100000 --segment 10000 -o test%04d.h264` ---- --circular Write the video recording into a circular buffer of the given @@ -111,7 +111,7 @@ Example: `libcamera-vid -t 100000 --segment 10000 -o test%04d.h264` The video recording is written to a circular buffer which is written to disk when the application quits. The size of the circular buffer may be given in units of megabytes, defaulting to 4MB. -Example: `libcamera-vid -t 0 --keypress --inline --circular -o test.h264` +Example: `rpicam-vid -t 0 --keypress --inline --circular -o test.h264` ---- --inline Write sequence header in every I frame (H.264 only) @@ -119,15 +119,15 @@ Example: `libcamera-vid -t 0 --keypress --inline --circular -o test.h264` This option causes the H.264 sequence headers to be written into every I (Intra) frame. This is helpful because it means a client can understand and decode the video sequence from any I frame, not just from the very beginning of the stream. It is recommended to use this option with any output type that breaks the output into pieces (`--segment`, `--split`, `--circular`), or transmits the output over a network. -Example: `libcamera-vid -t 0 --keypress --inline --split -o test%04d.h264` +Example: `rpicam-vid -t 0 --keypress --inline --split -o test%04d.h264` ---- --listen Wait for an incoming TCP connection ---- -This option is provided for streaming over a network using TCP/IP. Using `--listen` will cause `libcamera-vid` to wait for an incoming client connection before starting the video encode process, which will then be forwarded to that client. +This option is provided for streaming over a network using TCP/IP. Using `--listen` will cause `rpicam-vid` to wait for an incoming client connection before starting the video encode process, which will then be forwarded to that client. -Example: `libcamera-vid -t 0 --inline --listen -o tcp://0.0.0.0:8123` +Example: `rpicam-vid -t 0 --inline --listen -o tcp://0.0.0.0:8123` ---- --frames Record exactly this many frames @@ -135,4 +135,4 @@ Example: `libcamera-vid -t 0 --inline --listen -o tcp://0.0.0.0:8123` Exactly `` frames are recorded. Specifying a non-zero value will override any timeout. -Example: `libcamera-vid -o test.h264 --frames 1000` +Example: `rpicam-vid -o test.h264 --frames 1000` diff --git a/documentation/asciidoc/computers/camera/rpicam_raw.adoc b/documentation/asciidoc/computers/camera/rpicam_raw.adoc new file mode 100644 index 0000000000..ec9f55bad9 --- /dev/null +++ b/documentation/asciidoc/computers/camera/rpicam_raw.adoc @@ -0,0 +1,23 @@ +=== `rpicam-raw` + +`rpicam-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 + +[,bash] +---- +rpicam-raw -t 2000 -o test.raw +---- + +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. + +By default the raw frames are saved in a single (potentially very large) file. As we saw previously, the `--segment` option can be used conveniently to direct each to a separate file. +[,bash] +---- +rpicam-raw -t 2000 --segment 1 -o test%05d.raw +---- + +In good conditions (using a fast SSD) `rpicam-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 `rpicam-still`). If you want to be sure not to drop frames you could reduce the framerate slightly using the `--framerate` option, for example + +[,bash] +---- +rpicam-raw -t 5000 --width 4056 --height 3040 -o test.raw --framerate 8 +---- diff --git a/documentation/asciidoc/computers/camera/libcamera_still.adoc b/documentation/asciidoc/computers/camera/rpicam_still.adoc similarity index 83% rename from documentation/asciidoc/computers/camera/libcamera_still.adoc rename to documentation/asciidoc/computers/camera/rpicam_still.adoc index b70c728392..52e1d05b56 100644 --- a/documentation/asciidoc/computers/camera/libcamera_still.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_still.adoc @@ -1,22 +1,22 @@ -=== `libcamera-still` +=== `rpicam-still` -`libcamera-still` is very similar to `libcamera-jpeg` but supports more of the legacy `raspistill` options. As before, a single image can be captured with +`rpicam-still` is very similar to `rpicam-jpeg` but supports more of the legacy `raspistill` options. As before, a single image can be captured with [,bash] ---- -libcamera-still -o test.jpg +rpicam-still -o test.jpg ---- ==== Encoders -`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. +`rpicam-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. [,bash] ---- -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 +rpicam-still -e png -o test.png +rpicam-still -e bmp -o test.bmp +rpicam-still -e rgb -o test.data +rpicam-still -e yuv420 -o test.data ---- Note that the format in which the image is saved depends on the `-e` (equivalently `--encoding`) option and is _not_ selected automatically based on the output file name. @@ -28,7 +28,7 @@ To capture a raw image use [,bash] ---- -libcamera-still -r -o test.jpg +rpicam-still -r -o test.jpg ---- Here, the `-r` option (also `--raw`) indicates to capture the raw image as well as the JPEG. In fact, the raw image is the exact image from which the JPEG was produced. Raw images are saved in DNG (Adobe Digital Negative) format and are compatible with many standard applications, such as _dcraw_ or _RawTherapee_. The raw image is saved to a file with the same name but the extension `.dng`, thus `test.dng` in this case. @@ -50,7 +50,7 @@ Exif Byte Order : Little-endian (Intel, II) Make : Raspberry Pi Camera Model Name : /base/soc/i2c0mux/i2c@1/imx477@1a Orientation : Horizontal (normal) -Software : libcamera-still +Software : rpicam-still Subfile Type : Full-resolution Image Image Width : 4056 Image Height : 3040 @@ -87,6 +87,6 @@ To capture very long exposure images, we need to be careful to disable the AEC/A So to perform a 100 second exposure capture, use -`libcamera-still -o long_exposure.jpg --shutter 100000000 --gain 1 --awbgains 1,1 --immediate` +`rpicam-still -o long_exposure.jpg --shutter 100000000 --gain 1 --awbgains 1,1 --immediate` For reference, the maximum exposure times of the three official Raspberry Pi cameras can be found in xref:../accessories/camera.adoc#hardware-specification[this table]. diff --git a/documentation/asciidoc/computers/camera/libcamera_vid.adoc b/documentation/asciidoc/computers/camera/rpicam_vid.adoc similarity index 76% rename from documentation/asciidoc/computers/camera/libcamera_vid.adoc rename to documentation/asciidoc/computers/camera/rpicam_vid.adoc index 41fbea80de..bd71d4a9e7 100644 --- a/documentation/asciidoc/computers/camera/libcamera_vid.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_vid.adoc @@ -1,10 +1,10 @@ -=== `libcamera-vid` +=== `rpicam-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. For example, to write a 10 second video to file use +`rpicam-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. For example, to write a 10 second video to file use [,bash] ---- -libcamera-vid -t 10000 -o test.h264 +rpicam-vid -t 10000 -o test.h264 ---- The resulting file can be played with `vlc` (among other applications) [,bash] @@ -13,7 +13,7 @@ vlc test.h264 ---- 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 using a tool like `mkvmerge`. -`libcamera-vid -o test.h264 --save-pts timestamps.txt` +`rpicam-vid -o test.h264 --save-pts timestamps.txt` and then if you want an _mkv_ file: @@ -24,28 +24,28 @@ and then if you want an _mkv_ file: There is support for motion JPEG, and also for uncompressed and unformatted YUV420, for example [,bash] ---- -libcamera-vid -t 10000 --codec mjpeg -o test.mjpeg -libcamera-vid -t 10000 --codec yuv420 -o test.data +rpicam-vid -t 10000 --codec mjpeg -o test.mjpeg +rpicam-vid -t 10000 --codec yuv420 -o test.data ---- In both cases the `--codec` parameter determines the output format, not the extension of the output file. 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. [,bash] ---- -libcamera-vid -t 10000 --codec mjpeg --segment 1 -o test%05d.jpeg +rpicam-vid -t 10000 --codec mjpeg --segment 1 -o test%05d.jpeg ---- Observe that the output file name is normally only sensible if we avoid over-writing the previous file every time, such as by using a file name that includes a counter (as above). More information on output file names is available below. ==== Network Streaming -NOTE: This section describes native streaming from `libcamera-vid`. However, it is also possible to use the libav backend for network streaming. See the xref:camera_software.adoc#libav-integration-with-libcamera-vid[libav section] for further details. +NOTE: This section describes native streaming from `rpicam-vid`. However, it is also possible to use the libav backend for network streaming. See the xref:camera_software.adoc#libav-integration-with-rpicam-vid[libav section] for further details. ===== UDP To stream video using UDP, on the Raspberry Pi (server) use [,bash] ---- -libcamera-vid -t 0 --inline -o udp://: +rpicam-vid -t 0 --inline -o udp://: ---- where `` is the IP address of the client, or multicast address (if appropriately configured to reach the client). On the client use (for example) [,bash] @@ -63,7 +63,7 @@ with the same `` value. Video can be streamed using TCP. To use the Raspberry Pi as a server [,bash] ---- -libcamera-vid -t 0 --inline --listen -o tcp://0.0.0.0: +rpicam-vid -t 0 --inline --listen -o tcp://0.0.0.0: ---- and on the client [,bash] @@ -83,7 +83,7 @@ The Raspberry Pi will wait until the client connects, and then start streaming v vlc is useful on the Raspberry Pi for formatting an RTSP stream, though there are other RTSP servers available. [,bash] ---- -libcamera-vid -t 0 --inline -o - | cvlc stream:///dev/stdin --sout '#rtp{sdp=rtsp://:8554/stream1}' :demux=h264 +rpicam-vid -t 0 --inline -o - | cvlc stream:///dev/stdin --sout '#rtp{sdp=rtsp://:8554/stream1}' :demux=h264 ---- and this can be played with [,bash] @@ -101,7 +101,7 @@ NOTE: Recent versions of VLC seem to have problems with playback of H.264 stream ==== High framerate capture -Using `libcamera-vid` to capture high framerate video (generally anything over 60 fps) while minimising frame drops requires a few considerations: +Using `rpicam-vid` to capture high framerate video (generally anything over 60 fps) while minimising frame drops requires a few considerations: 1. The https://en.wikipedia.org/wiki/Advanced_Video_Coding#Levels[H.264 target level] must be set to 4.2 with the `--level 4.2` argument. 2. Software colour denoise processing must be turned off with the `--denoise cdn_off` argument. @@ -114,5 +114,5 @@ An example command for 1280x720 120fps video encode would be: [,bash] ---- -libcamera-vid --level 4.2 --framerate 120 --width 1280 --height 720 --save-pts timestamp.pts -o video.264 -t 10000 --denoise cdn_off -n +rpicam-vid --level 4.2 --framerate 120 --width 1280 --height 720 --save-pts timestamp.pts -o video.264 -t 10000 --denoise cdn_off -n ---- \ No newline at end of file diff --git a/documentation/asciidoc/computers/camera/timelapse.adoc b/documentation/asciidoc/computers/camera/timelapse.adoc index 7e2915c4b4..61fee3deee 100644 --- a/documentation/asciidoc/computers/camera/timelapse.adoc +++ b/documentation/asciidoc/computers/camera/timelapse.adoc @@ -4,12 +4,12 @@ To create a time-lapse video, you simply configure the Raspberry Pi to take a picture at a regular interval, such as once a minute, then use an application to stitch the pictures together into a video. -==== Using `libcamera-still` Timelapse Mode +==== Using `rpicam-still` Timelapse Mode -`libcamera-still` has a built in time-lapse mode, using the `--timelapse` command line switch. The value that follows the switch is the time between shots in milliseconds: +`rpicam-still` has a built in time-lapse mode, using the `--timelapse` command line switch. The value that follows the switch is the time between shots in milliseconds: ---- -libcamera-still -t 30000 --timelapse 2000 -o image%04d.jpg +rpicam-still -t 30000 --timelapse 2000 -o image%04d.jpg ---- [NOTE] @@ -28,7 +28,7 @@ A good way to automate taking a picture at a regular interval is running a scrip ---- #!/bin/bash DATE=$(date +"%Y-%m-%d_%H%M") -libcamera-still -o /home/pi/camera/$DATE.jpg +rpicam-still -o /home/pi/camera/$DATE.jpg ---- and save it as `camera.sh`. You'll need to make the script executable: diff --git a/documentation/asciidoc/computers/camera_software.adoc b/documentation/asciidoc/computers/camera_software.adoc index 395dce5429..1d0581a995 100644 --- a/documentation/asciidoc/computers/camera_software.adoc +++ b/documentation/asciidoc/computers/camera_software.adoc @@ -1,46 +1,46 @@ include::camera/camera_usage.adoc[] -include::camera/libcamera_apps_intro.adoc[] +include::camera/rpicam_apps_intro.adoc[] -include::camera/libcamera_apps_getting_started.adoc[] +include::camera/rpicam_apps_getting_started.adoc[] -include::camera/libcamera_hello.adoc[] +include::camera/rpicam_hello.adoc[] -include::camera/libcamera_jpeg.adoc[] +include::camera/rpicam_jpeg.adoc[] -include::camera/libcamera_still.adoc[] +include::camera/rpicam_still.adoc[] -include::camera/libcamera_vid.adoc[] +include::camera/rpicam_vid.adoc[] -include::camera/libcamera_apps_libav.adoc[] +include::camera/rpicam_apps_libav.adoc[] -include::camera/libcamera_raw.adoc[] +include::camera/rpicam_raw.adoc[] -include::camera/libcamera_detect.adoc[] +include::camera/rpicam_detect.adoc[] -include::camera/libcamera_options_common.adoc[] +include::camera/rpicam_options_common.adoc[] -include::camera/libcamera_options_still.adoc[] +include::camera/rpicam_options_still.adoc[] -include::camera/libcamera_options_vid.adoc[] +include::camera/rpicam_options_vid.adoc[] include::camera/libcamera_differences.adoc[] -include::camera/libcamera_apps_post_processing.adoc[] +include::camera/rpicam_apps_post_processing.adoc[] -include::camera/libcamera_apps_post_processing_opencv.adoc[] +include::camera/rpicam_apps_post_processing_opencv.adoc[] -include::camera/libcamera_apps_post_processing_tflite.adoc[] +include::camera/rpicam_apps_post_processing_tflite.adoc[] -include::camera/libcamera_apps_post_processing_writing.adoc[] +include::camera/rpicam_apps_post_processing_writing.adoc[] -include::camera/libcamera_apps_multicam.adoc[] +include::camera/rpicam_apps_multicam.adoc[] -include::camera/libcamera_apps_packages.adoc[] +include::camera/rpicam_apps_packages.adoc[] -include::camera/libcamera_apps_building.adoc[] +include::camera/rpicam_apps_building.adoc[] -include::camera/libcamera_apps_writing.adoc[] +include::camera/rpicam_apps_writing.adoc[] include::camera/libcamera_python.adoc[] @@ -48,7 +48,7 @@ include::camera/libcamera_3rd_party_tuning.adoc[] include::camera/libcamera_known_issues.adoc[] -include::camera/libcamera_apps_getting_help.adoc[] +include::camera/rpicam_apps_getting_help.adoc[] include::camera/timelapse.adoc[] @@ -59,5 +59,3 @@ include::camera/qt.adoc[] include::camera/v4l2.adoc[] include::camera/csi-2-usage.adoc[] - - diff --git a/documentation/asciidoc/computers/compute-module/cmio-camera.adoc b/documentation/asciidoc/computers/compute-module/cmio-camera.adoc index 3b97d876e0..2e5352ec2b 100644 --- a/documentation/asciidoc/computers/compute-module/cmio-camera.adoc +++ b/documentation/asciidoc/computers/compute-module/cmio-camera.adoc @@ -82,7 +82,7 @@ dtparam=cam1_reg . Run the following command to check the list of detected cameras: + ---- -libcamera-hello --list +rpicam-hello --list ---- You should see your camera model, referred to by the driver directive in the table above, in the output. @@ -142,7 +142,7 @@ NOTE: If your Compute Module includes onboard EMMC storage, you can boot, edit t . Run the following command to check the list of detected cameras: + ---- -libcamera-hello --list +rpicam-hello --list ---- + You should see both camera models, referred to by the driver directives in the table above, in the output. @@ -157,7 +157,7 @@ Raspberry Pi OS includes the `libcamera` library to help you take images with yo Use the following command to immediately take a picture and save it to a file in PNG encoding using the `MMDDhhmmss` date format as a filename: ---- -libcamera-still --datetime -e png +rpicam-still --datetime -e png ---- Use the `-t` option to add a delay in milliseconds. @@ -168,7 +168,7 @@ Use the `--width` and `--height` options to specify a width and height for the i Use the following command to immediately start recording a 10 second long video and save it to a file with the h264 codec named `video.h264`: ---- -libcamera-vid -t 10000 -o video.h264 +rpicam-vid -t 10000 -o video.h264 ---- ==== Specify which camera to use @@ -177,7 +177,7 @@ By default, `libcamera` always uses the camera with index `0` in the `--list-cam To specify a camera option, get an index value for each camera from the following command: ---- -$ libcamera-hello --list-cameras +$ rpicam-hello --list-cameras Available cameras ----------------- 0 : imx477 [4056x3040] (/base/soc/i2c0mux/i2c@1/imx477@1a) @@ -200,13 +200,13 @@ In the above output: To use the HQ camera, pass its index (`0`) to the `--camera` `libcamera` option: ---- -libcamera-hello --camera 0 +rpicam-hello --camera 0 ---- To use the v3 camera, pass its index (`1`) to the `--camera` `libcamera` option: ---- -libcamera-hello --camera 1 +rpicam-hello --camera 1 ----