Python API安装详解

关于安装、升级和使用 DepthAI Python API 的说明。

支持的平台

DepthAI API python 模块是为 Ubuntu, MaxOS 和 Windows 预制的。 对于其他操作系统或 Python 版本,可以 从源码编译 DepthAI。.

安装系统依赖

运行 DepthAI 库需要几个基本的系统依赖。 它们中的大多数应该已经安装在大多数系统中,但是如果没有安装, 我们准备了一个 安装脚本 ,这将确保安装了所有依赖项以及方便的开发/编程工具。还有适用于 macOS ( 此处 ),Raspberry Pi ( 此处 ), Ubuntu( 此处 )和 Windows 10( 此处 )的视频指南。

macOS

bash -c "$(curl -fL https://cdn.jsdelivr.net/gh/OAKChina/depthai-docs-website@develop/source/_static/install_dependencies.sh)"

执行此命令后,关闭并重新打开终端窗口。

该脚本还可以在 M1 Mac 上运行,并且在 Rosetta 2 下安装了 Homebrew,因为某些 Python 软件包仍缺少对M1的原生支持。如果您已经在本地安装了 Homebrew 并且无法正常工作,请参见 此处 以了解其他一些疑难解答步骤。

请注意,如果未出现视频流窗口,请考虑运行以下命令:

python3 -m pip install opencv-python --force-reinstall --no-cache-dir

有关更多信息,请参见我们论坛上的 macOS 视频预览窗口未能出现 话题讨论。

Raspberry Pi OS

sudo curl -fL https://cdn.jsdelivr.net/gh/OAKChina/depthai-docs-website@develop/source/_static/install_dependencies.sh | bash

Ubuntu

sudo wget -qO- https://cdn.jsdelivr.net/gh/OAKChina/depthai-docs-website@develop/source/_static/install_dependencies.sh | bash

openSUSE

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

Windows

  • 右键单击开始按钮

  • 选择 Windows PowerShell (管理员)

  • 安装 Chocolatey 软件包管理器(类似于 macOS 的 Homebrew):

Set-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

choco install cmake git python pycharm-community -y

启用 USB 设备(仅在 Linux 上)

由于 DepthAI 是 USB 设备,因此为了在使用 udev 工具的系统上与之通信, 您需要添加 udev 规则以使设备可访问。

以下命令将向您的系统添加新的 udev 规则

Warning

提示:

第一次使用一定要配置此规则!

第一次使用一定要配置此规则!

第一次使用一定要配置此规则!

echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="03e7", MODE="0666"' | sudo tee /etc/udev/rules.d/80-movidius.rules
sudo udevadm control --reload-rules && sudo udevadm trigger

从 PyPi 安装

我们的软件包是 通过 PyPi 分发的,为了可以在您的环境中安装,请使用

python3 -m pip install depthai

有关其他安装选项,请参阅 其他安装选项

镜像加速

pypi 镜像使用帮助

临时使用

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple some-package

注意,simple 不能少, 是 https 而不是 http

设为默认

  • 使用命令行

升级 pip 到最新的版本 (>=10.0.0) 后进行配置:

pip install pip -U
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

如果您的 pip 默认源的网络连接较差,临时使用镜像站来升级 pip:

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple pip -U
  • 文本编辑

Pip 的配置文件为用户根目录下的:~/.pip/pip.conf(Windows 路径为:C:\Users\<UserName>\pip\pip.ini), 您可以配置如下内容:

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
timeout = 120

Ubuntu 镜像使用帮助

备份配置文件:

sudo cp -a /etc/apt/sources.list /etc/apt/sources.list.bak

修改 sources.list 文件

sudo sed -i "s@http://.*archive.ubuntu.com@https://mirrors.tuna.tsinghua.edu.cn@g" /etc/apt/sources.list
sudo sed -i "s@http://.*security.ubuntu.com@https://mirrors.tuna.tsinghua.edu.cn@g" /etc/apt/sources.list

更新索引

sudo apt-get update

GitHub 镜像使用帮助

FastGit 是一个适用于 GitHub 的加速服务,fgit 一个在克隆项目时自动把 GitHub 链接替换为 FastGit 链接的工具。

如何使用?

  • Linux

sudo curl -L https://github.com/fastgh/fgit/releases/download/v1.0.0/fgit.linux -o /usr/local/bin/fgit
sudo chmod +x /usr/local/bin/fgit
  • Mac

sudo curl -L https://github.com/fastgh/fgit/releases/download/v1.0.0/fgit.darwin -o /usr/local/bin/fgit
sudo chmod +x /usr/local/bin/fgit
  • Windows

https://github.com/fastgh/fgit/releases/download/v1.0.0/fgit.exe 下载后把它加入系统路径环境变量

Homebrew 镜像使用帮助

注:该镜像是 Homebrew 源程序以及 formula/cask 索引的镜像(即 brew update 时所更新内容)。

首次安装 Homebrew

  • 首先,需要确保系统中安装了 bash、git 和 curl,对于 macOS 用户需额外要求安装 Command Line Tools (CLT) for Xcode。

# 在命令行输入 xcode-select --install 安装 CLT for Xcode 即可
xcode-select --install
  • 接着,在终端输入以下两行命令设置环境变量:

# macOS 用户,请使用以下两句命令
export OMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"

export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"
  • 最后,在终端运行以下命令以安装 Homebrew / Linuxbrew:

# 从镜像下载安装脚本,修改其中的仓库源并安装 Homebrew
git clone --depth=1 https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/install.git brew-install

/bin/bash -c "$(sed 's|^HOMEBREW_BREW_GIT_REMOTE=.*$|HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"|g' brew-install/install.sh)"

rm -rf brew-install

# 也可从 GitHub 获取官方安装脚本,修改其中的仓库源,运行以安装 Homebrew / Linuxbrew
/bin/bash -c "$( curl -fsSL https://github.com/Homebrew/install/raw/master/install.sh | sed 's|^HOMEBREW_BREW_GIT_REMOTE=.*$|HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"|g' )"

这样在首次安装的时候也可以使用镜像。

替换现有仓库上游

替换 brew 程序本身的源:

git -C "$(brew --repo)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git

以下针对 macOS 系统上的 Homebrew:

# 手动设置
git -C "$(brew --repo homebrew/core)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git
git -C "$(brew --repo homebrew/cask)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask.git
git -C "$(brew --repo homebrew/cask-fonts)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask-fonts.git
git -C "$(brew --repo homebrew/cask-drivers)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask-drivers.git
git -C "$(brew --repo homebrew/cask-versions)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask-versions.git

# 使用脚本
bash -c "$(curl -fL https://cdn.jsdelivr.net/gh/OAKChina/depthai-docs-website@develop/source/_static/replace_existing_upstream.sh)"

更换上游后需重新设置 git 仓库 HEAD:

brew update-reset

Homebrew-bottles 镜像使用帮助

注:该镜像是 Homebrew 二进制预编译包的镜像。

临时使用

export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles

设为默认

  • 如果你使用 bash:

echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles' >> ~/.bashrc
source ~/.bashrc
  • 如果你使用 zsh:

echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles' >> ~/.zshrc
source ~/.zshrc

测试安装

我们在 GitHub 上有 depthai 存储库, 其中包含许多有用的示例和准备好的神经网络, 您可以使用它们来加快原型制作速度。它还包括由我们的贡献者维护的测试脚本, 该脚本应有助于您验证设置是否正确。

首先,克隆 depthai 存储库,并将目录更改为该目录:

git clone https://github.com/luxonis/depthai.git
cd depthai

接下来是安装此仓库的要求。请注意,我们建议将依赖项安装在虚拟环境中,以免它们干扰系统上的其他Python工具/环境。

  • 对于 Mac / Windows / Ubuntu 等开发工具,我们建议使用 PyCharm IDE,因为它会自动为您创建和管理虚拟环境,以及许多其他好处。可替代的有: conda , pipenv 或者 virtualenv 可以直接使用(或用您的首选IDE)。

  • 有关资源受限的系统,如树莓派或其他小型Linux系统的安装,我们建议 conda , pipenv 或者 virtualenv 中的一个。要使用 virtualenv 设置虚拟环境,请运行 virtualenv venv && source venv/bin/activate

使用虚拟环境(或者如果需要在整个系统范围内),运行以下命令以安装此示例存储库的依赖:

python3 install_requirements.py

现在,从 DepthAI 内部运行演示脚本,以确保一切正常:

python3 depthai_demo.py

如果一切顺利的话,会弹出一个小视频窗口。 如果画面中的物体属于 物体检测示例 20 类 中的某一类,画面上会叠加该物体的信息。

运行其他示例

运行此演示之后,您可以运行 python3 depthai_demo.py -h 来查看默认情况下可以运行的其他神经网络。

检查完之后,继续执行以下操作:

  • 我们的教程,如何使用 OpenVINO 的预训练模型, 此处

  • 我们的实验性示例,在 这里 可以学习更多使用 DepthAI 的方法。

您还可以在下面继续学习如何转换自己的神经网络以在DepthAI上运行。

另外,我们还在下面提供了在线模型训练,该演示向您展示了如何为 DepthAI 训练和转换模型。

  • 在线机器学习训练和模型转换: 此处

准备 MyriadX blob 文件和它的配置文件

正如你在 本例 中所看到的,Device.create_pipeline() 方法的基本用法包括指定所需的输出流和 AI 部分,在其中指定 MyriadX blob 及其配置。

在本节中,我们将介绍如何同时获取 blob_fileblob_file_config

获取 MyriadX Blob

由于我们使用的是 MyriadX VPU, 您的模型需要被编译(或准确地进行优化和转换)为 MyriadX Blob 文件,然后将其发送到设备并执行。

最简单的方法是使用我们的在线 BlobConverter应用程序 来获取这个 blob 文件。 它有编译所需的所有工具, 所以你不需要设置任何东西–你甚至可以从 OpenVINO模型Zoo 下载一个模型的 blob。

如果你愿意,你也可以自己编译 blob。 你需要安装 OpenVINO 工具包, 然后使用 Model OptimizerMyriad Compiler 来获得 MyriadX blob。 我们已经在 这里 记录了这些编译器的使用实例。

创建 Blob 配置文件

如果未提供配置文件或将 output_format 设置为 raw, 则设备上不会进行解码,用户必须在主机端手动进行解码。

当前支持在设备上对基于 Mobilenet-SSD(tiny-)YOLO-v3 的网络进行解码。 对于该配置文件,需要使用网络特定的参数。

tiny-yolo-v3 网络示例:

{
    "NN_config":
    {
        "output_format" : "detection",
        "NN_family" : "YOLO",
        "NN_specific_metadata" :
        {
            "classes" : 80,
            "coordinates" : 4,
            "anchors" : [10,14, 23,27, 37,58, 81,82, 135,169, 344,319],
            "anchor_masks" :
            {
                "side26" : [1,2,3],
                "side13" : [3,4,5]
            },
            "iou_threshold" : 0.5,
            "confidence_threshold" : 0.5
        }
    },
    "mappings":
    {
        "labels":
        [
            "person",
            "bicycle",
            "car",
            "..."
        ]
    }
}
  • NN_config - 网络配置
    • output_format
      • "detection" - 设备上完成解码, 接收到的数据包为 Detections 格式

      • "raw" - 在主机上完成解码

    • NN_family - “YOLO”“mobilenet”

    • NN_specific_metadata - 仅用于 “YOLO”
      • classes - classes 数量

      • coordinates - coordinates 数量

      • anchors - YOLO 网络的锚点

      • anchor_masks - 每个输出层的锚定遮罩 : 26x26, 13x13 (+ 52x52 for full YOLO-v3)

      • iou_threshold - 检测到的对象的联合阈值交集

      • confidence_threshold - 检测物体的得分置信度阈值

  • mappings.labels - 使用 depthai_demo.py 脚本来解码ID的标签

output_format 设置为 detection 时的解码示例:

nnet_packets, data_packets = p.get_available_nnet_and_data_packets()

for nnet_packet in nnet_packets:
  in_layers = nnet_packet.getInputLayersInfo()

  input_width  = in_layers[0].get_dimension(depthai.TensorInfo.Dimension.W)
  input_height = in_layers[0].get_dimension(depthai.TensorInfo.Dimension.H)

  detections = nnet_packet.getDetectedObjects()
  objects = list()

  for detection in detections:
      detection_dict = detection.get_dict()
      # 将标准化坐标缩放为图像坐标
      detection_dict["x_min"] = int(detection_dict["x_min"] * input_width)
      detection_dict["y_min"] = int(detection_dict["y_min"] * input_height)
      detection_dict["x_max"] = int(detection_dict["x_max"] * input_width)
      detection_dict["y_max"] = int(detection_dict["y_max"] * input_height)
      objects.append(detection_dict)

print(objects)

主机和设备上基于完整 yolo-v3tiny-yolo-v3 的解码示例在 此处

主机和设备上基于 mobilenet 的网络的解码示例在 此处

其他安装方式

要从我们的源代码中获取最新但尚未发布的功能,您可以继续手动编译 DepthAI 软件包。

从源构建的依赖项

  • CMake > 3.2.0

  • 生成工具 (Ninja, make, …)

  • C/C++ 编译器

  • libusb1 开发包

Ubuntu, Raspberry Pi OS, … (基于 Debian 的系统)

在基于 Debian 的系统 (Raspberyy Pi OS, Ubuntu, …)上,可以通过运行以下命令获取安装依赖:

sudo apt-get -y install cmake libusb-1.0-0-dev build-essential

macOS (Mac OS X)

假设安装了 Mac OS X , 则 depthai-python 库需要以下依赖项

  • HomeBrew (如果尚未安装)

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
    
  • Python, libusb, CMake, wget

    brew install coreutils python3 cmake libusb wget
    

现在你已经准备好克隆 depthai-python ,并在 Mac OSX 上构建。

使用 GitHub commit 进行安装

Pip 允许用户从特定的 commit 安装软件包,即使它们尚未在 PyPi 上发布。

为此,请使用以下命令 - 并确保使用正确的 commit hash 替换 <commit_sha>

python3 -m pip install git+https://github.com/luxonis/depthai-python.git@<commit_sha>

使用/测试特定的 分支/PR

有时,使用特定分支可能会引起您的注意。 例如,这可能是因为我们已经听取了您的功能要求并在分支中实现。 或者可能是出于稳定性目的,在合并到 main 中之前,在 develop 中实现。

因此,当在 depthai 存储库中工作时, 可以通过以下命令来使用分支。 在此示例中, 我们将尝试使用 develop 分支 (这是在将新功能合并到 main 之前我们用来吸收新功能的分支):

在运行以下命令之前, 您可以独立克隆存储库 (以免覆盖任何本地更改) 也可以先执行 git pull

git checkout develop
python3 install_requirements.py

从源安装

如果需要,您还可以从源代码本身安装该软件包 - 它将允许您对 API 进行更改,并看到它们的实际操作。

为此,请先下载存储库,然后在开发模式下将该包添加到您的 python 解释器中

git clone https://github.com/luxonis/depthai-python.git
cd depthai-python
git submodule update --init --recursive
python3 setup.py develop  # 如果使用系统解释器而不是虚拟环境,则可能需要添加sudo

如果您要使用默认(main)以外的其他分支(e.g. develop), 可以通过键入

git checkout develop  # replace the "develop" with a desired branch name
git submodule update --recursive
python3 setup.py develop

或者,如果您要使用特定的 commit,请键入

git checkout <commit_sha>
git submodule update --recursive
python3 setup.py develop

有疑问?

我们很乐意为您提供代码或其他问题的帮助。