Custom Integration

U-Alarm is not only a standalone solution but can be used in an integrated system as well. All important information that belongs to an incident (eg. location, timestamp, detection coordinates, etc.) can be sent instantly to a third party software.

HTTP message

An external API endpoint can be set for each alarm. Whenever an alarm is triggered, a POST message will be sent to the API with metadata that belongs to the incident.

Message schema

Messages' content type is application/json. The content is described in proto in this document.

message Event{
  enum Type
  {
    UNKNOWN = 0;
    CROWD_DETECTION = 1; ///< result of Crowd detection
    INTRUSION_DETECTION = 2; ///< result of Intrusion detection
    MULTI_OBJECT_DETECTION = 3; ///< result of Multi object detection
  }

  string id = 1; ///< Global unique id of current event
  uint64 timestamp = 2; ///< Timestamp of the last video frame in window
  string display_name = 3; ///< Human readable name of source alarm configuration
  Type type = 4; ///< Type of source alarm configuration
  string config_id = 5; ///< id of source alarm configuration
  bool heartbeat = 6;
  
  oneof value
  {
    CrowdDetectionDetails crowd_detection_details = 7; ///< Only for type=CROWD_DETECTION
    IntrusionDetectionDetails intrusion_detection_details = 8; ///< Only for type=INTRUSION_DETECTION. Not set when heartbeat is true
    IntrusionDetectionDetails multi_object_detection_details = 9; ///< Only for type=MULTI_OBJECT_DETECTION. Not set when heartbeat is true
  }
}

message CrowdDetectionDetails {
  int32 num_of_people = 1; ///< Number of detected people
  repeated CameraRecord sources = 2; ///< Detection details per camera
}

message IntrusionDetectionDetails {
  CameraRecord source = 1; ///< Detection detail from last frame
}

message CameraRecord {
  string camera_id = 1; ///< ID of current camera
  string camera_display_name = 2; ///< Display name of current camera
  string camera_technical_name = 3; ///< Technical name of current camera
  int32 width = 4; ///< Frame width of the video stream
  int32 height = 5; ///< Frame height of the video stream
  string source_topic = 6; ///< Source topic name of detection
  uint64 frame_timestamp = 7; ///< Timestamp of current video frame
  repeated Detection detections = 8; ///< Details of detections
}

message Detection {
  ObjectType type = 1; ///< Type of detected object.
  Rect bounding_box = 2; ///< Rectangular box containing the detection.
  float detection_confidence = 3; ///< Confidence of the detection. Range: [0..1]
}

enum ObjectType
{
  PERSON_HEAD = 0; ///< Head detection result type. Supported event type CROWD_DETECTION
  PERSON_FULL_BODY = 1; ///< Person detection result type. Supported event type INTRUSION_DETECTION
  CAR = 2; ///< Car detection result type. Supported event type INTRUSION_DETECTION
  BUS = 3; ///< Bus detection result type. Supported event type INTRUSION_DETECTION
  BOAT = 4; ///< Boat detection result type. Supported event type INTRUSION_DETECTION
  TRUCK = 5; ///< Truck detection result type. Supported event type INTRUSION_DETECTION
  MOTORCYCLE = 6; ///< Motorcycle detection result type. Supported event type INTRUSION_DETECTION
  BICYCLE = 7; ///< Bicycle detection result type. Supported event type INTRUSION_DETECTION
  TRAIN = 8; ///< Train detection result type. Supported event type INTRUSION_DETECTION
  AIRPLANE = 9; ///< Airplane detection result type. Supported event type INTRUSION_DETECTION
}

/**  Rectangle
unit: pixels
*/
message Rect {
  int32 x = 1; ///< Horizontal coordinate of the upper left corner.
  int32 y = 2; ///< Vertical coordinate of the upper left corner.
  uint32 width = 3; // Rectangle width in pixels.
  uint32 height = 4; // Rectangle height in pixels.
}

/** Two dimensional point
range: [(0,0)..(width,height)); (0,0) is upper left corner
unit: pixels
*/
message Point {
  int32 x = 1; ///< Horizontal coordinate
  int32 y = 2; ///< Vertical coordinate
}

Intrusion detection example

{
  "id": "1611842334668@mvp01.alert8.Event.json",
  "timestamp": 1611842334668,
  "display_name": "Test Intrusion Det.",
  "type": "INTRUSION_DETECTION",
  "config_id": "alert8",
  "heartbeat": false,
  "crowd_detection_details": null,
  "intrusion_detection_details": {
    "source": {
      "camera_id": "cam2",
      "camera_display_name": "cam2 (117)",
      "camera_technical_name": "cam2 tech. name",
      "width": 1920,
      "height": 1080,
      "source_topic": "mvp01.cam2alert8DetFilterPort.ObjectDetectionRecord.json",
      "frame_timestamp": 1611842334668,
      "detections": [
        {
          "type": "PERSON_FULL_BODY",
          "bounding_box": {
            "x": 0,
            "y": 10,
            "width": 44,
            "height": 55
          },
          "detection_confidence": 0.9
        }, {
          "type": "BUS",
          "bounding_box": {
            "x": 28,
            "y": 32,
            "width": 54,
            "height": 45
          },
          "detection_confidence": 0.9
        }
      ]
    }
  },
  "multi_object_detection_details": null
}

Multi object detection example

{
  "id": "1611842334668@mvp01.alert8.Event.json",
  "timestamp": 1611842334668,
  "display_name": "Test Intrusion Det.",
  "type": "MULTI_OBJECT_DETECTION",
  "config_id": "alert8",
  "heartbeat": false,
  "crowd_detection_details": null,
  "intrusion_detection_details": null,
  "multi_object_detection_details": {
    "source": {
      "camera_id": "cam2",
      "camera_display_name": "cam2 (117)",
      "camera_technical_name": "cam2 tech. name",
      "width": 1920,
      "height": 1080,
      "source_topic": "mvp01.cam2alert8DetFilterPort.ObjectDetectionRecord.json",
      "frame_timestamp": 1611842334668,
      "detections": [
        {
          "type": "PERSON_FULL_BODY",
          "bounding_box": {
            "x": 0,
            "y": 10,
            "width": 44,
            "height": 55
          },
          "detection_confidence": 0.9
        }, {
          "type": "BUS",
          "bounding_box": {
            "x": 28,
            "y": 32,
            "width": 54,
            "height": 45
          },
          "detection_confidence": 0.9
        }
      ]
    }
  }
}

Crowd detection example

{
  "id": "1606727720510@mvp01.alert12.Event.json",
  "timestamp": 1606727720510,
  "display_name": "first alarm",
  "type": "CROWD_DETECTION",
  "config_id": "alert.12",
  "heartbeat": false,
  "crowd_detection_details": {
    "num_of_people": 1,
    "sources": [
      {
        "camera_id": "cam.1",
        "camera_display_name": "first cam",
        "camera_technical_name": "Outer_ID_01",
        "width": 1920,
        "height": 1080,
        "source_topic": "mvp01.cam1alert12DetFilterPortObjectDetectionRecord.json",
        "frame_timestamp": 1606727720510,
        "detections": []
      }, {
        "camera_id": "cam.10",
        "camera_display_name": "second cam",
        "camera_technical_name": "Outer_ID_02",
        "width": 1920,
        "height": 1080,
        "source_topic": "mvp01.cam10alert12DetFilterPortObjectDetectionRecord.json",
        "frame_timestamp": 1606727720478,
        "detections": [
          {
            "type": "PERSON_HEAD",
            "bounding_box": {
              "x": 1052,
              "y": 415,
              "width": 89,
              "height": 112
            },
            "detection_confidence": 0.99902487
          }
        ]
      }
    ]
  },
  "intrusion_detection_cascading_details": null,
  "multi_object_detection_details": null
}

Setup message sending in U-Alarm

1. Give unique technical names to cameras. The technical name will appear in the metadata and will aid the identification of the camera.
2. Fill HTTP client settings for each alarm. Give the address, the security credentials in a custom message header (if any) and cert settings for the external API.