Push to production

documentation/asciidoc/accessories/camera/camera_hardware.adoc

@@ -1,6 +1,19 @@
+:figure-caption!:
 == Camera Modules
 
-There are several official Raspberry Pi camera modules. The original 5-megapixel model was https://www.raspberrypi.com/news/camera-board-available-for-sale/[released] in 2013, and an 8-megapixel https://www.raspberrypi.com/products/camera-module-v2/[Camera Module v2] was https://www.raspberrypi.com/news/new-8-megapixel-camera-board-sale-25/[released] in 2016. For both iterations, there are visible light and https://www.raspberrypi.com/products/pi-noir-camera-v2/[infrared] versions. A 12-megapixel https://www.raspberrypi.com/products/raspberry-pi-high-quality-camera/[High Quality Camera] was https://www.raspberrypi.com/news/new-product-raspberry-pi-high-quality-camera-on-sale-now-at-50/[released] in 2020. There is no infrared version of the HQ Camera, however the xref:camera.adoc#raspberry-pi-hq-camera-filter-removal[IR Filter can be removed] if required.
+There are now several official Raspberry Pi camera modules. The original 5-megapixel model was https://www.raspberrypi.com/news/camera-board-available-for-sale/[released] in 2013, it was followed by an 8-megapixel https://www.raspberrypi.com/products/camera-module-v2/[Camera Module 2] which was https://www.raspberrypi.com/news/new-8-megapixel-camera-board-sale-25/[released] in 2016. The latest camera model is the 12-megapixel https://raspberrypi.com/products/camera-module-3/[Camera Module 3] which was https://www.raspberrypi.com/news/new-autofocus-camera-modules/[released] in 2023. The original 5MP device is no longer available from Raspberry Pi. 
+
+All of these cameras come in visible light and infrared versions, while the Camera Module 3 also comes as a standard or wide FoV model for a total of four different variants.
+
+NOTE: Camera Module 3 is compatible with all Raspberry Pi computers with CSI connectors - that is, all except Raspberry Pi 400 and the 2016 launch version of Zero.
+
+.Camera Module 3 (left) and Camera Module 3 Wide (right)
+image::images/cm3.jpg[Camera Module 3 normal and wide angle]
+
+.Camera Module 3 NoIR (left) and Camera Module 3 NoIR Wide (right)
+image::images/cm3_noir.jpg[Camera Module 3 NoIR normal and wide angle]
+
+Aditionally a 12-megapixel https://www.raspberrypi.com/products/raspberry-pi-high-quality-camera/[High Quality Camera] with CS- or M12-mount variants for use with external lenses was https://www.raspberrypi.com/news/new-product-raspberry-pi-high-quality-camera-on-sale-now-at-50/[released in 2020] and https://www.raspberrypi.com/news/new-autofocus-camera-modules/[2023] respectively. There is no infrared version of the HQ Camera, however the xref:camera.adoc#hq-camera-filter-removal[IR Filter can be removed] if required.
 
 === Installing a Raspberry Pi camera
 
@@ -16,144 +29,165 @@ video::GImeVqHQzsE[youtube]
 
 Depending on the model, the camera may come with a small piece of translucent blue plastic film covering the lens. This is only present to protect the lens while it is being mailed to you, and needs to be removed by gently peeling it off.
 
+NOTE: There is additional documentation available around fitting the recommended https://datasheets.raspberrypi.com/hq-camera/cs-mount-lens-guide.pdf[6mm] and https://datasheets.raspberrypi.com/hq-camera/c-mount-lens-guide.pdf[16mm] lens to the HQ Camera.
+
 === Preparing the Software
 
 Before proceeding, we recommend ensuring that your kernel, GPU firmware and applications are all up to date. Please follow the instructions on xref:../computers/os.adoc#using-apt[keeping your operating system up to date].
 
-Then, please follow the relevant setup instructions for the xref:../computers/camera_software.adoc#getting-started[libcamera] software stack.
+Then, please follow the relevant setup instructions for the xref:../computers/camera_software.adoc#getting-started[libcamera] software stack, and the https://datasheets.raspberrypi.com/camera/picamera2-manual.pdf[Picamera2 Python library].
 
 === Hardware Specification
 
 |===
-|  | Camera Module v1 | Camera Module v2 | HQ Camera
+|  | Camera Module v1 | Camera Module v2 | Camera Module 3 | Camera Module 3 Wide | HQ Camera
 
 | Net price
 | $25
 | $25
+| $25 
+| $35
 | $50
 
 | Size
 | Around 25 × 24 × 9 mm
-|
+| Around 25 × 24 × 9 mm
+| Around 25 × 24 × 11.5 mm
+| Around 25 × 24 × 12.4 mm
 | 38 x 38 x 18.4mm (excluding lens)
 
 | Weight
 | 3g
 | 3g
+| 4g
+| 4g
 |
 
 | Still resolution
 | 5 Megapixels
 | 8 Megapixels
+| 11.9 Megapixels
+| 11.9 Megapixels
 | 12.3 Megapixels
 
 | Video modes
 | 1080p30, 720p60 and 640 × 480p60/90
 | 1080p47, 1640 × 1232p41 and 640 × 480p206
+| 1080p50 / 720p100 / 640 x 480p120
+| 1080p50 / 720p100 / 640 x 480p120
 | 2028 × 1080p50, 2028 × 1520p40 and 1332 × 990p120
 
 | Sensor
 | OmniVision OV5647
 | Sony IMX219
-| https://www.sony-semicon.co.jp/products/common/pdf/IMX477-AACK_Flyer.pdf[Sony IMX477]
+| Sony IMX708
+| Sony IMX708
+| Sony IMX477
 
 | Sensor resolution
 | 2592 × 1944 pixels
 | 3280 × 2464 pixels
+| 4608 x 2592 pixels
+| 4608 x 2592 pixels
 | 4056 x 3040 pixels
 
 | Sensor image area
 | 3.76 × 2.74 mm
 | 3.68 x 2.76 mm (4.6 mm diagonal)
+| 6.45 x 3.63mm (7.4mm diagonal)
+| 6.45 x 3.63mm (7.4mm diagonal)
 | 6.287mm x 4.712 mm (7.9mm diagonal)
 
 | Pixel size
 | 1.4 µm × 1.4 µm
 | 1.12 µm x 1.12 µm
+| 1.4 µm x 1.4 µm
+| 1.4 µm x 1.4 µm
 | 1.55 µm x 1.55 µm
 
 | Optical size
 | 1/4"
 | 1/4"
+| 1/2.43"
+| 1/2.43"
 | 1/2.3"
 
-| Full-frame SLR lens equivalent
-| 35 mm
-|
-|
-
-| S/N ratio
-| 36 dB
-|
-|
-
-| Dynamic range
-| 67 dB @ 8x gain
-|
-|
-
-| Sensitivity
-| 680 mV/lux-sec
-|
-|
-
-| Dark current
-| 16 mV/sec @ 60 C
-|
-|
-
-| Well capacity
-| 4.3 Ke-
-|
-|
+| Focus
+| Fixed
+| Adjustable
+| Motorized
+| Motorized
+| Adjustable
 
 | Depth of field
-| approx. 1 m to infinity
-| adjustable with supplied tool
+| Approx 1 m to ∞ 
+| Approx 10 cm to ∞ 
+| Approx 10 cm to ∞ 
+| Approx 5 cm to ∞ 
 | N/A
 
 | Focal length
 | 3.60 mm +/- 0.01
 | 3.04 mm
+| 4.74 mm
+| 2.75 mmm
 | Depends on lens
 
-| Horizontal field of view
+| Horizontal Field of View (FoV)
 | 53.50  +/- 0.13 degrees
 | 62.2 degrees
+| 66 degrees
+| 102 degrees
 | Depends on lens
 
-| Vertical field of view
+| Vertical Field of View (FoV)
 | 41.41 +/- 0.11 degrees
 | 48.8 degrees
+| 41 degrees
+| 67 degrees
 | Depends on lens
 
 | Focal ratio (F-Stop)
-| 2.9
-| 2.0
+| F2.9
+| F2.0
+| F1.8
+| F2.2
 | Depends on lens
 
 | Maximum exposure times (seconds)
 | 6
 | 11.76
+| 112
+| 112
 | 670.74
 
+| Lens Mount
+| N/A
+| N/A
+| N/A 
+| N/A
+| CS- or M12-mount
 |===
 
-=== HQ Camera IR Filter Transmission
+=== Mechanical Drawings
 
-The HQ Camera uses a Hoya CM500 infrared filter. Its transmission characteristics are as represented in the following graph.
+Available mechanical drawings;
 
-image::images/hoyacm500.png[CM500 Transmission Graph]
+* Camera Module 2 https://datasheets.raspberrypi.com/camera/camera-module-2-mechanical-drawing.pdf[PDF]
+* Camera Module 3 https://datasheets.raspberrypi.com/camera/camera-module-3-standard-mechanical-drawing.pdf[PDF]
+* Camera Module 3 Wide https://datasheets.raspberrypi.com/camera/camera-module-3-wide-mechanical-drawing.pdf[PDF]
+* HQ Camera Module (CS-mount version) https://datasheets.raspberrypi.com/hq-camera/hq-camera-cs-mechanical-drawing.pdf[PDF]
+** The CS-mount https://datasheets.raspberrypi.com/hq-camera/hq-camera-cs-lensmount-drawing.pdf[PDF]
+* HQ Camera Module (M12-mount version) https://datasheets.raspberrypi.com/hq-camera/hq-camera-m12-mechanical-drawing.pdf[PDF]
 
-=== Mechanical Drawings
+NOTE: Board dimensions and mounting-hole positions for Camera Module 3 are identical to Camera Module 2. However, due to changes in the size and position of the sensor module, it is not mechanically compatible with the camera lid for the Raspberry Pi Zero Case.
 
-image:images/RPi-S5-conn.png[camera connector]
+=== Schematics
 
-* Camera Module v2 https://datasheets.raspberrypi.com/camera/camera-v2-mechanical-drawing.pdf[PDF]
-* HQ Camera Module https://datasheets.raspberrypi.com/hq-camera/hq-camera-mechanical-drawing.pdf[PDF]
-* HQ Camera Module lens mount https://datasheets.raspberrypi.com/hq-camera/hq-camera-lensmount-drawing.pdf[PDF]
+.Schematic of the Raspberry Pi CSI camera connector.
+image:images/RPi-S5-conn.png[camera connector]
 
-=== Schematics
+Other available schematics;
 
-* Camera Module v2 https://datasheets.raspberrypi.com/camera/camera-v2-schematics.pdf[PDF]
+* Camera Module v2 https://datasheets.raspberrypi.com/camera/camera-module-2-schematics.pdf[PDF]
 * HQ Camera Module https://datasheets.raspberrypi.com/hq-camera/hq-camera-schematics.pdf[PDF]

documentation/asciidoc/accessories/camera/hqcam_filter_removal.adoc

@@ -1,4 +1,10 @@
-== Raspberry Pi HQ Camera Filter Removal
+== HQ Camera Filter Transmission
+
+The HQ Camera uses a Hoya CM500 infrared filter. Its transmission characteristics are as represented in the following graph.
+
+image::images/hoyacm500.png[CM500 Transmission Graph]
+
+== HQ Camera Filter Removal
 
 The High Quality Camera contains an IR filter, which is used to reduce the camera's sensitivity to infrared light. This ensures that outdoor photos look more natural. However, some nature photography can be enhanced with the removal of this filter; the colours of sky, plants, and water can be affected by its removal. The camera can also be used without the filter for night vision in a location that is illuminated with infrared light.
 
@@ -17,7 +23,7 @@ image:images/rpi_hq_cam_gasket.jpg[camera gasket, width="70%"]
 *  Lift up the board and place it down on a very clean surface. Make sure the sensor does not touch the surface.
 *  Before completing the next step, read through all of the steps and decide whether you are willing to void your warranty. *Do not proceed* unless you are sure that you are willing to void your warranty.
 *  Turn the lens around so that it is "looking" upwards and place it on a table.
-* ou may try some ways to weaken the adhesive, such as a little isopropyl alcohol and/or heat (~20-30 C). Using a pen top or similar soft plastic item, push down on the filter only at the very edges where the glass attaches to the aluminium - to minimise the risk of breaking the filter. The glue will break and the filter will detach from the lens mount.
+* You may try some ways to weaken the adhesive, such as a little isopropyl alcohol and/or heat (~20-30 C). Using a pen top or similar soft plastic item, push down on the filter only at the very edges where the glass attaches to the aluminium - to minimise the risk of breaking the filter. The glue will break and the filter will detach from the lens mount.
 
 image:images/rpi_hq_cam_ir_filter.jpg[camera ir filter, width="70%"]
 
@@ -29,3 +35,4 @@ image:images/rpi_hq_cam_clear_filter.jpg[camera protective filter, width="70%"]
 *  The nylon washer prevents damage to the circuit board; apply this washer first. Next, fit the steel washer, which prevents damage to the nylon washer.
 *  Screw down the two hex lock keys. As long as the washers have been fitted in the correct order, they do not need to be screwed very tightly.
 *  Note that it is likely to be difficult or impossible to glue the filter back in place and return the device to functioning as a normal optical camera.
+

documentation/asciidoc/computers/camera/camera_usage.adoc

@@ -1,6 +1,12 @@
 == Introducing the Raspberry Pi Cameras
 
-Raspberry Pi currently sell two types of camera board: an https://www.raspberrypi.com/products/camera-module-v2/[8MP device] and a https://www.raspberrypi.com/products/raspberry-pi-high-quality-camera/[12MP High Quality (HQ)] camera. The 8MP device is also available in https://www.raspberrypi.com/products/pi-noir-camera-v2/[NoIR form] without an IR filter. The original 5MP device is no longer available from Raspberry Pi. Further details on the camera modules can be found in the xref:../accessories/camera.adoc#camera-modules[camera hardware] page.
+There are now several official Raspberry Pi camera modules. The original 5-megapixel model was https://www.raspberrypi.com/news/camera-board-available-for-sale/[released] in 2013, it was followed by an 8-megapixel https://www.raspberrypi.com/products/camera-module-v2/[Camera Module 2] which was https://www.raspberrypi.com/news/new-8-megapixel-camera-board-sale-25/[released] in 2016. The latest camera model is the 12-megapixel https://raspberrypi.com/products/camera-module-3/[Camera Module 3] which was https://www.raspberrypi.com/news/new-autofocus-camera-modules/[released] in 2023. The original 5MP device is no longer available from Raspberry Pi. 
+
+Aditionally a 12-megapixel https://www.raspberrypi.com/products/raspberry-pi-high-quality-camera/[High Quality Camera] with CS- or M12-mount variants for use with external lenses was https://www.raspberrypi.com/news/new-product-raspberry-pi-high-quality-camera-on-sale-now-at-50/[released in 2020] and https://www.raspberrypi.com/news/new-autofocus-camera-modules/[2023] respectively. There is no infrared version of the HQ Camera.
+
+All of these cameras come in visible light and infrared versions, while the Camera Module 3 also comes as a standard or wide FoV model for a total of four different variants.
+
+Further details on the camera modules can be found in the xref:../accessories/camera.adoc#camera-modules[camera hardware] page.
 
 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.
 

documentation/asciidoc/computers/camera/libcamera_options_common.adoc

@@ -153,6 +153,12 @@ The supplied string is set as the title of the preview window (when running unde
 
 | %focus
 | The focus metric for the image, where a larger value implies a sharper image
+
+| %lp
+| The current lens position in dioptres (1 / distance in metres).
+
+| %afstate
+| The autofocus algorithm state (one of `idle`, `scanning`, `focused` or `failed`).
 |===
 
 When not provided, the `--info-text` string defaults to `"#%frame (%fps fps) exp %exp ag %ag dg %dg"`.
@@ -253,6 +259,20 @@ 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)
+----
+
+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_.
+
+Example: `libcamera-still --hdr -o hdr.jpg` for capturing a still image, or `libcamera-vid --hdr -o hdr.h264` to capture a video.
+
+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`.
+
+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.
+
+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.
+
 ==== Camera Control
 
 The following options affect the image processing and control algorithms that affect the camera image quality.
@@ -428,6 +448,67 @@ For more information on the camera tuning file, please consult the https://datas
 
 Example: `libcamera-hello --tuning-file ~/my-camera-tuning.json`
 
+----
+	--autofocus-mode			Specify the autofocus mode <string>
+----
+
+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)
+* `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_).
+
+----
+	--autofocus-range			Specify the autofocus range <string>
+----
+
+Specifies the autofocus range, which may be one of
+
+* `normal` (the default) - focuses from reasonably close to infinity
+* `macro` - focuses only on close objects, including the closest focal distances supported by the camera
+* `full` - will focus on the entire range, from the very closest objects to infinity.
+
+This option is only supported for certain camera modules (such as the _Raspberry Pi Camera Module 3_).
+
+----
+	--autofocus-speed			Specify the autofocus speed <string>
+----
+
+Specifies the autofocus speed, which may be one of
+
+* `normal` (the default) - the lens position will change at the normal speed
+* `fast` - the lens position may change more quickly.
+
+This option is only supported for certain camera modules (such as the _Raspberry Pi Camera Module 3_).
+
+----
+	--autofocus-window			Specify the autofocus window
+----
+
+Specifies the autofocus window, in the form `x,y,width,height` where the coordinates are given as a proportion of the entire image. For example, `--autofocus-window 0.25,0.25,0.5,0.5` would choose a window that is half the size of the output image in each dimension, and centred in the middle.
+
+The default value causes the algorithm to use the middle third of the output image in both dimensions (so 1/9 of the total image area).
+
+This option is only supported for certain camera modules (such as the _Raspberry Pi Camera Module 3_).
+
+----
+	--lens-position				Set the lens to a given position <string>
+----
+
+Moves the lens to a fixed focal distance, normally given in dioptres (units of 1 / _distance in metres_). We have
+
+* 0.0 will move the lens to the "infinity" position
+* Any other `number`: move the lens to the 1 / `number` position, so the value 2 would focus at approximately 0.5m
+* `default` - move the lens to a default position which corresponds to the hyperfocal position of the lens.
+
+It should be noted that lenses can only be expected to be calibrated approximately, and there may well be variation between different camera modules.
+
+This option is only supported for certain camera modules (such as the _Raspberry Pi Camera Module 3_).
+
+
 ==== Output File Options
 
 ----

documentation/asciidoc/computers/camera/libcamera_options_still.adoc

@@ -128,3 +128,21 @@ The image data in the raw file is exactly what came out of the sensor, with no p
 This causes `libcamera-still` to make a symbolic link to the most recently saved file, thereby making it easier to identify. (`libcamera-still` only.)
 
 Example: `libcamera-still -t 100000 --timelapse 10000 -o test%d.jpg --latest latest.jpg`
+
+----
+	--autofocus-on-capture			Whether to run an autofocus cycle before capture
+----
+
+If set, this will cause an autofocus cycle to be run just before the image is captured.
+
+If `--autofocus-mode` is not specified, or was set to `default` or `manual`, this will be the only autofocus cycle.
+
+If `--autofocus-mode` was set to `auto`, there will be an additional autofocus cycle at the start of the preview window.
+
+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`
+
+This option is only supported for certain camera modules (such as the _Raspberry Pi Camera Module 3_).