此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 入门
  • 快照限制
  • 认证
  • 使用 ImgFrames 和 ImgDetections 发送快照
  • 退出前等待待处理的上传
  • 上传回调参数(可选)
  • 高级用法:使用 FileGroups 发送快照
  • 缓存
  • 概述
  • 启用缓存
  • 配置缓存目录
  • 在应用程序启动时上传以前缓存的快照
  • 上传速率管理和上传优先级
  • 快照如何以及何时上传到 Hub?
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新
快照允许您的应用程序可靠地发送视觉数据(图像、视频、点云)和可选注释到 Luxonis Hub。 一旦作为快照存储,这些数据可以被浏览、过滤或下载,使快照成为 Luxonis 应用程序中数据收集的主要构建块。 有关快照的更多信息,请参阅 Hub 的快照页面。在底层,快照是作为通过 EventsManager 发送的一种特殊类型的事件实现的。不支持直接发送原始事件;作为 DepthAI 用户,您只与快照交互。

入门

要从您的应用程序发送快照,您首先需要创建并重用一个 EventsManager 实例。在典型的应用程序中,您:
  1. 创建 EventsManager 一次(例如,在您的管道/设备设置旁边)。
  2. 在您的主应用程序类或上下文中保留对其的引用。
  3. 每当您想将视觉数据上传到 Luxonis Hub 时,调用 sendSnap()。
每个快照必须有一个定义的名称和至少一个关联文件。可以包含以下参数:
参数描述示例
Name快照的主要标识符car_detected、gate_open、image
Files随快照上传的附件ImgFrame、ImgDetections
Tags (可选)用于分组和过滤的附加过滤器dataset_collection、Dataset 1、Location 72、Assembly Line 17
Extras (可选)用于分组和过滤的附加过滤器Car brand:volvo、State: open、Location: New York
Success Callback (可选)成功上传尝试后调用的回调on_success
Failure Callback (可选)上传尝试失败后调用的回调on_failure

快照限制

发送快照时,请注意以下限制:
字段规则
Name1–56 个字符(必填)
Files每个快照最多 20 个文件(最少 1 个必填)
Tags最多 20 个标签;每个 1–56 个字符
Extras最多 25 个条目;extras.key 1–40 个字符;extras.value 0–100 个字符
此外,如果文件上传超出 Luxonis Hub 强制执行的团队配额限制(可在您的 Hub 账单页面上找到),则可能会被拒绝:
  • 最大文件大小
  • 剩余存储空间
  • 文件上传的每小时限制(文件数量和带宽)
  • 事件和快照发送的每小时限制
注意: 调用 sendSnap() 只验证基本参数并将快照排队等待上传。它不保证快照已发送到 Hub。 当快照成功排队时,sendSnap() 返回一个本地快照 ID(字符串),当未成功排队时,返回 None/nullopt。成功排队的快照不确认交付或文件上传。 要在上传尝试完成时收到通知,请将 successCallback 和 failureCallback 参数传递给 sendSnap()。

认证

如果您使用 oakctl 运行您的应用程序,则认证将由系统为您处理。您无需自己提供 API 密钥。对于 oakctl run-script,这使用您通过 oakctl hub login 登录的团队。 对于 oakctl app run,这使用设备连接到的团队。要发送快照,必须定义您的团队的 API 密钥。这通常通过使用 DEPTHAI_HUB_API_KEY 环境变量或在创建 EventsManager 实例时传递它来设置。 在独立模式下运行并适配到 Hub 时,DEPTHAI_HUB_API_KEY 会预填充。EventsManager 构造函数 API 密钥参数是可选的,未设置时默认为空字符串 ("")。 如果您在构造函数中传递非空 API 密钥,则使用它而不是 DEPTHAI_HUB_API_KEY。 仅当 DEPTHAI_HUB_API_KEY 未设置或您有意覆盖它时,才设置构造函数 API 密钥。API 密钥的最佳实践和实际示例可以在 此处找到。

使用 ImgFrames 和 ImgDetections 发送快照

本节演示如何在 Luxonis DepthAI 应用程序中创建 EventsManager 实例并使用它发送包含单个图像或带有检测的图像的快照。

Python

Python
1# 创建 EventsManager 实例
2eventMan = dai.EventsManager()
3
4# 发送带有 ImgFrame 和 ImgDetections 的快照
5localSnapID = eventMan.sendSnap(
6    name="snap_name",
7    fileTag="file_tag",
8    imgFrame=inImgFrame,
9    imgDetections=inImgDetections,
10    tags=["examples", "python"],
11    extras={"confidence": "0.75", "location": "01"},
12    successCallback=uploadSuccessCallback,
13    failureCallback=uploadFailureCallback
14)

C++

C++
1// 创建 EventsManager 实例
2auto eventsManager = std::make_shared<dai::utility::EventsManager>();
3
4// 发送带有 ImgFrame 和 ImgDetections 的快照
5auto localSnapID = eventsManager->sendSnap(
6    "snap_name",
7    "file_tag",
8    inImgFrame,
9    inImgDetections,
10    {"examples", "C++"},
11    {{"confidence", "0.75"}, {"location", "01"}},
12    uploadSuccessCallback,
13    uploadFailureCallback
14);
sendSnap() 中的某些参数是可选的。例如,您可以只使用快照名称和 ImgFrame 发送快照,省略文件标签、检测、标签、额外信息和回调:

Python

Python
1# 创建 EventsManager 实例
2eventMan = dai.EventsManager()
3
4# 发送带有 ImgFrame 的快照
5localSnapID = eventMan.sendSnap(
6    name="snap_name",
7    fileTag=None,
8    imgFrame=inImgFrame,
9    imgDetections=None,
10    tags=[],
11    extras={}
12)

C++

C++
1// 创建 EventsManager 实例
2auto eventsManager = std::make_shared<dai::utility::EventsManager>();
3
4// 发送带有 ImgFrame 的快照
5auto localSnapID = eventsManager->sendSnap(
6    "snap_name",
7    std::nullopt,
8    inImgFrame
9);

退出前等待待处理的上传

sendSnap() 将上传排队,然后这些上传在后台处理。如果 EventsManager 实例在上传仍在待处理时被销毁,则这些上传将被丢弃。在您的应用程序退出之前,调用 waitForPendingUploads(timeoutMs) 以在处理待处理上传时保持 EventsManager 处于活动状态。 timeoutMs 参数是可选的,默认为 0。值为 0 意味着调用将无限期等待,直到上传完成、连接断开或管理器停止。waitForPendingUploads(timeoutMs) 在所有待处理上传完成时返回 true。如果达到所选超时、连接断开或管理器停止,则返回 false。
注意: 当许多快照待处理(排队或缓存)时,此等待可能需要很长时间。

上传回调参数(可选)

sendSnap() 可以在上传尝试完成后调用可选的 successCallback 和 failureCallback 参数。如果您需要快照上传的确认或来自 SendSnapCallbackResult 的附加信息(例如其 Hub ID(如果成功上传)、有效负载或上传状态),请使用这些参数。

Python

Python
1# 定义可选的回调函数
2def uploadSuccessCallback(sendSnapResult):
3    print(f"成功上传快照:{sendSnapResult.snapName} 到 Hub。")
4
5def uploadFailureCallback(sendSnapResult):
6    print(f"快照:{sendSnapResult.snapName} 上传到 Hub 失败。")
7
8# 创建 EventsManager 实例
9eventMan = dai.EventsManager()
10
11# 发送带有 ImgFrame 和 ImgDetections 的快照
12localSnapID = eventMan.sendSnap(
13    name="snap_name",
14    fileTag="file_tag",
15    imgFrame=inImgFrame,
16    imgDetections=inImgDetections,
17    tags=["examples", "python"],
18    extras={"confidence": "0.75", "location": "01"},
19    successCallback=uploadSuccessCallback,
20    failureCallback=uploadFailureCallback
21)

C++

C++
1// 定义可选的回调函数
2void uploadSuccessCallback(const dai::utility::SendSnapCallbackResult sendSnapResult) {
3    std::cout << "成功上传快照:" << sendSnapResult.snapName <<
4    " 到 Hub。" << std::endl;
5}
6
7void uploadFailureCallback(const dai::utility::SendSnapCallbackResult sendSnapResult) {
8    std::cout << "快照:" << sendSnapResult.snapName <<
9    " 上传到 Hub 失败。" << std::endl;
10}
11
12// 创建 EventsManager 实例
13auto eventsManager = std::make_shared<dai::utility::EventsManager>();
14
15// 发送带有 ImgFrame 和 ImgDetections 的快照
16auto localSnapID = eventsManager->sendSnap(
17    "snap_name",
18    "file_tag",
19    inImgFrame,
20    inImgDetections,
21    {"examples", "C++"},
22    {{"confidence", "0.75"}, {"location", "01"}},
23    uploadSuccessCallback,
24    uploadFailureCallback
25);
具体用例的详细示例可以在以下链接中找到:

发送快照 (python)

GitHub 标志

发送快照 (C++)

GitHub 标志

高级用法:使用 FileGroups 发送快照

在上面的示例中,当使用 sendSnap() 时,FileGroup 会自动从图像(和检测)创建。您也可以显式创建 FileGroup。 发送 FileGroup 时,所有包含的文件都会一起上传到 Luxonis Hub。该组的上传将完全成功或失败,具体取决于您分配的存储容量——它必须足够大以容纳组中的所有文件。下面的示例演示了使用 FileGroup 对象显式实现相同功能。此方法涉及创建 FileGroup 实例并向其中添加文件。 常见的文件对,例如 ImgFrame 和 ImgDetections,可以同时添加,也可以作为单个文件单独添加。 更多信息可以在 FileGroup 类文档中找到。

Python

Python
1# 创建 EventsManager 实例
2eventMan = dai.EventsManager()
3
4# 创建 FileGroup 实例
5fileGroup = dai.FileGroup()
6
7# 将文件添加到 fileGroup
8fileGroup.addImageDetectionsPair("file_tag", inImgFrame, inImgDetections)
9
10# 使用 fileGroup 发送快照
11localSnapID = eventMan.sendSnap(
12    name="snap_name",
13    fileGroup=fileGroup,
14    tags=["examples", "python"],
15    extras={"confidence": "0.75", "location": "01"}
16)

C++

C++
1// 创建 EventsManager 实例
2auto eventsManager = std::make_shared<dai::utility::EventsManager>();
3
4// 创建 FileGroup 实例
5auto fileGroup = std::make_shared<dai::utility::FileGroup>();
6
7// 将文件添加到 fileGroup
8fileGroup->addImageDetectionsPair("file_tag", inImgFrame, inImgDetections);
9
10// 使用 fileGroup 发送快照
11auto localSnapID = eventsManager->sendSnap(
12    "snap_name",
13    fileGroup,
14    {"examples", "C++"},
15    {{"confidence", "0.75"}, {"location", "01"}}
16);
具体用例的详细示例可以在以下链接中找到:

使用 FileGroup 发送快照 (python)

GitHub 标志

使用 FileGroup 发送快照 (C++)

GitHub 标志

缓存

将快照发送到 Luxonis Hub 时,网络连接是一个关键依赖项。然而,DepthAI 提供了强大的缓存机制,以确保视觉数据不会因临时网络中断或连接失败而丢失。本节解释了如何配置和使用快照缓存。

概述

默认情况下,当调用 sendSnap() 并且快照在多次重试后仍无法传递到 Hub 时,快照将被丢弃。如果您想在网络中断期间保留快照,可以启用本地缓存。启用后,上传失败的快照将存储在本地,并在连接恢复时重新传输。

启用缓存

要启用缓存,请在您的 EventsManager 实例上调用 setCacheIfCannotSend() 方法:

Python

Python
1# 创建 EventsManager 实例
2eventMan = dai.EventsManager()
3
4# 启用无法发送的快照的缓存
5eventMan.setCacheIfCannotSend(True)

C++

C++
1// 创建 EventsManager 实例
2auto eventsManager = std::make_shared<dai::utility::EventsManager>();
3
4// 启用无法发送的快照的缓存
5eventsManager->setCacheIfCannotSend(true);

配置缓存目录

默认情况下,缓存的快照存储在默认目录中。要为缓存指定自定义位置,请使用 setCacheDir() 方法:

Python

Python
1# 创建 EventsManager 实例
2eventMan = dai.EventsManager()
3
4# 启用缓存
5eventMan.setCacheIfCannotSend(True)
6
7# 设置自定义缓存目录
8eventMan.setCacheDir("/path/to/cache/directory")

C++

C++
1// 创建 EventsManager 实例
2auto eventsManager = std::make_shared<dai::utility::EventsManager>();
3
4// 启用缓存
5eventsManager->setCacheIfCannotSend(true);
6
7// 设置自定义缓存目录
8eventsManager->setCacheDir("/path/to/cache/directory");

在应用程序启动时上传以前缓存的快照

当您的应用程序重新启动时,以前缓存的快照(如果有)可以在下一次应用程序运行时自动上传到 Hub。要启用此行为,请在构造 EventsManager 时将 uploadCachedOnStart 标志设置为 true:

Python

Python
1# 创建 EventsManager 实例,并启用 uploadCachedOnStart
2eventMan = dai.EventsManager(uploadCachedOnStart=True)

C++

C++
1// 创建 EventsManager 实例,并启用 uploadCachedOnStart
2auto eventsManager = std::make_shared<dai::utility::EventsManager>("", true);
uploadCachedOnStart 标志决定了缓存的快照是否在应用程序重新启动后仍然存在。如果未启用 uploadCachedOnStart(false 或未设置),并且本地存储中存在缓存数据,则在初始化 EventsManager 时会自动清除。为了在应用程序重新启动后保留缓存的快照并在下一次运行时将其上传到 Hub,您必须明确将 uploadCachedOnStart 设置为 true。否则,缓存数据将被删除。

上传速率管理和上传优先级

缓存的快照会与新添加的快照一起逐步上传,新添加的快照在上传队列中具有优先权。DepthAI 并非尽可能快地上传缓存的快照,而是有意限制上传速率,以遵守 Luxonis Hub 强制执行的上传限制和配额配置。这种方法确保:
  • 您的应用程序可以继续发送新的快照,而不会被积压的缓存数据阻塞
  • 不会超出 Hub 速率限制(每小时文件上传计数、带宽限制)
  • 缓存的快照最终会上传,而不会降低实时数据收集
随着您的应用程序继续生成新的快照,缓存的快照会在后台逐步上传,从而允许从网络中断中恢复,而不会中断正常操作或违反 Hub 限制。

快照如何以及何时上传到 Hub?

DepthAI 以批处理方式上传和发送事件,这意味着多个 FileGroup 实例或快照会分组在一个请求中。 批处理会定期发送(默认每 30 秒),这可能会导致快照出现在 Hub 中之前出现短暂延迟。 要增加批处理频率,请联系支持人员。