DepthAI v2 has been superseded by DepthAI v3. You are viewing legacy documentation.
此页面由 AI 自动翻译。查看英文原版
最后更新
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

手动安装 DepthAI

最后更新
本指南将介绍设置 OAK 摄像头和 DepthAI 库的第一步。
  1. 安装依赖项
  2. 安装 DepthAI
  3. 运行 OAK Viewer

Ubuntu/Debian

执行以下命令安装所需的依赖项:
Command Line
1sudo wget -qO- /install_dependencies.sh | bash
这将执行以下操作:
  • 执行 apt 更新和升级
  • 安装 python3、pip3、cmake、git、udev(如果尚未安装)
  • 安装其他依赖项,如 libusb、libudev 等

MacOS

执行以下命令安装所需的依赖项:
Command Line
1curl -fL /install_dependencies.sh | bash
这将执行以下操作:
  • 安装 brew 和 git(如果尚未安装)

Windows 10/11

您可以通过 Windows 安装程序 安装要求,或使用 Chocolatey 包管理器手动安装:

通过 Chocolatey 安装

要安装 Chocolatey 并使用它来安装 DepthAI 的依赖项,请执行以下操作:
  • 右键单击“开始”
  • 选择 Windows PowerShell (管理员) 并运行以下命令:
Powershell
1Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
  • 关闭 PowerShell,然后重复前两个步骤重新打开另一个 PowerShell (管理员)。
  • 安装 Python 和 PyCharm
Powershell
1choco install cmake git python pycharm-community -y

Windows 7

尽管我们不正式支持 Windows 7,但社区成员已成功使用 Zadig 手动安装 WinUSB。连接 DepthAI 设备后,查找 USB ID 为 03E7 2485 的设备,并通过选择 WinUSB(v6.1.7600.16385) 然后 Install WCID Driver 来安装 WinUSB 驱动程序。

Docker

我们维护一个包含 DepthAI、其依赖项和有用工具的 Docker 镜像,位于 Docker Hub 上的 luxonis/depthai-library 仓库 中。它基于 luxonis/depthai-base 镜像构建。在 Linux 主机(使用 X11 窗口系统)上的 Docker 容器中运行 rgb_preview.py 示例:
Command Line
1docker pull luxonis/depthai-library
2docker run --rm \
3    --privileged \
4    -v /dev/bus/usb:/dev/bus/usb \
5    --device-cgroup-rule='c 189:* rmw' \
6    -e DISPLAY=$DISPLAY \
7    -v /tmp/.X11-unix:/tmp/.X11-unix \
8    luxonis/depthai-library:latest \
9    python3 /depthai-python/examples/ColorCamera/rgb_preview.py
要允许容器更新 X11,您可能需要在主机上运行 xhost local:root。

WSL 2

以下步骤在运行 Ubuntu 20.04 的 WSL 2 上执行,而主机运行 Win10 20H2 (OS build 19042.1586)。原始教程由 SputTheBot 在此处 编写。要在 WSL 2 上运行 OAK,您首先需要将 USB 设备连接到 WSL 2。我们为此使用了 usbipd-win (2.3.0)。在 WSL 2 内部,您还需要安装 depthai 依赖项(Ubuntu/Debian)和 USB/IP 客户端工具(2 条命令)。要将 OAK 摄像头连接到 WSL 2,我们准备了以下 Python 脚本,您需要在主机计算机上(以管理员模式)执行。
Python
1import time
2import os
3while True:
4    output = os.popen('usbipd wsl list').read() # 列出所有 USB 设备
5    rows = output.split('\n')
6    for row in rows:
7        if ('Movidius MyriadX' in row or 'Luxonis Device' in row) and 'Not attached' in row: # 检查未连接的 OAK 摄像头
8            busid = row.split(' ')[0]
9            out = os.popen(f'usbipd wsl attach --busid {busid}').read() # 连接 OAK 摄像头
10            print(out)
11            print(f'Usbipd attached Myriad X on bus {busid}') # 日志
12    time.sleep(.5)
之后,您可以在 WSL 2 中检查 lsusb 命令,您应该能够看到 Movidius MyriadX。如果您想使用 usbipd-win >= 4.0,那么 usbipd wsl 命令不再可用,因此您需要使用不同的脚本,最初由 kazuya 在此处 编写。
Python
1import time
2import subprocess
3
4while True:
5    output = subprocess.run('usbipd list', capture_output=True, encoding="UTF-8")
6    rows = output.stdout.split('\n')
7    for row in rows:
8        if ('Movidius MyriadX' in row or 'Luxonis Device' in row) and 'Not shared' in row:
9            busid = row.split(' ')[0]
10            out = subprocess.run(f'usbipd bind -b {busid}', capture_output=True, encoding="UTF-8")
11            print(out.stdout)
12            print(f'Usbipd bind Myriad X')
13        if ('Movidius MyriadX' in row or 'Luxonis Device' in row) and 'Shared' in row:
14            busid = row.split(' ')[0]
15            out = subprocess.run(f'usbipd attach -w -b {busid}', capture_output=True, encoding="UTF-8")
16            print(out.stdout)
17            print(f'Usbipd attached Myriad X on bus {busid}')
18    time.sleep(0.5)

OpenSUSE

对于 openSUSE,这篇官方文章 提供了如何在 openSUSE 平台上安装 OAK 设备的说明。

内核虚拟机 (KVM)

要在 内核虚拟机 中访问 OAK-D 摄像头,需要在主机检测到 USB 总线变化时动态连接和分离 USB 设备。当 DepthAI API 使用 OAK-D 摄像头时,它会更改 USB 设备类型。这在摄像头原生使用时在后台发生。但当摄像头在虚拟环境中使用时,情况就不同了。在您的主机上,使用以下代码:
Text
1SUBSYSTEM=="usb", ACTION=="bind", ENV{ID_VENDOR_ID}=="03e7", MODE="0666", RUN+="/usr/local/bin/movidius_usb_hotplug.sh depthai-vm"
2SUBSYSTEM=="usb", ACTION=="remove", ENV{PRODUCT}=="3e7/2485/1", ENV{DEVTYPE}=="usb_device", MODE="0666", RUN+="/usr/local/bin/movidius_usb_hotplug.sh depthai-vm"
3SUBSYSTEM=="usb", ACTION=="remove", ENV{PRODUCT}=="3e7/f63b/100", ENV{DEVTYPE}=="usb_device", MODE="0666", RUN+="/usr/local/bin/movidius_usb_hotplug.sh depthai-vm"
udev 规则调用的脚本 (movidius_usb_hotplug.sh) 应该将 USB 设备连接/分离到虚拟机。在这种情况下,我们需要调用 virsh 命令。例如,脚本可以执行以下操作:
Text
1#!/bin/bash
2# 发生错误时中止脚本执行
3set -e
4if [ "${ACTION}" == 'bind' ]; then
5  COMMAND='attach-device'
6elif [ "${ACTION}" == 'remove' ]; then
7  COMMAND='detach-device'
8  if [ "${PRODUCT}" == '3e7/2485/1' ]; then
9    ID_VENDOR_ID=03e7
10    ID_MODEL_ID=2485
11  fi
12  if [ "${PRODUCT}" == '3e7/f63b/100' ]; then
13    ID_VENDOR_ID=03e7
14    ID_MODEL_ID=f63b
15  fi
16else
17  echo "无效的 udev ACTION: ${ACTION}" >&2
18  exit 1
19fi
20echo "正在为 ${ID_VENDOR} 运行 virsh ${COMMAND} ${DOMAIN}。" >&2
21virsh "${COMMAND}" "${DOMAIN}" /dev/stdin <<END
22<hostdev mode='subsystem' type='usb'>
23  <source>
24    <vendor id='0x${ID_VENDOR_ID}'/>
25    <product id='0x${ID_MODEL_ID}'/>
26  </source>
27</hostdev>
28END
29exit 0
请注意,当设备从 USB 总线断开连接时,某些 udev 环境变量不可用(ID_VENDOR_ID 或 ID_MODEL_ID),这就是为什么您需要使用 PRODUCT 环境变量来识别哪个设备已断开连接。运行 DepthAI API 应用程序的虚拟机应该定义一个识别 OAK-D 摄像头的 udev 规则。udev 规则在此处描述。

VMware

在 VMware 中使用 OAK-D 设备需要一些额外的一次性设置才能使其工作。首先,确保 USB 控制器从 USB2 切换到 USB3。转到 虚拟机设置 -> USB 控制器 -> USB 兼容性 并更改为 USB 3.1(或对于较旧的 VMware 版本,更改为 USB 3.0,如果可用)。根据设备的状态,可能会显示两个设备,并且都需要路由到 VM。这些设备可能在 播放器 -> 可移动设备 中可见:
  • Intel Movidius MyriadX
  • Intel VSC Loopback Device 或 Intel Luxonis Device
在 Linux 操作系统中,运行这些命令以授予普通用户 USB 权限:
Command Line
1echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="03e7", MODE="0666"' | sudo tee /etc/udev/rules.d/80-movidius.rules
2sudo udevadm control --reload-rules && sudo udevadm trigger
如果虚拟机未检测到设备,请尝试以下操作:找到并选择类似 忘记连接规则 的选项(对于两个设备),然后尝试在 VM 中再次运行 DepthAI 示例。选择路由到 VM 并选择 不再询问(这很重要,因为存在超时,如果主机在几秒钟内未开始通信,设备看门狗可能会被触发)。您可能需要重复运行脚本几次,直到所有设置都为 VMware 正确设置。

VirtualBox

如果您想使用 VirtualBox 运行 DepthAI 源代码,请确保允许 VM 访问 USB 设备。此外,请注意,默认情况下,它仅支持 USB 1.1 设备,而 DepthAI 在两个阶段运行:
  1. 插入时显示。我们使用此端点将固件加载到设备上,这是一种 USB 引导技术。此设备是 USB2。
  2. 运行实际代码。这在 USB 引导后显示,是 USB3。
为了支持 DepthAI 模式,您需要下载并安装 Oracle VM VirtualBox Extension Pack。安装完成后,在 USB 设置中启用 USB3 (xHCI) 控制器。完成此操作后,您需要将 Myriad 作为 USB 设备从主机路由到 VBox。这是 depthai 尚未启动之前的过滤器,此时它是一个 USB2 设备:将尚未启动的 depthai 路由到 VirtualBox
将尚未启动的 depthai 路由到 VirtualBox
最后一步是添加 USB Intel Loopback 设备。depthai 设备通过 USB 引导其固件,并在引导后显示为新设备。此设备仅在 depthai/OAK 尝试重新连接时显示(在运行时,即在 depthai 上运行管道后,例如 python3 depthai_demo.py)。可能需要尝试几次才能使此环回设备显示并添加,因为您需要在 depthai 尝试在管道构建后连接时执行此操作(此时它已通过 USB2 引导其内部固件)。要仅启用一次,您可以在此处看到环回设备(在管道启动后):在您告诉 depthai 启动管道后立即找到环回设备,并选择它。
在您告诉 depthai 启动管道后立即找到环回设备,并选择它。
然后,为了永久启用此直通到 virtual box,请在以下设置中启用此功能: 为 depthai/OAK 创建 USB 环回设备,以允许已引导的设备在 virtualbox 中通信为 depthai/OAK 创建 USB 环回设备,以允许已引导的设备在 virtualbox 中通信
为 depthai/OAK 创建 USB 环回设备,以允许已引导的设备在 virtualbox 中通信
然后,对于您想要直通的每个额外的 depthai/OAK 设备,只需为每个单元重复此最后的环回设置步骤(因为每个单元都有其自己唯一的 ID)。
安装 depthai 依赖项后,您可以参考 depthai-core 进行 C++ 开发,或通过 PyPi 下载 depthai Python 库:
Command Line
1python3 -m pip install depthai

测试安装

我们有一组示例可以帮助您验证设置是否正确。首先,克隆 depthai-python 仓库并进入此仓库目录:
Command Line
1git clone https://github.com/luxonis/depthai-python.git
2cd depthai-python
接下来安装此仓库的要求。 请注意,我们建议在虚拟环境中安装依赖项,这样它们就不会干扰您系统上的其他 Python 工具/环境。
  • 对于 Mac/Windows/Ubuntu 等开发机器,我们推荐 PyCharm IDE,因为它会自动为您创建/管理虚拟环境,并提供许多其他好处。或者,可以直接使用 conda、pipenv 或 virtualenv(和/或与您首选的 IDE 一起使用)。
  • 对于 Raspberry Pi 或其他小型 Linux 系统等资源受限系统上的安装,我们推荐 conda、pipenv 或 virtualenv。要使用 virtualenv 设置虚拟环境,请运行 virtualenv venv && source venv/bin/activate。
使用虚拟环境(或者如果您愿意,也可以在系统范围内)运行以下命令以安装此示例仓库的要求:
Command Line
1cd examples
2python3 install_requirements.py
现在,从 examples 目录中运行 rgb_preview.py 脚本,以确保一切正常:
Command Line
1python3 ColorCamera/rgb_preview.py
如果一切顺利,将出现一个小型视频显示窗口。示例如下:

运行其他示例

运行此示例后,您可以运行其他示例以了解 DepthAI 的可能性。您还可以继续:
  • 我们的教程,从 Hello World 教程开始,逐步解释 API 用法(此处)
  • 我们的示例,包含 DepthAI 上各种用户用例的实现(此处)
您还可以继续阅读以下内容,了解如何转换您自己的神经网络以在 DepthAI 上运行。我们还有在线模型训练,向您展示如何训练和转换 DepthAI 模型:
OAK Viewer 是 DepthAI 和 OAK 摄像头的可视化工具。它是一个 GUI 应用程序,默认情况下会运行一个演示应用程序,该应用程序将可视化所有流并在设备上运行推理。它还允许您更改设备的配置。DepthAI Viewer 适用于 USB 和 POE 摄像头。更多信息此处。