DepthAI V3 迁移指南

本文档描述了DepthAI v2和v3 API之间的变化，以及如何迁移现有代码。

v3 API 的新特性

不再需要显式的XLink节点 - XLink“桥接”会自动创建。
主机节点 - 在主机上运行的节点现在能与设备端节点无缝协作。
自定义主机节点 - 用户可以创建在主机上运行的自定义节点
- 支持 ThreadedHostNode 和 HostNode。
- ThreadedHostNode 的工作方式与 ScriptNode 类似；用户指定一个 run 函数，该函数在单独的线程中执行。
- HostNode 暴露一个输入映射 inputs，其条目会隐式同步。
- 在 Python 和 C++ 中均可用。
录制与回放节点。
Pipeline 现在拥有一个在管道创建期间可查询的活动设备。
支持新的模型库。
ImageManip 拥有刷新后的 API，行为定义更清晰。
ColorCamera 和 MonoCamera 已被弃用，推荐使用新的 Camera 节点。

最小必要更改

移除显式创建 dai.Device（除非你故意通过管道构造函数传递活动设备句柄——这是一种罕见的边界情况）。
移除显式的 XLink 节点。
将 dai.Device(pipeline) 替换为 pipeline.start()。
将所有 .getOutputQueue() 调用替换为 output.createOutputQueue()。
将所有 .getInputQueue() 调用替换为 input.createInputQueue()。

快速迁移：简单的 RGB 流示例

下方，旧版 v2 代码以 # ORIG 注释，新版代码以 # NEW 注释。

Python

1#!/usr/bin/env python3
2
3import cv2
4import depthai as dai
5
6# Create pipeline
7pipeline = dai.Pipeline()
8
9# Define source and output
10camRgb = pipeline.create(dai.node.ColorCamera)
11
12# ORIG – explicit XLink removed in v3
13# xoutVideo = pipeline.create(dai.node.XLinkOut)
14# xoutVideo.setStreamName("video")
15
16# Properties
17camRgb.setBoardSocket(dai.CameraBoardSocket.CAM_A)
18camRgb.setResolution(dai.ColorCameraProperties.SensorResolution.THE_1080_P)
19camRgb.setVideoSize(1920, 1080)
20
21# Linking
22# ORIG
23# camRgb.video.link(xoutVideo.input)
24# NEW – output queue straight from the node
25videoQueue = camRgb.video.createOutputQueue()
26
27# ORIG – entire `with dai.Device` block removed
28# with dai.Device(pipeline) as device:
29#   video = device.getOutputQueue(name="video", maxSize=1, blocking=False)
30#   while True:
31# NEW – start the pipeline
32pipeline.start()
33while pipeline.isRunning():
34    videoIn = videoQueue.get()  # blocking
35    cv2.imshow("video", videoIn.getCvFrame())
36    if cv2.waitKey(1) == ord('q'):
37        break

此示例在RVC2设备上运行。注意 ColorCamera/MonoCamera 节点在RVC4上已被弃用；请参见下一节使用 Camera 替代。

将 `ColorCamera` / `MonoCamera` 的使用迁移到 `Camera`

新的 Camera 节点可以根据需要暴露任意多个输出。

Python

1camRgb = pipeline.create(dai.node.ColorCamera)
2camRgb.setPreviewSize(300, 300)
3camRgb.setInterleaved(False)
4camRgb.setColorOrder(dai.ColorCameraProperties.ColorOrder.RGB)
5outputQueue = camRgb.preview.createOutputQueue()

转化为

Python

1camRgb = pipeline.create(dai.node.Camera).build()  # 不要忘记 .build()
2cameraOutput = camRgb.requestOutput((300, 300), type=dai.ImgFrame.Type.RGB888p)  # 替换 .preview
3outputQueue = cameraOutput.createOutputQueue()

只需再次调用 requestOutput 即可请求多个输出。对于之前使用 .isp 的全分辨率用例，请改用 requestFullResolutionOutput()。对于之前的 MonoCamera 管道，将 .out 输出替换为 requestOutput，例如

Python

1mono = pipeline.create(dai.node.Camera).build()
2monoOut = mono.requestOutput((1280, 720), type=dai.ImgFrame.Type.GRAY8)

将旧的 `ImageManip` 迁移到新 API

新 API 按顺序跟踪每次变换，并将最终图像的缩放方式分离出来。有关完整详情，请参阅官方文档。

v2 示例

Python

1#!/usr/bin/env python3
2
3import cv2
4import depthai as dai
5
6# Create pipeline
7pipeline = dai.Pipeline()
8
9camRgb = pipeline.create(dai.node.ColorCamera)
10camRgb.setPreviewSize(1000, 500)
11camRgb.setInterleaved(False)
12maxFrameSize = camRgb.getPreviewHeight() * camRgb.getPreviewWidth() * 3
13
14# In this example we use 2 imageManips for splitting the original 1000x500
15# preview frame into 2 500x500 frames
16manip1 = pipeline.create(dai.node.ImageManip)
17manip1.initialConfig.setCropRect(0, 0, 0.5, 1)
18manip1.setMaxOutputFrameSize(maxFrameSize)
19camRgb.preview.link(manip1.inputImage)
20
21manip2 = pipeline.create(dai.node.ImageManip)
22manip2.initialConfig.setCropRect(0.5, 0, 1, 1)
23manip2.setMaxOutputFrameSize(maxFrameSize)
24camRgb.preview.link(manip2.inputImage)
25
26xout1 = pipeline.create(dai.node.XLinkOut)
27xout1.setStreamName('out1')
28manip1.out.link(xout1.input)
29
30xout2 = pipeline.create(dai.node.XLinkOut)
31xout2.setStreamName('out2')
32manip2.out.link(xout2.input)
33
34# Connect to device and start pipeline
35with dai.Device(pipeline) as device:
36    # Output queue will be used to get the rgb frames from the output defined above
37    q1 = device.getOutputQueue(name="out1", maxSize=4, blocking=False)
38    q2 = device.getOutputQueue(name="out2", maxSize=4, blocking=False)
39
40    while True:
41        if q1.has():
42            cv2.imshow("Tile 1", q1.get().getCvFrame())
43
44        if q2.has():
45            cv2.imshow("Tile 2", q2.get().getCvFrame())
46
47        if cv2.waitKey(1) == ord('q'):
48            break

v3 等效代码：

Python

1#!/usr/bin/env python3
2
3import cv2
4import depthai as dai
5
6# Create pipeline
7pipeline = dai.Pipeline()
8
9camRgb = pipeline.create(dai.node.Camera).build()
10preview = camRgb.requestOutput((1000, 500), type=dai.ImgFrame.Type.RGB888p)
11
12# In this example we use 2 imageManips for splitting the original 1000x500
13# preview frame into 2 500x500 frames
14manip1 = pipeline.create(dai.node.ImageManip)
15manip1.initialConfig.addCrop(0, 0, 500, 500)
16preview.link(manip1.inputImage)
17
18manip2 = pipeline.create(dai.node.ImageManip)
19manip2.initialConfig.addCrop(500, 0, 500, 500)
20preview.link(manip2.inputImage)
21
22q1 = manip1.out.createOutputQueue()
23q2 = manip2.out.createOutputQueue()
24
25pipeline.start()
26with pipeline:
27    while pipeline.isRunning():
28        if q1.has():
29            cv2.imshow("Tile 1", q1.get().getCvFrame())
30
31        if q2.has():
32            cv2.imshow("Tile 2", q2.get().getCvFrame())
33
34        if cv2.waitKey(1) == ord('q'):
35            break

本页目录

DepthAI V3 迁移指南

v3 API 的新特性

最小必要更改

快速迁移：简单的 RGB 流示例

将 ColorCamera / MonoCamera 的使用迁移到 Camera

将旧的 ImageManip 迁移到新 API

v2 示例

v3 等效代码：

将 `ColorCamera` / `MonoCamera` 的使用迁移到 `Camera`

将旧的 `ImageManip` 迁移到新 API