# OAK 应用概述

OAK 应用 让您能够开发、容器化、部署和管理容器化视觉应用，覆盖从单台设备到设备集群的 Luxonis OAK 设备。

它们运行在 OAK4 设备上预装的 oak-agent 服务中（属于 [Luxonis OS](https://docs.luxonis.com/software-v3/sw-stack/luxonis-os.md) 的一部分），因此您可以立即开始部署。

## 什么是 OAK 应用？

OAK 应用是构建在 DepthAI 框架之上的容器化计算机视觉应用，直接运行在 OAK 设备上。它们提供：

 * 一致的开发环境 - 构建一次，随处部署
 * 简化的部署流程 - 打包应用所需的一切
 * 设备集群管理 - 同时部署到多台设备
 * 与 Luxonis Hub 集成 - 远程监控和管理设备

需要特别说明的是，应用一旦构建完成（即生成了 .oakapp 文件），您就可以将其迁移并安装到其他设备上，无需重新构建或依赖网络连接。

### 默认应用演示

查看预构建的默认应用，预览一个完整的 OAK 应用可能会是什么样子。

[在 GitHub 上查看](https://github.com/luxonis/oak-examples/tree/main/apps/default-app)

## 创建您的 OAK 应用

#### Project Structure

一个基本的 OAK 应用项目结构：

```text
my-oak-app/
├── .oakappignore      # （可选）在设备上构建应用时要忽略的文件
├── main.py            # 您的主要应用代码
├── requirements.txt   # Python 依赖项
└── oakapp.toml        # 应用配置
```

oakapp.toml 文件是必需的，包含应用元数据和构建指令。

#### App Development

创建 OAK 应用始于 DepthAI API，这是驱动所有 OAK 设备能力的核心框架：

```bash
# 安装 DepthAI SDK
pip install depthai --force-reinstall

# 使用 DepthAI 的 Python API 创建您的应用
# - 访问摄像头流
# - 运行神经网络推理
# - 处理深度数据
# - 利用边缘处理能力
```

## 使用 oakctl 部署

oakctl 是一个命令行工具，允许您与 OAK4 摄像头进行交互。它可用于在运行 oak-agent 服务的设备上创建、部署和管理应用。

#### Linux/MacOS

在 64 位系统上，运行：

```bash
bash -c "$(curl -fsSL https://oakctl-releases.luxonis.com/oakctl-installer.sh)"
```

#### Windows

下载并使用 [Windows 安装程序](https://oakctl-releases.luxonis.com/data/latest/windows_x86_64/oakctl.msi) 进行安装。

### 操作系统兼容性表

| RVC4 OS 版本 | oakctl 版本 | 命令 |
| --- | --- | --- |
| OS 1.14.1+ | 0.11.0+ | `oakctl self-update`（当前稳定版） |
| OS 1.11 | 0.9.0 | `oakctl self-update -v 0.9.0` |
| OS 1.8 | 0.4.2 | `oakctl self-update -v 0.4.2` |
| OS 1.6 | 0.2.11 | `oakctl self-update -v 0.2.11` |

### 构建和运行应用

使用 oakctl 构建和运行 OAK 应用非常简单：

```bash
# 直接从源代码运行应用
oakctl app run ./my-oak-app

# 将应用构建为可分发的包
oakctl app build ./my-oak-app

# 安装已构建的应用
oakctl app install my-oak-app.oakapp
```

### 应用管理

您可以使用以下命令管理应用：

```bash
# 列出已安装的应用
oakctl app list

# 启动应用
oakctl app start <container-id>

# 查看应用日志
oakctl app logs <container-id>

# 停止应用
oakctl app stop <container-id>

# 启用自动启动
oakctl app enable <container-id>
```

## 设备管理

```bash
# 列出连接的设备
oakctl list

# 连接到特定设备
oakctl connect <device-ip>
```

## oakapp.toml 配置

oakapp.toml 文件定义了您应用的构建和运行时配置：

```toml
# (必需) 应用标识符
identifier = "com.luxonis.python_demo"
# (必需) 应用入口点
entrypoint = ["bash", "-c", "python3 /app/main.py"]

# (可选) 准备容器命令
# 这里是您可以在运行时安装所有依赖的地方
prepare_container = [
    { type = "COPY", source = "requirements.txt", target = "requirements.txt" },
    { type = "RUN", command = "apt-get update" },
    { type = "RUN", command = "apt-get install -y python3-pip" },
    { type = "RUN", command = "pip3 install -r /app/requirements.txt --break-system-packages" },
]

# (可选) 准备构建依赖
# 这里是您可以在构建时安装所有依赖的地方
prepare_build_container = [
    # 示例: npm, gcc, ...
]

# (可选) 所有应用程序文件复制到容器后的附加命令
build_steps = []
```

查看 [完整参考](https://docs.luxonis.com/software-v3/oak-apps/configuration.md) 以了解所有可用的配置选项。