This guide explains how to configure an integration to send analytics events to the Media Server.

The Media Server uses a Rules Engine to respond to integration-detected events. For example, when an integration detects a specific object, the server can automatically trigger an action, such as sending an HTTP request to an external system. You can configure these interactions in the Camera Rules dialog within the Desktop Client.

You can find the complete sample code for this guide in the Metadata SDK at step5/src/sample_company/vms_server_plugins/opencv_object_detection/.

Prerequisites

Before modifying the code, review the Metadata SDK documentation in src/nx/sdk/analytics/manifests.md. Read the following sections to understand how events are structured:

• Engine Manifest (specifically the eventTypes property)

• DeviceAgent Manifest (specifically the eventTypes property)

• Event types

1. Declare event types

To let the Nx Server know which events your integration supports, define your event types in the integration manifest.

1. Open device_agent.h and define your event IDs and suffixes:

   const std::string kDetectionEventType = "sample.opencv_object_detection.detection";
   const std::string kDetectionEventCaptionSuffix = " detected";
   const std::string kDetectionEventDescriptionSuffix = " detected";
   
   const std::string kProlongedDetectionEventType = "sample.opencv_object_detection.prolongedDetection";

2. Open device_agent.cpp and declare these event types inside the DeviceAgent::manifestString() function:

   "eventTypes": [
       {
           "id": ")json" + kDetectionEventType + R"json(",
           "name": "Object detected"
       },
       {
           "id": ")json" + kProlongedDetectionEventType + R"json(",
           "name": "Object detected (prolonged)",
           "flags": "stateDependent"
       }
   ]

2. Define structures for event data

To pass event data to and from the OpenCV framework, define the necessary internal tracking entities.

Open event.h and add the following enumeration and structure:

enum class EventType
{
     detection_started,
     detection_finished,
     object_detected
};

struct Event
{
    const EventType eventType;
    const int64_t timestampUs;
    const std::string classLabel;
};

3. Generate and process events

Integrations pass event data to the Nx Server using EventMetadataPacket packets. This is a distinct type from the ObjectMetadataPacket used for object bounding boxes. Because an integration might detect objects and trigger events simultaneously, you must configure the code to output both packet types.

Update the object tracker output

1. Open object_tracker.h and define a Result structure to hold both detections and events:

   struct Result
   {
       DetectionList detections;
       EventList events;
   };

2. Refactor the declarations and implementations of ObjectTracker::run() and ObjectTracker::runImpl() to return this new Result structure.

Convert events to metadata packets

1. Remove the existing DeviceAgent::generateEventMetadataPacket() method.

2. Define a new conversion method in the DeviceAgent class to translate the OpenCV tracker results into a list the Nx Server can read:

   MetadataPacketList eventsToEventMetadataPacketList(
       const EventList& events,
       int64_t timestampUs);

Update the frame processing pipeline

Update the try block in DeviceAgent::processFrame() to process both object detections and analytics events sequentially:

try
{
    DetectionList detections = m_objectDetector->run(frame);
    ObjectTracker::Result objectTrackerResult = m_objectTracker->run(frame, detections);
    
    const auto& objectMetadataPacket = detectionsToObjectMetadataPacket(
        objectTrackerResult.detections, 
        frame.timestampUs);
        
    const auto& eventMetadataPacketList = eventsToEventMetadataPacketList(
        objectTrackerResult.events,
        frame.timestampUs);
        
    MetadataPacketList result;
    if (objectMetadataPacket)
    {
        result.push_back(objectMetadataPacket);
    }
    
    result.insert(
        result.end(),
        std::make_move_iterator(eventMetadataPacketList.begin()),
        std::make_move_iterator(eventMetadataPacketList.end()));
        
    return result;
}

4. Verify the analytics events

Build your integration and verify that the Nx desktop client detects your new events.

1. Enable your integration on a camera through the desktop client interface.

2. Navigate to System Administration and open Event Rules.

3. Click Add.

4. In the Event section, click the drop-down menu and select Analytics Event.

5. In the At field, select the camera where you enabled the integration.

6. Open the Event Type drop-down menu. Your newly defined analytics events will appear in the list.