Using processing results from the TraceVision API

First, you need a processed video. If you need to make one, head here for a walk through.

You'll need the API URL and your credentials. Not sure where to find them? We've got you .

• Try https://studio.apollographql.com/sandbox/explorer for exploring the API
• Check out our public repo , which has sample code in Python for creating sessions to process video and using processing results
• Our public repo also has Postman resources (but seriously, try the sandbox first, because it's built for graphQL).

Query the sessionResult to retrieve tracking and highlights results. You'll get a SessionResult back.

Let's use this to do something cool. Maybe make some video overlays, or cut a highlight reel?

The SessionResult contains objects which contain all the tracking data.

Let's assume you've created a soccer_game session. (If you're processing retail or security footage, head here .) The objects are all the players identified by team and jersey number during the uploaded footage.

objects have:

• object_id , a global ID for the object. For players in a soccer game, this is typically of the form "team-jersey number", e.g. "home-1" or "away-12".
• type , the object type. For a soccer game, this could be "player" or "ball".
• side , the object side, or players' team association. For a soccer game this could be "home" or "away".
• tracking_url , the URL where tracking data can be downloaded.

The tracking data itself is stored in JSON format. These files are typically a few MB, so we offer URLs to download them rather than returning them in the query response. You can download the JSON file for each player from the tracking_url using a GET request.

The JSON format is a list of tracking data in the format [time_off, x, y, w, h] . For each tracking point:

• time_off - time offset after the video start time, in milliseconds
• x - horizontal coordinate of the track bounding box center
• y - vertical coordinate of the track bounding box center
• w - width of the track bounding box
• h - height of the track bounding box

Note that x , y , w and h are given in scaled units (0-1000) relative to the video frame size. Here's some sample code for converting from scaled units to pixel units:

Now what? Well, now you know where that player is in the video whenever they're identifiable. This can power features like:

• Drawing a box around the player when they're identifiable. Or, get fancy and make a nice ring overlay or arrow, video game style.
• Zooming in on the player in post-production by using a moving crop to follow the player around
• Creating images or graphics that feature a zoomed in crop of the player
• Or something we haven't thought of!

If you'd like some code samples to help you get started with using tracking data, check out our public repo .

The SessionResult also contains highlights which contain all the highlights found in the footage.

Let's keep assuming you've created a soccer_game session. The highlights are all the touches and passing chains found in the uploaded footage.

highlights have:

• highlight_id , the ID of the highlight in the TraceVision system.
  • You can probably ignore this for now
• video_id , ID of the video where the highlight was found.
  • Again, you can probably ignore this for now
• start_offset , the offset of the start of the highlight in in milliseconds after the video start time.
  • For example, if the video start time is 2024-02-14T10:47:21Z , and the start_offset is 1000, then the highlight starts at 2024-02-14T10:47:22Z .
• duration , the duration of the highlight in milliseconds.
• objects , the list of detected objects in the highlight. We're assuming a soccer game, so these are the players we identified during the footage.
  • Take a look at tracking above which explains more about objects
• tags , the list of the tags for the highlight excluding the detected objects.
  • For soccer games, you'll see tags like touch and touch-chain
    • A touch is an event where a player "has the ball"
    • A touch-chain is a sequence of these events for players on the same team
    • These are the only types of events currently available
  • We create highlights for each team separately, so the team (home or away ) is also listed
  • If we identified a player involved in the highlight, you will see their ID here too (e.g. home-7 , away-23 )
• video_stream , the URL for the video stream containing the highlight, if available.

Okay, so now you know when highlights were found in the video, and who's involved if they're identifiable. This can power features like:

• Creating a highlight reel for a team (filter the list of highlights on the home or away team)
• Creating a highlight reel for a specific player (filter on their ID)
• Also adding overlays or zoom for particular identified players using their tracking data
• Or some combination, or something totally different!

If you'd like some code samples to help you get started with using highlights, check out our public repo .