Configuring Analytics

SecuRT analytics are defined as areas (polygons) and lines (tripwires) drawn over the camera frame, each tied to one analytic type — intrusion, line crossing, loitering, crowding, and so on. This tutorial shows how to read, create, update, and delete them through the /v1/securt namespace, plus the per-instance detection options that go with them.

These endpoints apply to instances bound to the SecuRT solution. See Managing Instances to create one.

Concepts

A few rules apply to every area and line:

• Normalized coordinates. Each point is { "x": <0..1>, "y": <0..1> }, relative to the frame with (0,0) at the top-left and (1,1) at the bottom-right. This keeps analytics resolution-independent.
• Areas vs. lines. Areas are closed polygons (3+ points). Lines are tripwires (2 points) and usually carry a direction.
• Classes. The classes array restricts an analytic to certain object types. Valid values: Person, Vehicle, Animal, Face, Unknown. Some analytics (crowd estimation, armed person, fallen person) do not take classes.
• Color. color is an RGBA array [r, g, b, a] with each component in 0.0–1.0; it controls how the entity is drawn in rendered output.

Reading the current configuration

GET /v1/securt/instance/{instanceId}/analytics_entities returns every area and line, grouped by type:

curl "http://localhost:3546/v1/securt/instance/<instanceId>/analytics_entities"

{
  "intrusionAreas": [
    {
      "id": "6cbd8545-0889-4e27-8d7b-e313c9643d2a",
      "name": "Front gate",
      "type": "AreaIntrusion",
      "classes": ["Person", "Vehicle"],
      "color": [1.0, 0.0, 1.0, 1.0],
      "coordinates": [
        { "x": 0.1, "y": 0.1 },
        { "x": 0.9, "y": 0.1 },
        { "x": 0.9, "y": 0.9 },
        { "x": 0.1, "y": 0.9 }
      ]
    }
  ],
  "crossingLines": [],
  "loiteringAreas": [],
  "crowdingAreas": []
}

Empty groups are returned as empty arrays. The full set of keys is listed in the reference table below.

Creating an area

Each area type has its own POST endpoint. For example, an intrusion area:

curl -X POST "http://localhost:3546/v1/securt/instance/<instanceId>/area/intrusion" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Front gate",
    "coordinates": [
      { "x": 0.1, "y": 0.1 },
      { "x": 0.9, "y": 0.1 },
      { "x": 0.9, "y": 0.9 },
      { "x": 0.1, "y": 0.9 }
    ],
    "classes": ["Person", "Vehicle"],
    "color": [1, 0, 1, 1]
  }'

Response (201 Created):

{ "areaId": "6cbd8545-0889-4e27-8d7b-e313c9643d2a" }

Creating a line

Line types each have their own POST endpoint. A crossing line (tripwire):

curl -X POST "http://localhost:3546/v1/securt/instance/<instanceId>/line/crossing" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Doorway",
    "coordinates": [ { "x": 0.2, "y": 0.5 }, { "x": 0.8, "y": 0.5 } ],
    "classes": ["Person"],
    "direction": "Both",
    "color": [0, 1, 1, 1]
  }'

Response (201 Created):

{ "lineId": "d52795da-61c8-4761-8303-d9c625895c0b" }

direction is Up, Down, or Both and determines which crossing direction triggers an event.

Area and line types

Every type accepts the common fields name, coordinates, and color. The table lists the endpoint and the additional fields specific to each type.

Areas

Analytic	Endpoint (POST /v1/securt/instance/{id}/...)	Additional fields
Intrusion	area/intrusion	classes
Area crossing (enter/exit)	area/crossing	classes, areaEvent (Enter/Exit/Both), ignoreStationaryObjects
Loitering	area/loitering	classes, seconds (dwell threshold)
Crowding	area/crowding	classes, objectCount, seconds
Occupancy	area/occupancy	classes
Dwelling	area/dwelling	classes
Crowd estimation	area/crowd_estimation	(none — no classes)
Armed person	area/armed_person	(none — no classes)
Fallen person	area/fallen_person	(none — no classes)
Object left behind	area/object_left	seconds
Object removed	area/object_removed	seconds

Lines

Analytic	Endpoint (POST /v1/securt/instance/{id}/...)	Additional fields
Line crossing	line/crossing	classes, direction
Counting	line/counting	classes, direction
Tailgating	line/tailgating	classes, direction, seconds

For example, a crowding area triggers when at least objectCount objects are present for seconds:

curl -X POST "http://localhost:3546/v1/securt/instance/<instanceId>/area/crowding" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lobby",
    "coordinates": [ {"x":0,"y":0}, {"x":1,"y":0}, {"x":1,"y":1}, {"x":0,"y":1} ],
    "classes": ["Person"],
    "objectCount": 10,
    "seconds": 3,
    "color": [0.3, 0.6, 0, 1]
  }'

Updating an entity

To replace an existing area or line, PUT to the same endpoint with the entity's ID appended:

curl -X PUT "http://localhost:3546/v1/securt/instance/<instanceId>/area/intrusion/6cbd8545-0889-4e27-8d7b-e313c9643d2a" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Front gate (widened)",
    "coordinates": [ {"x":0.05,"y":0.05}, {"x":0.95,"y":0.05}, {"x":0.95,"y":0.95}, {"x":0.05,"y":0.95} ],
    "classes": ["Person", "Vehicle"],
    "color": [1, 0, 1, 1]
  }'

Deleting entities

ID=<instanceId>

# Delete a single area or line by its ID
curl -X DELETE "http://localhost:3546/v1/securt/instance/$ID/area/<areaId>"
curl -X DELETE "http://localhost:3546/v1/securt/instance/$ID/line/<lineId>"

# Delete all areas, or all lines
curl -X DELETE "http://localhost:3546/v1/securt/instance/$ID/areas"
curl -X DELETE "http://localhost:3546/v1/securt/instance/$ID/lines"

Replacing the whole configuration

The Web Panel applies a new analytics layout by deleting all areas and lines and then re-creating each entity. To reproduce that behavior, DELETE .../areas and DELETE .../lines first, then POST each entity.

Exclusion areas

Exclusion (mask) areas tell the detector to ignore regions of the frame:

# Add an exclusion area
curl -X POST "http://localhost:3546/v1/securt/instance/<instanceId>/exclusion_areas" \
  -H "Content-Type: application/json" \
  -d '{
    "coordinates": [ {"x":0,"y":0}, {"x":0.2,"y":0}, {"x":0.2,"y":0.2}, {"x":0,"y":0.2} ],
    "classes": ["Person", "Vehicle"]
  }'

# List exclusion areas
curl "http://localhost:3546/v1/securt/instance/<instanceId>/exclusion_areas"

# Remove all exclusion areas
curl -X DELETE "http://localhost:3546/v1/securt/instance/<instanceId>/exclusion_areas"

Detection options

Several per-instance toggles refine what the solution detects. Each has a matching GET to read the current value and a POST to set it.

Option	Endpoint (/v1/securt/instance/{id}/...)	Body
Feature extraction (re-ID)	feature_extraction	{ "types": ["Face", "Person", "Vehicle"] }
Attributes / appearance search	attributes_extraction	{ "classes": ["Person", "Vehicle", "Animal"] }
License plate recognition	lpr	{ "enable": true }
Picture-in-picture	pip	{ "enable": true }
Performance profile	performance_profile	{ "profile": "Balanced" }
Face detection	face_detection	{ "enable": true }

For example, enabling LPR:

curl -X POST "http://localhost:3546/v1/securt/instance/<instanceId>/lpr" \
  -H "Content-Type: application/json" \
  -d '{ "enable": true }'

performance_profile accepts Performance, Balanced, or Accurate.

Tuning sensitivity

Detection and movement sensitivity and the detector mode are properties of the instance itself, not of individual areas. Set them when creating the instance or update them later with PATCH /v1/core/instance/{instanceId}:

curl -X PATCH "http://localhost:3546/v1/core/instance/<instanceId>" \
  -H "Content-Type: application/json" \
  -d '{
    "detectorMode": "SmartDetection",
    "detectionSensitivity": "High",
    "movementSensitivity": "Medium"
  }'

See Managing Instances for the full list of instance properties.

End-to-end example

#!/bin/bash
BASE="http://localhost:3546"
ID="<instanceId>"   # an existing SecuRT instance

# Start from a clean slate
curl -s -X DELETE "$BASE/v1/securt/instance/$ID/areas"
curl -s -X DELETE "$BASE/v1/securt/instance/$ID/lines"

# Add an intrusion area
curl -s -X POST "$BASE/v1/securt/instance/$ID/area/intrusion" \
  -H "Content-Type: application/json" \
  -d '{"name":"Front gate","coordinates":[{"x":0.1,"y":0.1},{"x":0.9,"y":0.1},{"x":0.9,"y":0.9},{"x":0.1,"y":0.9}],"classes":["Person","Vehicle"],"color":[1,0,1,1]}'

# Add a crossing line
curl -s -X POST "$BASE/v1/securt/instance/$ID/line/crossing" \
  -H "Content-Type: application/json" \
  -d '{"name":"Doorway","coordinates":[{"x":0.2,"y":0.5},{"x":0.8,"y":0.5}],"classes":["Person"],"direction":"Both","color":[0,1,1,1]}'

# Verify
curl -s "$BASE/v1/securt/instance/$ID/analytics_entities"

Next steps

• Configuring Exporting - forward the resulting events to MQTT.
• Reading Events with SSE - watch the areas and lines fire in real time.
• Querying Stored Data - query the events these analytics record.