> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/rpicn/pei-jian/she-xiang-tou.md).

# 摄像头

## 关于摄像头模块

现有若干款树莓派官方摄像头模块。

* **摄像头模块 1。** 一款 500 万像素摄像头，有标准版（可见光）和 NoIR 版（可见光加红外光）两种版本，视场角（FoV）为标准。树莓派已不再提供该设备。
* [**摄像头模块 2。**](#摄像头模块-2) 一款 800 万像素摄像头，有标准版和 NoIR 版两种版本，视场角（FoV）为标准。
* [**摄像头模块 3。**](#摄像头模块-3) 一款 1200 万像素摄像头，有标准版和 NoIR 版两种版本。标准版和 NoIR 版均有标准视场角（FoV）和广角版本，共四种不同的变体。摄像头模块 3 传感器组件也可单独购买，使你能够将这些功能集成到更小的设备中。
* [**高质量（HQ）摄像头。**](#高质量hq摄像头) 一款 1200 万像素摄像头，配备 CS 卡口或 M12 卡口两种变体，用于搭配外置镜头。该型号没有 NoIR 版本。
* [**AI 摄像头。**](https://book.bsdcn.org/rpicn/pei-jian/ai-she-xiang-tou.md) 一款 1200 万像素摄像头，可为任何摄像头应用提供低延迟、高性能的 AI 能力。与[树莓派摄像头软件栈](https://book.bsdcn.org/rpicn/shu-mei-pai/she-xiang-tou-ruan-jian.md)的紧密集成使用户能够以极少的投入部署自己的神经网络模型。该型号没有 NoIR 版本。
* [**全局快门摄像头。**](#全局快门摄像头) 一款 150 万像素摄像头，采用全局快门机制。它能一次性捕捉场景中每个像素的光线，是拍摄高速运动物体的理想选择。它配备 CS 卡口，用于搭配外置镜头。该型号没有 NoIR 版本。

要比较这些摄像头的硬件特性，请参阅[硬件规格](#硬件规格)。

> **注意**
>
> 树莓派摄像头模块与所有配备 CSI 接口的树莓派计算机兼容。

有关摄像头软件的信息，请参阅[摄像头软件文档](https://book.bsdcn.org/rpicn/shu-mei-pai/she-xiang-tou-ruan-jian.md)。

## 安装树莓派摄像头

安装树莓派摄像头的过程对于各种摄像头和主板的组合基本一致。接口存在一些差异；以下步骤中会说明这些差异。

### 第 1 步：准备

> **警告**
>
> 摄像头对静电敏感。在处理 PCB 之前，请先将自己接地。如果没有接地带，可以触摸水龙头或类似物品来接地。

要完成此过程，你需要以下物品：

* 一块带有摄像头接口的树莓派主板。
* 一个树莓派摄像头。

  有些摄像头的镜头上可能覆有一小片半透明蓝色塑料薄膜。它只是在运输过程中保护镜头。要移除它，请轻轻剥下。
* 用于连接摄像头和主板的合适线缆。
  * 所有树莓派摄像头都使用标准的 15 针接口。
  * 包括树莓派 4 在内的树莓派旗舰型号使用标准的 15 针接口。对于这些主板，请使用摄像头随附的 Standard-Standard 摄像头线缆。
  * 树莓派 5、所有树莓派 Zero 型号和计算模块 IO 板使用迷你的 22 针接口。对于这些主板，请使用 [Standard-Mini 摄像头线缆](https://www.raspberrypi.com/products/camera-cable/)。
  * 有些计算模块开发套件附带一块计算模块摄像头和显示转接板（CMCDA）电路板，它将 IO 板上的迷你 22 针接口转换为标准的 15 针接口。

### 第 2 步：将线缆连接到树莓派

> **注意**
>
> 如果你打算在树莓派 5 上使用主动散热器，请考虑在安装主动散热器之前将线缆连接到树莓派设备上的摄像头接口。安装好主动散热器后，操作摄像头接口可能会不太方便。

1. 关闭树莓派并断开电源。
2. 找到树莓派主板上的摄像头接口。

   以下描述假定你手持树莓派主板时，芯片和接口朝上，树莓派徽标和主板名称方向正确。对于顶面没有徽标的树莓派 Zero 主板，请将 GPIO 排针沿离你最远的边缘摆放。

   * 在树莓派 Zero 设备上，摄像头接口位于右侧的短边，与存储卡插槽相对。
   * 在树莓派 4 之前的树莓派旗舰型号上，摄像头接口位于离你最近的边缘、HDMI 接口和音频插孔之间。它标注为 CAMERA。
   * 在树莓派 4 上，摄像头接口位于离你最近的边缘、micro HDMI 接口和音频插孔之间。它标注为 CAMERA。
   * 在树莓派 5 上，两个摄像头和显示接口位于离你最近的边缘、micro HDMI 接口和以太网口之间。它们标注为 CAM/DISP0 和 CAM/DISP1。你可以使用其中任一接口连接摄像头。
   * 在树莓派计算模块 1/3/3+ IO 板上，两个摄像头接口位于左边缘（IO 板上最靠近徽标的边缘）离你最近的一端。它们标注为 CAM0 和 CAM1。你可以使用其中任一接口连接摄像头。
   * 在树莓派计算模块 4 IO 板上，两个摄像头接口位于最左侧的角落。它们标注为 CAM0 和 CAM1。你可以使用其中任一接口连接摄像头。
   * 在树莓派计算模块 5 IO 板上，两个摄像头接口位于最远边缘的左端。它们标注为 CAM/DISP0 和 CAM/DISP1。你可以使用其中任一接口连接摄像头。
3. 打开接口上的翻盖。
   1. 如果有一条薄膜使接口翻盖保持关闭，请将其移除。
   2. 轻轻地将翻盖从接口中拉出，直到感觉它停止。此时翻盖有一定的活动空间。
   3. 将翻盖稍微向远离接口开口的方向倾斜。
4. 插入摄像头线缆的一端，使金属触点背向翻盖。

   确保摄像头线缆牢固地插入接口中并平直就位，以正确对齐所有触点。注意不要将柔性线缆弯成锐角。
5. 将翻盖向线缆方向翻回，并向下推入接口，直到感觉它咔嗒一声就位。

   翻盖将线缆固定到位，并确保接口引脚与线缆的金属触点之间良好接触。

你可以按相反的顺序执行这些步骤，从接口中移除线缆。

### 第 3 步：将线缆连接到摄像头

我们的摄像头出厂时已连接 Standard-Standard 线缆。如果你已移除此线缆或想改用其他线缆，请完成以下步骤。

摄像头接口位于主板上与镜头相对的一侧。手持摄像头时，使镜头朝下或远离你。

1. 打开接口上的翻盖。
   1. 轻轻地将翻盖从接口中拉出，直到感觉它停止。此时翻盖有一定的活动空间。
   2. 将翻盖稍微向远离接口开口的方向倾斜。
2. 插入摄像头线缆的一端，使金属触点背向翻盖并朝向摄像头主板。

   确保摄像头线缆牢固地插入接口中并平直就位，以正确对齐所有触点。注意不要将柔性线缆弯成锐角。
3. 将翻盖向线缆方向翻回，并向下推入接口，直到感觉它咔嗒一声就位。

   翻盖将线缆固定到位，并确保接口引脚与线缆的金属触点之间良好接触。

你可以按相反的顺序执行这些步骤，从接口中移除线缆。

### 第 4 步：准备软件

1. 将树莓派设备重新接通电源并开机。
2. 按照[保持操作系统最新](https://book.bsdcn.org/pages/QepaqtIsqMuh3R7p4SWr#%E6%9B%B4%E6%96%B0%E5%BD%93%E5%89%8D%E7%9A%84%E6%A0%91%E8%8E%93%E6%B4%BE%E8%BD%AF%E4%BB%B6)的说明，确保你的内核和应用程序都是最新版本。
3. 按照 [`rpicam-apps`](https://book.bsdcn.org/rpicn/shu-mei-pai/she-xiang-tou-ruan-jian.md#rpicam-apps) 的设置说明进行操作。
4. （可选）如果你想使用 Picamera2 Python 库，请按照 [Picamera2 Python 库](https://pip.raspberrypi.com/documents/RP-008156-DS) 的设置说明进行操作。

## 摄像头模块 2

这款 800 万像素摄像头基于索尼 IMX219 传感器，分辨率为 3280 × 2464 像素。它具有可调焦功能，最长可录制 11.76 秒的曝光时间。

摄像头模块 2 有以下版本：

* [**标准版。**](https://www.raspberrypi.com/products/camera-module-v2/) 此版本仅捕捉可见光；红外光会被滤除。
* [**NoIR 版。**](https://www.raspberrypi.com/products/pi-noir-camera-v2/) 此版本没有红外滤光片；它同时捕捉可见光和红外光。搭配红外照明可以在黑暗中看清物体，或使用随附的蓝色方块凝胶监测绿色植物的健康状况。

有关此摄像头硬件特性和功能的详细信息，请参阅[硬件规格](#硬件规格)。

## 摄像头模块 3

这款 [1200 万像素摄像头](https://www.raspberrypi.com/products/camera-module-3/)基于索尼 IMX708 传感器，分辨率为 4608 × 2592 像素。它具有[电动自动对焦](https://www.raspberrypi.com/news/new-autofocus-camera-modules/)，最长可录制 112 秒的曝光时间。

摄像头模块 3 有以下版本：

* 标准版，标准视场角（FoV）
* 标准版，广角视场角（FoV）
* NoIR 版，标准视场角（FoV）
* NoIR 版，广角视场角（FoV）

标准版仅捕捉可见光；红外光会被滤除。NoIR 版没有红外滤光片；它们同时捕捉可见光和红外光。将 NoIR 摄像头与红外照明搭配使用可以在黑暗中看清物体，或使用随附的蓝色方块凝胶监测绿色植物的健康状况。

所有这些版本也适用于独立的[摄像头模块 3 传感器组件](https://www.raspberrypi.com/products/camera-module-3-sensor-assembly/)。

![摄像头模块 3（左）和摄像头模块 3 广角（右）](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-14b0924ca712f013099a4a32de9c662e4c13a95b%2Fcm3.jpg?alt=media)

![摄像头模块 3 NoIR（左）和摄像头模块 3 NoIR 广角（右）](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-b2763db685aecc28d9c3f052bb0fd90d763018d0%2Fcm3_noir.jpg?alt=media)

有关此摄像头硬件特性和功能的详细信息，请参阅[硬件规格](#硬件规格)。

> **注意**
>
> 有[证据](https://github.com/raspberrypi/libcamera/issues/43)表明，摄像头模块 3 可能会在 CSI 时钟速率的谐波频率上发射射频干扰（RFI）。这种射频干扰所处的频段可能会干扰 GPS L1 频率（1575 MHz）。有关详细信息和建议的解决方法，请参阅 [GitHub 上的讨论帖](https://github.com/raspberrypi/libcamera/issues/43)。

### 传输特性

摄像头模块 3 中的 IMX708 传感器具有以下光谱灵敏度特性。

![摄像头模块 3 传输图](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-669f8c86e806d76257253c9ee55da2d1611679a3%2Fcm3-filter.png?alt=media)

## 全局快门摄像头

这款 160 万像素的[全局快门摄像头](https://www.raspberrypi.com/products/raspberry-pi-global-shutter-camera/)可捕捉快速移动的拍摄对象并最大限度减少失真。它基于索尼 IMX296 传感器，分辨率为 1456 × 1088 像素。

该摄像头配备 C/CS 卡口，可兼容各种镜头。更多信息请参阅[推荐镜头](#推荐镜头)。

你可以通过向板上的外部触发连接施加脉冲来触发全局快门（GS）摄像头。此功能使你能够同步多台全局快门摄像头。更多信息请参阅[全局快门摄像头的外部触发](#全局快门摄像头的外部触发)。

![全局快门摄像头](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-f03c35928a745af6a3582431285f25c85e16ef83%2Fgs-camera.jpg?alt=media)

有关此摄像头硬件特性和功能的详细信息，请参阅[硬件规格](#硬件规格)。

### 卷帘快门还是全局快门？

大多数数码相机（包括我们的其他摄像头模块）都使用 **卷帘快门**：它们逐行扫描正在捕捉的图像，然后输出结果。这在某些情况下可能会造成失真效果。例如，拍摄旋转的螺旋桨叶片时，图像可能看起来像是在闪烁，而不像一个正在旋转的物体。这是因为在相机扫描并观察场景的短暂瞬间，螺旋桨叶片有足够的时间改变位置。

**全局快门**（例如我们的全局快门摄像头模块所用的那种）不会这样做。它一次性捕捉场景中每个像素的光线，因此拍摄螺旋桨叶片等物体不会产生相同的失真。

这很有用，因为像螺旋桨叶片这样的高速运动物体现在很容易捕捉；我们还可以同步多台摄像头，在精确的同一时刻拍摄照片。这样做的好处包括在捕捉立体图像时最大限度减少失真；如果左眼中出现的运动尚未出现在右眼中，人类大脑会感到困惑。在光线充足的情况下，树莓派全局快门摄像头还可以使用比卷帘快门相机更短的曝光时间——低至 30 µs——这使它适用于高速摄影。

> **注意**
>
> 全局快门摄像头的图像传感器具有 6.3 mm 对角线的活动感应区域，大小与树莓派 HQ 摄像头类似。但是，它的像素更大，可以收集更多光线。大像素尺寸和低像素数在机器视觉应用中非常有价值；传感器产生的像素越多，实时处理图像就越困难。为了解决这个问题，许多应用程序会缩小和裁剪图像。使用全局快门摄像头和适当的镜头放大倍率则无此必要，因为较低的分辨率和较大的像素尺寸意味着可以原生捕捉图像。

### 传输特性

全局快门摄像头使用 Hoya CM500 红外滤光片。其传输特性如下图所示。

![CM500 传输图](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-2156d650ba8288db22525066a9b58a2c4d1781bd%2Fhoyacm500.png?alt=media)

如果你想增强全局快门摄像头对红外光的敏感度，可以拆除红外滤光片。此操作不可逆，会使保修失效。更多信息请参阅[红外滤光片](#红外滤光片)。

拆除滤光片后，树莓派全局快门摄像头具有以下传输特性：

![不带红外截止滤光片的 GS 摄像头传输图](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-e75662f401eacace5dce58b7f8ed1de2516584db%2Fgs.png?alt=media)

## 高质量（HQ）摄像头

这款 [1200 万像素高质量（HQ）摄像头](https://www.raspberrypi.com/products/raspberry-pi-high-quality-camera/)配备 M12 卡口或 C/CS 卡口，可兼容各种镜头。更多信息请参阅[推荐镜头](#推荐镜头)。该摄像头基于索尼 IMX477 传感器，分辨率为 4056 × 3040 像素。它最长可录制 670.74 秒的曝光时间。

你可以通过向外部触发施加脉冲来触发高质量（HQ）摄像头。此功能使你能够同步多台高质量（HQ）摄像头。更多信息请参阅[同步捕获](#同步捕获)。

![高质量（HQ）摄像头，M12 卡口（左）和 C/CS 卡口（右）](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-06897dfdd1f5e5179e37d21364c7c6e76f328fe0%2Fhq.jpg?alt=media)

有关此摄像头硬件特性和功能的详细信息，请参阅[硬件规格](#硬件规格)。

### 传输特性

高质量（HQ）摄像头使用 Hoya CM500 红外滤光片。其传输特性如下图所示。

![CM500 传输图](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-2156d650ba8288db22525066a9b58a2c4d1781bd%2Fhoyacm500.png?alt=media)

如果你想增强高质量（HQ）摄像头对红外光的敏感度，可以拆除红外滤光片。此操作不可逆，会使保修失效。更多信息请参阅[红外滤光片](#红外滤光片)。

拆除滤光片后，树莓派高质量（HQ）摄像头具有以下传输特性：

![不带红外截止滤光片的高质量摄像头传输图](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-42cd3b7c1e43fafb6bb98c6136370204a066b787%2Fhq.png?alt=media)

## 推荐镜头

以下镜头建议与我们的 HQ 和 GS 摄像头配合使用。

> **注意**
>
> HQ 摄像头有 C/CS 卡口和 M12 卡口两种版本，而 GS 摄像头仅有 C/CS 卡口版本。

### C/CS 镜头

我们推荐两款由 CGL Electronics Co. Ltd. 制造的镜头：一款 6 mm 广角镜头和一款 16 mm 远摄镜头。这些镜头可从离你最近的[授权经销商](https://www.raspberrypi.com/products/raspberry-pi-high-quality-camera/)处购买。

|                  |    | 16 mm 远摄            | 6 mm 广角       |
| ---------------- | -- | ------------------- | ------------- |
| 分辨率              |    | 10 MP               | 3 MP          |
| 图像格式             |    | 1 英寸                | 1/2 英寸        |
| 光圈               |    | F1.4 至 F16          | F1.2          |
| 卡口               |    | C                   | CS            |
| 视场角 水平°×垂直°（对角°） | HQ | 22.2°×16.7° (27.8°) | 55°×45° (71°) |
|                  | GS | 17.8°×13.4° (22.3°) | 45°×34° (56°) |
| 背焦距              |    | 17.53 mm            | 7.53 mm       |
| M.O.D.           |    | 0.2 m               | 0.2 m         |
| 尺寸               |    | φ39×50 mm           | φ30×34 mm     |

### M12 镜头

![M12 卡口](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-875f0297a21226ac87dabc7731e854fd9b95373c%2Fm12-lens.jpg?alt=media)

我们推荐三款由[高嘉光电](https://www.gaojiaoptotech.com/)制造的镜头。这些镜头可从离你最近的[授权经销商](https://www.raspberrypi.com/products/raspberry-pi-high-quality-camera/)处购买。

|                     |   | 8 mm          | 25 mm               | 鱼眼                   |
| ------------------- | - | ------------- | ------------------- | -------------------- |
| 分辨率                 |   | 12 MP         | 5 MP                | 15 MP                |
| 图像格式                |   | 1/1.7 英寸      | 1/2 英寸              | 1/2.3 英寸             |
| 光圈                  |   | F1.8          | F2.4                | F2.5                 |
| 卡口                  |   | M12           |                     |                      |
| HQ 视场角 水平°×垂直°（对角°） |   | 49°×36° (62°) | 14.4°×10.9° (17.9°) | 140°×102.6° (184.6°) |

## 同步捕获

高质量（HQ）摄像头支持同步捕获。一台摄像头（“源摄像头”）可以配置为在开始捕获一帧时，在其 XVS（垂直同步）引脚上产生脉冲。其他（即“接收”）摄像头可以监听此脉冲，并与源摄像头同时捕获帧。

此方法已在很大程度上被[软件摄像头同步](https://book.bsdcn.org/pages/9oXQamXmFqYkxuVjqWBi#%E8%BD%AF%E4%BB%B6%E6%91%84%E5%83%8F%E5%A4%B4%E5%90%8C%E6%AD%A5)取代，后者无需额外接线即可远距离工作，并具有亚毫秒级精度。但是，当摄像头物理位置接近时，你可以使用有线同步。

> **注意**
>
> 你也可以在同步模式下操作全局快门（GS）摄像头。但是，源摄像头会多录一帧。对于 GS 摄像头，我们建议改用[外部触发源](#全局快门摄像头的外部触发)。你不能同步 GS 摄像头和 HQ 摄像头。

### 连接摄像头

在每台摄像头的 XVS 测试点上焊接一根导线，并将它们连接在一起。

在每台摄像头的 GND 测试点上焊接一根导线，并将它们连接在一起。

*仅对于 GS 摄像头，* 你还必须将每台摄像头的 XHS（水平同步）测试点连接在一起。在你希望其用作接收摄像头的任何 GS 摄像头上，用焊料将 MAS 焊盘的两半搭接在一起。

> **注意**
>
> 本文档的早期版本建议为 XVS 使用外部上拉电阻。现已不再推荐这样做。请确保你拥有最新版本的树莓派系统，并为所有连接的摄像头设置 `always-on` 属性。

### 驱动程序配置

配置摄像头驱动程序，使其在非流传输期间保持 1.8 V 电源开启，并（可选）选择源摄像头和接收摄像头角色。

#### 对于 HQ 摄像头

编辑 `/boot/firmware/config.txt`。将 `camera_auto_detect=1` 更改为 `camera_auto_detect=0`。

对于源摄像头，追加以下行：

```
dtoverlay=imx477,always-on,sync-source
```

或者对于接收摄像头：

```
dtoverlay=imx477,always-on,sync-sink
```

在树莓派 5、CM4 或 CM5 上使用 CAM0 端口时，请在该行末尾追加 `,cam0`，不要留空格。如果两台摄像头连接在同一台树莓派上，你需要两行 `dtoverlay`，其中只有一行以 `,cam0` 结尾。

或者，如果你希望在运行时切换摄像头的角色（并且它们没有都连接到同一台树莓派上），请省略上面的 `,sync-source` 或 `,sync-sink`。此时你可以在启动每个摄像头之前设置一个模块参数。

对于连接源摄像头的树莓派：

```bash
$ echo 1 | sudo tee /sys/module/imx477/parameters/trigger_mode
```

对于连接接收摄像头的树莓派：

```bash
$ echo 2 | sudo tee /sys/module/imx477/parameters/trigger_mode
```

每次系统启动时都要执行此操作。

#### 对于 GS 摄像头

编辑 `/boot/firmware/config.txt`。将 `camera_auto_detect=1` 更改为 `camera_auto_detect=0`。

无论是源摄像头还是接收摄像头，都追加以下行：

```
dtoverlay=imx296,always-on
```

在树莓派 5、CM4 或 CM5 上使用 CAM0 端口时，请在该行末尾追加 `,cam0`，不要留空格。如果两台摄像头连接在同一台树莓派上，你需要两行 `dtoverlay`，其中只有一行以 `,cam0` 结尾。

在 GS 摄像头上，接收摄像头角色由 MAS 引脚启用，无法通过软件配置（`trigger_mode` 和 `sync-sink` 与[外部触发方法](#全局快门摄像头的外部触发)相关，不得用于此方法）。

### Libcamera 配置

如果摄像头未能在 1 秒内全部启动，`rpicam` 应用程序可能会超时。要防止此问题，请在带有接收摄像头的任何树莓派上编辑一个配置文件。

在树莓派 5 或 CM5 上：

```bash
$ cp /usr/share/libcamera/pipeline/rpi/pisp/example.yaml timeout.yaml
```

在其他树莓派型号上：

```bash
$ cp /usr/share/libcamera/pipeline/rpi/vc4/rpi_apps.yaml timeout.yaml
```

现在编辑该副本。在这两种情况下，删除 `"camera_timeout_value_ms":` 行中的 `#`（注释），并将数字更改为 `60000`（60 秒）。

### 启动摄像头

运行以下命令启动接收摄像头：

```bash
$ export LIBCAMERA_RPI_CONFIG_FILE=timeout.yaml
$ rpicam-vid --frames 300 --qt-preview -o sink.h264
```

等待几秒，然后运行以下命令启动源摄像头：

```bash
$ rpicam-vid --frames 300 --qt-preview -o source.h264
```

帧必须同步。使用 `--frames` 参数确保捕获相同数量的帧，并且录制长度完全相同。先运行接收摄像头可确保不会丢失任何帧。

> **注意**
>
> 在同步模式下使用 GS 摄像头时，接收摄像头录制的帧数与源摄像头不完全相同。**源摄像头在接收摄像头开始录制前会多录一帧**。因此，你需要使用 `--frames` 参数指定接收摄像头少录一帧。

## 全局快门摄像头的外部触发

全局快门（GS）摄像头可以通过向板上的外部触发连接（在板上标记为 XTR）施加脉冲，从外部触发。多台摄像头可以连接到同一个脉冲，从而提供了同步两台摄像头的另一种方式。

曝光时间等于低脉冲宽度加上额外的 14.26 µs。例如，10000 µs 的低脉冲会产生 10014.26 µs 的曝光时间。帧速率直接取决于你向该引脚施加脉冲的频率。30 Hz 的 PWM 频率对应每秒 30 帧的帧速率。

![显示脉冲格式的图片](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-dd6f4d27b30a034fa67d7ad897863daa3a60d52a%2Fexternal_trigger.jpg?alt=media)

### 准备工作

> **警告**
>
> 此修改包括拆除一个 SMD 焊接部件。除非你觉得自己有能力完成此修改，否则不要尝试。在摄像头板上焊接时，请拆下塑料背盖以避免损坏。

如果你的主板上安装了晶体管 Q2（如下图蓝色所示），则需要从主板上拆除 R11（如下图红色所示）。它将 GP1 连接到 XTR，如果不拆除 R11，摄像头将无法在外部触发模式下工作。元件的位置如下图所示。

![显示待拆除电阻器的图片](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-7d9fc1077e01deaa8a9f7c1b9aff170fd768d836%2Fresistor.jpg?alt=media)

接下来，在 GS 摄像头板的 XTR 和 GND 触点上焊接一根导线。请注意，XTR 是 1.8 V 输入，因此你可能需要电平转换器或电位分压器。

我们可以使用树莓派 Pico 来提供触发信号。将任意 Pico GPIO 引脚（本示例使用 GP28）通过 1.5 kΩ 电阻连接到 XTR。还在 XTR 和 GND 之间连接一个 1.8 kΩ 电阻，将高逻辑电平降低到 1.8 V。接线图如下图所示。

![显示树莓派 Pico 接线的图片](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-c26df7a84f3d5fadb46af2d14c12070256e98e78%2Fpico_wiring.jpg?alt=media)

#### 树莓派 Pico MicroPython 代码

```python
from machine import Pin, PWM

from time import sleep

pwm = PWM(Pin(28))

framerate = 30
shutter = 6000  # 单位为微秒

frame_length = 1000000 / framerate
pwm.freq(framerate)

pwm.duty_u16(int((1 - (shutter - 14) / frame_length) * 65535))
```

低脉冲宽度等于快门时间，PWM 的频率等于帧速率。

> **注意**
>
> 在本示例中，Pin 28 连接到 GS 摄像头板上的 XTR 触点。

### 摄像头驱动程序配置

仅当你有多台摄像头将 XTR 并联接线时，才需要执行此步骤。

编辑 `/boot/firmware/config.txt`。将 `camera_auto_detect=1` 更改为 `camera_auto_detect=0`。

追加以下行：

```
dtoverlay=imx296,always-on
```

在树莓派 5、CM4 或 CM5 上使用 CAM0 端口时，请在该行末尾追加 `,cam0`，不要留空格。如果两台摄像头都连接到同一台树莓派上，你需要两行 `dtoverlay`，其中只有一行以 `,cam0` 结尾。

如果外部触发不会立即启动，你还需要[如上](#libcamera-配置)所述增加 libcamera 超时时间。

### 启动摄像头

启用外部触发：

```bash
$ echo 1 | sudo tee /sys/module/imx296/parameters/trigger_mode
```

在 Pico 上运行代码，然后启动摄像头：

```bash
$ rpicam-hello -t 0 --qt-preview --shutter 3000
```

每次 Pico 向该引脚发送脉冲时，都会尝试捕获一帧。但是，如果未设置 `--gain` 和 `--awbgains`，则会丢弃一些帧，以便 AGC 和 AWB 算法稳定下来。

> **注意**
>
> 运行 `rpicam-apps` 时，请始终指定固定的快门持续时间，以确保 AGC 不会尝试调整摄像头的快门速度。具体数值并不重要，因为它实际上由外部触发脉冲控制。

## 红外滤光片

高质量（HQ）摄像头和全局快门摄像头都包含一个红外滤光片，用于降低摄像头对红外光的敏感度，并使户外照片看起来更自然。但是，你可以拆除滤光片来：

* 增强某些类型摄影中的色彩，例如植物、水和天空的图像
* 在红外光照明的位置提供夜视功能

### 拆卸滤光片

> **警告**
>
> **此过程不可逆：** 固定滤光片的粘合剂一旦揭起再装回，便无法继续粘牢，而且红外滤光片虽然厚约 1.1 mm，拆除时可能会破裂。**拆除它会使产品保修失效**。

你可以从 HQ 和 GS 摄像头上拆除滤光片。下面的演示展示了 HQ 摄像头。

![安装好滤光片的 HQ 摄像头](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-4de5eefe391aa6fc229fbb3f7df272fc88a7d763%2FFILTER_ON_small.jpg?alt=media)

> **重要**
>
> 传感器暴露在空气中时，请确保在干净无尘的环境中操作，以保护传感器。

1. 拧下主电路板底部的两个 1.5 mm 六角锁紧螺钉。小心不要让垫圈滚开。

   ![拧下六角锁紧螺钉后的摄像头](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-0c9cb169cf31601684143ede95219c2e7b289bc9%2FSCREW_REMOVED_small.jpg?alt=media)
2. 外壳和 PCB 之间有一层略带粘性的密封垫圈，需要用一点力气才能分开。你也可以尝试一些方法来弱化粘合剂，例如使用少量异丙醇或加热（约 20-30 °C）。
3. 粘合剂松动后，抬起主板并将其放在非常干净的表面上。确保传感器不会接触到表面。

   ![放置在干净表面上的摄像头主板](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-2cb6d17c2af3855f4fd566b39e5e8e223348c333%2FFLATLAY_small.jpg?alt=media)
4. 将镜头座翻转使镜头朝上，并将其放在平坦的表面上。

   ![使用溶剂弱化粘合剂](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-589f1a8c70f0aff8f19db48f0be3a36185ce47b3%2FSOLVENT_small.jpg?alt=media)
5. 为最大限度降低损坏滤光片的风险，请使用笔帽或类似的软塑料物品，仅在玻璃与铝相接的边缘处向下按压滤光片。胶水会断裂，滤光片将从镜头座上脱落。

   ![从镜头座上拆下的滤光片](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-46d2e73fc5ceecee6f544ccb4fe429a1ab9c693f%2FREMOVE_FILTER_small.jpg?alt=media)
6. 鉴于更换镜头会使传感器暴露，此时你可以安装一个透明滤光片（例如 OHP 塑料），以尽量减少灰尘进入传感器腔的机会。
7. 将主外壳重新装回电路板上。确保外壳与仍留在电路板上的密封垫圈重新对齐。
8. 先放上尼龙垫圈，以防止损坏电路板。
9. 接着放上钢垫圈，它可以防止尼龙垫圈损坏。拧紧两个六角锁紧螺钉。只要垫圈按正确顺序安装，就不需要拧得很紧。

   ![拆除滤光片后的 HQ 摄像头](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-a0ab753ff81a6a5c8c0abf6b5f43d1ac175f6823%2FFILTER_OFF_small.jpg?alt=media)

> **注意**
>
> 将滤光片粘回原位并使设备恢复正常光学摄像头的功能，可能很难甚至无法做到。

## 硬件规格

下表比较了树莓派摄像头硬件的特性与功能。

|             | 摄像头模块 1                          | 摄像头模块 2                                | 摄像头模块 3                                          | 摄像头模块 3 广角                                       | HQ 摄像头                                         | AI 摄像头                        | GS 摄像头                                 |
| ----------- | -------------------------------- | -------------------------------------- | ------------------------------------------------ | ------------------------------------------------ | ---------------------------------------------- | ----------------------------- | -------------------------------------- |
| 尺寸          | 大约 25 × 24 × 9 mm                | 大约 25 × 24 × 9 mm                      | 大约 25 × 24 × 11.5 mm                             | 大约 25 × 24 × 12.4 mm                             | 38 × 38 × 18.4 mm（不含镜头）                        | 25 × 24 × 11.9 mm             | 38 × 38 × 19.8 mm（搭配适配器和防尘盖则为 29.5 mm） |
| 重量          | 3 g                              | 3 g                                    | 4 g                                              | 4 g                                              | 30.4 g                                         | 6 g                           | 34 g（搭配适配器和防尘盖则为 41 g）                 |
| 静态分辨率       | 500 万像素                          | 800 万像素                                | 1190 万像素                                         | 1190 万像素                                         | 1230 万像素                                       | 1230 万像素                      | 158 万像素                                |
| 视频模式        | 1080p30，720p60 和 640 × 480p60/90 | 1080p47，1640 × 1232p41 和 640 × 480p206 | 2304 × 1296p56，2304 × 1296p30 HDR，1536 × 864p120 | 2304 × 1296p56，2304 × 1296p30 HDR，1536 × 864p120 | 2028 × 1080p50，2028 × 1520p40 和 1332 × 990p120 | 2028 × 1520p30，4056 × 3040p10 | 1456 × 1088p60                         |
| 传感器         | OmniVision OV5647                | 索尼 IMX219                              | 索尼 IMX708                                        | 索尼 IMX708                                        | 索尼 IMX477                                      | 索尼 IMX500                     | 索尼 IMX296                              |
| 传感器分辨率      | 2592 × 1944 像素                   | 3280 × 2464 像素                         | 4608 × 2592 像素                                   | 4608 × 2592 像素                                   | 4056 × 3040 像素                                 | 4056 × 3040 像素                | 1456 × 1088 像素                         |
| 传感器图像区域     | 3.76 × 2.74 mm                   | 3.68 × 2.76 mm（对角线 4.6 mm）             | 6.45 × 3.63 mm（对角线 7.4 mm）                       | 6.45 × 3.63 mm（对角线 7.4 mm）                       | 6.287 × 4.712 mm（对角线 7.9 mm）                   | 6.287 × 4.712 mm（对角线 7.9 mm）  | 对角线 6.3 mm                             |
| 像素大小        | 1.4 µm × 1.4 µm                  | 1.12 µm × 1.12 µm                      | 1.4 µm × 1.4 µm                                  | 1.4 µm × 1.4 µm                                  | 1.55 µm × 1.55 µm                              | 1.55 µm × 1.55 µm             | 3.45 µm × 3.45 µm                      |
| 光学尺寸        | 1/4 英寸                           | 1/4 英寸                                 | 1/2.43 英寸                                        | 1/2.43 英寸                                        | 1/2.3 英寸                                       | 1/2.3 英寸                      | 1/2.9 英寸                               |
| 对焦          | 固定                               | 可调                                     | 电动                                               | 电动                                               | 可调                                             | 可调                            | 可调                                     |
| 对焦范围        | 大约 1 m 到 ∞                       | 大约 10 cm 到 ∞                           | 大约 10 cm 到 ∞                                     | 大约 5 cm 到 ∞                                      | 取决于镜头                                          | 大约 20 cm 到 ∞                  | 取决于镜头                                  |
| 焦距          | 3.60 mm ± 0.01                   | 3.04 mm                                | 4.74 mm                                          | 2.75 mm                                          | 取决于镜头                                          | 4.74 mm                       | 取决于镜头                                  |
| 水平视场角（FoV）  | 53.50 ± 0.13°                    | 62.2°                                  | 66°                                              | 102°                                             | 取决于镜头                                          | 66 ± 3°                       | 取决于镜头                                  |
| 垂直视场角（FoV）  | 41.41 ± 0.11°                    | 48.8°                                  | 41°                                              | 67°                                              | 取决于镜头                                          | 52.3 ± 3°                     | 取决于镜头                                  |
| 焦距比（光圈）     | F2.9                             | F2.0                                   | F1.8                                             | F2.2                                             | 取决于镜头                                          | F1.79                         | 取决于镜头                                  |
| 最大曝光时间（秒）   | 3.28                             | 11.76                                  | 112                                              | 112                                              | 670.74                                         | 112                           | 15.5                                   |
| 镜头卡口        | 不适用                              | 不适用                                    | 不适用                                              | 不适用                                              | C/CS 或 M12 卡口                                  | 不适用                           | C/CS                                   |
| 有无 NoIR 版本？ | 有                                | 有                                      | 有                                                | 有                                                | 无                                              | 无                             | 无                                      |

## 高级信息

本节为高级用户提供信息。

### 机械图纸和原理图

机械图纸和原理图可在产品信息门户（Product Information Portal）的以下位置获取：

* [摄像头模块 2](https://pip.raspberrypi.com/categories/652-raspberry-pi-camera-module-2)
* [摄像头模块 3](https://pip.raspberrypi.com/categories/786-raspberry-pi-camera-module-3)
* [HQ 摄像头模块](https://pip.raspberrypi.com/categories/659-raspberry-pi-high-quality-camera)
* [GS 摄像头模块](https://pip.raspberrypi.com/categories/810-raspberry-pi-global-shutter-camera)

> **注意**
>
> 摄像头模块 3 的主板尺寸和安装孔位置与摄像头模块 2 相同。但是，由于传感器模块尺寸和位置的变化，它与树莓派 Zero 保护壳的摄像头盖不具备机械兼容性。

此外，下图展示了树莓派 CSI 摄像头连接器的原理图。

![树莓派 CSI 摄像头连接器的原理图](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-b587a6afcb43a96c488dd2b468e6cd7783081ee7%2FRPi-S5-conn.png?alt=media)

### 引脚信息

使用本节中的信息来了解摄像头连接器中各个引脚的功能。

#### 找到 1 号引脚

FPC 连接器上 1 号引脚的位置取决于硬件。

以下描述假定你手持树莓派主板时，芯片和接口朝上，树莓派徽标方向正确。对于顶面没有徽标的树莓派 Zero 主板，请将 GPIO 沿离你最远的边缘摆放。

* 在树莓派旗舰型号和树莓派 Zero 设备上，1 号引脚是离你最远且最靠近 GPIO 排针的引脚。
* 在树莓派计算模块 IO 板上，根据型号，1 号引脚用小圆圈或圆点标记。

手持树莓派摄像头板时，使镜头朝下、接口朝向你的右侧，1 号引脚是离你最近的引脚。

#### 摄像头连接器引脚定义（15 针）

这是树莓派 5 之前的旗舰树莓派型号上使用的 15 针摄像头串行接口（CSI）连接器的引脚定义。该连接器与 Amphenol SFW15R-2STE1LF 兼容。

信号方向从树莓派主板的角度指定。I2C 线路（SCL 和 SDA）在树莓派主板上被上拉至 3.3 V。

GPIO 线路的功能和方向取决于所使用的具体摄像头模块。通常，`CAM_IO0` 用作高电平有效的电源使能。某些产品不包含 `CAM_IO1`。

| 引脚 | 名称       | 说明             | 方向/类型    |
| -- | -------- | -------------- | -------- |
| 1  | GND      | -              | 接地       |
| 2  | CAM\_DN0 | D-PHY 通道 0（负极） | 输入，D-PHY |
| 3  | CAM\_DP0 | D-PHY 通道 0（正极） | 输入，D-PHY |
| 4  | GND      | -              | 接地       |
| 5  | CAM\_DN1 | D-PHY 通道 1（负极） | 输入，D-PHY |
| 6  | CAM\_DP1 | D-PHY 通道 1（正极） | 输入，D-PHY |
| 7  | GND      | -              | 接地       |
| 8  | CAM\_CN  | D-PHY 时钟（负极）   | 输入，D-PHY |
| 9  | CAM\_CP  | D-PHY 时钟（正极）   | 输入，D-PHY |
| 10 | GND      | -              | 接地       |
| 11 | CAM\_IO0 | GPIO（例如电源使能）   | 双向，3.3 V |
| 12 | CAM\_IO1 | GPIO（例如时钟、LED） | 双向，3.3 V |
| 13 | SCL      | I2C 时钟         | 双向，3.3 V |
| 14 | SDA      | I2C 数据         | 双向，3.3 V |
| 15 | 3V3      | 3.3 V 电源       | 输出       |

#### 摄像头连接器引脚定义（22 针）

这是树莓派 Zero 系列、计算模块 IO 板以及树莓派 5 及之后的旗舰型号上使用的 22 针摄像头串行接口（CSI）连接器的引脚定义。该连接器与 Amphenol F32Q-1A7H1-11022 兼容。

信号方向从树莓派主板的角度指定。I2C 线路（SCL 和 SDA）在树莓派主板上被上拉至 3.3 V。

GPIO 线路的功能和方向取决于所使用的具体摄像头模块。通常，`CAM_IO0` 用作高电平有效的电源使能。某些产品不包含 `CAM_IO1`。

| 引脚 | 名称       | 说明             | 方向/类型    |
| -- | -------- | -------------- | -------- |
| 1  | GND      | -              | 接地       |
| 2  | CAM\_DN0 | D-PHY 通道 0（负极） | 输入，D-PHY |
| 3  | CAM\_DP0 | D-PHY 通道 0（正极） | 输入，D-PHY |
| 4  | GND      | -              | 接地       |
| 5  | CAM\_DN1 | D-PHY 通道 1（负极） | 输入，D-PHY |
| 6  | CAM\_DP1 | D-PHY 通道 1（正极） | 输入，D-PHY |
| 7  | GND      | -              | 接地       |
| 8  | CAM\_CN  | D-PHY 时钟（负极）   | 输入，D-PHY |
| 9  | CAM\_CP  | D-PHY 时钟（正极）   | 输入，D-PHY |
| 10 | GND      | -              | 接地       |
| 11 | CAM\_DN2 | D-PHY 通道 2（负极） | 输入，D-PHY |
| 12 | CAM\_DP2 | D-PHY 通道 2（正极） | 输入，D-PHY |
| 13 | GND      | -              | 接地       |
| 14 | CAM\_DN3 | D-PHY 通道 3（负极） | 输入，D-PHY |
| 15 | CAM\_DP3 | D-PHY 通道 3（正极） | 输入，D-PHY |
| 16 | GND      | -              | 接地       |
| 17 | CAM\_IO0 | GPIO（例如电源使能）   | 双向，3.3 V |
| 18 | CAM\_IO1 | GPIO（例如时钟、LED） | 双向，3.3 V |
| 19 | GND      | -              | 接地       |
| 20 | SCL      | I2C 时钟         | 双向，3.3 V |
| 21 | SDA      | I2C 数据         | 双向，3.3 V |
| 22 | 3V3      | 3.3 V 电源       | 输出       |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://book.bsdcn.org/rpicn/pei-jian/she-xiang-tou.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
