Discussion Note (Tapway x Appomax)

SamurAI Copilot Event Requirements for Steel Product Tracking

https://docs.google.com/document/d/1drNQrbwhccOEKqZcogAaUPUb0rVXw0a3wFWLAwuoeps/edit?usp=sharing

Prepared by: Vikan

Purpose: Discussion and alignment with Tapway on Vision AI event outputs for the Steel Product Tracking System

1. Background

Appomax is designing a Steel Product Tracking System based on an event-driven architecture, in which Vision AI serves as the upstream event source, and the downstream platform performs normalisation, persistence, tracking logic, traceability, and visualisation. The intended role of SamurAI Copilot is therefore to detect and publish reliable machine vision events, rather than serve as the full business tracking engine.

The project objective is to record deterministic product movement events and preserve them as a traceable event history, so that downstream systems can interpret them into tracking transitions such as product entering, leaving, transferring, or completing a process step.

2. Discussion Objective with Tapway

This document is intended to align on what Appomax needs from SamurAI Copilot for the steel tracking use case, especially in relation to:

• multi-camera zone-based monitoring

• direction-aware event generation

• raw event semantics

• tracking continuity

• event quality and reliability

• compatibility with downstream tracking logic

At the current stage, Appomax assumes that the system will use 8 cameras, with one or more Areas of Interest (AOI) / zones configured per camera. The expected behavior is that SamurAI Copilot detects steel products entering or leaving a defined zone based on configured movement direction and publishes corresponding events.

3. Proposed Functional Role of SamurAI Copilot

Appomax proposes that SamurAI Copilot should primarily function as a Vision Event Source, with the following responsibilities:

• receive RTSP video streams from cameras / NVR

• run object detection and tracking inference

• apply zone-based and direction-based event logic

• publish raw movement events with sufficient context

• provide image / clip references when available

• maintain stable track continuity as much as possible while object is visible

Appomax does not expect SamurAI Copilot to perform the full downstream business interpretation, such as final process-state mapping, cross-camera route logic, or authoritative product lifecycle decisions. Those responsibilities remain in the downstream event normalisation and tracking logic layers.

4. Proposed Event Model

For the steel tracking use case, Appomax believes that the most useful and scalable Vision AI output is not merely raw object detection per frame, but meaningful movement events associated with configured zones.

The preferred model is:

• zone-based monitoring

• direction-aware event generation

• one raw event per meaningful occurrence

• stable identity references where possible

• optional supporting state signals for diagnostics and analytics

5. Recommended Event Types

5.1 Core Event Types

These are the key event types Appomax expects to support the tracking use case.

These two event types are considered the most important for downstream event-based tracking.

5.2 Optional Supporting Event Types

These are useful but secondary. Appomax would like to discuss whether and how they can be supported.

C. DWELL

Generated when an object remains inside a configured zone longer than a specified threshold.

Potential use:

• congestion / blockage detection

• station waiting analysis

• exception detection

• process delay monitoring

This should be threshold-based and configurable.

D. PRESENT / OCCUPIED

Represents that an object is currently occupying a zone.

This may be implemented either as:

• a state signal, or

• an event generated after a configurable presence duration

Appomax would like to clarify with Tapway whether this should be:

• continuously represented as current occupancy state only, or

• triggered as an event only after the object remains in the zone for a certain minimum duration

Potential use:

• live visualization

• operator awareness

• supporting evidence for movement events

• analytics

Appomax does not intend to use PRESENT / OCCUPIED alone as the main tracking event, but it may be useful as a supporting signal.

E. LOST TRACK / REAPPEAR

Represents a tracking continuity issue, for example:

• object temporarily lost due to occlusion

• object leaves view unexpectedly

• object is re-identified after being lost

Potential use:

• diagnostic monitoring

• track continuity quality assessment

• handling ambiguous tracking cases

This is optional but may become valuable where steel objects overlap, occlude one another, or move under challenging visual conditions.

6. Areas of Interest and Direction Logic

Appomax proposes that each camera should support one or more configured AOIs / zones. Each zone should ideally support:

• named zone/zone ID

• polygon-based or flexible zone shape

• configurable business purpose

• configurable expected movement direction

• association with specific event logic

For each zone, Appomax would like to define expected interpretations such as:

• inbound direction = generate IN

• outbound direction = generate OUT

It is also important to clarify the distinction between:

• event direction: business interpretation such as IN / OUT

• object direction: physical movement direction in image space, such as LEFT / RIGHT / UP / DOWN

The sample Copilot payload already appears to contain both event_direction and object_direction, which is promising, but Appomax would like to confirm the exact semantics and rules behind these fields.

7. Current MQTT Output and Alignment Points

Based on the MQTT sample provided by Tapway, Appomax understands that SamurAI Copilot already publishes zone-based movement-related events with event identity, timestamp, camera context, direction indicators, track references, and media references. This is generally aligned with Appomax’s intended event-driven integration approach.

{
  "siteID": "APPOMAX",
  "subgroupID": "Template-v3",
  "cameraID": "05",
  "cameraIP": "192.168.6.144",
  "cameraStage": 1,
  "uniqueEventID": "9QNVTVV4V9",
  "eventTimeStamp": "2026-04-02T07:59:02.877911",
  "camResolution": [720, 1280, 3],
  "eventClipFilename": "/videos/05/2026-04-02_145903_9QNVTVV4V9.mp4",
  "siteCustom": null,
  "customMain": {},
  "inout": {
    "zone5": {
      "class_id": [0],
      "class_name": ["yellow_steel"],
      "event_direction": ["IN"],
      "object_direction": ["LEFT"],
      "speed": [0.0],
      "dwell_duration": [0.79],
      "reID": [{}],
      "model_name": "Steeldetection-2026-9-1",
      "uniqueTrackID": ["e38991"],
      "occupancy": 1,
      "filename": "/images/Steeldetection-2026-9-1/05/instance_1_2026-04-02_145903_9QNVTVV4V9.jpg"
    }
  },
  "occupancy": null,
  "dwell": null,
  "detection": null,
  "tracker": null,
  "model-1": {
    "modelName": "Steeldetection-2026-9-1",
    "modelVersion": "1.0.0",
    "className": ["yellow_steel"],
    "imgResolution": [720, 1280, 3],
    "classIDs": [0],
    "confidence": [0.44],
    "boundingBoxes": [
      [714.0, 455.0, 762.0, 511.0]
    ],
    "zoneIDs": ["zone5"],
    "zoneOccupancy": [true],
    "logicType": ["INOUT"],
    "custom": {},
    "trackID": [97],
    "frameCount": [2],
    "dwellDuration": [0.79],
    "speed": [0.0],
    "reID": [{}],
    "objectDirection": ["LEFT"],
    "uniqueTrackID": ["e38991"]
  }
}

For integration alignment, Appomax would like to confirm the following points:

• whether uniqueEventID is stable for retries / republishes
• whether eventTimeStamp represents the actual event occurrence time
• whether inout.zoneX.event_direction is the primary field to use for IN / OUT logic
• the exact semantic difference between event_direction and object_direction
• how trackID and uniqueTrackID behave during temporary loss/re-identification
• whether occupancy and dwell are state-only indicators or can also drive event semantics
• whether the MQTT schema is stable across model versions

8. Important Discussion Points

8.1 Movement Events vs Occupancy State

Appomax’s preference is for SamurAI Copilot to publish movement events such as IN / OUT as the primary event model.

Occupancy or current presence is useful, but by itself it is not sufficient for deterministic tracking because it does not fully capture the transition history required for downstream traceability logic.

8.2 Event Uniqueness and Reprocessing

Because downstream systems may store raw events as immutable records and apply idempotent ingestion logic, Appomax needs to understand how unique event identity is handled.

In particular, Appomax needs to know whether:

• each event is guaranteed to have a unique identifier

• the same event may be republished

• retries can occur

• duplicate deliveries are possible

8.3 Tracking Continuity

Where track-based logic is involved, Appomax needs to understand the behavior of:

• trackID

• uniqueTrackID

• re-identification

• occlusion handling

• temporary loss of object visibility

This is especially relevant if downstream logic later uses historical event data to validate and improve tracking behavior analytically.

9. Questions Appomax Needs to Verify with Tapway

Below is the list of specific questions Appomax would like to verify.

Zone and AOI Configuration

1. Can SamurAI Copilot support multiple AOIs / zones per camera?

2. Can each zone be drawn as a polygon, or only as a rectangle?

3. Can each zone be assigned a business-friendly zone name / zone ID?

4. Can zones overlap or be placed adjacent to each other if required?

Direction and Event Semantics

1. Can each zone be configured with expected movement direction logic?

2. Can SamurAI Copilot generate both IN and OUT events explicitly?

3. What is the exact difference between event_direction and object_direction?

4. Is event_direction derived from zone logic, line-crossing logic, or some other rule?

5. Can bidirectional movement be supported in the same zone if needed?

PRESENT / OCCUPIED Logic

1. Is PRESENT / OCCUPIED available as a real-time state only, or can it also be published as an event?

2. If it can be published as an event, is it triggered only after the object remains in the zone for a configurable period?

3. Can the occupancy threshold or presence duration be configured per camera or per zone?

DWELL Logic

1. Can DWELL events be generated when an object remains in a zone longer than a configurable threshold?

2. Is the dwell threshold configurable per zone?

3. Can dwell time be included in both the event payload and the live zone state?

LOST TRACK / REAPPEAR Logic

1. Can SamurAI Copilot identify or flag temporary loss of tracking?

2. Can it indicate when an object is re-identified or reappears?

3. Under what conditions would LOST TRACK / REAPPEAR be emitted?

4. Is re-identification based on appearance, trajectory, or another method?

Identity and Event Reliability

1. Is uniqueEventID guaranteed to be unique?

2. Can the same event ever be resent or republished?

3. If the same event is resent, does it preserve the same uniqueEventID?

4. Is event ordering guaranteed per camera?

5. Can delayed or out-of-order events occur?

Track Identity

1. How stable is trackID and uniqueTrackID while the object is visible?

2. When does a track ID reset?

3. Can uniqueTrackID survive short-term occlusion?

4. Is there any camera-to-camera identity continuity, or is track identity only local to a single camera?

Event Filtering and Quality

1. Can confidence threshold be configured per model, class, camera, or zone?

2. Can repeated noisy events from the same object be suppressed?

3. Can minimum object size or filtering rules be configured?

4. Can event logic be tuned differently for different steel product classes?

Media and Auditability

1. Can every event include an image reference and/or event clip reference?

2. Are image and clip files retained for a configurable period?

3. Are file paths guaranteed to be available when the event is published?

4. Can the media reference be used later for audit / review purposes?

Integration and Output Format

1. Is the output schema stable across model versions?

2. Can Tapway provide a formal field definition for each output field?

3. Can Copilot publish a canonical event schema for external integration?

4. Can event payloads include custom fields if Appomax needs future extension?

10. Suggested Alignment Outcome

For Appomax, the preferred alignment outcome with Tapway is:

• SamurAI Copilot publishes reliable raw movement events

• zone-based and direction-based logic are configurable

• IN and OUT are the primary event types

• DWELL and PRESENT / OCCUPIED are optional supporting features

• LOST TRACK / REAPPEAR is optional diagnostic support

• event IDs, timestamps, and track IDs are clearly defined

• payload semantics are documented and stable

• downstream systems remain responsible for authoritative business tracking interpretation

11. Closing Position

Appomax sees SamurAI Copilot as a strong candidate to provide the upstream vision event layer for steel tracking, provided that the event semantics, zone logic, identity behavior, and reliability expectations are clearly aligned.

The key requirement is that the Vision AI output should be structured in a way that supports event-based downstream traceability, immutable event storage, and later business-level tracking logic, rather than merely producing frame-by-frame detection results.

I can also turn this into a more formal meeting memo format with sections like “Objectives / Assumptions / Open Questions / Proposed Next Steps” if you want.