跳到主要内容

前言

树莓派系统提供了一组小型示例程序 rpicam-apps。这些基于 libcamera 库开发的命令行（CLI）应用，可用于从摄像头捕获图像和视频。主要程序包括：

  • rpicam-hello：摄像头的 “入门示例程序”，启动摄像头预览流并在屏幕上显示画面。
  • rpicam-jpeg：运行预览窗口，随后拍摄高分辨率静态照片。
  • rpicam-still：模拟原版 raspistill 工具的大部分功能。
  • rpicam-vid：用于录制视频。
  • rpicam-raw：直接从图像传感器捕获原始（未处理的拜耳）帧数据。
  • rpicam-detect：默认不编译；若树莓派已安装 TensorFlow Lite，用户可自行编译。当检测到指定物体时，会自动拍摄 JPEG 照片。

用户在接入支持的 MIPI 摄像头型号时，可以通过 config.txt 文件配置后，使用指令来预览和使用摄像头。

rpicam-hello​

会看到一个大约五秒钟的相机预览窗口。

注意：如果运行在 Bullseye 的 Raspberry Pi 3 和更早版本的设备上，您需要重新启用 Glamor，才能使 X Windows 硬件加速预览窗口正常工作。

在终端窗口中输入 sudo raspi-config , 然后选择 Advanced Options 、 Glamor 和 Yes . 退出并重新启动您的树莓派主板。 默认情况下，运行 Bullseye 的 Raspberry Pi 3 和更早的设备可能未使用正确的显示驱动程序。请参阅 /boot/firmware/config.txt 文件，并确保 dtoverlay=vc4-fkms-v3d or dtoverlay=vc4-kms-v3d 当前处于开启状态。如果您需要更改此设置，请重新启动。

rpicam-hello 相当于相机的 “hello world” ，它启动相机预览流并将其显示在屏幕上，可以通过单击窗口的关闭按钮或在终端中使用 ctrl^C 来停止预览。

rpicam-hello -t 0

调谐文件​

Raspberry Pi 的 libcamera 有针对每种不同类型的相机模块的调谐文件。文件里的参数将传递给算法和硬件以产生最佳质量的图像。 libcamera 只能自动确定正在使用的图像传感器，而不能自动确定整个模块，即使整个模块会影响“调谐”。因此，有时需要覆盖特定传感器的默认调谐文件。

例如，无红外滤光片 （NoIR） 版本的传感器需要与标准版本不同的 AWB（白平衡） 设置，因此与 Pi 4 或更早设备一起使用的 IMX219 NoIR 应使用以下方式运行：

rpicam-hello --tuning-file /usr/share/libcamera/ipa/rpi/vc4/imx219_noir.json

Raspberry Pi 5 在不同的文件夹中使用不同的调谐文件，因此在这里您将使用：

rpicam-hello --tuning-file /usr/share/libcamera/ipa/rpi/pisp/imx219_noir.json

这也意味着用户可以复制现有的调谐文件并根据自己的喜好进行更改，只要参数 --tuning-file 指向新版本即可。

--tuning-file 参数与其他命令行选项一样，同样适用于所有 rpicam-apps.

rpicam-jpeg​

rpicam-jpeg 是一个简单的静态图像捕捉应用程序。 要捕获全分辨率 JPEG 图像，请使用以下指令，这将显示大约五秒钟的预览，然后将全分辨率 JPEG 图像捕获到文件中 test.jpg

rpicam-jpeg -o test.jpg

该-t 选项可用于更改预览显示的时间长度，并且--width 和--height 选项将更改捕获的静态图像的分辨率。例如：

rpicam-jpeg -o test.jpg -t 2000 --width 640 --height 480

曝光控制​

所有这些都 rpicam-apps 允许用户以固定的快门速度和增益运行相机。拍摄曝光时间为 20ms、增益为 1.5x 的图像，该增益将用作传感器内的模拟增益，直到达到内核传感器驱动程序允许的最大模拟增益，之后其余部分将用作数字增益。

rpicam-jpeg -o test.jpg -t 2000 --shutter 20000 --gain 1.5

Raspberry Pi 的 AEC/AGC 算法允许应用程序指定曝光补偿：能够通过给定的停止次数使图像变暗或变亮。

rpicam-jpeg --ev -0.5 -o darker.jpg
rpicam-jpeg --ev 0 -o normal.jpg
rpicam-jpeg --ev 0.5 -o brighter.jpg

数字增益​

数字增益由 ISP 应用，而不是由传感器应用。数字增益将始终非常接近 1.0，除非：

请求的总增益（通过选项 --gain 或通过相机调整中的曝光配置文件）超过了可以在传感器内用作模拟增益的增益。只有所需的额外增益才会用作数字增益。

其中一个颜色增益小于 1（请注意，颜色增益也用作数字增益）。在这种情况下，公布的数字增益将稳定为 1 / 分钟（红色增益，蓝色增益）。这意味着其中一个颜色通道（而不是绿色通道）应用了单位数字增益。

AEC/AGC 正在发生变化。当 AEC/AGC 移动时，数字增益通常会发生一定程度的变化，以尝试消除任何波动，但它会很快恢复到正常值。

rpicam-still​

模拟 raspistill 原始应用程序的许多功能。

rpicam-still -o test.jpg

编码器​

rpicam-still 允许文件以多种不同的格式保存。它支持 png 和 bmp 编码。它还允许将文件保存为 RGB 或 YUV 像素的二进制转储，没有编码或文件格式。在后一种情况下，读取文件的应用程序必须了解其自身的像素排列。

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

注意，保存图像的格式取决于 -e （相当于 ——encoding ) 选项，不会根据输出文件名自动选择。

Raw 图像捕捉​

raw 图是由图像传感器直接产生的图像，在 ISP（图像信号处理器）或任何 CPU 内核对其进行任何处理之前。对于彩色图像传感器，这些通常是 Bayer 格式图像。请注意，原始图像与我们之前看到的经过处理但未编码的 RGB 或 YUV 图像有很大不同。

获取 raw 图：

rpicam-still --raw --output test.jpg

这里， -r 选项（也是 ——raw ) 表示捕获原始图像和 JPEG。实际上，原始图像就是生成 JPEG 的 raw 图像。原始图像以 DNG (Adobe Digital Negative) 格式保存，并与许多标准应用程序（如 draw 或 RawTherapee) 兼容。原始图像保存到具有相同名称但扩展名为。ng 的文件中，因此是 test.dng。

这些 DNG 文件包含与图像捕获有关的元数据，包括黑电平、白平衡信息和 ISP 用于生成 JPEG 的颜色矩阵。这使得这些 DNG 文件在以后使用上述一些工具进行“手动”原始转换时更加方便。使用 exiftool 显示编码到 DNG 文件中的所有元数据：

File Name : test.dng
Directory : .
File Size : 24 MB
File Modification Date/Time : 2021:08:17 16:36:18+01:00
File Access Date/Time : 2021:08:17 16:36:18+01:00
File Inode Change Date/Time : 2021:08:17 16:36:18+01:00
File Permissions : rw-r--r--
File Type : DNG
File Type Extension : dng
MIME Type : image/x-adobe-dng
Exif Byte Order : Little-endian (Intel, II)
Make : Raspberry Pi
Camera Model Name : /base/soc/i2c0mux/i2c@1/imx477@1a
Orientation : Horizontal (normal)
Software : rpicam-still
Subfile Type : Full-resolution Image
Image Width : 4056
Image Height : 3040
Bits Per Sample : 16
Compression : Uncompressed
Photometric Interpretation : Color Filter Array
Samples Per Pixel : 1
Planar Configuration : Chunky
CFA Repeat Pattern Dim : 2 2
CFA Pattern 2 : 2 1 1 0
Black Level Repeat Dim : 2 2
Black Level : 256 256 256 256
White Level : 4095
DNG Version : 1.1.0.0
DNG Backward Version : 1.0.0.0
Unique Camera Model : /base/soc/i2c0mux/i2c@1/imx477@1a
Color Matrix 1 : 0.8545269369 -0.2382823821 -0.09044229197 -0.1890484985 1.063961506 0.1062747385 -0.01334283455 0.1440163847 0.2593136724
As Shot Neutral : 0.4754476844 1 0.413686484
Calibration Illuminant 1 : D65
Strip Offsets : 0
Strip Byte Counts : 0
Exposure Time : 1/20
ISO : 400
CFA Pattern : [Blue,Green][Green,Red]
Image Size : 4056x3040
Megapixels : 12.3
Shutter Speed : 1/20

我们注意到只有一个校准光源（由 AWB 算法确定的光源，尽管它总是被标记为“D65”)，并且将 ISO 数除以 100 给出正在使用的模拟增益。

超长曝光​

为了捕捉长时间曝光的图像，请禁用 AEC/AGC 和 AWB，因为这些算法将迫使用户在收敛时等待许多帧。

禁用它们的方法是提供显式的值。此外，可以使用 ——immediate 选项跳过捕获的整个预览阶段。

因此，要执行 100 秒曝光捕捉，使用；

rpicam-still -o long_exposure.jpg --shutter 100000000 --gain 1 --awbgains 1,1 --immediate

作为参考，三款官方树莓派相机的最大曝光时间可以在这个表格中找到。

rpicam-vid​

rpicam-vid 可以帮助我们在树莓派设备上捕获视频。 rpicam-vid 显示一个预览窗口，并将编码的比特流写入指定的输出。这将产生一个未打包的视频比特流，它没有被打包在任何类型的容器（如 mp4 文件）格式中。

rpicam-vid 默认使用的是 H.264 编码

例如，下面的命令将一个 10 秒的视频写入一个名为 test.h264 的文件：

rpicam-vid -t 10s -o test.h264

您可以使用 VLC 和其他视频播放器播放结果文件：

VLC test.h264

在 Raspberry Pi 5 上，您可以通过指定输出文件的 MP4 文件扩展名直接输出到 MP4 容器格式：

rpicam-vid -t 10s -o test.mp4

编码器​

rpicam-vid 支持动态 JPEG 以及未压缩和未格式化的 YUV420:

rpicam-vid -t 10000 --codec mjpeg -o test.mjpeg
rpicam-vid -t 10000 --codec yuv420 -o test.data

codec 选项决定输出格式，而不是输出文件的扩展名。

segment 选项将输出文件分割成段大小的块（以毫秒为单位）。通过指定非常短 (1 毫秒）的段，这可以方便地将运动 JPEG 流分解为单个 JPEG 文件。例如，下面的命令将 1 毫秒的段与输出文件名中的计数器结合起来，为每个段生成一个新的文件名：

rpicam-vid -t 10000 --codec mjpeg --segment 1 -o test%05d.jpeg

捕获高帧率视频​

为了尽量减少高帧率 (> 60fps) 视频的帧丢失，请尝试以下配置调整：

将 H.264 的目标水平用 --level 4.2 这个参数设置为 4.2

通过将 denoise 选项设置为 cdn_off 来禁用软件颜色降噪处理。

禁用 nopreview 的显示窗口以释放一些额外的 CPU 周期。

在 /boot/firmware/config.txt 中设置 force_turbo=1 ，确保在视频捕获过程中 CPU 时钟不节流。有关更多信息，请参阅 force_turbo 文档。

将 ISP 输出分辨率参数调整为 --width 1280 --height 720 或更低，以实现帧率目标。

在 Raspberry Pi 4 上，您可以通过在 /boot/firmware/config.txt 中添加 gpu_freq=550 或更高的频率来超频 GPU 以提高性能。有关详细信息，请参阅超频文档。

下面的命令演示了如何实现 1280×720 120fps 视频：

rpicam-vid --level 4.2 --framerate 120 --width 1280 --height 720 --save-pts timestamp.pts -o video.264 -t 10000 --denoise cdn_off -n

Libav 与 picam-vid 的集成​

Rpicam-vid 可以使用 ffmpeg/libav 编解码器后端对音频和视频流进行编码。您可以将这些流保存到文件中，也可以通过网络将它们流式传输。

要启用 libav 后端，将 libav 传递给 codec 选项：

rpicam-vid --codec libav --libav-format avi --libav-audio --output example.avi

UDP​

要使用树莓派作为服务器在 UDP 上流式传输视频，使用以下命令，将 < IP -addr> 占位符替换为客户端或多播地址的 IP 地址，并将 <port> 占位符替换为您想要用于流式传输的端口：

rpicam-vid -t 0 --inline -o udp://<ip-addr>:<port>

使用树莓派作为客户端通过 UDP 查看视频流，使用以下命令，将 <port> 占位符替换为您想要流式传输的端口：

vlc udp://@:<port> :demux=h264

或者，在客户端使用以下命令使用 ffplay 进行流：

ffplay udp://<ip-addr-of-server>:<port> -fflags nobuffer -flags low_delay -framedrop

TCP​

还可以通过 TCP 传输视频。使用树莓派作为服务器：

rpicam-vid -t 0 --inline --listen -o tcp://0.0.0.0:<port>

使用树莓派作为客户端通过 TCP 查看视频流，使用以下命令：

vlc tcp/h264://<ip-addr-of-server>:<port>

或者，在客户端使用以下命令以每秒 30 帧的速度使用 ffplay 流：

ffplay tcp://<ip-addr-of-server>:<port> -vf "setpts=N/30" -fflags nobuffer -flags low_delay -framedrop

RTSP​

要使用 VLC 通过 RTSP 传输视频，使用树莓派作为服务器，使用以下命令：

rpicam-vid -t 0 --inline -o - | cvlc stream:///dev/stdin --sout '#rtp{sdp=rtsp://:8554/stream1}' :demux=h264

使用树莓派作为客户端查看 RTSP 上的视频流，使用以下命令：

ffplay rtsp://<ip-addr-of-server>:8554/stream1 -vf "setpts=N/30" -fflags nobuffer -flags low_delay -framedrop

或者在客户端使用以下命令使用 VLC 进行流：

vlc rtsp://<ip-addr-of-server>:8554/stream1

如果需要关闭服务器上的预览窗口，使用 nopreview 命令。

使用内联标志强制流报头信息进入每个内帧，这有助于客户端在错过开头时理解流。

rpicam-raw​

rpicam-raw 直接从传感器将视频记录为原始的 Bayer 帧。它不显示预览窗口。将两秒钟的原始剪辑记录到一个名为 test.raw 的文件中，执行如下命令：

rpicam-raw -t 2000 -o test.raw

rpicam-raw 输出没有任何格式信息的原始帧。应用程序将像素格式和图像尺寸打印到终端窗口，以帮助用户解析像素数据。

默认情况下，rpicam-raw 在单个可能非常大的文件中输出原始帧。使用 segment 选项将每个原始帧定向到一个单独的文件，使用%05d 指令使每个帧文件名唯一：

rpicam-raw -t 2000 --segment 1 -o test%05d.raw

通过快速存储设备， rpicam-raw 可以以 10fps 的速度将 18MB 的 1200 万像素 HQ 相机帧写入磁盘。 rpicam-raw 无法将输出帧格式化为 DNG 文件；要实现这个功能，请使用 rpicam-still 以低于 10 的帧率选项来避免掉帧的情况：

rpicam-raw -t 5000 --width 4056 --height 3040 -o test.raw --framerate 8

有关原始格式的更多信息，请参阅 mode 文档。

rpicam-detect​

注意：树莓派操作系统不包含 rpicam-detect 。如果您已经安装了 TensorFlow Lite，则可以构建 rpicam-detect 。有关更多信息，请参见 rpicam-apps 构建说明。不要忘记在运行 cmake 时传递 -DENABLE_TFLITE=1 。

rpicam-detect 显示一个预览窗口，并使用 Google MobileNet v1 SSD (Single Shot Detector) 神经网络来监控内容，该神经网络经过训练，可以使用 Coco 数据集识别大约 80 类对象。 rpicam-detect 可以识别人、汽车、猫和许多其他物体。

每当 rpicam-detect 检测到目标对象时，它就捕获一个全分辨率 JPEG。然后返回到监控预览模式。

有关模型使用的一般信息，请参阅 TensorFlow Lite 对象检测器部分。例如，当你外出时，你就能监视你的猫：

rpicam-detect -t 0 -o cat%04d.jpg --lores-width 400 --lores-height 300 --post-process-file object_detect_tf.json --object cat

rpicam 参数设置​

--help -h 打印全部选项，以及每个选项的简要介绍

rpicam-hello -h

--version 输出 libcamera 和 rpicam-apps 的版本字符串

rpicam-hello --version

示例输出：

rpicam-apps build: ca559f46a97a 27-09-2021 (14:10:24)
libcamera build: v0.0.0+3058-c29143f7

--list-cameras 列出连接到树莓派的摄像头及其可用的传感器模式

rpicam-hello --list-cameras

传感器模式标识符有以下形式：

S<Bayer order><Bit-depth>*<Optional packing> : <Resolution list>

裁剪在原生传感器像素（即使在像素分割模式下）中指定为 (<x>， <y>) / <Width> × <Height> 。(x, y) 指定 width × height 大小的裁剪窗口在传感器阵列中的位置。

例如，以下输出显示索引为 0 的 IMX219 传感器和索引为 1 的 IMX477 传感器的信息：

Available cameras

---

0 : imx219 [3280x2464] (/base/soc/i2c0mux/i2c@1/imx219@10)
Modes: 'SRGGB10_CSI2P' : 640x480 [206.65 fps - (1000, 752)/1280x960 crop]
1640x1232 [41.85 fps - (0, 0)/3280x2464 crop]
1920x1080 [47.57 fps - (680, 692)/1920x1080 crop]
3280x2464 [21.19 fps - (0, 0)/3280x2464 crop]
'SRGGB8' : 640x480 [206.65 fps - (1000, 752)/1280x960 crop]
1640x1232 [41.85 fps - (0, 0)/3280x2464 crop]
1920x1080 [47.57 fps - (680, 692)/1920x1080 crop]
3280x2464 [21.19 fps - (0, 0)/3280x2464 crop]
1 : imx477 [4056x3040] (/base/soc/i2c0mux/i2c@1/imx477@1a)
Modes: 'SRGGB10_CSI2P' : 1332x990 [120.05 fps - (696, 528)/2664x1980 crop]
'SRGGB12_CSI2P' : 2028x1080 [50.03 fps - (0, 440)/4056x2160 crop]
2028x1520 [40.01 fps - (0, 0)/4056x3040 crop]
4056x3040 [10.00 fps - (0, 0)/4056x3040 crop]

--camera 选择要使用的相机。从可用摄像机列表中指定一个索引。

rpicam-hello --list-cameras 0
rpicam-hello --list-cameras 1

--config -c , 指定一个文件，里面包含了指令参数选项和值。一般是起名为 example_configuration.txt 的文件，将选项和值指定为键值对，每行一个选项

timeout=99000

verbose=

注意：省略通常在命令行中使用参数的前缀--。对于缺少值的标志，例如上面示例中的 verbose，必须包含尾随的=。 然后可以运行以下命令，来指定 99000 毫秒的超时和详细输出：

rpicam-hello --config example_configuration.txt

--time -t, 默认 5000 毫秒的延时

rpicam-hello -t

指定应用程序在关闭前运行多长时间。这适用于视频录制和预览窗口。当捕获静止图像时，应用程序在捕获输出图像之前显示一个超时毫秒的预览窗口。

rpicam-hello -t 0

--preview 设置桌面或 DRM 预览窗口的位置 (x,y 坐标）和大小 (w,h 尺寸）。不会影响从相机请求的图像的分辨率或宽高比 以以下逗号分隔的形式传递预览窗口尺寸：x,y,w,h

rpicam-hello --preview 100,100,500,500

--fullscreen -f , 强制预览窗口使用整个屏幕，没有边框或标题栏。缩放图像以适应整个屏幕。不接受值

rpicam-hello -f

--qt-preview 使用 Qt 预览窗口，它比其他选项消耗更多的资源，但支持 X 窗口转发。与全屏标志不兼容。不接受值。

rpicam-hello --qt-preview

--nopreview 使应用程序不显示预览窗口。不接受值

rpicam-hello --nopreview

--info-text 默认值："#%frame (%fps fps) exp %exp ag %ag dg %dg"

在桌面环境中运行时，将提供的字符串设置为预览窗口的标题。支持以下图像元数据替换： 指令 说明

%frame 帧序列号
%fps 瞬时帧速率
%exp 捕捉图像时的快门速度， 单位是 ms
%ag 感光芯片控制的图像模拟增益
%dg 通过 ISP 控制的图像数值增益
%rg 每个像素点红色组件的增益
%bg 每个像素点蓝色组件的增益
%focus 图像的角点度量，数值越大表示图像越清晰
%lp 当前镜头的屈光度 （1/米为单位的距离）
%afstate 自动对焦状态 (idle, scanning, focused, failed)
rpicam-hello --info-test "Focus measure: %focus"

--width

--height

每个都接受一个单独的数字来定义所捕获图像的尺寸（以像素为单位）。

对于 rpicam-still 、 rpicam-jpeg 和 rpicam-vid ，指定输出分辨率。

对于 rpicam-raw ，指定原始帧分辨率。对于具有 2×2 bin 读出模式的相机，指定一个等于或小于 bin 模式的分辨率捕获 2×2 bin 原始帧。

对于 rpicam-hello 没有效果。

录制 1080p 的视频

rpicam-vid -o test.h264 --width 1920 --height 1080

捕获 2028×1520 分辨率的 JPEG。如果与 HQ 相机一起使用，则使用 2×2 bin 模式，因此原始文件 (test. ng) 包含 2028×1520 原始 Bayer 图像。

rpicam-still -r -o test.jpg --width 2028 --height 1520
--viewfinder-width
--viewfinder-height

每个参数都能接受一个数字，以像素为单位定义预览窗口中显示的图像的尺寸。不影响预览窗口的尺寸，因为图像会调整大小以适应。不影响捕获的静止图像或视频。

rpicam-still --viewfinder-width 1920 --viewfinder-height 1080

--mode 允许以以下冒号分隔格式指定相机模式： <width>:<height>:<bit-depth>:<packing> , 如果提供的值没有精确匹配，系统将为传感器选择最接近的可用选项。可以使用 packed(P) 或者 unpacked(U) 的打包格式，影响存储的视频和静止图像的格式，但不影响传递到预览窗口的帧的格式。

Bit-depth 和 packing 是可选的，Bit-depth 默认是 12,Packing 默认为 P（已打包）。

有关传感器可用的位深度、分辨率和 packing 选项的信息，请参见 list-cameras。

如下所示：

4056:3040:12:P - 4056×3040 resolution, 12 bits/pixel, packed.
1632:1224:10 - 1632×1224 resolution, 10 bits/pixel.
2592:1944:10:U - 2592×1944 resolution, 10 bits/pixel, unpacked.
3264:2448 - 3264×2448 resolution.

--viewfinder-mode 与 mode 选项相同，但它适用于传递给预览窗口的数据。有关更多信息，请参阅 mode 文档。

--lores-width 和 --lores-height 提供来自相机的第二个低分辨率图像流，按比例缩小到指定的尺寸。每个都接受一个数字来定义低分辨率流的维度（以像素为单位）。可用于预览和视频模式。不提供静态捕获。对于 rpicam-vid，禁用额外的颜色去噪处理。对结合图像后处理的图像分析有用。

rpicam-hello --lores-width 224 --lores-height 224

--hflip 水平翻转图像。不接受值。

rpicam-hello --hflip -t 0

--vflip 垂直翻转图像。不接受值。

rpicam-hello --vflip -t 0

--rotation 旋转从传感器提取的图像。只接受值 0 或 180。

rpicam-hello --rotation 0

--roi 对从传感器全域提取的图像进行裁剪。接受四个十进制值，范围从 0 到 1，格式如下： <x>, <y>, <w>, <h> 。这些值中的每一个都以 0 到 1 之间的小数表示可用宽度和高度的百分比。

这些值定义了以下比例：

<x>: 在提取图像之前要跳过的 x 坐标

<y>: 在提取图像之前要跳过的 y 坐标

<w>: 要提取的图像宽度

<h>: 要提取的图像高度

默认为 0,0,1,1（从第一个 X 坐标和第一个 Y 坐标开始，使用 100%的图像宽度，使用 100%的图像高度）。

例子：

rpicam-hello --roi 0.25,0.25,0.5,0.5 选择从图像中心裁剪的像素总数的一半（跳过前 25%的 X 坐标，跳过前 25%的 Y 坐标，使用图像总宽度的 50%，使用图像总高度的 50%)。

rpicam-hello --roi 0,0,0.25,0.25 选择从图像左上角裁剪的像素总数的四分之一（跳过 X 坐标的前 0%，跳过 Y 坐标的前 0%，使用图像宽度的 25%，使用图像高度的 25%)。

--hdr 默认值：关闭，在 HDR 模式下运行相机。如果没有传递值，则假定为 auto。接受下列值之一：

off -禁用 HDR。

auto -在支持的设备上启用 HDR。如果可用，使用传感器的内置 HDR 模式。如果传感器没有内置 HDR 模式，则使用板载 HDR 模式（如果可用）。

single-exp 在支持的设备上启用 HDR。如果可用，使用传感器的内置 HDR 模式。如果传感器没有内置 HDR 模式，则使用板载 HDR 模式（如果可用）。

rpicam-hello --hdr

使用板载 HDR 模式，如果可用，即使传感器有一个内置的 HDR 模式。如果板载 HDR 模式不可用，则禁用 HDR。

Raspberry Pi 5 及更高版本的设备具有板载 HDR 模式。

要检查传感器中内置的 HDR 模式，将此选项添加到列表相机中。

camera 控制选项​

以下选项控制影响相机图像质量的图像处理和算法。

sharpness 设置图像清晰度。接受以下范围内的数值：

0.0 是不应用锐化

大于 0.0 但小于 1.0 的值应用的锐化量小于默认值

1.0 应用默认锐化量

大于 1.0 的值应用额外的锐化

rpicam-hello --sharpness 0.0

contrast 指定图像对比度。接受以下范围内的数值：

0.0 适用最小对比度

大于 0.0 但小于 1.0 的值应用的对比度小于默认值

1.0 应用默认的对比度

大于 1.0 的值应用额外的对比度

rpicam-hello --contrast 0.0

brightness 指定图像亮度，作为输出图像中所有像素的偏移量添加。接受以下范围内的数值：

-1.0 最小亮度（黑色）

0.0 应用标准亮度

1.0 应用最大亮度（白色）

对于更多的用法，推荐 ev。

rpicam-hello --brightness 1.0

saturation 指定图像颜色饱和度。接受以下范围内的数值：

0.0 应用最小饱和度（灰度）

大于 0.0 但小于 1.0 的值应用的饱和度小于默认值

1.0 应用默认的饱和度

大于 1.0 的值应用额外的饱和度

rpicam-hello --saturation 0.6

ev 指定图像的曝光值 (EV) 补偿。接受一个数值，该数值控制沿着以下频谱传递给自动曝光/增益控制 (AEC/AGC) 处理算法的目标值：

-10.0 应用最小目标值

0.0 应用标准目标值

10.0 应用最大目标值

rpicam-hello --ev 10.0

shutter 指定使用快门的曝光时间，以微秒为单位。当您使用此选项时，增益仍然可以变化。如果相机运行的帧率太快，它不允许指定的曝光时间（例如，帧率为 1fps，曝光时间为 10000 微秒），传感器将使用帧率允许的最大曝光时间。

有关官方相机的最小和最大快门时间列表，请参阅相机硬件文档。高于最大值的值会导致未定义的行为。

rpicam-hello --shutter 10000

gain

analoggain 与 gain 的效果是一样的 设置组合模拟和数字增益。当传感器驱动可以提供所要求的增益时，只使用模拟增益。当模拟增益达到最大值时，ISP 应用数字增益。 接受数值。

有关官方摄像机的模拟增益限制列表，请参阅摄像机硬件文档。

有时，即使在不超过模拟增益限制的情况下，数字增益也会超过 1.0。这可能发生在以下情况：

其中任何一个颜色增益低于 1.0，这将导致数字增益稳定在 1.0/min（红增益，蓝增益）。这使总数字增益应用于任何高于 1.0 的颜色通道，以避免变色伪影。

自动曝光/增益控制 (AEC/AGC) 变化时的轻微差异。

rpicam-hello --gain 0.8

metering 默认值：centre

设置自动曝光/增益控制 (AEC/AGC) 算法的测光模式。接受以下值：

centre 中心加权计量

spot 点测光

average 平均或全帧测光

custom 自定义测光模式定义在相机调整文件

有关定义自定义测光模式和在现有测光模式中调整区域权重的更多信息，请参阅 Raspberry Pi 相机和 libcamera 的调谐指南。

rpicam-hello --metering centre

exposure 设置曝光配置文件。更改曝光配置文件不应影响图像曝光。相反，不同的模式调整增益设置，以达到相同的净结果。接受以下值：

sport: 曝光时间短，收益大

normal: 正常暴露，正常增益

long: 曝光时间长，收益小

您可以使用调谐文件编辑曝光配置文件。有关更多信息，请参阅 Raspberry Pi 相机和 libcamera 的调谐指南。

rpicam-hello --exposure sport

awb 设置曝光配置文件。更改曝光配置文件不应影响图像曝光。相反，不同的模式调整增益设置，以达到相同的最终结果。接受以下值：可用的白平衡模式：

模式 色温
auto 2500K ~ 8000K
incadescent 2500K ~ 3000K
tungsten 3000K ~3500K
fluorescent 4000K ~ 4700K
indoor 3000K ~ 5000K
daylight 5500K ~ 6500 K
cloudy 7000K ~ 8500K

custom 自定义范围， 通过调谐文件设置

这些值只是近似值：值可能会根据相机调整而变化。

没有模式完全禁用 AWB。相反，你可以用 awbgains 来修正颜色增益。

有关 AWB 模式的更多信息，包括如何定义自定义模式，请参阅 Raspberry Pi 相机和 libcamera 的调谐指南。

rpicam-hello --awb auto

awbgains 设置一个固定的红蓝增益值来代替自动白平衡 (AWB) 算法。设置非零值禁用 AWB。接受以逗号分隔的数字输入，格式如下：<red_gain>, <blue_gain>

rpicam-jpeg -o test.jpg --awbgains 1.5,2.0

denoise

默认值：auto

设置去噪模式。接受以下值：

auto: 启用标准空间降噪。对视频使用超快的彩色去噪，对图像使用高质量的彩色去噪。在预览窗口中不启用额外的颜色噪点。

off: 关闭空间和颜色去噪。

cdn_off: 禁用颜色噪点。

cdn_fast: 使用快速颜色去噪。

cdn_hq: 使用高质量的颜色去噪。由于吞吐量降低，不适合视频/取景器。

即使是快速的色彩降噪也会降低帧率。高质量的色彩降噪显著降低了帧率。

rpicam-hello --denoise off

tuning-file

指定摄像机调谐文件。调整文件允许您控制图像处理的许多方面，包括自动曝光/增益控制 (AEC/AGC)，自动白平衡 (AWB)，色彩阴影校正，色彩处理，去噪等等。接受调谐文件路径作为输入。 有关调谐文件的详细信息，请参见调谐文件。

autofocus-mode

默认值：default 指定自动对焦模式。接受以下值：

default: 将相机置于连续自动对焦模式，除非镜头位置或自动对焦捕捉覆盖到手动模式

manual: 不移动镜头，除非手动配置镜头位置

auto: 仅在相机启动时或在捕捉之前移动镜头进行自动对焦扫描，如果也使用了自动对焦捕捉功能

continuous: 随场景变化自动调整镜头位置

此选项仅支持某些相机模块。

rpicam-hello --autofocus-mode auto

autofocus-range

默认值：normal

指定自动对焦范围。接受以下值：

normal: 聚焦范围相当接近无穷远

macro: 仅对焦近处的物体，包括相机支持的最近焦距

full: 聚焦整个范围，从最近的物体到无穷远

此选项仅支持某些相机模块。

rpicam-hello autofocus-range normal

autofocus-speed

默认值：normal

指定自动对焦速度。接受以下值：

normal: 以正常速度改变镜头位置

fast: 快速改变镜头位置

此选项仅支持某些相机模块。

rpicam-hello --autofocus-speed normal

autofocus-window

指定传感器全域内的自动对焦窗口。接受四个十进制值，范围从 0 到 1，格式如下： <x>,<y>,<w>,<h> 。这些值中的每一个都以 0 到 1 之间的小数表示可用宽度和高度的百分比。

这些值定义了以下比例：

<x> : 在应用自动对焦之前要跳过的 x 坐标

<y> : 在应用自动对焦之前要跳过的 y 坐标

<w> : 自动对焦区域宽度

<h> : 自动对焦区域高度

默认值在两个维度中使用输出图像的中间三分之一（总图像区域的 1/9)。

例子：

rpicam-hello—autofocus-window 0.25,0.25,0.5,0.5

选择从图像中心裁剪的像素总数的一半（跳过前 25%的 X 坐标，跳过前 25%的 Y 坐标，使用图像总宽度的 50%，使用图像总高度的 50%)。

rpicam-hello—autofocus-window 0,0,0.25,0.25

选择从图像左上角裁剪的像素总数的四分之一（跳过 X 坐标的前 0%，跳过 Y 坐标的前 0%，使用图像宽度的 25%，使用图像高度的 25%)。

此选项仅支持某些相机模块。

lens-position

默认值：default 将镜头移动到一个固定的焦距，通常以屈光度表示（单位为 1/米距离）。接受以下值范围：

0.0: 将镜头移动到“无限远”位置

任何其他数字：将镜头移动到 1 /数字位置。例如，值 2.0 将聚焦在大约 0.5m 处

normal: 将镜头移动到与镜头超焦距位置相对应的默认位置

镜头校准并不完善，因此同一型号的不同相机模块可能会有所不同。

verbose

别名： -v

默认值：1 设置详细程度。接受以下值：

0：无输出

1：正常输出

2：详细输出

rpicam-hello --verbose 1

更详细的资料，请参考 树莓派官方文档。