CloudSoftwareHardware
Software Stack
DepthAI
OAK Apps
AI Models
Troubleshooting

ON THIS PAGE

  • Snaps
  • Getting Started
  • Snap Limits
  • Authentication
  • Sending Snaps with ImgFrames and ImgDetections
  • Advanced Use: Sending Snaps using FileGroups
  • How and when are snaps uploaded to the Hub?

Snaps

Snaps let your application reliably send visual data (images, videos, pointclouds) and optional annotations to Luxonis Hub. Once stored as snaps, this data can be browsed, filtered, or downloaded, making snaps the primary building block for data collection in Luxonis apps. More information about snaps can be found on the Hub's snaps page.Under the hood, snaps are implemented as a special type of event sent via the EventsManager. Sending raw events directly is not supported; as a depthai user, you interact with snaps only.

Getting Started

To send snaps from your app, you first create and reuse a single EventsManager instance. In a typical application, you:
  1. Create the EventsManager once (for example, next to your pipeline / device setup).
  2. Keep a reference to it in your main application class or context.
  3. Call sendSnap() whenever you want to upload visual data to Luxonis Hub.
Each snap must have a defined name and at least one associated file. The following parameters can be included:
ParameterDescriptionExample
NameThe primary identifier for a snapcar_detected, gate_open, image
FilesAttachments uploaded with the snapImgFrame, ImgDetections
Tags (Optional)Additional filters for grouping and filteringdataset_collection, Dataset 1, Location 72, Assembly Line 17
Extras (Optional)Additional filters for grouping and filteringCar brand:volvo, State: open, Location: New York

Snap Limits

When sending snaps, be aware of the following limits:
FieldRule
Name1–56 characters (required)
FilesMax 20 files per snap (Min 1 required)
TagsMax 20 tags; each 1–56 characters
ExtrasMax 25 entries; extras.key 1–40 characters; extras.value 0–100 characters
Additionally, file uploads may be rejected if they exceed team quota limits enforced by the Luxonis Hub (which can be found on your Hub billing page):
  • Maximum file size
  • Remaining storage
  • Hourly limits for file uploads (number of files and bandwidth)
  • Hourly limits for events and snaps sent
Note: Calling sendSnap() only validates basic parameters and queues the snap for upload. It does not guarantee the snap has been sent to the Hub. A return value of true means the snap has been successfully added to the queue, but it does not confirm successful delivery nor successful file uploads.

Authentication

If you are using oakctl to run your application, the authentication is handled on your behalf. You do not provide an API key yourself.For oakctl run-script this uses the team you logged into using oakctl hub login. For oakctl app run this uses the team where the device is connected.To send snaps, your team's API Key must be defined. This is typically set using the environment variable DEPTHAI_HUB_API_KEY or inside your application using the EventsManager's setToken() method. When running in standalone mode and adopted to Hub, this environment variable is pre-populated.API Key good practices with practical examples can be found here.

Sending Snaps with ImgFrames and ImgDetections

This section demonstrates creating an EventsManager instance and using it to send snaps containing either a single image or an image with detections in a Luxonis DepthAI application.
Python
C++

Python

Python
1# Create the EventsManager instance
2eventMan = dai.EventsManager()
3
4# Send snap with ImgFrame and ImgDetections
5eventMan.sendSnap(
6    name="snap_name",
7    fileName="file_name",
8    imgFrame=inImgFrame,
9    imgDetections=inImgDetections,
10    tags=["examples", "python"],
11    extras={"confidence": "0.75", "location": "01"},
12    deviceSerialNo="serialNum"
13)
Some parameters in sendSnap() are optional. For example, you can send a snap with only a snap name and an ImgFrame, omitting the file name, detections, tags, and extras:
Python
C++

Python

Python
1# Create the EventsManager instance
2eventMan = dai.EventsManager()
3
4# Send snap with ImgFrame
5eventMan.sendSnap(
6    name="snap_name",
7    fileName=None,
8    imgFrame=inImgFrame,
9    imgDetections=None,
10    tags=[],
11    extras={},
12    deviceSerialNo=""
13)
Detailed examples of concrete use cases can be found in the following links:

Sending snaps (python)

GitHub logo

Sending snaps (C++)

GitHub logo

Advanced Use: Sending Snaps using FileGroups

In the examples above, a FileGroup is created automatically from the image (and detections) when using sendSnap(). You can also create a FileGroup explicitly. When sending a FileGroup, all included files are uploaded to the Luxonis Hub together. The group's upload will either fully succeed or fail, depending on your allocated storage capacity - it must be large enough to accommodate all files in the group.The example below demonstrates the same functionality using the FileGroup object explicitly. This approach involves creating a FileGroup instance and adding files to it. Common file pairs, such as ImgFrame and ImgDetections, can be added simultaneously, or separately as individual files. More information can be found in the FileGroup class documentation.
Python
C++

Python

Python
1# Create the EventsManager instance
2eventMan = dai.EventsManager()
3
4# Create the FileGroup instance
5fileGroup = dai.FileGroup()
6
7# Add files to fileGroup
8fileGroup.addImageDetectionsPair("file_name", inImgFrame, inImgDetections)
9
10# Send snap with the fileGroup
11eventMan.sendSnap(
12    name="snap_name",
13    fileGroup=fileGroup,
14    tags=["examples", "python"],
15    extras={"confidence": "0.75", "location": "01"},
16    deviceSerialNo="serialNum"
17)
Detailed examples of concrete use cases can be found in the following links:

Sending snaps using a FileGroup (python)

GitHub logo

Sending snaps using a FileGroup (C++)

GitHub logo

How and when are snaps uploaded to the Hub?

DepthAI uploads and sends events in batches, which means multiple FileGroup instances or snaps are grouped together in a single request. Batches are sent at regular intervals (by default every 30 seconds), which may cause a brief delay before snaps appear in the Hub. For increased batch frequency, please contact support.