Split out camera documentation v2

documentation/asciidoc/accessories/camera.adoc

@@ -1,66 +1,3 @@
-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[]
-
+include::camera/hqcam_filter_removal.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 for the xref:../computers/camera_software.adoc#getting-started[libcamera] software stack.
 
 === 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]
@@ -241,27 +157,3 @@ image:images/RPi-S5-conn.png[camera connector]
 
 * Camera Module v2 https://datasheets.raspberrypi.com/camera/camera-v2-schematics.pdf[PDF]
 * HQ Camera Module https://datasheets.raspberrypi.com/hq-camera/hq-camera-schematics.pdf[PDF]
-
-=== Raspberry Pi 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.
-
-WARNING: *This procedure cannot be reversed:* the adhesive that attaches the filter will not survive being lifted and replaced, and while the IR filter is about 1.1mm thick, it may crack when it is removed. *Removing it will void the warranty on the product*. Nevertheless, removing the filter will be desirable to some users.
-
-To remove the filter:
-
-. Work in a clean and dust-free environment, as the sensor will be exposed to the air.
-image:images/rpi_hq_cam_sensor.jpg[camera sensor]
-. Unscrew the two 1.5 mm hex lock keys on the underside of the main circuit board. Be careful not to let the washers roll away. There is a gasket of slightly sticky material between the housing and PCB which will require some force to separate.
-image:images/rpi_hq_cam_gasket.jpg[camera gasket]
-. 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.
-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]
-. Given that changing lenses will expose the sensor, at this point you could affix a clear filter (for example, OHP plastic) to minimize the chance of dust entering the sensor cavity.
-image:images/rpi_hq_cam_clear_filter.jpg[camera protective filter]
-. Replace the main housing over the circuit board. Be sure to realign the housing with the gasket, which remains on the circuit board.
-. 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

@@ -0,0 +1,7 @@
+== 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.
+
+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`.

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

@@ -32,7 +32,13 @@ If you want to use the Qt preview window, please also execute
 sudo apt install -y qtbase5-dev libqt5core5a libqt5gui5 libqt5widgets5
 ----
 
-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`).
+If you want xref:camera_software.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_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`).
 
 ==== Building `libcamera`
 
@@ -174,4 +180,4 @@ 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.
 
-Finally, if you have not already done so, please be sure to follow the `dtoverlay` and display driver instructions in the  xref:camera.adoc#getting-started[Getting Started section] (and rebooting if you changed anything there).
+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).

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

@@ -15,7 +15,7 @@ libcamera-hello
 
 You should see a camera preview window for about 5 seconds.
 
-Users running _Buster_ will need to xref:camera.adoc#binary-packages[install one of the `libcamera-apps` packages] first and then configure their `/boot/config.txt` file xref:camera.adoc#if-you-do-need-to-alter-the-configuration[with the appropriate overlay] for the connected camera. Be aware that _libcamera_ and the legacy _raspicam_ stack cannot operate at the same time - to return to the legacy stack after using _libcamera_ you will need to comment out the `dtoverlay` change you made and reboot the system.
+Users running _Buster_ will need to xref:camera_software.adoc#binary-packages[install one of the `libcamera-apps` packages] first and then configure their `/boot/config.txt` file xref:camera_software.adoc#if-you-do-need-to-alter-the-configuration[with the appropriate overlay] for the connected camera. Be aware that _libcamera_ and the legacy _raspicam_ stack cannot operate at the same time - to return to the legacy stack after using _libcamera_ you will need to comment out the `dtoverlay` change you made and reboot the system.
 
 NOTE: Raspberry Pi 3 and older devices may not by default be using the correct display driver. Refer to the `/boot/config.txt` file and ensure that either `dtoverlay=vc4-fkms-v3d` or `dtoverlay=vc4-kms-v3d` is currently active. Please reboot if you needed to change this.
 

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_apps_packages.adoc → documentation/asciidoc/computers/camera/libcamera_apps_packages.adoc

@@ -10,7 +10,7 @@ There are two `libcamera-apps` packages available, that contain the necessary ex
 
 * `libcamera-apps-lite` omits X Windows support and only the DRM preview is available. This package is pre-installed in the _Bullseye_ release of Raspberry Pi OS Lite, and can be installed in _Buster_ using `sudo apt install libcamera-apps-lite`.
 
-For _Bullseye_ users, official Raspberry Pi cameras should be detected automatically. Other users will need to xref:camera.adoc#if-you-do-need-to-alter-the-configuration[edit their `/boot/config.txt`] file if they have not done so previously.
+For _Bullseye_ users, official Raspberry Pi cameras should be detected automatically. Other users will need to xref:camera_software.adoc#if-you-do-need-to-alter-the-configuration[edit their `/boot/config.txt`] file if they have not done so previously.
 
 ==== Dependencies
 
@@ -30,4 +30,4 @@ These will be installed automatically when needed.
 
 * `libepoxy-dev` contains the necessary `libepoxy` header files and resources. You will only need this if you want support for the X11/GLES preview window.
 
-Subsequently `libcamera-apps` can be xref:camera.adoc#building-libcamera-apps-without-rebuilding-libcamera[checked out from Github and rebuilt].
+Subsequently `libcamera-apps` can be xref:camera_software.adoc#building-libcamera-apps-without-rebuilding-libcamera[checked out from GitHub and rebuilt].