1. Picamera2 简介：
picamera 树莓派开发中基于libcamera 的python库，在使用中常用到一些相机的参数控制，位于（附录A-B），将其翻译下来方便查看。
原文链接：Picamera2 使用文档
附录 A：像素和图像格式
下表列出了 Picamera2 支持的图像和像素格式。对于每种格式，我们列出：
- 每个像素的位数
- 该格式在像素单位中的最优对齐方式
- 使用
capture_array（如果支持）获取的数组在 numpy 中报告的图像形状
表 1. 不同图像格式
| 格式 | 每像素位数 | 最优对齐 | 形状 | 描述 |
|---|---|---|---|---|
| XBGR8888 | 32 | 16 | (高度, 宽度, 4) | 带有 alpha 通道的 RGB 格式。每个像素排列为 [R, G, B, A]，其中 A（或 alpha）值固定为 255。 |
| XRGB8888 | 32 | 16 | (高度, 宽度, 4) | 带有 alpha 通道的 RGB 格式。每个像素排列为 [B, G, R, A]，其中 A（或 alpha）值固定为 255。 |
| BGR888 | 24 | 32 | (高度, 宽度, 3) | RGB 格式。每个像素排列为 [R, G, B]。 |
| RGB888 | 24 | 32 | (高度, 宽度, 3) | RGB 格式。每个像素排列为 [B, G, R]。 |
| YUV420 | 12 | 64 | (高度x3/2, 宽度) | YUV 4:2:0 格式。有高度行的 Y 值，然后是高度/2 行半宽 U 和高度/2 行半宽 V。数组形式在矩阵的每一行上有两行 U（或 V）值。 |
| YVU420 | 12 | 64 | (高度x3/2, 宽度) | YUV 4:2:0 格式。有高度行的 Y 值，然后是高度/2 行半宽 V 和高度/2 行半宽 U。数组形式在矩阵的每一行上有两行 V（或 U）值。 |
| NV12 | 12 | 32 | 不支持 | YUV 4:2:0 格式。一个高度x步长 Y 值的平面，后跟高度/2x步长交错的 U 和 V 值。 |
| NV21 | 12 | 32 | 不支持 | YUV 4:2:0 格式。一个高度x步长 Y 值的平面，后跟高度/2x步长交错的 V 和 U 值。 |
| YUYV | 16 | 32 | 不支持 | YUV 4:2:2 格式。一个高度x步长交错值的平面，每两个像素的顺序为 Y U Y V。 |
| YVYU | 16 | 32 | 不支持 | YUV 4:2:2 格式。一个高度x步长交错值的平面，每两个像素的顺序为 Y V Y U。 |
| VYVY | 16 | 32 | 不支持 | YUV 4:2:2 格式。一个高度x步长交错值的平面，每两个像素的顺序为 U Y V Y。 |
| VYUY | 16 | 32 | 不支持 | YUV 4:2:2 格式。一个高度x步长交错值的平面，每两个像素的顺序为 V Y U Y。 |
表 2. 不同图像格式的支持
表2列出了这些格式在 Picamera2 和一些第三方库中的支持程度。
| 格式支持 | XRG88888/XBGR88888 | RGB888/BGR888 | YUV420/YVU420 | NV12/NV21 | YUYV/UYVY | YVYU/VYU |
|---|---|---|---|---|---|---|
| Capture buffer | 是 | 是 | 是 | 是 | 是 | 是 |
| Capture array | 是 | 是 | 是 | 否 | 否 | 否 |
| QtGL preview | 是 | 否 | 是 | 否 | 是 | 否 |
| Qt preview | 是，慢 | 是，慢 | 需要 OpenCV，非常慢 | 否 | 否 | 否 |
| DRM preview | 是 | 是 | 是 | 否 | 否 | 否 |
| Null preview | 是 | 是 | 是 | 是 | 是 | 是 |
| JPEG 编码 | 是 | 是 | 否 | 否 | 否 | 否 |
| 视频编码 | 是 | 是 | 是 | 是 | 是 | 是 |
| OpenCV | 经常 | 是 | 仅转换为 RGB | 否 | 否 | 否 |
| Python 图像库 | 是 | 是 | 否 | 否 | 否 | 否 |
附录 B：相机配置参数
下表列出了所有相机配置参数、允许的值，并给出了描述。我们从全局参数开始：这些参数不特定于任何main、lores 或原始流。
表 3. 全局相机配置参数
| 参数名称 | 允许的值 | 描述 |
|---|---|---|
| “use_case” | ‘preview’ ‘still’ ‘video’ | 此参数仅作为对用户的辅助，显示配置的预期用途。create_preview_configuration() 将创建此参数设置为 “preview” 的配置；静止和视频版本以相同的方式工作。 |
| “transform” | Transform() Transform(hflip=1) Transform(vflip=1) Transform(hflip=1, vflip=1) | 应用于所有配置流中所有图像的二维平面变换。列出的值分别表示：恒等变换、水平镜像、垂直翻转和180度旋转。默认值始终是恒等变换。 |
| “colour_space” | Sycc() Smpte170m() Rec709() | 用于主要和lores流的颜色空间。允许的值是JPEG颜色空间（意味着sRGB原色和传输函数以及全范围BT.601 YCbCr编码）、SMPTE 170M颜色空间或Rec.709颜色空间。create_preview_configuration() 和 create_still_configuration() 默认为Sycc()。create_video_configuration() 如果主流使用RGB格式，则选择Sycc()。对于YUV格式，如果分辨率小于1280x720，默认为Smpte170m()，否则为Rec709()。 |
| “buffer_count” | 1, 2, … | 为请求分配的缓冲区数量，这将成为相机系统可用的“请求”对象的数量。默认情况下，我们为预览配置选择四个，为静态捕获配置选择一个，为视频选择六个。 增加缓冲区数量将减少帧丢失，尽管回报递减。最大可能的缓冲区数量取决于平台、图像分辨率和分配的CMA数量。 |
| “display” | None ‘main’ ‘lores’ | 将在预览窗口中显示的流的名称（如果有）。通常显示主流，尽管如果定义了lores流，也可以显示它。默认情况下，create_still_configuration() 将使用None值，因为缓冲区通常很大，如果显示堆栈保留它们，可能会导致内存碎片问题。 |
| “encode” | None ‘main’ ‘lores’ | 将用于视频录制的流的名称。默认情况下，create_video_configuration() 将设置为主流，尽管如果定义了lores流，也可以使用它。对于预览和静态用例，值将设置为None。此值在启动编码器时始终可以覆盖。 |
| “sensor” | 包含 “output_size” 和 “bit_depth” 的字典 | 当存在时，这决定了所选的传感器模式，覆盖任何原始流参数（这些参数将被调整以匹配所选的传感器模式）。此参数是一个字典，包含传感器 “output_size”，即 (宽度, 高度) 元组，以及 “bit_depth”，即每个像素样本中的位数（大多数 Raspberry Pi 相机为 10 或 12）。 |
| “controls” | 请参阅相机控制部分。 | 使用此参数，我们可以指定一组运行时控制，这些控制可以被视为相机配置的一部分，并在配置（重新）应用时应用。不同的用例也可能提供一些略有不同的默认控制值。 |
表 4. 流特定的配置参数
| 参数名称 | 允许的值 | 描述 |
|---|---|---|
| “format” | 描述图像格式的字符串。请参考此表。 | 像素和图像格式。请参考链接的表以获取完整描述。对于原始流，允许的值将是原始图像格式，可以通过查询 Picamera2.sensor_modes 属性或从终端运行 libcamera-hello --list-cameras 列出。格式将是以下划线S开头的字符串，后跟如 RGGB 或 GBRG 之类的内容。如果需要未打包的原始像素，可以省略尾随_CSI2P，尽管在大多数情况下不建议这样做，因为它使用更多的总内存和更多的系统内存带宽。 |
| “size” | (宽度，高度) | 输出图像的宽度和高度的两个值的元组。两个数字都不应小于64。对于原始流，允许的分辨率再次由 libcamera-hello --list-cameras 列出，以及该分辨率的正确格式。你可以选择不同的大小，但系统将简单地使用它认为“最接近”的允许值。 |
补充：picam2.configure(config) 配置参数详解
display 和 encode 中的 None、main、lores
-
display：
指定用于实时预览显示的图像流来源。None：禁用预览显示功能。"main"：使用main流的图像进行预览（高分辨率，可能降低性能）。"lores"：使用低分辨率流 (lores) 进行预览（更流畅，适合实时显示）。
-
encode：
指定用于视频编码的流来源（例如录制视频）。None：禁用编码功能。"main"：使用main流进行编码（高画质，高资源占用）。"lores"：使用低分辨率流编码（适合网络传输或低带宽场景）。
sensor 中的 output_size 和 bit_depth
-
output_size：
设置传感器输出的原始图像分辨率（需在传感器支持的范围内）。
例如，IMX477 传感器最大支持4056x3040，但可设置为2028x1520以降低处理负载。 -
bit_depth：
控制传感器输出的 RAW 图像位深度，可选值通常为10或12。10：10 位深度（文件较小，精度足够多数场景）。12：12 位深度（保留更多细节，文件更大，需后期处理）。
完整代码示例
config = self.picam2.create_still_configuration(
# --- 传感器配置 ---
sensor={
"output_size": (4056, 3040), # 传感器原始输出尺寸（HQ Camera IMX477 最大分辨率）
"bit_depth": 10 # RAW 位深度：10 或 12
},
# --- 显示和编码流配置 ---
display="lores", # 使用低分辨率流进行实时预览（节省性能）
encode="main", # 使用主流进行编码（高画质保存）
# --- 主流参数 ---
main={
"size": (1332, 990), # ISP 处理后输出的主流尺寸（全分辨率模式）
"format": "RGB888" # 输出格式：RGB888 或 XRGB8888（兼容 OpenCV）
},
# --- 低分辨率流参数（可选）---
lores={
"size": (640, 480), # 低分辨率流尺寸（用于预览或算法处理）
"format": "YUV420" # 格式：YUV420 节省带宽
},
# --- 其他参数 ---
transform=Transform(hflip=True, vflip=False), # 图像水平翻转（镜像模式）
buffer_count=3, # 缓冲区数量（建议 3-6，平衡速度和内存）
queue=False # 禁用队列提升捕获速度（但可能丢帧）
)
self.picam2.configure(config)
参数使用场景建议
-
高分辨率拍照：
main设为最大分辨率（如4056x3040），format用RGB888。sensor["output_size"]匹配传感器最大尺寸。
-
实时预览优化：
display="lores"+lores={"size": (640,480)}，降低预览分辨率提升流畅度。
-
视频录制：
encode="main"保证画质，或encode="lores"降低码率。- 格式设为
YUV420或H264。
-
高速抓拍：
queue=False+buffer_count=6，减少延迟但需处理可能的丢帧。
附录 C：相机控制
设置枚举控制值
一些相机控制具有枚举值，也就是说，具有明确枚举的可接受值列表。要使用这些值，正确的方法是从 libcamera 导入控制并使用如下代码：
from picamera2 import Picamera2
from libcamera import controls
picam2 = Picamera2()
picam2.set_controls({"AeMeteringMode": controls.AeMeteringModeEnum.Spot})
随相机配置变化的控制
一些控制的限值会随着相机配置而变化。在这种情况下，可以从 camera_controls 属性中查询每个控制的有效值范围，每个控制都有一个(最小值，最大值，默认值)三元组。具体受影响的控制包括：AnalogGain、ExposureTime、FrameDurationLimits 和 ScalerCrop。例如：
from picamera2 import Picamera2
picam2 = Picamera2()
picam2.configure(picam2.create_preview_configuration())
min_exp, max_exp, default_exp = picam2.camera_controls["ExposureTime"]
相机控制和图像元数据
请注意，控制也作为捕获图像元数据中报告的值。有些控制仅出现在这样的元数据中，这意味着它们不能被设置，因此是只读的。我们在 表4：可用相机控制 中指出了这一点。
表5：可用相机控制
| 控制 | 描述 | 允许的值 |
|---|---|---|
| “AeConstraintMode” | 设置 AEC/AGC 算法的约束模式。 | AeConstraintModeEnum 后跟以下之一：Normal - 正常测光，Highlight - 测光用于高光，Shadows - 测光用于阴影，Custom - 用户定义的测光 |
| “AeEnable” | 允许 AEC/AGC 算法打开和关闭。如果关闭，则相机的增益或曝光设置不会自动更新。 | False - 关闭 AEC/AGC，True - 打开 AEC/AGC |
| “AeExposureMode” | 设置 AEC/AGC 算法的曝光模式。 | AeExposureModeEnum 后跟以下之一：Normal - 正常曝光，Short - 使用较短曝光，Long - 使用较长曝光，Custom - 使用自定义曝光 |
| “AeFlickerMode” | 设置 AEC/AGC 算法的闪烁避免模式。 | AeFlickerModeEnum 后跟以下之一：FlickerOff - 无闪烁避免，FlickerManual - 使用在 AeFlickerPeriod 控制中设置的周期避免闪烁 |
| “AeFlickerPeriod” | 设置照明闪烁周期为微秒。 | 照明周期的时间，以微秒为单位。例如，对于50Hz的主照明，闪烁发生在100Hz，因此周期将是10000微秒。 |
| “AeMeteringMode” | 设置 AEC/AGC 算法的测光模式。 | AeMeteringModeEnum 后跟以下之一：CentreWeighted - 中心加权测光，Spot - 点测光，Matrix - 矩阵测光，Custom - 自定义测光。 |
| “AfMetering” | 测量对焦的位置。 | AfMeteringEnum 后跟以下之一：Auto - 使用图像的中央区域，Windows - 使用“AfWindows”控制中给出的窗口。 |
| “AfMode” | 自动对焦模式。 | AfModeEnum 后跟以下之一：Manual - 手动模式，可以设置镜头位置，Auto - 自动模式，可由应用程序触发，Continuous - 连续模式，持续运行。 |
| “AfPause” | 暂停连续自动对焦。仅在连续自动对焦模式下有效。 | AfPauseEnum 后跟以下之一：Deferred - 当不再扫描时暂停连续自动对焦，Immediate - 立即暂停连续自动对焦，即使在扫描中，Resume - 恢复连续自动对焦。 |
| “AfRange” | 搜索的镜头位置范围。 | AfRangeEnum 后跟以下之一：Normal - 搜索正常范围（可能排除非常近的物体），Macro - 仅搜索范围中最近的部分，Full - 搜索所有内容。 |
| “AfSpeed” | 自动对焦搜索的速度。 | AfSpeedEnum 后跟以下之一：Normal - 正常速度，Fast - 尝试更快移动。 |
| “AfTrigger” | 启动自动对焦周期。仅在自动模式下有效。 | AfTriggerEnum 后跟以下之一：Start - 启动周期，Cancel - 取消正在进行的周期。 |
| “AfWindows” | 图像中用于测量对焦的窗口位置。 | 一系列矩形（表示 x_offset、y_offset、width 和 height 的4个数字元组）。矩形单位指的是最大缩放裁剪窗口（请参阅 camera_properties 属性中的 ScalerCropMaximum 值）。 |
| “AnalogueGain” | 传感器应用的模拟增益。 | 请查阅 camera_controls 属性。 |
| “AwbEnable” | 打开或关闭自动白平衡（AWB）算法。关闭时，将不会自动更新颜色增益。 | False - 关闭 AWB，True - 打开 AWB。 |
| “AwbMode” | 设置 AWB 算法的模式。 | AwbModeEnum 后跟以下之一：Auto - 任意光源，Tungsten - 白炽灯照明，Fluorescent - 荧光灯照明，Indoor - 室内照明，Daylight - 日光照明，Cloudy - 阴天照明，Custom - 自定义设置 |
| “Brightness” | 调整图像亮度，其中 -1.0 表示非常暗，1.0 表示非常亮，0.0 是默认的“正常”亮度。 | 从 -1.0 到 1.0 的浮点数 |
| “ColourCorrectionMatrix” | 在图像信号处理器 (ISP) 中使用的 3x3 矩阵，用于将原始相机颜色转换为 sRGB。此控制仅出现在捕获的图像元数据中，并且是只读的。 | 九个浮点数的元组，介于 -16.0 和 16.0 之间 |
| “ColourGains” | 一对数字，第一个是红色增益（AWB 算法应用于红色像素的增益），第二个是蓝色增益。设置这些数字将禁用 AWB。 | 两个浮点数的元组，介于 0.0 和 32.0 之间 |
| “ColourTemperature” | 当前图像颜色温度的估计值（以开尔文为单位）。它仅在捕获的图像元数据中可用，并且是只读的。 | 整数 |
| “Contrast” | 设置图像的对比度，其中零表示“无对比度”，1.0 是默认的“正常”对比度，更大的值成比例地增加对比度。 | 从 0.0 到 32.0 的浮点数 |
| “DigitalGain” | 应用于图像的数字增益量。当传感器的模拟增益控制无法足够高时，会自动使用数字增益，因此此值仅在捕获的图像元数据中报告。它不能直接设置 - 用户应设置 AnalogueGain 并在需要时使用数字增益。 | 浮点数 |
| “ExposureTime” | 传感器使用的曝光时间，以微秒为单位。 | 请查阅 camera_controls 属性 |
| “ExposureValue” | 以“档”为单位的曝光补偿值，它调整 AEC/AGC 算法的目标。正值增加目标亮度，负值减少目标亮度。零表示基础或“正常”曝光水平。 | -8.0 到 8.0 之间的浮点数 |
| “FrameDuration” | 自上一帧相机帧以来的时间（以微秒为单位）。此值仅在捕获的图像元数据中可用，并且是只读的。要改变相机的帧率，应使用“FrameDurationLimits”控制。 | 整数 |
| “FrameDurationLimits” | 传感器提供一帧图像所需的最大和最小时间，以微秒为单位。 | 请查阅 camera_controls 属性 |
| “HdrChannel” | 报告当前帧代表的HDR通道。它是只读的，不能设置。 | HdrChannelEnum 后跟以下之一：HdrChannelNone - 图像不用于HDR，HdrChannelShort - HDR的短曝光图像，HdrChannelMedium - HDR的中等曝光图像，HdrChannelLong - HDR的长曝光图像 |
| “HdrMode” | 是否以HDR模式运行相机（与Camera Module 3支持的相机内HDR不同）。 | HdrModeEnum 后跟以下之一：Off - 禁用HDR（默认），SingleExposure - 合并多个短曝光图像，这是推荐模式（仅限Pi 5），MultiExposure - 合并短曝光和长曝光图像，仅在场景完全静态时推荐（仅限Pi 5），Night - 一种HDR模式，结合多个低光图像，可以恢复一些高光（仅限Pi 5），MultiExposureUnmerged - 返回未合并的独立短曝光和长曝光图像。 |
| “LensPosition” | 镜头的位置。单位是屈光度（米距离的倒数）。 | 请查阅 camera_controls 属性。 |
| “Lux” | 场景亮度的估计值（以勒克斯为单位）。它仅在捕获的图像元数据中可用，并且是只读的。 | 整数 |
| “NoiseReductionMode” | 选择适当的降噪模式。通常，Picamera2的配置会自动选择适当的模式，因此通常不需要更改它。 | draft.NoiseReductionModeEnum 后跟以下之一：Off - 无降噪，Fast - 快速降噪，HighQuality - 最佳降噪 |
| “Saturation” | 色彩饱和度的量，其中零产生灰度图像，1.0代表默认的“正常”饱和度，更高的值产生更饱和的颜色。 | 从 0.0 到 32.0 的浮点数 |
| “ScalerCrop” | 缩放裁剪矩形确定从传感器接收的图像的哪一部分被裁剪，然后缩放以产生正确大小的输出图像。 | 由以下组成的 libcamera.Rectangle：x_offset，y_offset，width，height |
| “SensorTimestamp” | 传感器生成此帧的时间，以系统启动后的纳秒为单位。 | 整数 |
| “SensorBlackLevels” | 原始传感器图像的黑电平。 | 四个整数的元组 |
| “Sharpness” | 设置图像锐度，其中零意味着没有执行额外的锐化，1.0是默认的“正常”锐化级别，更大的值应用相应更强的锐化。 | 从 0.0 到 16.0 的浮点数 |
附录 D：相机属性
下表列出了所有可用的相机属性。某些属性仅在配置相机模式时更新。它们可以通过 Picamera2 对象的 camera_properties 属性访问，并且都是只读的。
表 6. 相机属性
| 属性名称 | 描述 | 数据类型 |
|---|---|---|
| “ColourfilterArrangement” | 表示传感器原生拜耳排列顺序的数字（在考虑任何旋转之前）。 | 0-RGGB 1-GRBG 2-GBRG 3-BGGR 4-单色 |
| “Location” | 指定相机在设备上的位置的整数（例如，前面或后面）。对于 Raspberry Pi，该值没有意义。 | 整数 |
| “Model” | 附加传感器所宣传的名称。 | 字符串 |
| “PixelArrayActiveAreas” | 传感器像素阵列在整个传感器像素阵列中的活动区域。给定为 (x_offset, y_offset, width, height) 值的元组。 | 四个整数的元组 |
| “PixelArraySize” | 活动像素区域的大小，作为 (x, y) 元组。这是传感器的完整可用分辨率。 | 两个整数的元组 |
| “Rotation” | 传感器相对于相机板的旋转。在许多 Raspberry Pi 设备上，当相机板底部连接时，传感器实际上是倒置的，这里将返回 180° 的值。 | 整数 |
| “ScalerCropMaximum” | 当配置相机模式时更新。它返回一个 (x_offset, y_offset, width, height) 元组，表示此相机模式读取的活动像素区域内的矩形。 | 四个整数的元组 |
| “SensorSensitivity” | 当配置相机模式时更新。它表示此相机模式相对于其他相机模式的相对灵敏度。通常，相机模式都具有相同的灵敏度，以便相同的曝光时间和增益产生相同亮度的图像。有时相机的模式并非如此，为了获得相同的亮度，您需要通过这些灵敏度的比率调整总请求曝光。对于大多数传感器，这将始终返回 1.0。 | 浮点数 |
| “UnitCellSize” | 如果已知，此传感器像素的物理尺寸。以纳米为单位的 (x, y) 元组给出。 | 两个整数的元组 |
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
