Camera software

libcamera is an open source Linux community project. More information is available at the libcamera website. libcamera是一个开源的 Linux 社区项目。更多信息可在https://libcamera.org[libcamera网站]上找到。

libcamera源代码可以在官方的https://git.linuxtv.org/libcamera.git/[libcamera存储库]中找到并签出，尽管我们从一个https://github.com/raspberrypi/libcamera.git[fork]开始工作，这个fork允许我们控制何时获得libcamera更新。

在libcamera内核的下面，Raspberry Pi提供了一个自定义的管道处理程序，libcamera使用这个层来驱动Raspberry Pi本身上的传感器和ISP(图像信号处理器)。其中还有一部分是众所周知的控制算法，或libcamera术语中的IPAs(图像处理算法)，如AEC/AGC(自动曝光/增益控制)，AWB(自动白平衡)，ALSC(自动镜头阴影校正)等。

所有这些代码都是开源的，现在运行在Raspberry Pi的ARM内核上。GPU上只有一个非常薄的代码层，它将Raspberry Pi自己的控制参数转换为Broadcom ISP的寄存器写入。

Raspberry Pi的libcamera实现不仅支持四个标准Raspberry Pi摄像机(OV5647或V1摄像机、IMX219或V2摄像机、IMX477或HQ摄像机以及IMX708或摄像机模块3)，还支持第三方传感器，如IMX290、IMX327、OV9281、IMX378。Raspberry Pi渴望与那些希望libcamera直接支持其传感器的供应商合作。

此外，Raspberry Pi 为每个传感器提供了一个调整文件，可以对其进行编辑以更改 Raspberry Pi 硬件对从图像传感器接收的原始图像执行的处理，包括颜色处理、噪声抑制量或控制算法的行为等方面。

raspberry-pi-camera-guide.pdf[Tuning Guide for the Raspberry Pi cameras and libcamera]. 有关Raspberry Pi的libcamera更多信息，请参阅https://datasheets.raspberrypi.com/camera/raspberry-pi-camera-guide.pdf[Raspberry Pi相机和 libcamera 的调优指南]。

当运行基于Bullseye的Raspberry Pi操作系统时，已经安装了5个基本的libcamera应用程序。在这种情况下，官方的Raspberry Pi摄像头也会被自动检测并启用。

您可以通过输入以下内容来检查一切是否正常：

您应该会看到相机预览窗口约 5 秒钟。

仍在运行Buster的用户应该升级到Bullseye。那里不再支持新的基于 libcamera 的堆栈，任何仍在使用 Buster 的人都应该继续使用旧的相机堆栈。

在以下情况下，您可能需要更改/boot/config.txt文件中的相机配置：

如果您确实需要添加自己的dtoverlay,目前可以识别以下内容。

要覆盖自动摄像机检测，Bullseye 用户还需要删除条目camera_auto_detect=1(如果在config.txt文件中存在)。编辑此文件后，您的Raspberry Pi需要重新启动。

libcamera-apps使用第三方库来解释命令行选项。这包括长格式选项和短格式选项，长格式选项的选项名由多个以-开头的字符组成，短格式选项只能是以单个-开头的单个字符。在很大程度上，选择的选项名称与传统raspicam应用程序使用的名称相匹配，只是我们不能再用单个-来处理多字符选项名称。任何此类传统选项都已被删除，必须使用带-的长格式来代替。 这些选项大致分为 3 组，即常见选项、特定于静止图像的选项和用于视频编码的选项。它们在应用的所有应用程序中都以相同的方式受支持。 有关完整列表，请参阅命令行选项文档。

Raspberry Pi的libcamera实现包括一个针对每种不同类型的相机模块的调整文件。这是一个描述或“调整”参数的文件，这些参数将被传递给算法和硬件以产生最佳图像质量。libcamera只能自动确定正在使用的图像传感器，而不是作为一个整体的模块——即使整个模块会影响“调整”。

因此，有时需要覆盖特定传感器的默认调整文件。 例如，NOIR（无红外滤光片）版本的传感器需要与标准版本不同的AWB设置，因此IMX219 NOIR应使用运行

如果您使用的是 Soho 企业 SE327M12 模块，则应使用

请注意，这也意味着用户可以复制现有的优化文件并根据自己的首选项对其进行更改，只要—​tuning-file参数指向新版本即可。

最后，与其他libcamera-hello命令行选项一样，tuning-file参数同样适用于所有libcamera-apps。

大多数在窗口中显示libcamera-apps预览图像。当 X Windows 未运行时，它将使用 Linux DRM（直接渲染管理器）直接绘制到显示器，否则它将尝试使用 X Windows。两条路径都使用与 GPU 共享的零拷贝缓冲区，其结果是不支持 X 转发。

出于这个原因，还有第三种预览窗口，它确实支持 X 转发，并且可以通过该—​qt-preview选项请求。此实现既不能受益于零拷贝缓冲区共享，也不能受益于 3D 加速，这使得它的计算成本很高（尤其是对于大型预览），因此通常不建议这样做。

预览窗口可以使用-n （--nopreview） 选项完全禁止显示。

该—​info-text选项允许用户请求使用“%指令”在窗口标题栏上显示某些有用的图像信息。例如

将显示当前的红色和蓝色增益值。

对于 HQ 相机，--info-text "%focus"用于显示对焦测量值，这将有助于对焦镜头。

命令行选项文档中提供了—​info-text参数的完整说明。

所有这些libcamera-apps都允许用户以固定的快门速度和增益运行相机。例如

将捕获曝光为 20 毫秒、增益为 1.5 倍的图像。请注意，增益将作为传感器内的模拟增益应用，直到达到内核传感器驱动程序允许的最大模拟增益，之后其余增益将作为数字增益应用。

Raspberry Pi 的 AEC/AGC 算法允许应用程序指定曝光补偿，即通过给定的停靠点数使图像变暗或变亮的能力，如下所示

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

请注意，保存图像的格式取决于-e（等效）--encoding选项，并且不会根据输出文件名自动选择。

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

捕获原始图像使用

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

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

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

为了拍摄曝光时间很长的图像，我们需要小心禁用AEC/AGC和AWB，否则这些算法将迫使用户在收敛时等待多个帧。禁用它们的方法是提供显式值。此外，可以使用该—​immediate选项跳过捕获的整个预览阶段。

因此，要执行 100 秒曝光捕获，请使用

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

作为参考，三款官方Raspberry Pi相机的最大曝光时间可以在此表中找到。

例如，支持运动JPEG，以及未压缩和未格式化的YUV420

在这两种情况下，--codec参数确定输出格式，而不是输出文件的扩展名。

该—​segment参数将输出文件分解为段大小的块（以毫秒为单位）。这对于通过指定非常短（1毫秒）的段将运动 JPEG 流分解为单独的 JPEG 文件非常方便。

请注意，输出文件名通常只有在我们避免每次都覆盖前一个文件时才明智，例如使用包含计数器的文件名（如上所述）。下面提供了有关输出文件名的更多信息。

使用libcamera-vid捕获高帧率视频（通常超过 60 fps）同时最大限度地减少丢帧需要一些注意事项：

2.软件颜色去噪处理必须与参数—​denoise cdn_off一起关闭。

3.对于超过 100 fps 的速率，使用该-n选项禁用显示窗口将释放一些额外的 CPU 周期，以帮助避免丢帧。

6.在Pi 4上，您可以通过在/boot/config.txt中添加gpu_freq=550或更高版本来对GPU进行超频以提高性能，详细信息请参见https://www.raspberrypi.com/documentation/computers/config_txt.html#overclocking[此处。]

1280x720 120fps 视频编码的示例命令为：

可以使用 libav 后端作为音频/视频的网络流源。为此，-o参数指定的输出文件名必须作为协议 url 提供，有关协议使用的更多详细信息，请参阅 ffmpeg 协议。一些例子：

使用 TCP 流式传输音频/视频

使用 UDP 流式传输音频/视频

设置预览窗口的大小和位置（X Windows 和 DRM 版本）。它不会影响从相机请求的图像的分辨率或纵横比。相机图像将缩放到预览窗口的大小以进行显示，并将采用柱子/信箱以适合。

例: libcamera-hello -p 100,100,500,500

强制预览窗口使用整个屏幕，并且窗口将没有边框或标题栏。同样，图像可能是柱子/信箱。

例 libcamera-still -f -o test.jpg

预览窗口切换为使用基于 Qt 的实现。通常不建议使用此选项，因为它不再使用零拷贝缓冲区共享或 GPU 加速，因此非常昂贵，但是，它确实支持 X 转发（其他预览实现不支持）。

Qt 预览窗口不支持该—​fullscreen选项。通常建议尽量保持预览窗口较小。

例 libcamera-hello --qt-preview

预览窗口被完全禁止显示。

例 libcamera-still -n -o test.jpg

提供的字符串设置为预览窗口的标题（在 X 窗口下运行时）。此外，该字符串可能包含许多%指令，这些指令被来自图像元数据的信息替换。允许的指令是

如果未提供，则- info-text字符串默认为“# % frame(% fps fps)exp % exp ag % ag DG % DG”。

例: libcamera-hello --info-text "Focus measure: %focus"

这些数字指定由libcamera-still、libcamera-jpeg和libcamera-vid捕获的相机图像的输出分辨率。

对于libcamera-raw ，它会影响捕获的原始帧的大小。如果相机具有 2x2 像素合并读出模式，则指定不大于此像素合并模式的分辨率将导致捕获 2x2 像素合并原始帧。

对于libcamera-hello这些参数没有影响。

例子：

libcamera-vid -o test.h264 --width 1920 --height 1080将捕获 1080p 视频。

libcamera-still -r -o test.jpg --width 2028 --height 1520将捕获 2028x1520 分辨率的 JPEG。使用HQ相机时，传感器将以2x2像素合并模式驱动，因此捕获的test.dng原始文件将包含2028x1520原始拜耳图像。

这些选项仅影响预览(意味着libcamera-hello以及libcamera-jpeg和libcamera-still的预览阶段)，并指定预览窗口将从相机请求的图像大小。它们对拍摄的静态图像或视频没有影响。它们也不会影响预览窗口，因为它们会调整图像的大小以适合预览窗口。

例: libcamera-hello --viewfinder-width 640 --viewfinder-height 480

该选项强制传感器以全分辨率读出模式进行静态和视频捕捉，而不考虑所要求的输出分辨率(由-宽度和-高度给出)。对libcamera-hello没有影响。

使用此选项通常会导致帧速率损失，因为分辨率较大的帧读出速度较慢。

示例:lib camera-raw-t 2000-segment 1-raw full-o test % 03d . raw将导致捕获多个全分辨率原始帧。在HQ摄像机上，每帧的大小约为18MB。如果没有- rawfull选项，默认的视频输出分辨率会导致选择2x2装箱模式，从而产生4.5MB的原始帧。

此选项比- rawfull更通用，允许精确选择一种相机模式。应该通过给出其宽度、高度、位深度和包装来指定模式，用冒号分隔。这些数字不必精确，因为系统将选择它能找到的最接近的数字。此外，位深度和打包是可选的(分别默认为12和P表示“打包”)。例如:

此选项与- mode选项相同，只是它仅适用于静止图像捕捉的预览阶段(也由libcamera-hello应用程序使用)。

libcamera允许将第二个较低分辨率的图像流从相机系统传送到应用程序。该流可用于预览和视频模式(即libcamera-hello和libcamera-still的预览阶段，以及libcamera-vid)，并且可用于图像分析等。对于静止图像捕捉，低分辨率图像流不可用。

低分辨率流与其他图像流具有相同的视野。如果为低分辨率流指定了不同的纵横比，则将挤压这些图像，以便像素不再是正方形。

在视频录制 （libcamera-vid） 期间，指定低分辨率流将禁用通常会发生的一些额外的颜色去噪处理。

例: libcamera-hello --lores-width 224 --lores-height 224

请注意，除非与图像后处理结合使用，否则低分辨率流不是特别有用。

这些选项影响传感器的读取顺序，可用于水平镜像图像和/或垂直翻转图像。- rotation选项只允许值0或180，因此请注意，不支持90或270度旋转。而且，-旋转180°等同于- hflip - vflip。

例: libcamera-hello --vflip --hflip

该—​roi参数实现了通常称为“数字变焦”的内容。

示例libcamera-hello --roi 0.25,0.25,0.5,0.5将精确选择从图像中心裁剪的像素总数的四分之一。

hdr选项使摄像机运行在HDR(高动态范围)模式。此选项仅适用于某些受支持的相机，包括Raspberry Pi相机模块3。

例如:lib camera-still-HDR-o hdr.jpg用于捕捉静态图像，或libcamera-vid - hdr -o hdr.h264用于捕捉视频。

用户也可以提供- hdr 0或- hdr 1，前者禁用hdr模式(相当于完全省略该选项)，后者与单独使用- hdr相同。

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

给定<number>调整图像清晰度。值零表示不应用锐化，值 1.0 使用默认锐化量，大于 1.0 的值使用额外锐化。

例：libcamera-still -o test.jpg --sharpness 2.0

给定<number>调整图像对比度。值零产生最小对比度，值 1.0 使用默认对比度量，大于 1.0 的值应用额外的对比度。

例：libcamera-still -o test.jpg --contrast 1.5

给定<number>调整图像亮度。值 -1.0 生成（几乎）黑色图像，值 1.0 生成几乎完全白色的图像，值 0.0 生成标准图像亮度。

请注意，亮度参数会添加（或减去）输出图像中所有像素的偏移量。该—​ev选项通常更合适。

例：libcamera-still -o test.jpg --brightness 0.2

给定的调整颜色饱和度。值零生成灰度图像，值 1.0 使用默认的分色量，大于 1.0 的值应用额外的颜色饱和度。<number>

例: libcamera-still -o test.jpg --saturation 0.8

以光圈为单位设置图像的 EV 补偿，范围为 -10 到 10。默认值为 0。它通过提高或降低 AEC/AGC 算法尝试匹配的目标值来工作。

例: libcamera-still -o test.jpg --ev 0.3

快门时间固定为给定值。增益仍将允许变化（除非这也是固定的）。

请注意，如果照相机以太快而不允许的帧速率运行，则可能无法实现此快门时间。在这种情况下，该—​framerate选项可用于降低帧速率。官方支持的Raspberry Pi的最大可能快门时间可以在此表中找到。

使用高于这些最大值的值将导致未定义的行为。相机也将具有不同的最小快门时间，尽管实际上这并不重要，因为它们都足够低，可以适当地曝光明亮的场景。

例: libcamera-hello --shutter 30000

这两个选项实际上是相同的，并且设置将要使用的组合模拟和数字增益。允许使用- analoggain格式，以便与传统的raspicam应用程序更加兼容。在传感器驱动器可以提供所需增益的情况下，将只使用模拟增益。一旦模拟增益达到最大允许值，超过该值的额外增益将作为数字增益提供。

请注意，在某些情况下，即使未超过模拟增益限值，数字增益也可能超过1。这可能发生在以下情况下

设置 AEC/AGC 算法的计量模式。这可能是以下值之一

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

例: libcamera-still -o test.jpg --metering spot

曝光曲线可以是正常的、运动的或长的。改变曝光模式应该不会影响图像的整体曝光，但是运动模式倾向于选择更短的曝光时间和更大的增益来获得相同的最终结果。

可以在相机调整文件中编辑曝光配置文件。有关更多信息，请参阅 Raspberry Pi 相机和 libcamera 的调优指南 。

例: libcamera-still -o test.jpg --exposure sport

此选项将 AWB 算法设置为命名 AWB 模式。有效模式包括：

没有关闭AWB的模式，而是应使用该—​awbgains选项指定固定的颜色增益。

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

有关AWB模式以及如何定义自定义模式的更多信息，请参阅https://datasheets.raspberrypi.com/camera/raspberry-pi-camera-guide.pdf[Raspberry Pi相机和libcamera的调整指南]。

例: libcamera-still -o test.jpg --awb tungsten

此选项接受红色和蓝色增益值，并直接使用它们来代替运行AWB算法。在此处设置非零值具有禁用 AWB 计算的效果。

例: libcamera-still -o test.jpg --awbgains 1.5,2.0

支持以下降噪模式：

请注意，即使使用快速去色也会导致帧速率降低。高质量的色彩去噪通常会导致低得多的帧速率。

例: libcamera-vid -o test.h264 --denoise cdn_off

这标识应使用的 JSON 格式优化文件的名称。调谐文件涵盖了图像处理的许多方面，包括 AEC/AGC、AWB、色彩渐晕校正、色彩处理、去噪等。

For more information on the camera tuning file, please consult the Tuning guide for the Raspberry Pi cameras and libcamera. 有关相机调谐文件的更多信息，请参阅https://datasheets.raspberrypi.com/camera/raspberry-pi-camera-guide.pdf[Raspberry Pi相机和 libcamera 的调优指南]。

例: libcamera-hello --tuning-file ~/my-camera-tuning.json

指定要使用的自动对焦模式，该模式可能是以下模式之一

此选项仅支持某些相机模块（例如Raspberry Pi相机模块 3）。

指定自动对焦范围，可以是以下范围之一

此选项仅支持某些相机模块（例如Raspberry Pi相机模块 3）。

指定自动对焦速度，可以是

此选项仅支持某些相机模块（例如Raspberry Pi相机模块 3）。

以x，y，width，height的形式指定自动对焦窗口，其中坐标以整个图像的比例给出。例如，-自动聚焦-窗口0.25，0.25，0.5，0.5将选择一个窗口，该窗口在每个维度上是输出图像大小的一半，并且居中。

默认值会导致算法在两个维度上使用输出图像的中间三分之一（即总图像面积的 1/9）。

此选项仅支持某些相机模块（例如Raspberry Pi相机模块 3）。

将镜头移动到固定焦距，通常以屈光度（单位 1 / 以米为单位的距离）给出。我们有

应该注意的是，镜头只能预期近似校准，并且不同相机模块之间可能存在差异。 此选项仅支持某些相机模块（例如Raspberry Pi相机模块 3）。

--output 设置要写入输出图像或视频的输出文件的名称。除了常规文件名外，这可能采用以下特殊值：

例子：

lib camera-vid-t 100000-segment 10000-o chunk % 04d . h264以10秒的片段记录一个100秒的文件，其中每个文件都被命名为chunk.h264，但包含一个递增计数器。请注意,%04d将计数写入字符串，但通过添加前导零来填充总宽度至少为4个字符。

libcamera-vid -t 0 --inline -o udp://192.168.1.13:5000将 H.264 视频流式传输到端口 192 上的网络地址 168.1.13.5000。

当输出到具有递增计数器的文件时（例如 %d在输出文件名中），当计数器达到此值时，将计数器包装回零。

例: libcamera-vid -t 0 --codec mjpeg --segment 1 --wrap 100 -o image%d.jpg

--flush 导致输出文件在写入每一帧后立即刷新到磁盘，而不是等待系统执行此操作。

例: libcamera-vid -t 10000 --flush -o test.h264

后处理是一个大话题，它承认使用OpenCV和TensorFlowLite等第三方软件来分析和操作图像。有关更多信息，请参阅后处理部分。

例: libcamera-hello --post-process-file negate.json

如果negate.json文件配置正确，这可能会对映像应用“否定”效果。

该negate阶段不需要第三方库。

在Raspberry Pi 3 设备或运行 4 位操作系统的Raspberry Pi 32 上，如果使用-DENABLE_COMPILE_FLAGS_FOR_TARGET=armv8-neon .（请参阅构建说明)。

negate阶段没有用户可配置的参数。

默认negate.json文件：

Example:

hdr阶段同时实现HDR（高动态范围）成像和DRC（动态范围压缩）。我们在这里使用的术语将 DRC 视为对单个图像进行操作，而 HDR 的工作原理是累积多个曝光不足的图像，然后执行与 DRC 相同的算法。

hdr阶段不依赖于第三方库，但是(像其他一些阶段一样)如果使用-den able _ COMPILE _ FLAGS _ FOR _ TARGET = arm V8-neon重新编译，可能会在运行32位操作系统的Raspberry Pi 3或Raspberry Pi 4设备上执行得更快(请参见构建说明)。具体来说，图像累积阶段将运行得更快，并导致更少的丢帧，尽管该过程的色调映射部分没有改变。

基本步骤是我们获取图像（在HDR的情况下可能是多个图像累积在一起）并应用边缘保留平滑过滤器来生成低通（LP）图像。我们将高通（HP）图像定义为LP图像与原始图像之间的差异。接下来，我们将全局色调图应用于 LP 图像并添加回 HP 图像。与将色调图直接应用于原始图像相比，此过程可防止我们挤压和丢失结果图像中的所有局部对比度。

值得注意的是，一旦ISP完成处理完图像，这一切都是使用完全处理的图像进行的。HDR通常在原始（Byer）域中进行时效果更好，因为信号仍然是线性的并且具有更大的位深度。我们希望在libcamera导出用于“重新处理”拜耳图像的API后实现此类功能，这些图像不是来自传感器，而是应用程序代码可以传入。

总之，用户可配置的参数大致分为三组：定义LP滤波器的参数，负责全局色调映射的参数，以及负责重新应用局部对比度的参数。

我们注意到，通过更改global_tonemap_strength 和 local_tonemap_strength参数来最好地控制加工的整体强度。

Raspberry Pi 2 上的 3MP 图像需要 12 到 4 秒的完整处理时间。舞台仅在静止图像捕获上运行，它忽略预览和视频图像。特别是，当累积多个帧时，舞台“吞噬”输出图像，以便应用程序不会接收它们，最后仅通过组合和处理的图像发送。

DRC 的drc.json默认文件：

Example:

如果没有 DRC：

使用全强度 DRC：（使用libcamera-still -o test.jpg --post-process-file drc.json)

HDR 的默认hdr.json文件：

Example:

没有 HDR：

使用 HDR：（使用libcamera-still -o test.jpg --ev -2 --denoise cdn_off --post-process-file hdr.json)

motion_detect阶段通过分析低分辨率图像流中的帧来工作，必须对其进行配置才能使其工作。它将帧中的感兴趣区域（“roi”）与前一个帧的相应部分进行比较，如果有足够的像素足够不同，则将采取这些像素来指示运动。结果将添加到“motion_detect.result”下的元数据中。

此阶段不依赖于任何第三方库。

它具有以下可调参数。尺寸始终作为低分辨率图像大小的比例给出。

默认motion_detect.json配置文件：

注意，可以调整场difference_m和difference_c以及region_threshold的值，以使算法对运动或多或少地敏感。 如果需要减少计算量（也许您还有其他阶段需要更大的低分辨率图像），则可以使用 hskip和vskip 参数减少计算量。

若要使用该motion_detect阶段，可以输入以下示例命令：

libcamera-hello --lores-width 128 --lores-height 96 --post-process-file motion_detect.json

sobel_cv阶段具有以下用户可配置的参数：

默认sobel_cv.json文件：

Example:

此阶段使用 OpenCV Haar 分类器来检测图像中的人脸。它返回元数据中的人脸位置（在键“face_detect.results”下），并选择性地将它们绘制在图像上。

face_detect_cv阶段具有以下用户可配置的参数：

“face_detect_cv”阶段仅在预览和视频捕获期间运行;它忽略静止图像捕获。它在低分辨率流上运行，该流通常配置为大约 320x240 到 640x480 像素的分辨率。

默认face_detect_cv.json文件：

Example:

此阶段允许将文本写入图像的上角。它允许与%--info-text参数相同的替换。

除了--info-text标志之外，您还可以提供https://www.man7.org/linux/man-pages/man3/strftime.3.html[strftime]能够理解的任何标记来显示当前日期/时间。首先解释- info-text标记，然后strftime解释剩余的任何百分比标记。要在视频上获得日期时间标记，您可以使用%F %T %z (%F表示ISO-8601日期(2023-03-07)，%T表示24小时本地时间(09:57:12)，而%z表示与UTC (-0800)的时区差异。）

该阶段不输出任何元数据，但如果它在键“annotate.text”下找到元数据，它将写入此文本来代替 JSON 配置文件中的任何内容。这允许其他后处理阶段将其传递给要写入图像顶部的文本字符串。

annotate_cv阶段具有以下用户可配置的参数：

默认annotate_cv.json文件：

Example:

object_classify_tf使用 Google MobileNet v1 模型对相机图像中的对象进行分类。 它可以从需要解压缩的 https://storage.googleapis.com/download.tensorflow.org/models/mobilenet_v1_2018_08_02/mobilenet_v1_1.0_224_quant.tgz 中获得。您还需要可以在 https://storage.googleapis.com/download.tensorflow.org/models/mobilenet_v1_1.0_224_frozen.tgz 中找到labels.txt文件。

此阶段具有以下可配置参数。

示例文件object_classify_tf.json：

此阶段在大小为 224x224 的低分辨率流图像上运行，因此可以按如下方式使用： libcamera-hello --post-process-file object_classify_tf.json --lores-width 224 --lores-height 224

pose_estimation_tf使用一个Google MobileNet v1模型posenet _ MobileNet _ v1 _ 100 _ 257 x257 _ multi _ kpt _ stripped . tflite，可以在https://github . com/QE engineering/tensor flow _ Lite _ Pose _ RPi _ 32-bits找到。

此阶段具有以下可配置参数。

还提供了单独的plot_pose_cv阶段，可以包含在 JSON 配置文件中，并将检测到的姿势绘制到主图像上。此阶段具有以下配置参数。

示例文件pose_estimation_tf.json：

此阶段在大小为 257x257 的低分辨率流图像上运行（但对于 YUV258 图像，必须向上舍入为 258x420），因此可以按如下方式使用：

libcamera-hello --post-process-file pose_estimation_tf.json --lores-width 258 --lores-height 258

object_detect_tf使用Google MobileNet v1 SSD（单发检测器）模型。可以从 https://storage.googleapis.com/download.tensorflow.org/models/tflite/coco_ssd_mobilenet_v1_1.0_quant_2018_06_29.zip 下载模型和标签文件。

此阶段具有以下可配置参数。

还提供了单独的object_detect_draw_cv阶段，可以包含在 JSON 配置文件中，并将检测到的对象绘制到主映像上。此阶段具有以下配置参数。

示例文件object_detect_tf.json：

此阶段在大小为 300x300 的低分辨率流图像上运行。以下示例将从 300x300 低分辨率图像的中心将 400x300 裁剪传递到检测器。

libcamera-hello --post-process-file object_detect_tf.json --lores-width 400 --lores-height 300

segmentation_tf使用Google MobileNet v1模型。模型文件可以从https://tfhub . dev/tensor flow/lite-model/deeplabv3/1/metadata/2下载？lite-format=tflite，而标签文件可以在assets文件夹中找到，名为segmentation_labels.txt。

此舞台在大小为 257x257 的图像上运行。由于 YUV420 图像必须具有均匀的尺寸，因此低分辨率图像的宽度和高度都应至少为 258 像素。舞台将 257x257 值的矢量添加到图像元数据中，其中每个值指示像素属于哪个类别（在标签文件中列出）。或者，可以将分割的表示绘制到图像的右下角。

此阶段具有以下可配置参数。

示例文件segmentation_tf.json：

本示例拍摄一个方形相机图像，并将其缩小到 258x258 像素的大小。事实上，当非方形图像被不均匀地挤压到 258x258 像素而不裁剪时，舞台也运行良好。下图显示了右下角的分割图。

libcamera-hello --post-process-file segmentation_tf.json --lores-width 258 --lores-height 258 --viewfinder-width 1024 --viewfinder-height 1024

后处理阶段有一个简单的API，用户可以通过从PostProcessingStage类派生来创建自己的API。下面列出了必须实现的成员函数，但请注意，对于简单阶段，某些函数可能是不必要的。

编写自己的阶段的一些有用提示：

最简单的示例是 negate_stage.cpp，它“否定”图像（将黑白，反之亦然）。除了少量派生类样板文件外，它只包含六行代码。

接下来的复杂性是sobel_cv_stage.cpp 。这只使用几行OpenCV函数实现了Sobel过滤器。

对于想要使用TensorFlowLite分析图像的阶段，我们提供TfStage基类。这提供了一定数量的样板代码，并且通过从此类派生来实现基于 TFLite 的新阶段变得更加容易。特别是，它将模型的执行委托给另一个线程，以便仍然保持完整的相机帧速率 - 它只是模型将以较低的帧速率运行。

TfStage类实现所有通常必须重新定义的公共PostProcessingStage方法，但Name方法除外，它仍然必须提供。然后它给出了下面的虚方法，派生类应该实现这些虚方法。

For further information, readers are referred to the supplied example code implementing the ObjectClassifyTfStage and PoseEstimationTfStage classes.

有两个libcamera-apps包可用，其中包含必要的可执行文件：

对于Bullseye用户，官方Raspberry Pi相机应该会自动检测。其他用户将需要编辑他们的 /boot/config.txt 文件，如果他们以前没有这样做过。

这些应用程序依赖于许多名为 library-name<n 的库包>其中 <n> 是一个版本号（实际上是 ABI，或应用程序二进制接口，版本），在撰写本文时为零。因此，我们有以下内容：

这些将在需要时自动安装。

libcamera-apps可以自行重建，无需从头开始安装和构建libcamera和libepoxy。要实现这一点，应该安装以下软件包:

随后libcamera-apps可以从 GitHub 签出并重建。

You can rebuild libcamera-apps without first rebuilding the whole of libcamera and libepoxy. If you do not need support for the X11/GLES preview window then libepoxy can be omitted entirely. Mostly this will include Raspberry Pi OS Lite users, and they must be sure to use -DENABLE_X11=0 when running cmake later. These users should run: 您可以重新构建libcamera-apps，而无需首先重新构建整个libcamera和libepoxy。如果你不需要X11/GLES预览窗口的支持，那么libepoxy可以完全省略。这主要包括Raspberry Pi OS Lite用户，并且他们在以后运行cmake时必须确保使用-DENABLE_X11=0。这些用户应该运行:

所有其他用户应执行：

如果您想使用Qt预览窗口，请同时执行

如果要在libcamera-vid 中支持 libav，则必须安装其他库：

现在直接进入构建 libcamera-app 的说明。Raspberry Pi OS Lite 用户应首先检查 git 是否已安装（sudo apt install -y git）。

Rebuilding libcamera from scratch should be necessary only if you need the latest features that may not yet have reached the apt repositories, or if you need to customise its behaviour in some way. 只有当您获取不到“apt”库的最新功能，或者您需要以某种方式定制其行为时，才需要从头开始重建“libcamera”。

首先安装libcamera 的所有必需依赖项。

然后，所有用户都应安装以下内容：

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: 在下面的meson命令中，我们启用了gstreamer插件。如果不需要，可以改为设置-Dgstreamer=disabled，这样就不需要下一对依赖项了。但是如果您让gstreamer保持启用状态，那么您将需要以下内容:

现在我们可以检查并构建libcamera自己。我们查看了Raspberry Pi的libcamera分支，它跟踪官方存储库，但让我们可以准确控制何时选择新功能。

接下来，我们建议Raspberry Pi OS Lite用户运行

Raspberry Pi OS的用户可以改用

唯一的区别是后者还构建了qcam测试应用程序，它依赖于Qt和X Windows(在完成libcamera构建之后，用户可以运行build/src/qcam/qcam来验证libcamera是否正常工作)。

要完成libcamera构建，请运行

libepoxy通常不需要重新构建，因为此库很少更改。但是，如果您确实想从头开始构建它，请按照以下说明进行操作。

首先安装必要的依赖项。

接下来，签出并构建libepoxy.

首先获取libcamera-apps 的必要依赖项。

libcamera-apps生成过程从以下内容开始：

此时，在决定传递什么额外的标志之后，您需要运行cmake。有效标志包括:

对于Raspberry Pi操作系统用户，我们建议使用以下cmake命令：

对于Raspberry Pi OS Lite用户：

在这两种情况下，如果您在Raspberry Pi 3或Raspberry Pi 4上使用32位操作系统，请考虑-den able _ COMPILE _ FLAGS _ FOR _ TARGET = arm V8-neon。如果您已经安装了OpenCV并希望使用基于OPENCV的后处理阶段，请考虑-DENABLE_OPENCV=1。最后，如果您已经安装了TensorFlow Lite并希望在后处理阶段使用它，请考虑-DENABLE_TFLITE=1。

执行您选择的cmake命令后，整个过程以以下内容结束：

最后，如果您尚未这样做，请务必按照dtoverlay“入门”部分中的驱动程序说明进行操作（如果您在那里更改了任何内容，请重新启动）

libcamera-hello是最容易理解的应用程序。它对相机图像做的唯一事情是从消息中提取CompletedRequestPtr(指向CompletedRequest的共享指针):

并将其转发到预览窗口：

需要注意的一件重要事情是，每个完成的请求都必须被回收到摄像机系统，以便可以重用缓冲区，否则它将耗尽用于接收新摄像机帧的缓冲区。使用C++的共享指针和自定义删除机制，当所有对CompletedRequest的引用都被删除时，这个回收过程会自动发生。 因此，在libcamera-hello中，要将完整的请求返回到相机，必须发生两件事。

libcamera-vid与 libcamera-hello不同，但它向事件循环和预览中添加了编解码器。在事件循环开始之前，我们必须为该编码器配置一个回调，该回调说明包含编码图像数据的缓冲区会发生什么。

在这里，我们将缓冲区发送到Output对象，该对象可以根据我们启动应用程序时的选择将其写入文件或通过网络发送。 编码器还获取对CompletedRequest的新引用，因此一旦事件循环、预览窗口和编码器都丢弃了它们的引用，CompletedRequest将自动回收到摄像机系统。

libcamera-raw与libcamera-vid 没有太大区别。它也使用编码器，尽管这次它是一个名为NullEncoder .这仅将输入图像直接视为输出缓冲区，并且注意在输出回调首先处理它之前不要删除其对输入的引用。 但是，这一次，我们不会将任何内容转发到预览窗口，尽管如果需要，我们可以显示（处理过的）视频流。 在此应用程序中使用NullEncoder 可能是矫枉过正的，因为我们可能只是将图像直接发送到Output对象。但是，它有助于强调一般原则，即直接在事件循环中执行过多工作通常是一个坏主意，并且耗时的过程通常最好留给其他线程。

我们讨论libcamera-jpeg，而不是libcamera-still，因为基本思想(将相机从预览模式切换到捕捉模式)是相同的，libcamera-jpeg的附加选项(如延时捕捉)少得多，这些选项会分散对基本功能的注意力。

libcamera-jpeg以通常的方式在预览模式下启动相机，但在适当的时候停止它并切换到静止拍摄：

然后，事件循环将获取不再处于预览模式后出现的第一帧，并将其另存为 JPEG。

Picamera2仅在Raspberry Pi OS Bullseye（或更高版本）图像（32位和64位）上受支持。

Picamera2 在以下设备上不受支持：

在Raspberry Pi OS映像上，Picamera2现在安装了所有GUI（Qt和OpenGL）依赖项。在Raspberry Pi OS Lite上，它是在没有GUI依赖项的情况下安装的，尽管预览图像仍然可以使用DRM / KMS显示。如果这些用户希望使用其他 X-Windows GUI 功能，他们将需要运行

如果您的映像未预装 Picamera2 apt，则推荐安装和更新 Picamera2。

此后，您可以使用以下方法安装Picamera2以及所有GUI（Qt和OpenGL）依赖项。

如果您不需要 GUI 依赖项，请使用

应用于传感器帧的大部分图像处理都是由硬件ISP（图像信号处理器）完成的。这种处理由一组控制算法控制，这些算法又必须提供广泛的参数。这些参数专门针对每个传感器进行调优，并一起收集在称为相机调整文件的 JSON 文件中。

用户可以检查和编辑此调整文件。使用命令行选项`--tuning-file`，用户可以将系统指向完全自定义的相机调整文件。

[[3rd-party-sensors]] ==== 第三方传感器

libcamera可以在Raspberry Pi平台上支持第三方传感器（即Raspberry Pi官方支持的传感器以外的传感器）。为此，必须提供一个有效的开源传感器驱动程序，作者很乐意将其提交给 Linux 内核。`libcamera`需要添加几个额外的文件，其中提供内核驱动程序中可用的特定于设备的信息，包括前面讨论的相机调整文件。

Raspberry Pi 还提供了一个调优工具，可以从几个简单的校准图像自动生成调整文件。

这两个主题都超出了此处文档的范围，但是， Raspberry Pi相机和libcamera的调优指南中提供了完整的信息。

libcamera-still和raspistill都有内置的延时模式，使用- timelapse命令行开关。开关后的值是拍摄之间的时间，以毫秒为单位:

或

定期自动拍照的一个好方法是使用cron。打开cron表进行编辑:

这将询问您想要使用哪个编辑器，或者在您的默认编辑器中打开。在编辑器中打开文件后，添加下面一行来安排每分钟拍摄一张照片(参考raspistill页面中的Bash脚本，尽管您可以使用lib camera——仍然以完全相同的方式):

保存并退出，您应该看到以下消息：

确保您使用例如%04d来确保每个图像都被写入一个新文件:如果您不这样做，那么每个新图像都将覆盖前一个文件。

现在你需要把这些照片拼接成一个视频。你可以用ffmpeg在Raspberry Pi上做这个，但是处理会很慢。您可能更喜欢将图像文件传输到您的台式计算机或笔记本电脑上，并在那里制作视频。

首先，如果尚未安装，则需要安装ffmpeg。

现在您可以使用该ffmpeg工具将 JPEG 文件转换为 mp4 视频：

在Raspberry Pi 3上，每秒可以编码两帧多一点。其他Raspberry Pi型号的性能会有所不同。使用的参数包括：

ffmpeg具有用于各种编码选项和其他设置的全面参数集。可以使用ffmpeg --help 列出这些内容。

要使用 RTP 协议进行流式传输，您可以在服务器上使用：

在客户端窗口中

最后，我们举一个从一台机器流到另一台机器的例子。让我们假设客户端计算机具有 IP地址192.168.0.3 。在服务器（Raspberry Pi）上，管道是相同的，但对于目标地址：

如果客户端不是Raspberry Pi，它可能有不同的 gstreamer 元素可用。对于 Linux PC，我们可能会使用：

libcamera提供了一个libcamerasrc gstreamer元素，可以直接用来代替libcamera-vid。在服务器上，您可以使用:

在客户端上，我们使用与以前相同的播放管道。

闭源GPU固件具有Unicam驱动程序和三个摄像头传感器以及一个桥接芯片。它们是Raspberry Pi Camera v1.3（Omnivision OV5647），Raspberry Pi Camera v2.1（Sony IMX219），Raspberry Pi HQ相机（Sony IMX477），以及东芝TC358743 HDMI→CSI2桥接芯片不支持的驱动程序。不支持更新的相机，例如相机模块 3（索尼 IMX708）。

此驱动程序将源驱动程序、Unicam、ISP 和调谐器控制集成到一个完整的相机堆栈中，提供经过处理的输出图像。它可以通过MMAL，OpenMAX IL和V4L2使用bcm2835-v4l2内核模块。此接口仅支持Raspberry Pi相机。

这是 V4L2 驱动程序可用之前的临时选项。MMAL 组件vc.ril.rawcam允许以与 V2L4 驱动程序相同的方式接收原始 CSI2 数据，但所有源配置都必须由用户空间通过源所需的任何接口完成。raspiraw应用程序可在https://github.com/raspberrypi/raspiraw[github]上使用。它使用此组件和OV2、IMX5647和ADV219M的标准I7282C寄存器集来支持流传输。

有一个完全开源的内核驱动程序可用于Unicam块，是叫做 BCM2835-UNICAM 的内核模块。这接口到 V4L2 子设备驱动程序，为源提供原始帧。此 bcm2835-unicam 驱动程序控制传感器，并配置 CSI-2 接收器，以便外设将原始帧（在 Debayer 之后）写入 SDRAM，使 V4L2 交付给应用程序。除了能够将CSI-2拜耳格式解压缩为16位/像素之外，图像源（例如相机传感器）和将图像数据放置在SDRAM中的bcm2835-unicam之间没有图像处理。

Mainline Linux有一系列现有的驱动程序。Raspberry Pi内核树有一些额外的驱动程序和设备树覆盖来配置它们，这些驱动程序和设备树覆盖都已经过测试并确认可以工作。它们包括：

由于子设备驱动程序也是内核驱动程序，因此具有标准化的API，因此第三方可以自由地为他们选择的任何来源编写自己的驱动程序。

相机传感器的驱动程序负责设备的所有配置，通常通过 I2C 或 SPI。通常，将现有驱动程序作为基础并根据需要对其进行修改通常更容易，而不是从头开始编写驱动程序。

IMX219 驱动程序是一个很好的起点。此驱动程序支持 8 位和 10 位Bayer读出，因此枚举帧格式和帧大小稍微复杂一些。

传感器通常支持 V4L2 用户控件。并非所有这些控件都需要在驱动程序中实现。IMX219 驱动程序仅实现下面列出的一小部分，其实现由imx219_set_ctrl函数处理。

可以在 libcamera 的https://git.linuxtv.org/libcamera.git/tree/Documentation/sensor_driver_requirements.rst[传感器驱动程序要求]以及  Raspberry Pi 相机调整指南的第 3 章中找到进一步的指导。

这些设备将传入的视频流（例如HDMI或复合）转换为Raspberry Pi CSI-2接收器可以接受的CSI-2流。

处理桥接芯片更为复杂，因为与相机传感器不同，它们必须响应输入信号并将其报告给应用程序。

处理桥接芯片的机制可以大致分为模拟或数字。

在下面的部分中使用`ioctl`时，`ioctl`名称中的`S`表示它是一个set函数，而`G`是一个get函数，并且`_ENUM`枚举一组允许的值。

从桌面菜单中选择首选项和Raspberry Pi配置:将出现一个窗口。选择接口选项卡，然后单击启用摄像机选项。单击确定。您需要重新启动以使更改生效。

从终端打开raspi-config工具：

选择接口选项，然后选择相机，并按回车键。选择是，然后选择确定。转到“完成”,系统会提示您重新启动。

要测试系统是否已安装并正常工作，请尝试以下命令：

显示屏应显示相机的五秒钟预览，然后拍摄照片，保存到文件test.jpg中，同时显示各种信息性消息。

连接并启用相机模块后，在终端中输入以下命令以拍照：

在此示例中，相机已倒置放置。如果将相机放置在此位置，则必须翻转图像才能正确向上显示。

将相机倒置放置时，图像必须旋转 180° 才能正确显示。纠正此问题的方法是通过传入-vf 和-hf 标志来应用垂直和水平翻转：

现在照片已正确捕获。

相机模块以2592 x 1944的分辨率拍摄照片，分辨率为5，038，848像素或500万像素

使用相机模块拍摄的照片约为2.4MB。这大约是每 GB 425 张照片。

每分钟拍摄 1 张照片将在大约 1 小时内占用 7GB。这是每小时约144MB或每天3.3GB的速率。

您可以创建一个 Bash 脚本，该脚本使用相机拍照。若要创建脚本，请打开所选编辑器并编写以下示例代码：

此脚本将拍摄照片并使用时间戳命名文件。

您还需要通过创建camera文件夹来确保路径存在：

假设我们将其保存为 camera.sh，我们将首先使文件可执行：

然后运行：

有关可能选项的完整列表，请不带任何参数运行raspistill。若要滚动，请将stderr重定向到stdout，并将输出管道化为less:

使用箭头键滚动并键入q退出。

连接并启用摄像头模块后，使用以下命令录制视频：

如果需要，记得使用-hf和-vf来翻转图像，就像使用raspistill一样

这将把一个5秒钟的视频文件保存到此处给定的路径vid.h264(默认时间长度)。

要指定所拍摄视频的长度，请传入带有毫秒数的-t标志。例如：

这将录制 10 秒的视频。

有关可能选项的完整列表，请不带任何参数运行raspivid，或者通过管道将此命令传递给less并滚动浏览:

使用箭头键滚动并键入q退出。

Raspberry Pi将视频捕获为原始 H264 视频流。许多媒体播放器会拒绝播放它，或者以不正确的速度播放它，除非它被“包装”在合适的容器格式中，如 MP4。从 raspivid 命令获取 MP4 文件的最简单方法是使用 MP4Box。

使用以下命令安装 MP4Box：

使用raspivid捕获原始视频并将其包装在MP4容器中，如下所示：

或者，将 MP4 包裹在现有的 raspivid 输出周围，如下所示：

允许用户定义预览窗口的大小及其在屏幕上的位置。请注意，这将叠加在任何其他窗口/图形的顶部。

强制预览窗口使用整个屏幕。请注意，将保留传入图像的纵横比，因此某些边缘上可能会有条形图。

完全禁用预览窗口。请注意，即使禁用预览，相机仍将生成帧，因此会使用电源。

设置预览窗口的不透明度。0 = 不可见，255 = 完全不透明。

设置图像的锐度。0 是默认值。

设置图像的对比度。0 是默认值。

设置图像的亮度。默认值为 50。0 表示黑色，100 表示白色。

设置图像的颜色饱和度。0 是默认值。

设置用于捕获的 ISO。

仅在视频模式下，打开视频防抖动。

设置图像的 EV 补偿。默认值为 0。

可能的选项包括：

请注意，并非所有这些设置都可以实现，具体取决于相机调整。

设置一种模式以补偿在电源频率闪烁的灯光，这可以看作是图像上的暗水平带。避免闪烁将曝光时间锁定在电源闪烁频率的倍数（8Hz为33.60ms，10Hz为50ms）。这意味着图像可能会更加嘈杂，因为如果控制算法希望获得中间曝光值，则必须增加增益而不是曝光时间。 auto可能会被外部因素混淆，因此除非实际需要，否则最好关闭此设置。

可能的选项包括：

色温范围 （K） 可用的模式在括号中具有这些设置。

请注意，并非所有这些设置都可以实现，具体取决于相机类型。

设置要应用于图像的效果：

请注意，并非所有这些设置在所有情况下都可用。

提供的 U 和 V 参数（范围 0 - 255）应用于图像的 U 和 Y 通道。例如，--colfx 128：128 应生成单色图像。

指定用于预览和捕获的测光模式：

设定取景器中图像的旋转和生成的图像。这可以取 0 以上的任何值，但由于硬件限制，仅支持 0、90、180 和 270 度旋转。

水平翻转预览和保存的图像。

垂直翻转预览和保存的图像。

允许将传感器区域的规范用作预览和捕获的源。这定义为左上角的 x，y 以及宽度和高度，所有值均采用规范化坐标 （0.0 - 1.0）。因此，若要在传感器的中间和下方设置 ROI，以及传感器四分之一的宽度和高度，请使用：

将快门打开时间设置为指定值（以微秒为单位）。快门速度限制如下：

使用高于这些最大值的值将导致未定义的行为。

DRC 通过增加暗区范围和减少较亮区域来更改图像。这可以改善低光照区域的图像。

默认情况下，DRC 处于关闭状态。

强制重新计算静止图像捕获传递的统计信息。数字增益和AWB是根据实际捕获帧统计信息重新计算的，而不是前面的预览帧。

设置蓝色和红色增益（作为浮点数）以在设置时应用，例如 -awbg 1.5，1.2-awb off

直接在传感器上设置模拟增益值（相机模块 V1 上的 OV0 传感器的浮点值为 8.0 到 5647.1，相机模块 V1 上的 IMX0 传感器和 HQ 相机上的 IMX12 的浮点值为 0.219 到 2.447）。

设置 ISP 应用的数字增益值（浮点值从 1.0 到 64.0，但大于 4.0 的值将产生曝光过度的图像）

设置指定的传感器模式，禁用自动选择。可能的值取决于所使用的相机模块的版本：

Version 1.x (OV5647)

Version 2.x (IMX219)

¹对于超过 120fps 的帧速率，需要使用-ex off 关闭自动曝光和增益控制。这样做应该可以实现更高的帧速率，但曝光时间和增益需要设置为用户提供的固定值。

HQ摄像机

选择要在多相机系统上使用的摄像机。使用 0 或 1。

向图片添加一些文本和/或元数据。

元数据使用位掩码表示法表示，因此将它们相加以显示多个参数。例如，12 将显示 time（4） 和日期 （8），因为 4+8=12。

文本可以使用  strftime 使用的“%”字符包含日期/时间占位符。

指定批注大小、文本颜色和背景颜色。颜色采用十六进制 YUV 格式。

尺寸范围从 6 - 160;默认值为 32。请求无效大小应提供默认值。

选择指定的立体成像模式；sbs选择并排模式，tb选择顶/底模式；关闭关闭立体声模式(默认)。

将立体图像的宽度和高度减半。

交换立体成像中使用的相机顺序;注：当前不工作。

检索当前相机设置并将其写入标准输出。

Quality 100 几乎完全未压缩。75是一个很好的全方位值。

此选项将来自相机的原始拜耳数据插入到 JPEG 元数据中。

指定输出文件名。如果未指定，则不保存任何文件。如果文件名为“-”，则所有输出都将发送到标准输出。

在此名称下建立指向最新帧的文件系统链接。

在程序运行期间输出调试/信息消息。

程序将运行指定的时间长度，以毫秒为单位输入。然后，它会捕获并在指定输出时保存它。如果未指定超时值，则将其设置为 5 秒 （-t 5000）。请注意，低值（小于 500 毫秒，尽管它可能取决于其他设置）可能无法为相机提供足够的启动时间，也无法为 AWB 和 AGC 等自动算法提供足够的帧来提供准确的结果。

如果设置为 0，预览将无限期运行，直到使用 CTRL-C 停止。在这种情况下，不会进行捕获。

具体值是以毫秒为单位的拍摄间隔时间。请注意，您应该在文件名中希望显示帧数的位置指定%04d。例如，下面的代码将每2秒产生一个捕获，总时间为30秒，命名为image0001.jpg、image0002.jpg等等，一直到image0015.jpg。

请注意,%04d表示一个4位数字，并添加了前导零以构成所需的位数。例如，%08d会产生一个8位数。

如果输入延时值0，应用程序将尽快拍照。请注意，两次拍摄之间至少有 30 毫秒的强制暂停，以确保可以进行曝光计算。

指定延时摄影中的第一个帧号。如果您已经保存了许多帧，并希望从下一帧重新开始，则很有用。

延时文件名称将使用aabbccddee格式的日期/时间值，而不是简单的帧编号，其中aa是月，bb是月中的日，cc是小时，dd是分钟，ee是秒。

延时摄影文件名将使用一个数字，即Unix时间戳，即自1970年以来的秒数，而不是简单的帧号。

允许指定插入到 JPEG 文件中的缩略图。如果未指定，则默认值为 64x48，质量为 35。 如果指定—​thumb none，则不会在文件中放置缩略图信息。这会略微减小文件大小。

此选项在相机选项范围内循环。不会进行任何捕获，并且演示将在超时期限结束时结束，无论是否已循环所有选项。周期之间的时间应指定为毫秒值。

有效选项为jpg 、bmp、gif 和 png。请注意，未加速的图像类型（GIF、PNG、BMP）的保存时间比硬件加速的 jpg 要长得多。另请注意，在决定文件的编码时，将完全忽略文件名后缀。

将 JPEG 重新启动标记间隔设置为特定值。对于有损传输流很有用，因为它允许损坏的 JPEG 文件仍部分显示。

允许将特定的EXIF标签插入JPEG图像。您最多可以有 32 个 EXIF 标记条目。这对于添加 GPS 元数据等任务非常有用。例如，要设置经度：

将经度设置为 5 度 10 分 15 秒。有关可用标签范围的更多详细信息，请参阅 EXIF 文档;支持的标签如下：

请注意，这些标签的一小部分将由相机系统自动设置—​exif none，但将被命令行上的任何EXIF选项覆盖。

设置将防止任何 EXIF 信息存储在文件中。这会略微减小文件大小。

将来自任何连接的GPS加密狗（使用GSPD）的实时EXIF信息应用于图像;需要安装libgps.so。

这将使用全分辨率捕获模式运行预览窗口。在此模式下，每秒最大帧数为 15fps，预览将具有与捕获相同的视野。捕获应该更快地发生，因为不需要更改模式。此功能目前正在开发中。

照相机在请求的时间 （-t） 内运行，并且可以通过按 Enter 键在整个时间内启动捕获。按 X 然后按 Enter 将在达到超时之前退出应用程序。如果超时设置为 0，摄像机将无限期运行，直到用户按 X 然后按 Enter 键。 使用详细选项 （-v） 将显示要求用户输入的提示，否则不显示提示。

摄像机在请求的时间(-t)内运行，通过向摄像机进程发送USR1信号，可以在这段时间内启动捕获。这可以使用kill命令来完成。您可以使用pgrep raspistill命令找到相机进程ID。

kill -USR1 <process id of raspistill>

设置突发捕获模式。这可以防止相机在两次拍摄之间返回预览模式，这意味着拍摄可以更紧密地拍摄。

生成的视频的宽度。这应该在 64 到 1920 之间。

生成的视频的高度。这应该在 64 到 1080 之间。

使用比特每秒，所以10Mbps就是-b 10000000。对于H264、1080p30，高质量的比特率将是15Mbps或更高。最大比特率是25Mbps (-b 25000000)，但远超过17Mbps在1080p30时不会有明显的改善。

指定输出文件名。如果未指定，则不保存任何文件。如果文件名为“-”，则所有输出都将发送到标准输出。

要连接到远程IPv4主机，请使用tcp或udp，后跟所需的IP地址。例如tcp://192.168.1.2:1234或udp://192.168.1.2:1234。

要侦听TCP端口(IPv4)并等待传入连接，请使用- listen (-l)选项，例如，raspivid -l -o tcp://0.0.0.0:3333将绑定到所有网络接口，raspivid-l-o TCP://192 . 168 . 1 . 1:3333将绑定到本地IPv4。

使用网络连接作为数据接收器时，此选项将使系统在发送数据之前等待来自远程系统的连接。

在程序运行期间输出调试/信息消息。

程序将运行的总时间长度。如果未指定，则默认值为 5000 毫秒（5 秒）。如果设置为 0，应用程序将无限期运行，直到使用 Ctrl-C 停止。

此选项在相机选项范围内循环。不进行录制，演示将在超时期限结束时结束，无论是否已循环所有选项。周期之间的时间应指定为毫秒值。

目前允许的最小帧速率为 2fps，最大为 30fps。这种情况将来可能会改变。

打开一个选项以在压缩后显示预览。这将在预览窗口中显示任何压缩伪影。在正常操作中，预览将显示压缩前的相机输出。此选项不保证在将来的版本中有效。

设置录制视频的刷新周期内 （GoP） 速率。H264 视频在每个刷新期间使用完整帧（I 帧），后续帧基于该帧。此选项指定每个 I 帧之间的帧数。此处的数字越大，生成的视频越小，数字越小，流越不容易出错。

设置流的初始量化参数。从大约 10 到 40 不等，将极大地影响录音质量。值越高，质量越好，文件大小越大。将此设置与比特率 0 结合使用，以设置完全可变的比特率。

设置要用于编码的 H264 配置文件。选项包括：

指定用于编码的H264编码器级别。选项有4、4.1和4.2。

设置H264内部刷新类型。可能的选项有循环、自适应、两者和循环。

强制流在每个 I 帧上包含 PPS 和 SPS 标头。某些流媒体案例需要，例如 Apple HLS。这些标头很小，因此不要大大增加文件大小。

将计时信息插入 SPS 块。

此选项允许在特定时间间隔暂停和重新启动视频捕获。需要两个值：导通时间和关断时间。“开”时间是捕获视频的时间量，“关机”是视频暂停的时间量。录制的总时间由该timeout选项定义。请注意，录制可能会稍微超过超时设置，具体取决于开和关时间。

例如：

将录制 25 秒。录制将在由 2500 毫秒（2.5 秒）段和 5000 毫秒（5 秒）间隙组成的时间范围内进行，在 20 秒内重复。因此，整个录音实际上只有 10 秒长，因为 4 段 2.5 秒 = 10 秒，间隔 5 秒。所以：

2.5 记录 — 5 暂停 - 2.5 记录 — 5 暂停 - 2.5 记录 — 5 暂停 — 2.5 记录

总录制周期为 25 秒，但实际录制的素材只有 10 秒。

每次按 Enter 键时，录制将暂停或重新启动。按X然后回车将停止录制并关闭应用程序。请注意，超时值将用于表示录制结束，但仅在每次按 Enter 键后检查;因此，如果系统正在等待按键，即使超时已过期，它仍然会等待按键后再退出。

向raspivid进程发送USR1信号将在记录和暂停之间切换。这可以使用kill命令来完成，如下所示。您可以使用pgrep raspivid找到raspivid进程id。

kill -USR1 <process id of raspivid>

请注意，超时值将用于指示录制结束，但仅在每次收到SIGUSR1信号后进行检查;因此，如果系统正在等待信号，即使超时已过期，它仍然会等待信号后再退出。

在信号或按键模式下，每次重新启动录制时，都会创建一个新文件。

选择循环缓冲区模式。所有编码数据都存储在循环缓冲区中，直到激活触发器，然后保存缓冲区。

打开从 H264 编码器到指定文件名的运动矢量输出。

写入视频数据后立即强制刷新输出数据缓冲区。这会绕过写入数据的任何操作系统缓存，并且可以减少延迟。

将时间戳信息保存到指定的文件。可用作mkvmerge 的输入文件。

指定要使用的编码器编解码器。选项是H264 和MJPEG 。H264 可以编码高达 1080p，而 MJPEG 可以编码到传感器尺寸，但由于更高的处理和存储要求，帧速率会降低。

定义摄像机是暂停还是立即开始录制。选项包括录制或暂停。请注意，如果您使用简单的超时，并且initial设置为pause，则不会记录任何输出。

文件不是创建单个文件，而是拆分为大约指定毫秒数的段。为了提供不同的文件名，您应该在文件名中希望出现段计数编号的位置添加%04d或类似名称，例如：

将制作大约3000毫秒(3s)长的视频剪辑，命名为video0001.h264、video0002.h264等。剪辑应该是无缝的(剪辑之间没有丢帧)，但是每个剪辑长度的精度将取决于帧内周期，因为片段将总是从I帧开始。因此，它们将始终等于或长于指定的周期。

最新版本的 Raspivid 还将允许文件名基于时间，而不是使用段号。例如：

将生成格式如下的文件名：video_Fri Jul 20 16:23:48 2018.h264

有http://man7.org/linux/man-pages/man3/strftime.3.html[许多不同的格式]选项可用。请注意，%d和%u 选项不可用，因为它们用于段号格式，并且某些组合可能会产生无效的文件名。

输出段时，这是段号在被重置为1之前可以达到的最大值，可以保留录制的段，但会覆盖最早的段。因此，如果设置为4，在上面的片段示例中，产生的文件将是video0001.h264、video0002.h264、video0003.h264和video0004.h264。一旦记录了video0004.h264，计数将重置为1，video0001.h264将被覆盖。

输出片段时，这是初始片段编号，能够从给定片段恢复先前的记录。默认值为 1。

为请求的任何原始数据文件指定输出文件名。

指定请求原始输出时要使用的原始格式。yuv、rgb和灰色选项。灰色只是保存YUV图像的Y通道。

raspiyuv的许多选项与raspistill的选项相同。本节显示了不同之处。

不支持的选项：

额外选项 ：

此选项强制将图像另存为每通道 8 位的 RGB 数据，而不是 YUV420。

请注意，保存的raspiyuv图像缓冲区填充为可被 32 整除的水平大小，因此每行末尾可能有未使用的字节。缓冲区也垂直填充以可被 16 整除，在 YUV 模式下，Y、U、V 的每个平面都以这种方式填充。

仅输出 YUV 图像的亮度 （Y） 通道。这实际上是图像的黑白或强度部分。

将图像数据另存为 BGR 数据而不是 YUV。

默认情况下，捕获以传感器支持的最高分辨率完成。这可以使用 -w和 -h

命令行选项进行更改。 在取景器上拍摄2秒后的默认拍摄（时间以毫秒为单位），保存image.jpg：

以不同的分辨率拍摄：

大幅降低质量以减小文件大小：

强制预览显示在坐标 100，100、宽度为 300 像素、高度为 200 像素处：

完全禁用预览：

将图像另存为 PNG 文件（无损压缩，但比 JPEG 慢）。请注意，选择图像编码时会忽略文件名后缀：

将一些 EXIF 信息添加到 JPEG 中。这会将艺术家标签名称设置为 Boris，并将 GPS 高度设置为 123.5m。请注意，如果设置GPS标签，则应设置为最低GPSLatitude，GPSLatitudeRef，GPSLongitudeRef，GPSLongitudeRef，GPSAltitude和GPSAltitudeRef：

设置浮雕图像效果：

将 YUV 图像的 U 和 V 通道设置为特定值（128：128 生成灰度图像）：

运行预览 2 秒，没有保存图像：

每隔10秒拍摄一张延时照片，持续10分钟(10分钟= 600000毫秒)，将文件命名为image_num_001_today.jpg、image_num_002_today.jpg等，最新的照片也可以用latest.jpg命名:

拍照并将图像数据发送到标准输出：

拍摄照片并将图像数据发送到文件：

永久运行相机，在按 Enter 时拍照：

图像大小和预览设置与静止图像拍摄相同。视频录制的默认大小为 1080p （1920x1080）。

使用默认设置 （5p1080） 录制 30s 剪辑：

以指定的比特率 （5.3Mbps） 录制 5 秒剪辑：

以指定的帧速率 （5fps） 录制 5 秒剪辑：

对 5s 相机流进行编码，并将图像数据发送到标准输出：

对 5s 相机流进行编码并将图像数据发送到文件：

raspistill的通常输出是一个压缩的JPEG文件，它经过了图像处理的所有阶段，以产生高质量的图像。然而，作为一种有损格式，JPEG确实丢弃了一些用户可能想要的信息。

raspistill有一个编码选项，允许您指定输出格式:jpg、bmp、png或gif。除了jpg之外，其他格式都是无损的，因此不会为了提高压缩率而丢弃任何数据，但是需要从原始YUV进行转换，并且因为这些格式没有硬件支持，所以它们生成图像的速度比JPEG稍慢。

例如

raspistill --encoding png -o fred.png

另一种选择是使用 raspiyuv  应用程序输出完全格式化的 YUV420 或 RGB 数据。

对于某些应用，例如天文摄影，直接从传感器获取原始拜耳数据可能很有用。这些数据需要进行后处理以生成有用的图像。

raspistill有一个原始选项，将导致输出拜耳数据。

raspistill --raw -o fred.jpg

原始数据被附加到JPEG文件的末尾， 需要被提取出来。