Line Crossing 👣

Table of Contents

1. Endpoint Information
   1. Update Camera Line Crossing Thresholds
   2. Retrieve Line Crossing Events
   3. Retrieve Line Crossing Counts
   4. Get Camera Configuration Details
2. Reference Images
3. Additional Information

Endpoint Information

1. Update Camera Line Crossing Thresholds

Endpoint: [/camera/updateCameraLineCrossingThresholds]

Description: This endpoint allows you to enable, disable, or update the line-crossing feature for a specific camera.

The top-left corner of a camera's image is the origin (0,0) and the bottom-right corner (1,1). Both of which are out of bounds.

Parameters:

• cameraUuid (required): Device UUID to update the line-crossing feature for.

• pointA: (X,Y) coordinate expressed as a percent of the max image width/height.

  • Minimum range is 0.1 and maximum range is 0.9. Leave this value as null to disable line-crossing.

• pointB: (X,Y) coordinate expressed as a percent of the max image width/height.

  • Minimum range is 0.1 and maximum range is 0.9. Leave this value as null to disable line-crossing.

• inverted: By default, INGRESS events occur when the following condition is met for the following line types:

  • Moves from top -> bottom when a horizontal line is defined
  • Moves from left -> right when a vertical line is defined
  • Moves from top-left -> bottom-right when an upwards sloping line is defined
  • Moves from top-right to bottom-left when a downwards sloping line is defined

  Setting this value to true will switch INGRESS to EGRESS events and vice-versa.

Example Body Request:

{
  "inverted": false,
  "pointA": {
    "x": 0.1,
    "y": 0.5
  },
  "pointB": {
    "x": 0.8,
    "y": 0.5
  },
  "cameraUuid": "XXXXXCXXXXXXXXX"
}

Successful Example Response:

{
  "error" : false
}

Test here 👉 /updateCameraLineCrossingThresholds👈

2. Retrieve Line Crossing Events

Endpoint: /report/getThresholdCrossingEvents

Description: Use this endpoint to retrieve events related to line crossings for specified devices within a given time range.

Parameters:

• crossingObject (required): Human or Vehicle
• startTimeMs (required): Start time for the query in epoch ms
• endTimeMs (required): End time for the query in epoch ms
• devices (required): Array of device UUIDs to query

Example Body Request:

{
  "crossingObject": "HUMAN",
  "devices": [
    "XXXXXXXXXXXXXX"
  ],
  "startTimeMs": 1723044419000, 
  "endTimeMs": 1723649219358
}

Example Response:

{
  "deviceToThresholdCrossingEventMap": {
    "CAMERA_UUID": [
      {
        "crossingObject": "HUMAN",
        "direction": "EGRESS",
        "timestampMs": 1723572999705
      },
      {
        "crossingObject": "HUMAN",
        "direction": "INGRESS",
        "timestampMs": 1723572983053
      },
      // ... more events ...
    ]
  },
  "error": false
}

Test here 👉 /getThresholdCrossingEvents👈

3. Retrieve Line Crossing Counts

Endpoint: /report/getThresholdCrossingCounts

Description: This endpoint provides counts of line crossing events for specified devices within a given time range.

Parameters:

• crossingObject (required): Human or Vehicle
• startTimeMs (required): Start time for the query in milliseconds since epoch
• endTimeMs (required): End time for the query in milliseconds since epoch
• devices (required): Array of device UUIDs to query

Example Body Request:

{
  "crossingObject": "HUMAN",
  "devices": [
    "lG-M2-BrRZK1hFzkNNnjnA"
  ],
  "startTimeMs": 1723044419000,
  "endTimeMs": 1723649219358
}

Example Response:

{
  "counts": [
    {
      "count": 0,
      "timestampMs": 1723154400000
    },
    {
      "count": 1,
      "timestampMs": 1723248700061
    },
    // ... more count entries ...
    {
      "count": 1,
      "timestampMs": 1723572999705
    }
  ],
  "error": false
}

Test here 👉 /getThresholdCrossingCounts👈

4. Get Camera Configuration Details

Endpoint: /deviceconfig/getFacetedConfig

Description: Use this endpoint to retrieve the detailed configuration of a specific camera.

Parameters:

• deviceUuid (required): UUID of the device to query

Example Body Request:

{
  "deviceUuid" : "XXXXXXXXXXXXX"
}

Example Response:

{
  "config": {
    
    //.. other video settings ...
    
    "videoFacetSettings": {
      "v0": {
        "cross_counting": true,
        "cross_counting_settings": {
          "in_roi": [
            {
              "coordinates": [
                {"x": 0.5, "y": 0.1},
                {"x": 0.5, "y": 0.9},
                {"x": 0.6, "y": 0.1},
                {"x": 0.6, "y": 0.9}
              ]
            }
          ],
          "out_roi": [
            {
              "coordinates": [
                {"x": 0.5, "y": 0.1},
                {"x": 0.5, "y": 0.9},
                {"x": 0.4, "y": 0.1},
                {"x": 0.4, "y": 0.9}
              ]
            }
          ]
        },
        // ... other video settings ...
      }
    }
  },
  "error": false
}

Test here 👉 /getFacetedConfig👈

Reference Images

The following images illustrate the ingress, egress, and regions of interest (ROI) for the line-crossing feature:

• INGRESS represents the direction of entry
• EGRESS represents the direction of exit
• outROI and inROI represent the outer and inner regions of interest

By default, these are the orientations for INGRESS / EGRESS events. The red line is defined by two points entered by the user. If you would like them to be flipped, there is a value in the request called inverted that will swap the inROI and outROI.

Additional Information

• When updating the line-crossing thresholds, providing both pointA and pointB enables the feature, while setting both to null disables it.

• The inverted parameter allows you to flip the definition of INGRESS and EGRESS events, which can be useful for adjusting the feature to specific camera orientations or use cases.

• The getThresholdCrossingEvents and getThresholdCrossingCounts endpoints both use millisecond timestamps.

• The cross_counting_settings in the camera configuration define the regions of interest (ROI) for ingress and egress. These are specified as coordinates relative to the camera's field of view, where (0,0) is the top-left corner and (1,1) is the bottom-right corner.

• For R600s - be sure to include correct video stream UUID.v0 => UUID.v3

• How to get the most accurate point data? Open Dev Tools -> Network, create an "activity region" with 3 points (point 1 and 2 being A & B), and look into the updateFacetedConfig payload. Example shown below.

  
  • Be sure to reset Activity Region once done!