Snaps

Snaps 允许您的应用程序可靠地将视觉数据（图像、视频、点云）和可选的注释发送到 Luxonis Hub。一旦数据被存储为 snaps，就可以对其进行浏览、过滤或下载，这使得 snaps 成为 Luxonis 应用程序中数据收集的主要构建块。有关 snaps 的更多信息，请参阅 Hub 的 snaps 页面。在底层，snaps 作为一种特殊的事件类型，通过 EventsManager 发送。不支持直接发送原始事件；作为 depthai 用户，您只能与 snaps 进行交互。

入门

要从您的应用程序发送 snaps，您首先需要创建并重用一个 EventsManager 实例。在典型的应用程序中，您需要：

创建一次 EventsManager（例如，在管道/设备设置旁边）。
在您的主应用程序类或上下文中保留对其的引用。
在您想要将视觉数据上传到 Luxonis Hub 时调用 sendSnap()。

每个 snap 都必须有一个定义的名称和至少一个关联的文件。可以包含以下参数：

参数	描述	示例
`Name`	snap 的主要标识符	`car_detected`, `gate_open`, `image`
`Files`	随 snap 上传的附件	`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`

Snap 限制

发送 snaps 时，请注意以下限制：

字段	规则
`Name`	1–56 个字符（必需）
`Files`	每个 snap 最多 20 个文件（最少 1 个必需）
`Tags`	最多 20 个标签；每个标签 1–56 个字符
`Extras`	最多 25 个条目；extras.key 1–40 个字符；extras.value 0–100 个字符

此外，如果文件上传超过 Luxonis Hub 强制执行的团队配额限制（可在 Hub 账单页面找到），则可能会被拒绝：

最大文件大小
剩余存储空间
文件上传的每小时限制（文件数量和带宽）
事件和 snaps 发送的每小时限制

注意：调用 sendSnap() 仅验证基本参数并将 snap 排队等待上传。它不能保证 snap 已发送到 Hub。 sendSnap() 在 snap 成功排队时返回本地 snap ID（字符串），在未成功排队时返回 None/nullopt。成功排队的 snap 并不确认已送达或文件已上传。要获得上传尝试完成时的通知，请将 successCallback 和 failureCallback 参数传递给 sendSnap()。

身份验证

如果您使用 oakctl 运行应用程序，身份验证将由您代表处理。您无需自行提供 API 密钥。对于 oakctl run-script，它使用您通过 oakctl hub login 登录的团队。对于 oakctl app run，它使用设备连接到的团队。要发送 snaps，必须定义您团队的 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 发送 Snaps

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

Python

1# 创建 EventsManager 实例
2eventMan = dai.EventsManager()
3
4# 发送包含 ImgFrame 和 ImgDetections 的 snap
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++

1// 创建 EventsManager 实例
2auto eventsManager = std::make_shared<dai::utility::EventsManager>();
3
4// 发送包含 ImgFrame 和 ImgDetections 的 snap
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 的快照，而省略 file 标签、detections、tags、extras 和 callbacks：

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

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（如果成功上传）、payload 或上传状态），请使用它们。

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

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)

发送快照 (C++)

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

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

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

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)

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

缓存

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

概述

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

启用缓存

要启用缓存，请在 EventsManager 实例上调用 setCacheIfCannotSend() 方法：

Python

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

C++

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

配置缓存目录

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

Python

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

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

1# 创建启用了 uploadCachedOnStart 的 EventsManager 实例
2eventMan = dai.EventsManager(uploadCachedOnStart=True)

C++

1// 创建启用了 uploadCachedOnStart 的 EventsManager 实例
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 中出现短暂延迟。如需增加批次频率，请联系支持部门。

本页目录

SnapsView as Markdown

入门

Snap 限制

身份验证

使用 ImgFrames 和 ImgDetections 发送 Snaps

Python

C++

Python

C++

退出前等待待处理上传

上传回调参数（可选）

Python

C++

发送快照 (python)

发送快照 (C++)

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

Python

C++

使用 FileGroup 发送快照 (python)

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

缓存

概述

启用缓存

Python

C++

配置缓存目录

Python

C++

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

Python

C++

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

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

Snaps