Alarms

Alarms allow BrainFrame to notify you when a specified condition happens within a zone. When the conditions for an alarm are met, the alarm generates alerts which contain the time at which the conditions occurred as well as a frame from the video at that time. See the Alarms section in the User Manual for details.

API Methods

BrainFrameAPI.get_zone_alarm(alarm_id, timeout=30) → brainframe.api.bf_codecs.alarm_codecs.ZoneAlarm

Gets the zone alarm with the given ID.

Parameters

  • alarm_id – The ID of the alarm to get

  • timeout – The timeout to use for this request

Returns

The alarm

BrainFrameAPI.get_zone_alarms(stream_id: Optional[int] = None, zone_id: Optional[int] = None, timeout=30) → List[brainframe.api.bf_codecs.alarm_codecs.ZoneAlarm]

Gets all zone alarms that fit the given filters.

Parameters

  • stream_id – If supplied, only zone alarms that are for a zone in this stream will be returned

  • zone_id – if supplied, only zone alarms attached to this zone will be returned

  • timeout – The timeout to use for this request

Returns

Zone alarms

BrainFrameAPI.set_zone_alarm(alarm: brainframe.api.bf_codecs.alarm_codecs.ZoneAlarm, timeout=30) → brainframe.api.bf_codecs.alarm_codecs.ZoneAlarm

Creates or updates a zone alarm.

A new zone alarm is created if the given zone alarm’s ID is None.

Parameters

  • alarm – The zone alarm to create or update

  • timeout – The timeout to use for this request

Returns

Created or updated zone alarm

BrainFrameAPI.delete_zone_alarm(alarm_id, timeout=30)

Deletes the zone alarm with the given ID.

Parameters

  • alarm_id – The ID of the zone alarm to delete

  • timeout – The timeout to use for this request

BrainFrameAPI.get_alert(alert_id, timeout=30) → brainframe.api.bf_codecs.alarm_codecs.Alert

Gets the alert with the given ID.

Parameters

  • alert_id – The ID of the alert to get

  • timeout – The timeout to use for this request

Returns

The alert

BrainFrameAPI.get_alerts(stream_id: Optional[int] = None, zone_id: Optional[int] = None, alarm_id: Optional[int] = None, verification: Optional[brainframe.api.stubs.alerts.AlertStubMixin.AlertVerificationQueryType] = <AlertVerificationQueryType.ALL: 7>, limit: Optional[int] = None, offset: Optional[int] = None, timeout=30) → Tuple[List[brainframe.api.bf_codecs.alarm_codecs.Alert], int]

Gets all alerts that match a query

Parameters

  • stream_id – The ID of the stream to get alerts for

  • zone_id – The ID of the zone to get alerts for

  • alarm_id – The ID of the alarm to get alerts for

  • verification – The verification states of the alerts

  • limit – The maximum number of alerts to return. If None, no limit will be applied

  • offset – The offset from the most recent alerts to return. This is only useful when providing a limit.

  • timeout – The timeout to use for this request

Returns

A list of alerts, and the total number of alerts that fit this criteria, ignoring pagination (the limit and offset)

BrainFrameAPI.set_alert_verification(alert_id, verified_as: bool, timeout=30)

Sets an alert verified as True or False.

Parameters

  • alert_id – The ID of the alert to set

  • verified_as – Set verification to True or False

  • timeout – The timeout to use for this request

Returns

The modified Alert

BrainFrameAPI.get_alert_frame(alert_id: int, timeout=30) → Optional[numpy.ndarray]

Returns the frame saved for this alert, or None if no frame is recorded for this alert.

Parameters

  • alert_id – The ID of the alert to get a frame for.

  • timeout – The timeout to use for this request

Returns

The image as loaded by OpenCV, or None

Data Structures

class Alert(alarm_id: int, zone_id: int, stream_id: int, start_time: float, end_time: Optional[float], verified_as: Optional[bool], id: Optional[int] = None)

This is sent when an Alarm has been triggered.

alarm_id: int

The ID of the alarm that this alert came from

end_time: Optional[float]

When the event stopped happening, in Unix Time (seconds), or None if the alert is ongoing.

id: Optional[int] = None

A unique identifier

start_time: float

When the event started happening, in Unix Time (seconds)

stream_id: int

The ID of the stream this alert pertains to

verified_as: Optional[bool]

  • If True, then this alert was labeled by a person as legitimate

  • If False, then this alert was labeled by a person as a false alarm

  • If None, then this alert has not been reviewed by a person

zone_id: int

The ID of the zone this alert pertains to

class ZoneAlarm(name: str, count_conditions: List[brainframe.api.bf_codecs.condition_codecs.ZoneAlarmCountCondition], rate_conditions: List[brainframe.api.bf_codecs.condition_codecs.ZoneAlarmRateCondition], use_active_time: bool, active_start_time: str, active_end_time: str, id: Optional[int] = None, zone_id: Optional[int] = None, stream_id: Optional[int] = None)

This is the configuration for an alarm.

active_end_time: str

The time of day where this alarm starts being active, in the format “hh:mm:ss”

active_start_time: str

The time of day where this alarm starts being active, in the format “hh:mm:ss”

count_conditions: List[ZoneAlarmCountCondition]

All count conditions for this alarm

id: Optional[int] = None

A unique identifier

name: str

A friendly name for the zone alarm

rate_conditions: List[ZoneAlarmRateCondition]

All rate conditions for this alarm

stream_id: Optional[int] = None

The ID of the stream the associated zone is in

use_active_time: bool

If True, the alarm will only be triggered when the current time is between the active_start_time and active_end_time.

zone_id: Optional[int] = None

The ID of the zone this alarm is associated with

class IntersectionPointType(value)

The point on a detection that must be inside a zone for the detection to count as being inside the zone. The most commonly used intersection point is BOTTOM, which counts a detection as being inside a zone if the bottom center point of the detection in the zone.

class ZoneAlarmCountCondition(test: brainframe.api.bf_codecs.condition_codecs.ZoneAlarmCountCondition.TestType, check_value: int, with_class_name: str, with_attribute: Optional[brainframe.api.bf_codecs.detection_codecs.Attribute], window_duration: float, window_threshold: float, intersection_point: brainframe.api.bf_codecs.condition_codecs.IntersectionPointType, id: Optional[int] = None)

A condition that must be met for an alarm to go off. Compares the number of objects in a zone to some number.

class TestType(value)

Defines the way a count condition compares the actual value to the alarm’s test value.

classmethod values()
check_value: int

The value to test the actual count against

id: Optional[int] = None

A unique identifier

intersection_point: IntersectionPointType

The point in each detection that must be within the zone in order for that detection to be counted as in that zone

test: TestType

The way that the check value will be compared to the actual count

window_duration: float

The sliding window duration for this condition

window_threshold: float

The portion of time during the sliding window duration that this condition must be true in order for the associated alarm to trigger

with_attribute: Optional[Attribute]

If provided, only objects that have this attribute value will be counted.

with_class_name: str

The class name of the objects to count

class ZoneAlarmRateCondition(test: brainframe.api.bf_codecs.condition_codecs.ZoneAlarmRateCondition.TestType, duration: float, change: float, direction: brainframe.api.bf_codecs.condition_codecs.ZoneAlarmRateCondition.DirectionType, with_class_name: str, with_attribute: Optional[brainframe.api.bf_codecs.detection_codecs.Attribute], intersection_point: brainframe.api.bf_codecs.condition_codecs.IntersectionPointType, id: int = None)

A condition that must be met for an alarm to go off. Compares the rate of change in the count of some object against a test value.

class DirectionType(value)

Defines the direction of flow that a rate condition pertains to.

classmethod values()
class TestType(value)

Defines the way a rate condition compares the actual rate value to the alarm’s test value.

classmethod values()
change: float

The rate change value to compare the actual rate value against

direction: DirectionType

The direction of flow this condition tests for

duration: float

The time in seconds for this rate change to occur

id: int = None

A unique identifier

intersection_point: IntersectionPointType

The point in each detection that must be within the zone in order for that detection to be counted as in that zone

test: TestType

The way that the change value will be compared to the actual rate

with_attribute: Optional[Attribute]

If provided, only objects that have this attribute will be counted in the rate calculation

with_class_name: str

The class name of the objects to measure rate of change for