模板:Raspberry Pi Camera User Manual

使用说明

驱动支持

• 

硬件连接

把摄像头的排线插入到网口和 HDMI 口之间的排线插槽，银色亮面朝向 HDMI 口。需要先把树莓派板载的排线插槽的扣子拨开，才能插入排线。排线需要紧密插入排线插槽，同时应注意避免排线折弯。排线插入之后，需要把插槽的扣子重新扣上。

测试摄像头

Bullseye系统

• 更多摄像头设置说明，请参考官方文档
• 如果使用的是Raspberry Pi Camera Module 3系列，只支持最新的bullseye系统，如测试时出现问题可尝试#Camera Module 3 系列配置

注：最新的bullseye镜像，摄像头接口已经默认开启，故无需配置raapi-config。

• 进入命令行终端，执行以下语句获取系统更新：

sudo apt-get update
sudo apt-get upgrade

• 输入命令，进行摄像头预览

sudo libcamera-hello -t 0

如果要关掉预览窗口，可以点击x关掉。 也可以回到终端界面，用ctrl-c终止程序。

• 若想抓取图片，可执行命令

libcamera-jpeg -o test.jpg

注：如果是Camera module 3，会开启自动对焦功能

Buster系统

• 进入命令行终端，执行以下语句获取系统更新：

sudo apt-get update
sudo apt-get upgrade

• 使用 raspi-config 配置摄像头。执行：

sudo raspi-config

依次选择：Interfacing Options --> Camera --> Would you like the camera interface to be enabled? 选择 <Yes>

重启系统：提示 Would you like to reboot now? 选择 Yes

或者执行这个命令重启：

sudo reboot

• 配置并且连接完摄像头，只要给树莓派上电即可使用拍照和摄像功能。
• 打开树莓派终端，并开启摄像头预览：

sudo raspistill -t 0

如果要关掉预览窗口，可以用ctrl-c终止程序。

Camera Module 3 系列配置

当使用libcamera库调用摄像头出现报错 ERROR: *** no cameras available *** 时，可尝试进行以下操作：

• 确认在断电状态下正确连接好了摄像头和树莓派主板的 CSI 接口
• 上电进入系统后，执行一下指令，进入系统配置工具。

sudo raspi-config 

选择 Interfacing Options – Legacy Camera 菜单 禁用 Legacy 摄像头。

重启系统：提示 Would you like to reboot now? 选择 Yes

• 等待系统再次开机后，修改配置文件config.txt，执行：

sudo nano /boot/config.txt

• 找到下面几行配置，修改后面的数值如下。如果某行没有找到，可在文件末尾添加一行。

camera_auto_detect=0
gpu_mem=128

• 在文件最后面再加一行，手动配置摄像头传感器型号，CTRL+X 后键入 Y 回车保存。

dtoverlay=imx708

• 运行下面的命令修改 /etc/modules 内容：

sudo nano /etc/modules

• 在文件末尾添加一行,CTRL+X 后键入 Y 回车保存。

bcm2835-v4l2

• 运行命令 sudo reboot 重启树莓派，随后按照#Bullseye系统里的操作测试Camera Module 3

检测摄像头

• 安装好摄像头后，可通过以下命令来检测摄像头是否有问题，以及开发板是否检测出摄像头和摄像头的数量

ls /dev/video*

• 可通过v4l2-utils进一步检测摄像头数量以及规格

检测摄像头较完整信息
v4l2-ctl --list-devices
当接入多个摄像头时可通过此命令判断编号对应的摄像头

检测摄像头的规格参数
v4l2-ctl --device=/dev/video0 --list-formats-ext
其中video0可根据你需要查询的摄像头进行更改

调用摄像头

bullseye系统

libcamera-hello

• 该命令用来预览摄像头并将摄像头画面显示在屏幕上。
• 示例：

终端执行以下语句即可实时预览摄像头

libcamera-hello -t 0

其中 -t 0 表示一直预览至终止程序，用户可根据自己的需要进行调整。

• 调谐文件:
  • 树莓派的libcamera驱动会针对不同的摄像头模块调用一个调谐文件，调谐文件中提供了各种参数，器调用摄像头的时候，libcamera会调用调谐文件中的参数，结合算法对图像进行处理最终输出成预览画面。由于libcamera驱动只能自动感光芯片信号，但是摄像头的最终显示效果还会受整个模块的影响，调谐文件的使用就是为了可以灵活处理不同模块的摄像头，调整提高图像质量。
  • 如果在使用默认调谐文件的情况下，摄像头的输出图像不理想的话，用户可以通过调用自定义的调谐文件来对图像进行调整。比如，如果你使用的是官方的NOIR版本摄像头，相对于于Raspberry Pi Camera V2 常规款，NOIR摄像头可能需要不同的白平衡参数，这种情况下就可以通过调用调谐文件来进行切换。

libcamera-hello --tuning-file /usr/share/libcamera/ipa/raspberrypi/imx219_noir.json

• 用户可以复制默认的调谐文件，根据自己的需求进行修改。
• 备注：调谐文件的使用适用于其他的libcamera指令，后续指令中就不再做介绍

• 预览窗口：
  • 大部分的libcamera指令都会显示一个预览窗口在屏幕上，用户可以通过--info-text 参数来自定义预览窗口的标题信息， 同时也可以通过%directives 调用一些摄像头参数并显示在窗口上
  • 比如如果使用HQ Camera： 可以通过--info-txe "%focus" 在窗口上显示摄像头的焦距

libcamera-hello --info-text "focus %focus"

• 备注：更多关于参数的设置，可以参考后续的指令参数设置章节

libcamera-jpeg

• 该命令一个简单的静态图片拍摄程序，libcamera-jpeg相对于libcamera-still来讲更加简洁，并且有很多相同的功能来完成图片拍摄。
• 示例：

终端执行以下语句会显示一个5秒左右的预览串口，然后拍摄一张全像素的JPEG图像：

libcamera-jpeg -o test.jpg

其中test.jpg表示文件名

• 曝光控制：
  • 用户可以通过-t 参数来设置预览时间，同时可以通过--width 和 --height来设置拍摄图像的分辨率。例如

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

• 所有的libcamera指令都允许用户自己设置快门时间和增益，比如：

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

其中 --shutter 20000 表示曝光 20ms, --gain 1.5 表示摄像头增益被设置为1.5倍。

• 这个指令会拍摄一张图像，拍摄中会曝光20ms并且摄像头增益被设置为1.5倍。设置的增益参数，会首先设置感光芯片内部的模拟增益参数，如果设置的增益超过了驱动内置的最大的模拟增益的数值，会先设置芯片的最大模拟增益，然后将剩下的增益倍数作为数字增益来生效。
• 备注：数字增益是通过ISP(图像信号处理）来实现的，并非是直接调整芯片内置寄存器。正常情况下，默认的数字增益趋近于1.0，除非是有有以下三种情况。
  • 整体的增益参数需求，也就是当模拟增益无法满足设定的增益参数需求的时候，会需要数字增益来做补偿
  • 其中一个颜色增益小于1 （颜色增益是通过数字增益来实现的），在这种情况下， 最后获得增益就是稳定为 1/min(red_gain, blue_gain), 也就是实际是上应用了统一的数字增益， 且是其中一个颜色通道的增益值（非绿色通道）。
  • AEC/AGC被修改了。如果AEC/AGC有变化的时候， 数值增益也会一定程度上会发生变化，从何来来消除任何波动，但是这种变化会被快速恢复到"正常"值
• 树莓派的AEC/AGX算法允许程序指定曝光补偿，也就是通过设置光圈数值来调整图像的亮度。比如：

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

libcamera-still

• libcamera-still和libcamera-jpeg非常相似，不同的是libcamera继承了更多raspistill的功能。
• 示例：终端执行以下语句即可拍照

libcamera-still -o test.jpg

其中test.jpg表示文件名

• 编码器:
  • libcamea-still支持不同格式的图像文件，可以支持png和bmp编码，也支持直接不带编码或者任何图像格式地将RGB或者YUV像素的二进制转储保存成文件。如果是直接保存RGB或者YUV数据，程序在读取此类文件的时候必须了解文件的像素排列方式。

libcamera-still -e png -o test.png
libcamera-still -e bmp -o test.bmp
libcamera-still -e rgb -o test.data
libcamera-still -e yuv420 -o test.data

图像保存的格式是通过-e参数控制的， 如果没有调用-e参数设置的话，默认按照输出的文件名的格式保存。

• 原始图像拍摄
  • 原始图像（Raw image)图像就是直接图像传感器输出的图像， 没有经过任何ISP或者CPU处理。对于彩色相机传感器，一般来说原始图像的输出格式是Bayer. 注意原始图和我们之前说的位编码的RGB和YUV图像不同，RGB和YUV也是经过ISP处理后的图像的。
  • 拍摄一张原始图像的指令：

libcamera-still -r -o test.jpg

• 原始图像一般是以DNG （Adobe digital Negative) 格式保存的，DNG格式可以兼容大部分标准程序， 比如dcraw 或者RawTherapee. 原始图像会被保存为.dng后缀的相同名字的文件,比如如果运行上面的指令，为被另存为test.dng， 并同时生成一张jpeg文件。DNG文件中包含了已图像获取有关的元数据， 比如白平衡数据，ISP颜色矩阵等。

• 超长曝光
  • 如果要拍摄一张超长曝光的图片，我们需要禁用AEC/AGC和白平衡，否则这些算法会导致图片在收敛的时候多等待很多帧数据。禁用这些算法需要另设置显式值，另外, 用户可以通过--immediate设置来跳过预览过程。
  • 这里是拍摄一张曝光100秒的图像指令：

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

备注：几款官方摄像头的最长曝光时间参考表格.

libcamera-vid

• libcamera-vid是一个视频录制程序, 默认使用的是树莓派的硬件H.264编码器。这个程序运行之后会在屏幕上显示一个预览窗口，同时将比特流编码输出到指定文件。
• 示例：终端执行以下语句即可录制视频

libcamera-vid -t 10000 -o test.h264

其中-t 10000 表示录制10秒的视频，test.h264表示文件名

如果要查看视频可以用vlc来进行播放

vlc test.h264

备注：录制的是未打包的视频流， 用户可以使用--save-pts 设置输出时间戳，方便后续将比特流转成其他视频格式。

libcamera-vid -o test.h264 --save-pts timestamps.txt

• 如果想要输出mkv文件，可以用以下指令：

mkvmerge -o test.mkv --timecodes 0:timestamps.txt test.h264

• 编码器
  • 树莓派支持JPEG格式以及没有压缩和格式的YUV420：

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

--codec选项设置的是输出格式，而不是输出文件的扩展名。

• 使用--segment参数可以将输出文件分割成段（单位是ms)，适用于需要脚JPEG视频流分割成单独的时间比较短（大概1ms)的JPEG文件

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

• UDP 视频流传输
  • 可以使用UDP进行视频流传输，树莓派端运行（server）:

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

其中<ip-addr>需要替换成实际的客户端IP地址或者组播地址。

• 在客户端(client)，输入以下指令进行视频流获取和显示（两个指令使用一种即可）；

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

注意：port需要跟你在树莓派端设置的一致

• TCP视频流传输
  • 可以使用TCp进行视频流传输， 树莓派端运行（server）:

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

• 客户端（client）运行：

vlc tcp/h264://<ip-addr-of-server>:<port> #两条指令选一条即可
ffplay tcp://<ip-addr-of-server>:<port> -vf "setpts=N/30" -fflags nobuffer -flags low_delay -framedrop

• RTSP视频流传输
  • 在树莓派上，通常使用vlc来对RTSP视频流做处理,

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

• 播放端，可以运行以下任一条指令：

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

• 在所有预览指令中，如果想要关掉树莓派端的预览窗口，可以用参数-n(--nopreview)设置。另外注意--inline参数的设置，改设置会强制将视频流的报头信息包含在每个 I (intra)帧中，这个设置可以让客户端在丢失视频头的情况下仍然可以正确解析视频流。

• 高帧率模式
  • 如果使用libcamera-vid指令录制高帧率视频（一般高于60fps），同时减少丢帧情况，需要注意以下几点：
    • H264 的目标级别需要设置成4.2， 可以使用--level 4.2 参数设置
    • 必须关闭彩色降噪功能，可以使用--denoise cdn_off参数设置
    • 如果设置的帧率高于100fps，关掉预览窗口，释放更多CPU资源，避免丢帧。可以使用参数-n设置
    • 建议在/boot/config.txt文件中添加设置force_turbo=1， 来保证视频流或中中，CPU时钟不会被限制
    • 调整ISP输出分辨率，使用-width 1280 --height 720 设置分辨率，或者设置成更低的分辨率，具体以摄像头型号为准。
    • 如果你使用的是Pi 4或这个更高性能的型号，可以在/boot/config.txt文件中添加设置gpu_freq=550或者更高，来对主板GPU进行超频，来达到更高的性能效果。
    • 例如，录制 1280 x720 120fps视频。

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

libcamera-raw

• libcamera-raw类似于视频录制程序，不同的地方时，libcamera-raw录制的是直接传感器输出的Bayer格式的数据，也就是原始图像数据。libcamera-raw不会显示预览窗口。
• 终端执行以下语句即可录制一个2秒的原始数据片段：

libcamera-raw -t 2000 -o test.raw

程序会在没有格式信息的情况下直接转储原始帧，程序会将像素格式和图像尺寸直接打印在终端，用户可以根据输出的数据查看像素数据.默认情况下，程序会将原始帧保存成一个文件，文件通常比较大，用户可以通过--segement参数将文件进行分割。

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

• 如果内存条件比较好（比如使用SSD), libcamera-raw可以以大概10帧每秒的速度将官方的HQ Camera的数据（大概18MB每帧）写入到硬盘中， 为了达到这个速度，程序写入的是没有格式化过的原始帧，没有办法像libcamera-still那样保存成DNG文件。 如果想要确保不出现丢帧的情况，可以使用--framerate 降低帧率。

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

静态图片拍摄设置参数

--qiality, -q  #设置JPEG图像质量 <0 ~ 100>
--exif, -x #添加而外的EXIF标志
--timelapse  #延时拍照的时间间隔， 单位是ms
--framestart #帧计数的开始数值
--datetime  #用日期格式命名输出文件
--timestamp #用系统时间戳命名输出文件
-- restart  #设置JPEG重启时间间隔
--keypress, -k  # 设置回车按键拍照模式
--signal, -s  #设置信号触发拍照
--thumb #设置缩略图参数 <w:h:q>
--ebcoding, -e  #设置图像编码类型。 jpg / png / bmp / rgb / yuv420
--raw, -r  #保存原始图像
--latest #关联符号到最新保存的文件
--autofocus-on-capture  #设置在拍照前做一次对焦动作

静态图片拍摄设置参数

--quality, -q  # 设置JPEG指令 <0 - 100>
--bitrate, -b  # 设置H.264比特率
--intra, -g #设置内部帧周期 （只支持H.264）
--profile #设置H.264配置
--level  #设置H.264等级
--codec  #设置编码类型 h264 / mjpeg / yuv420
--keypress, -k  #设置回车暂停和录制
--signal， -s #设置信号暂停和录制
--initial #在录制或者暂停状态下启动程序
--split #切割视频并保存到另外的文件
--segment #将视频分割成多个视频段
--circular  #将视频写入循环缓冲区中
--inline #在每个I帧中写入数据头（只支持H.264）
--listen #等待TCP连接
--frames #设置录制的帧数

Buster系统

拍照

终端执行以下语句即可拍照：

raspistill -o image.jpg

此处 image.jpg 是照片文件名。

摄像

终端执行以下语句即可摄像：

raspivid -o video.h264 -t 10000

其中 -t 10000 表示录制 10 秒，用户各根据自己的需要进行调整。

参考资料

• 树莓派摄像头教程

Python 代码控制摄像头

• 可借助picamera库，使python支持摄像头的控制
• 树莓派镜像在Bullseye版本之后，底层的树莓派驱动由Raspicam切换成libcamera。libcamera是一个开源的软件栈（后面会称呼做驱动，方便理解），方便于第三方移植和开发自己的摄像头驱动。当前的libcamera不支持python， 因此树莓派官方还是提供了Raspicam的安装下载的方法。对于切换成libcamera困难，但是又需要用最新系统的用户，请直接移步到Raspicam的使用说明。

预览

• 打开python IDE，如Thonny Python IDE，或打开记事本

• 新建名字为camera.py的python文件，并保存到桌面
• 输入以下代码

from picamera import PiCamera
from time import sleep

camera = PiCamera()

camera.start_preview()
sleep(5)
camera.stop_preview()

• 进入终端，执行

python3 Desktop/camera.py

桌面将弹出预览框，实时取景并预览

需要注意的是，预览框仅在直接连接屏幕时有效，而是使用VNC等软件远程连接树莓派桌面，则不会弹出该预览框

如果预览画面是上下颠倒的，则可以通过以下代码旋转180度

camera = PiCamera()
camera.rotation = 180

• 预览画面可旋转90度、180度、270度
• 如果要重置画面，可将画面旋转0度

设置预览框的透明度

camera.start_preview(alpha=100)

alpha的值范围是0-255

拍照

• 在预览代码的中间插入camera.capture()命令

camera.start_preview()
sleep(5)
camera.capture('/home/pi/Desktop/image.jpg')
camera.stop_preview()

请注意：必须要执行代码sleep(5)，以便给摄像头的传感器留下一定时间调整亮度和白平衡

录像

移除 camera.captue()，并加入camera.start_recording()和camera.stop_recording()

camera.start_preview()
camera.start_recording('/home/pi/Desktop/video.h264')
sleep(5)
camera.stop_recording()
camera.stop_preview()

以上代码执行后，将在桌面生成video.h264的视频，长度为5秒

更多参数

• picamera可以给图片添加很多参数

设置分辨率

• 默认情况下，图片的分辨率等于显示器的分辨率，但最大的图像尺寸不超过2592*1944像素，视频尺寸不超过1920*1080像素；图像和视频的最小尺寸则为64*64像素
• 可使用以下代码设置图像的分辨率

camera.resolution = (2592, 1944)
camera.framerate = 15
camera.start_preview()
sleep(5)
camera.capture('/home/pi/Desktop/max.jpg')
camera.stop_preview()

• 请注意，相机的帧数需设置为≤15帧，以支持最大分辨率

给图片加文字

添加文字

camera.start_preview()
camera.annotate_text = "Hello world!"
sleep(5)
camera.capture('/home/pi/Desktop/text.jpg')
camera.stop_preview()

文字大小

camera.annotate_text_size = 50

annotate_text_size的取值范围为6-160，默认值32

文字颜色

camera.start_preview()
camera.annotate_background = Color('blue')
camera.annotate_foreground = Color('yellow')
camera.annotate_text = " Hello world "
sleep(5)
camera.stop_preview()

修改图片的参数

• 亮度

camera.start_preview()
camera.brightness = 70
sleep(5)
camera.capture('/home/pi/Desktop/bright.jpg')
camera.stop_preview()

brightness的取值范围为0-100，默认值50

• 对比度

 camera.contrast = 50

contrast的取值范围为0-100，默认值50

• 风格

可通过camera.image_effect，给图片添加特效

有效值：

• none(默认)
• negative
• solarize
• sketch
• denoise
• emboss
• oilpaint
• hatch
• gpen
• pastel
• watercolor
• film
• blur
• saturation
• colorswap
• washedout
• posterise
• colorpoint
• colorbalance
• cartoon
• deinterlace1
• deinterlace2

例如

camera.start_preview()
camera.image_effect = 'colorswap'
sleep(5)
camera.capture('/home/pi/Desktop/colorswap.jpg')
camera.stop_preview()

• 模式

可使用camera.exposure_mode，设置拍照模式（如夜晚、运动、雪地等模式）

有效值：

• off
• auto(默认)
• night
• nightpreview
• backlight
• spotlight
• sports
• snow
• beach
• verylong
• fixedfps
• antishake
• fireworks

例如

camera.start_preview()
camera.exposure_mode = 'beach'
sleep(5)
camera.capture('/home/pi/Desktop/beach.jpg')
camera.stop_preview()

• 白平衡

可使用camera.awb_mode设置白平衡

有效值：

• off
• auto(默认)
• sunlight
• cloudy
• shade
• tungsten
• fluorescent
• incandescent
• flash
• horizon

例如设置白平衡为“白天”

camera.start_preview()
camera.awb_mode = 'sunlight'
sleep(5)
camera.capture('/home/pi/Desktop/sunlight.jpg')
camera.stop_preview()