最后更新
入门
- 创建
EventsManager一次(例如,在您的管道/设备设置旁边)。 - 在您的主应用程序类或上下文中保留对其的引用。
- 每当您想将视觉数据上传到 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 |
快照限制
| 字段 | 规则 |
|---|---|
Name | 1–56 个字符(必填) |
Files | 每个快照最多 20 个文件(最少 1 个必填) |
Tags | 最多 20 个标签;每个 1–56 个字符 |
Extras | 最多 25 个条目;extras.key 1–40 个字符;extras.value 0–100 个字符 |
- 最大文件大小
- 剩余存储空间
- 文件上传的每小时限制(文件数量和带宽)
- 事件和快照发送的每小时限制
注意: 调用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 发送快照
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)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)退出前等待待处理的上传
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)发送快照 (python)
发送快照 (C++)
高级用法:使用 FileGroups 发送快照
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)使用 FileGroup 发送快照 (python)
使用 FileGroup 发送快照 (C++)
缓存
概述
sendSnap() 并且快照在多次重试后仍无法传递到 Hub 时,快照将被丢弃。如果您想在网络中断期间保留快照,可以启用本地缓存。启用后,上传失败的快照将存储在本地,并在连接恢复时重新传输。启用缓存
EventsManager 实例上调用 setCacheIfCannotSend() 方法:Python
Python
1# 创建 EventsManager 实例
2eventMan = dai.EventsManager()
3
4# 启用无法发送的快照的缓存
5eventMan.setCacheIfCannotSend(True)配置缓存目录
setCacheDir() 方法:Python
Python
1# 创建 EventsManager 实例
2eventMan = dai.EventsManager()
3
4# 启用缓存
5eventMan.setCacheIfCannotSend(True)
6
7# 设置自定义缓存目录
8eventMan.setCacheDir("/path/to/cache/directory")在应用程序启动时上传以前缓存的快照
EventsManager 时将 uploadCachedOnStart 标志设置为 true:Python
Python
1# 创建 EventsManager 实例,并启用 uploadCachedOnStart
2eventMan = dai.EventsManager(uploadCachedOnStart=True)uploadCachedOnStart 标志决定了缓存的快照是否在应用程序重新启动后仍然存在。如果未启用 uploadCachedOnStart(false 或未设置),并且本地存储中存在缓存数据,则在初始化 EventsManager 时会自动清除。为了在应用程序重新启动后保留缓存的快照并在下一次运行时将其上传到 Hub,您必须明确将 uploadCachedOnStart 设置为 true。否则,缓存数据将被删除。上传速率管理和上传优先级
- 您的应用程序可以继续发送新的快照,而不会被积压的缓存数据阻塞
- 不会超出 Hub 速率限制(每小时文件上传计数、带宽限制)
- 缓存的快照最终会上传,而不会降低实时数据收集
快照如何以及何时上传到 Hub?
FileGroup 实例或快照会分组在一个请求中。 批处理会定期发送(默认每 30 秒),这可能会导致快照出现在 Hub 中之前出现短暂延迟。 要增加批处理频率,请联系支持人员。