Type III: Track Interaction

Type III checks evaluate whether a track had interactions with other tracked objects. Interactions are detected by the state machine based on bounding box overlap and proximity, and this node applies tag filtering and threshold conditions.

When to use

Use Type III for any use case where the core question is “did this object interact with that type of object?”:

Safety near-miss — person within dangerous proximity of a forklift
Equipment interaction — two specific vehicle types overlapping
Congestion interaction — tracks of the same type clustering together
Escort compliance — vehicle must be accompanied by a person

How it works

The node reads the track’s interactions array (populated by the state machine in batch mode)
It matches the primary tag (current track’s object type) against configured groups
For matching groups, it checks the secondary tag (interacting track’s object type)
If both tags match, it evaluates threshold conditions (overlap, duration, distance)
The check passes if at least one interaction meets all enabled thresholds

Tag matching

Type III uses a two-tag system:

Tag	Description	Example
Primary tag	The object type of the current track	`person`
Secondary tag	The object type of the interacting track	`forklift`

A threshold group only applies when both the primary and secondary tags match.

Configuration

Interaction threshold groups

Each group defines a tag pair and optional thresholds:

Parameter	Description
Primary Tags	Object type(s) of the current track (e.g., person)
Secondary Tags	Object type(s) of the interacting track (e.g., forklift, vehicle)
Overlap	Minimum bounding box overlap percentage (0–100%)
Duration	Minimum interaction duration in seconds
Distance	Maximum distance between tracks (pixels or meters)

Each threshold has an enable toggle, operator (>=, >, <=, <, ==), and value.

If no thresholds are enabled, the check passes on tag match alone — any interaction between the configured tag types will pass.

Debug mode

Boolean toggle for verbose logging.

Output

{
  "track_state": { ... },
  "checks": {
    "type3": {
      "passed": true,
      "primary_track_id": "track-uuid-1",
      "primary_tag": "person",
      "primary_tag_matched": true,
      "matching_interactions": ["track-uuid-2"],
      "matching_interaction_count": 1,
      "matching_track_pair_ids": ["track-uuid-1::track-uuid-2"],
      "matching_tags": ["forklift"],
      "interaction_details": {
        "track-uuid-2": {
          "track_id": "track-uuid-2",
          "tag": "forklift",
          "track_pair_id": "track-uuid-1::track-uuid-2",
          "passed": true,
          "total_duration": 12.5,
          "first_interaction_at": "2026-01-13T15:12:52.005Z",
          "last_interaction_at": "2026-01-13T15:13:04.505Z",
          "thresholds": {
            "overlap": {
              "enabled": true,
              "operator": ">=",
              "threshold": 10,
              "actual": 25.5,
              "passed": true,
              "unit": "%"
            },
            "duration": {
              "enabled": true,
              "operator": ">=",
              "threshold": 5,
              "actual": 12.5,
              "passed": true,
              "unit": "s"
            }
          }
        }
      },
      "interactions_checked": 3
    }
  }
}

Key output fields

Field	Description
`passed`	Whether any interaction met all thresholds
`primary_tag_matched`	Whether the current track’s tag matched any group’s primary tags
`matching_interactions`	Track IDs of interacting tracks that passed
`matching_track_pair_ids`	Canonical pair IDs (sorted alphabetically) for deduplication
`matching_tags`	Object types of matching interacting tracks
`interaction_details`	Per-interaction threshold breakdown
`reason`	If failed: `primary_tag_not_configured`, `no_interactions_in_input`, `no_interactions_met_thresholds`, etc.

Track pair IDs

Type III generates canonical track pair IDs by alphabetically sorting the two track IDs. This ensures the same pair always produces the same ID regardless of which track is primary:

track-a::track-b  (always this order, never track-b::track-a)

This is useful for deduplication when both tracks in a pair trigger the same workflow.

Business use case examples

PPE compliance — person + PPE bounding box overlap

Detect whether workers are wearing high-visibility safety vests in designated PPE zones. The CV model detects both person and ppe objects — if a person’s bounding box overlaps with a PPE detection, they’re wearing it.

Parameter	Value
Primary Tags	`person`
Secondary Tags	`ppe`
Overlap	Enabled, `>= 1%`
Duration	Not enabled
Distance	Not enabled

Mode: Batch — the trigger must include both person and ppe object types so the state machine calculates interactions between them.The overlap threshold is intentionally low (1%) because any bounding box overlap between a person and a PPE detection indicates the person is wearing the equipment. When the check fails (no PPE overlap found), the workflow routes to a VLM fallback — a Vision Language Model analyzes the image for a second opinion before flagging a violation. This reduces false violations when the CV model misses a PPE detection.

The trigger must include all relevant object types for interactions to be calculated. If you only include person, the state machine won’t track ppe objects and no interactions will appear.

Vehicle collision / near-miss — proximity between tracks

Detect when vehicles come dangerously close to each other or to pedestrians. This uses the proximity thresholds rather than overlap.

Parameter	Value
Primary Tags	`person` (or vehicle types)
Secondary Tags	`forklift`, `vehicle`, `tugger`
Overlap	Not enabled (or enabled for actual collisions)
Duration	Enabled, `>= 2s`
Distance	Enabled, `<= 50 px`

Mode: Batch — the trigger includes all relevant object types.For near-miss detection, you typically care about proximity (how close they got) and duration (how long they were close). For actual collision detection, you’d enable overlap instead. The matching_track_pair_ids output is critical for deduplication — since both tracks in a near-miss may trigger the workflow, the canonical pair ID ensures you only create one event per interaction.

Adapting for other use cases

Type III threshold combinations serve different interaction scenarios:

Use Case	Primary	Secondary	Key Threshold
PPE compliance	`person`	`ppe`	Overlap `>= 1%`
Near-miss	`person`	Vehicle types	Distance `<= 50 px`, Duration `>= 2s`
Vehicle collision	Vehicle types	Vehicle types	Overlap `>= 10%`, Duration `>= 1s`
Escort compliance	`vehicle`	`person`	Distance `<= 100 px`, Duration `>= 30s`
Tailgating	`vehicle`	`vehicle`	Distance `<= 30 px`

Remember: if no thresholds are enabled, the check passes on tag match alone. Always enable at least one threshold to filter meaningful interactions.

Batch mode requirement

Type III checks require interaction data which is only available in batch mode. The state machine calculates interactions (bounding box overlap, proximity) when processing batch subscriptions. Streaming mode does not include interaction data.

Credentials

No credentials required. Tag options are configured manually.

Trigger Nodes

Check Nodes

Event Nodes

Action Nodes

When to use

How it works

Tag matching

Configuration

Interaction threshold groups

Debug mode

Output

Key output fields

Track pair IDs

Business use case examples

Batch mode requirement

Credentials

​When to use

​How it works

​Tag matching

​Configuration

​Interaction threshold groups

​Debug mode

​Output

​Key output fields

​Track pair IDs

​Business use case examples

​Batch mode requirement

​Credentials

When to use

How it works

Tag matching

Configuration

Interaction threshold groups

Debug mode

Output

Key output fields

Track pair IDs

Business use case examples

Batch mode requirement

Credentials