Merge pull request raspberrypi#3236 from davidplowman/develop

Camera doc updates

Author: Alasdair Allan

documentation/asciidoc/computers/camera/libcamera_apps_building.adoc

@@ -49,8 +49,7 @@ First install all the necessary dependencies for `libcamera`.
 NOTE: Raspberry Pi OS Lite users will first need to install the following additional packages if they have not done so previously:
 
 ----
-sudo apt install -y python3-pip git
-sudo pip3 install jinja2
+sudo apt install -y python3-pip git python3-jinja2
 ----
 
 All users should then install the following:
@@ -59,10 +58,8 @@ All users should then install the following:
 sudo apt install -y libboost-dev
 sudo apt install -y libgnutls28-dev openssl libtiff5-dev pybind11-dev
 sudo apt install -y qtbase5-dev libqt5core5a libqt5gui5 libqt5widgets5
-sudo apt install -y meson
-sudo apt install -y cmake
-sudo pip3 install pyyaml ply
-sudo pip3 install --upgrade meson
+sudo apt install -y meson cmake
+sudo apt install -y python3-yaml python3-ply
 ----
 
 In the `meson` commands below we have enabled the _gstreamer_ plugin. If you _do not_ need this you can set `-Dgstreamer=disabled` instead and the next pair of dependencies will not be required. But if you do leave _gstreamer_ enabled, then you will need the following:
@@ -79,23 +76,13 @@ git clone https://github.com/raspberrypi/libcamera.git
 cd libcamera
 ----
 
-Next we recommend that Raspberry Pi OS Lite users run
+Next, please run
 
 ----
-meson build --buildtype=release -Dpipelines=raspberrypi -Dipas=raspberrypi -Dv4l2=true -Dgstreamer=enabled -Dtest=false -Dlc-compliance=disabled -Dcam=disabled -Dqcam=disabled -Ddocumentation=disabled -Dpycamera=enabled
+meson setup build --buildtype=release -Dpipelines=rpi/vc4,rpi/pisp -Dipas=rpi/vc4,rpi/pisp -Dv4l2=true -Dgstreamer=enabled -Dtest=false -Dlc-compliance=disabled -Dcam=disabled -Dqcam=disabled -Ddocumentation=disabled -Dpycamera=enabled
 ----
 
-Users of Raspberry Pi OS can instead use
-
-----
-meson build --buildtype=release -Dpipelines=raspberrypi -Dipas=raspberrypi -Dv4l2=true -Dgstreamer=enabled -Dtest=false -Dlc-compliance=disabled -Dcam=disabled -Dqcam=enabled -Ddocumentation=disabled -Dpycamera=enabled
-----
-
-NOTE: As of 6th May 2023, there has been a directory restructuring in the upstream libcamera git tree (https://git.libcamera.org/). If users are building libcamera from this tree, please replace `-Dpipelines=raspberrypi -Dipas=raspberrypi` with `-Dpipelines=rpi/vc4 -Dipas=rpi/vc4` in the above commands. This directory restructuring has not yet made it into the Raspberry Pi libcamera repo (https://github.com/raspberrypi/libcamera.git), so the above commands should be used without modifications if using that repo.
-
-The only difference is that the latter also builds the `qcam` test application, which has dependencies on Qt and a desktop environment (after completing the `libcamera` build users can run `build/src/qcam/qcam` to verify that `libcamera` is functioning correctly).
-
-To complete the `libcamera` build, please run
+To complete the `libcamera` build, use
 
 ----
 ninja -C build   # use -j 2 on Raspberry Pi 3 or earlier devices
@@ -133,7 +120,7 @@ First fetch the necessary dependencies for `libcamera-apps`.
 
 ----
 sudo apt install -y cmake libboost-program-options-dev libdrm-dev libexif-dev
-sudo pip3 install ninja meson
+sudo apt install -y meson ninja-build
 ----
 
 The `libcamera-apps` build process begins with the following:

documentation/asciidoc/computers/camera/libcamera_differences.adoc

@@ -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/raspberrypi/imx219_noir.json`.
+* `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).
 
 * 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.
 

documentation/asciidoc/computers/camera/libcamera_hello.adoc

@@ -29,18 +29,25 @@ Raspberry Pi's `libcamera` implementation includes a _tuning file_ for each diff
 
 For this reason it is sometimes necessary to override the default tuning file for a particular sensor.
 
-For example, the NOIR (no IR-filter) versions of sensors require different AWB settings to the standard versions, so the IMX219 NOIR should be run using
+For example, the NOIR (no IR-filter) versions of sensors require different AWB settings to the standard versions, so the IMX219 NOIR being used with a Pi 4 or earlier device should be run using
 
 [,bash]
 ----
-libcamera-hello --tuning-file /usr/share/libcamera/ipa/raspberrypi/imx219_noir.json
+libcamera-hello --tuning-file /usr/share/libcamera/ipa/rpi/vc4/imx219_noir.json
 ----
 
-If you are using a Soho Enterprises SE327M12 module you should use
+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/raspberrypi/se327m12.json
+libcamera-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
 ----
 
 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.

documentation/asciidoc/computers/camera/libcamera_options_common.adoc

@@ -260,16 +260,18 @@ 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.
 
 ----
-	--hdr				Run the camera in HDR mode (supported cameras only)
+	--hdr				Run the camera in HDR mode <mode>
 ----
 
-The `--hdr` option causes the camera to be run in HDR (High Dynamic Range) mode. This option only works for certain supported cameras, including the _Raspberry Pi Camera Module 3_.
+The `--hdr` option causes the camera to be run in the HDR (High Dynamic Range) mode given by `<mode>`. On Pi 4 and earlier devices, this option only works for certain supported cameras, including the _Raspberry Pi Camera Module 3_, and on Pi 5 devices it can be used with all cameras. `<mode>` may take the following values:
 
-Example: `libcamera-still --hdr -o hdr.jpg` for capturing a still image, or `libcamera-vid --hdr -o hdr.h264` to capture a video.
+* `off` - HDR is disabled. This is the default value if the `--hdr` option is omitted entirely.
+* `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 `<mode>` 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.
 
-Use of the HDR 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 --list-cameras`.
+Example: `libcamera-still --hdr -o hdr.jpg` for capturing a still image, or `libcamera-vid --hdr -o hdr.h264` to capture a video.
 
-Users may also supply `--hdr 0` or `--hdr 1`, where the former disables the HDR modes (and is equivalent to omitting the option entirely), and the latter is the same as using `--hdr` on its own.
+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`.
 
 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.