Split of the camera documentation

documentation/asciidoc/accessories/camera.adoc

@@ -1,66 +1 @@
-include::camera/camera_usage.adoc[]
-
 include::camera/camera_hardware.adoc[]
-
-include::camera/libcamera_apps_intro.adoc[]
-
-include::camera/libcamera_apps_getting_started.adoc[]
-
-include::camera/libcamera_hello.adoc[]
-
-include::camera/libcamera_jpeg.adoc[]
-
-include::camera/libcamera_still.adoc[]
-
-include::camera/libcamera_vid.adoc[]
-
-include::camera/libcamera_apps_libav.adoc[]
-
-include::camera/libcamera_raw.adoc[]
-
-include::camera/libcamera_detect.adoc[]
-
-include::camera/libcamera_options_common.adoc[]
-
-include::camera/libcamera_options_still.adoc[]
-
-include::camera/libcamera_options_vid.adoc[]
-
-include::camera/libcamera_differences.adoc[]
-
-include::camera/libcamera_apps_post_processing.adoc[]
-
-include::camera/libcamera_apps_post_processing_opencv.adoc[]
-
-include::camera/libcamera_apps_post_processing_tflite.adoc[]
-
-include::camera/libcamera_apps_post_processing_writing.adoc[]
-
-include::camera/libcamera_apps_multicam.adoc[]
-
-include::camera/libcamera_apps_packages.adoc[]
-
-include::camera/libcamera_apps_building.adoc[]
-
-include::camera/libcamera_apps_writing.adoc[]
-
-include::camera/libcamera_python.adoc[]
-
-include::camera/libcamera_3rd_party_tuning.adoc[]
-
-include::camera/libcamera_known_issues.adoc[]
-
-include::camera/libcamera_apps_getting_help.adoc[]
-
-include::camera/raspicam.adoc[]
-
-include::camera/timelapse.adoc[]
-
-include::camera/gstreamer.adoc[]
-
-include::camera/qt.adoc[]
-
-include::camera/v4l2.adoc[]
-
-include::camera/csi-2-usage.adoc[]
-

documentation/asciidoc/accessories/camera/camera_hardware.adoc

@@ -20,7 +20,7 @@ Depending on the model, the camera may come with a small piece of translucent bl
 
 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 either for xref:camera.adoc#getting-started[`libcamera`] or for xref:camera.adoc#enabling-the-camera[_Raspicam_].
+Then, please follow the relevant setup instructions either for xref:../computers/camera.adoc#getting-started[libcamera] or for xref:../computers/camera.adoc#enabling-the-camera[Raspicam].
 
 === Hardware Specification
 
@@ -49,18 +49,8 @@ Then, please follow the relevant setup instructions either for xref:camera.adoc#
 
 | Video modes
 | 1080p30, 720p60 and 640 × 480p60/90
-| 1080p30, 720p60 and 640 × 480p60/90
-| 1080p30, 720p60 and 640 × 480p60/90
-
-| Linux integration
-| V4L2 driver available
-| V4L2 driver available
-| V4L2 driver available
-
-| C programming API
-| OpenMAX IL and others available
-| OpenMAX IL and others available
-|
+| 1080p47, 1640 × 1232p41 and 640 × 480p206
+| 2028 × 1080p50, 2028 × 1520p40 and 1332 × 990p120
 
 | Sensor
 | OmniVision OV5647
@@ -85,7 +75,7 @@ Then, please follow the relevant setup instructions either for xref:camera.adoc#
 | Optical size
 | 1/4"
 | 1/4"
-|
+| 1/2.3"
 
 | Full-frame SLR lens equivalent
 | 35 mm
@@ -141,68 +131,12 @@ Then, please follow the relevant setup instructions either for xref:camera.adoc#
 | 2.9
 | 2.0
 | Depends on lens
-|===
-
-=== Software Features
-
-==== `libcamera` stack
-
-[cols=2]
-|===
-
-| Picture formats
-| JPEG, JPEG + DNG (raw), BMP, PNG, YUV420, RGB888
-
-| Video formats
-| raw h.264 (accelerated), MJPEG
-
-| Post-processing
-| User-definable image effects, customisable DRC and HDR, motion detection, OpenCV integration, TensorFlowLite integration
-
-| Exposure modes
-| normal, short, long, fixed fps, customisable
-
-| Metering modes
-| centre-weighted, average, spot, customisable
-
-| Automatic white balance modes
-| off, auto, incandescent, tungsten, fluorescent, indoor, daylight, cloudy, customisable
-
-| Triggers
-| Keypress, UNIX signal, timeout
-
-| Extra modes
-| timelapse, circular buffer, motion detection, segmented video, many features through flexible post-processing
-|===
 
-==== Legacy stack
-
-[cols=2]
-|===
-
-| Picture formats
-| JPEG (accelerated), JPEG + RAW, GIF, BMP, PNG, YUV420, RGB888
-
-| Video formats
-| raw h.264 (accelerated)
-
-| Effects
-| negative, solarise, posterize, whiteboard, blackboard, sketch, denoise, emboss, oilpaint, hatch, gpen, pastel, watercolour, film, blur, saturation
-
-| Exposure modes
-| auto, night, nightpreview, backlight, spotlight, sports, snow, beach, verylong, fixedfps, antishake, fireworks
-
-| Metering modes
-| average, spot, backlit, matrix
-
-| Automatic white balance modes
-| off, auto, sun, cloud, shade, tungsten, fluorescent, incandescent, flash, horizon
-
-| Triggers
-| Keypress, UNIX signal, timeout
+| Maximum exposure times (seconds)
+| 6
+| 11.76
+| 670.74
 
-| Extra modes
-| demo, burst/timelapse, circular buffer, video with motion vectors, segmented video, live preview on 3D models
 |===
 
 === HQ Camera IR Filter Transmission
@@ -211,24 +145,6 @@ The HQ Camera uses a Hoya CM500 infrared filter. Its transmission characteristic
 
 image::images/hoyacm500.png[CM500 Transmission Graph]
 
-=== Maximum Exposure Times
-
-The maximum exposure times of the three official Raspberry Pi cameras are given in the table below.
-
-[cols=",^"]
-|===
-| Module | Max exposure (seconds)
-
-| V1 (OMx5647)
-| 6
-
-| V2 (IMX219)
-| 10
-
-| HQ (IMX477)
-| 230
-|===
-
 === Mechanical Drawings
 
 image:images/RPi-S5-conn.png[camera connector]

documentation/asciidoc/computers/camera.adoc

@@ -1 +1,64 @@
-include::camera/introduction.adoc[]
+include::camera/camera_usage.adoc[]
+
+include::camera/libcamera_apps_intro.adoc[]
+
+include::camera/libcamera_apps_getting_started.adoc[]
+
+include::camera/libcamera_hello.adoc[]
+
+include::camera/libcamera_jpeg.adoc[]
+
+include::camera/libcamera_still.adoc[]
+
+include::camera/libcamera_vid.adoc[]
+
+include::camera/libcamera_apps_libav.adoc[]
+
+include::camera/libcamera_raw.adoc[]
+
+include::camera/libcamera_detect.adoc[]
+
+include::camera/libcamera_options_common.adoc[]
+
+include::camera/libcamera_options_still.adoc[]
+
+include::camera/libcamera_options_vid.adoc[]
+
+include::camera/libcamera_differences.adoc[]
+
+include::camera/libcamera_apps_post_processing.adoc[]
+
+include::camera/libcamera_apps_post_processing_opencv.adoc[]
+
+include::camera/libcamera_apps_post_processing_tflite.adoc[]
+
+include::camera/libcamera_apps_post_processing_writing.adoc[]
+
+include::camera/libcamera_apps_multicam.adoc[]
+
+include::camera/libcamera_apps_packages.adoc[]
+
+include::camera/libcamera_apps_building.adoc[]
+
+include::camera/libcamera_apps_writing.adoc[]
+
+include::camera/libcamera_python.adoc[]
+
+include::camera/libcamera_3rd_party_tuning.adoc[]
+
+include::camera/libcamera_known_issues.adoc[]
+
+include::camera/libcamera_apps_getting_help.adoc[]
+
+include::camera/raspicam.adoc[]
+
+include::camera/timelapse.adoc[]
+
+include::camera/gstreamer.adoc[]
+
+include::camera/qt.adoc[]
+
+include::camera/v4l2.adoc[]
+
+include::camera/csi-2-usage.adoc[]
+

documentation/asciidoc/accessories/camera/camera_usage.adoc → documentation/asciidoc/computers/camera/camera_usage.adoc

@@ -4,13 +4,13 @@ Raspberry Pi currently sell two types of camera board: an https://www.raspberryp
 
 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 xref:camera.adoc#installing-a-raspberry-pi-camera[installed], 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 `raspistill`.
+Once xref:../accessories/camera.adoc#installing-a-raspberry-pi-camera[installed], 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 `raspistill`.
 
 === `libcamera` and the legacy _Raspicam_ camera stack
 
 [NOTE]
 ====
-Raspberry Pi is transitioning from a legacy camera software stack based on proprietary Broadcom GPU code to an open-source stack based on `libcamera`. Raspberry Pi OS images from _Bullseye_ onwards will contain *only* the `libcamera`-based stack. Raspberry Pi OS images up to and including _Buster_ will contain the legacy _Raspicam_ stack, though the `libcamera` stack and applications can be installed xref:camera.adoc#libcamera-and-libcamera-apps-packages[using _apt_], or built by following the xref:camera.adoc#building-libcamera-and-libcamera-apps[normal build instructions].
+Raspberry Pi has transitioned from a legacy camera software stack based on proprietary Broadcom GPU code to an open-source stack based on `libcamera`. Raspberry Pi OS images from _Bullseye_ onwards will contain *only* the `libcamera`-based stack. Raspberry Pi OS images up to and including _Buster_ will contain the legacy _Raspicam_ stack, though the `libcamera` stack and applications can be installed xref:camera.adoc#libcamera-and-libcamera-apps-packages[using _apt_], or built by following the xref:camera.adoc#building-libcamera-and-libcamera-apps[normal build instructions].
 ====
 
 Users are encouraged to use the newest OS images and the `libcamera`-based stack because:
@@ -32,7 +32,7 @@ Reasons to consider staying with an older OS and using the legacy _Raspicam_ sta
 * It may perform better on Raspberry Pi 2 and Raspberry Pi Zero devices, as it offloads more to the GPU and is less dependent on the ARM cores.
 * `libcamera` is still missing certain features, most notably Python bindings. Whilst this work is in progress, users who need a Python interface (such as _Picamera_) will have to stay with the legacy stack for the time being.
 
-Apart from some general information on setting up the camera, most of this documentation is divided into sections on xref:camera.adoc#libcamera-and-libcamera-apps[libcamera and the libcamera-apps], and the xref:camera.adoc#raspicam-commands[legacy _Raspicam_ apps]. Once you've xref:camera.adoc#installing-a-raspberry-pi-camera[installed your camera module], please click on one of these two links.
+Apart from some general information on setting up the camera, most of this documentation is divided into sections on xref:camera.adoc#libcamera-and-libcamera-apps[libcamera and the libcamera-apps], and the xref:camera.adoc#raspicam-commands[legacy _Raspicam_ apps]. Once you've xref:../accessories/camera.adoc#installing-a-raspberry-pi-camera[installed your camera module], please click on one of these two links.
 
 ==== Re-enabling the legacy stack
 

documentation/asciidoc/accessories/camera/libcamera_apps_building.adoc → documentation/asciidoc/computers/camera/libcamera_apps_building.adoc

@@ -32,6 +32,12 @@ 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.adoc#libav-integration-with-libcamera-vid[libav] support in `libcamera-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.adoc#building-libcamera-apps[building `libcamera-apps`]. Raspberry Pi OS Lite users should check that _git_ is installed first (`sudo apt install -y git`).
 
 ==== Building `libcamera`

documentation/asciidoc/accessories/camera/libcamera_apps_libav.adoc → documentation/asciidoc/computers/camera/libcamera_apps_libav.adoc

@@ -37,6 +37,12 @@ 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`
 
+----
+    --audio-samplerate,     Set the audio sampling rate <number>
+----
+
+Set the audio sampling rate in Hz for encoding. Set to 0 (default) to use the input sample rate.
+
 ----
     --audio-device,     Chooses an audio recording device to use <string>
 ----

documentation/asciidoc/accessories/camera/libcamera_options_common.adoc → documentation/asciidoc/computers/camera/libcamera_options_common.adoc

@@ -305,7 +305,7 @@ Example: `libcamera-still -o test.jpg --ev 0.3`
 
 The shutter time is fixed to the given value. The gain will still be allowed to vary (unless that is also fixed).
 
-Note that this shutter time may not be achieved if the camera is running at a frame rate that is too fast to allow it. In this case the `--framerate` option may be used to lower the frame rate. The maximum possible shutter times for the official Raspberry Pi supported can be found xref:camera.adoc#maximum-exposure-times[in this table].
+Note that this shutter time may not be achieved if the camera is running at a frame rate that is too fast to allow it. In this case the `--framerate` option may be used to lower the frame rate. The maximum possible shutter times for the official Raspberry Pi supported can be found xref:../accessories/camera.adoc#hardware-specification[in this table].
 
 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.
 

documentation/asciidoc/accessories/camera/libcamera_still.adoc → documentation/asciidoc/computers/camera/libcamera_still.adoc

@@ -89,4 +89,4 @@ So to perform a 100 second exposure capture, use
 
 `libcamera-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:camera.adoc#maximum-exposure-times[this table].
+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].

documentation/asciidoc/accessories/camera/raspicam.adoc → documentation/asciidoc/computers/camera/raspicam.adoc

@@ -36,7 +36,7 @@ The display should show a five-second preview from the camera and then take a pi
 
 ==== Basic usage of raspistill
 
-With a camera module xref:camera.adoc#camera-modules[connected and enabled], enter the following command in the terminal to take a picture:
+With a camera module xref:../accessories/camera.adoc#camera-modules[connected and enabled], enter the following command in the terminal to take a picture:
 
 [,bash]
 ----
@@ -123,7 +123,7 @@ Use the arrow keys to scroll and type `q` to exit.
 
 ==== Basic usage of raspivid
 
-With a camera module xref:camera.adoc#camera-modules[connected and enabled], record a video using the following command:
+With a camera module xref:../accessories/camera.adoc#camera-modules[connected and enabled], record a video using the following command:
 
 [,bash]
 ----
@@ -1362,7 +1362,7 @@ The applications described here will return a standard error code to the shell o
 
 === Long Exposures
 
-The maximum exposure times of the three official Raspberry Pi cameras can be found in xref:camera.adoc#maximum-exposure-times[this table].
+The maximum exposure times of the three official Raspberry Pi cameras can be found in xref:../accessories/camera.adoc#hardware-specification[this table].
 
 Due to the way the ISP works, by default asking for a long exposure can result in the capture process taking up to 7 times the exposure time, so a 200 second exposure on the HQ camera could take 1400 seconds to actually return an image. This is due to the way the camera system works out the correct exposures and gains to use in the image, using it's AGC (automatic gain control) and AWB (automatic white balance) algorithms. The system needs a few frames to calculate these numbers in order to produce a decent image. When combined with frame discards at the start of processing (in case they are corrupt), and the switching between preview and captures modes, this can result in up to 7 frames needed to produce a final image. With long exposures, that can take a long time.