PEvent Class Reference

Detailed Description

The PEvent class represents an event detected by a video analytics algorithm (PAnalytics); NOT thread-safe.

This class can be inherited.

For instance, SafeZoneEdge2d analytics plugin is an advanced plug-and-play motion detection on video streams. Each time you call Apply() to analyse a frame, it returns a list of PEvent which contains bounding boxes of all detected persons or vehicles (list can be empty is no motion detected).

To build an event, the simplest approach is to use the builder pattern, see following example: PEvent e = PEvent::Create("alarm", "", myDetector.GetId()).Certainty(0.7).Done(); Unless you develop a new PAnalytics plugin, you should not have to build your own events.

Definition at line 43 of file PEvent.h.

#include <PEvent.h>

Member Enumeration Documentation

◆ EEventTimeGranularity

All the available time granularity for events.

Enumerator
E_MILLISECONDS 
E_SECONDS 
E_MINUTES 
E_HOURS 
E_DAYS 
E_UNDEFINED 

Definition at line 49 of file PEvent.h.

Constructor & Destructor Documentation

◆ PEvent() [1/2]

PEvent::PEvent ( )

Constructs an empty event.

The state of the object is the following:

  • EventType is set to empty
  • EventAnnotation is set to empty
  • EventSource is set to PGuid::Null()
  • EventSourceName is set to empty
  • Payload is set to empty
  • EventCertainty is set to 0
  • OccurrenceTime is set to an invalid PDateTime
  • TimeGranularity is set to PEvent::E_UNDEFINED
  • DetectionTime is set to an invalid PDateTime
  • EventId is set to PGuid::Null()
  • EventComposition is set to false
  • Ancestors is set to empty list

◆ PEvent() [2/2]

PEvent::PEvent ( const PEvent other)

Constructs a shared copy of other.

◆ ~PEvent()

virtual PEvent::~PEvent ( )
virtual

Destroys this object.

Member Function Documentation

◆ AddAncestor()

void PEvent::AddAncestor ( const PGuid ancestor)

Add an ancestor for this event.

◆ Create()

static PEventBuilder PEvent::Create ( const PString type,
const PString annotation = PString::Empty(),
const PGuid sourceId = PGuid::Null() 
)
static

Returns a builder object to be able to create any event.

Typical usage is: PEvent e = PEvent::Create("alarm", "", myDetector.GetId()).Certainty(0.7).Done();

The following default parameters are applied:

◆ FromJSON()

PResult PEvent::FromJSON ( const PString jsonString)

Construct PEvent from JSON.

The format of JSON is defined in the schema defined in Event Schema. When constructing an event from JSON the header is fixed. However, the payload can contain any Papillon object. When constructing a PEvent the following rules are applied.

  • All JSON integer are mapped to PInt64
  • All JSON numbers are mapped to PDouble
  • All JSON strings are mapped to PString
  • All PDate or PDateTime timestamps must be in ISO 8601 format and UTC
  • All PGuid must be in correct string format, i.e. five hex-fields separated by '-'.
  • All PImage data must be in base-64 encoded string and compressed with JPG, PNG, TIF, BMP, WEBP, PNM or JP2. It is loaded using PImage::LoadFromBase64().
  • All other Papillon objects must be in base-64 binary serialisation strings

See mirror function PEvent::ToJson()

Parameters
jsonStringThe string in JSON format
Returns
PResult Whether the decoding of JSON into this PEvent was a success.

◆ GetAncestors()

const PList& PEvent::GetAncestors ( ) const

Get a list of all the ancestors for this event.

◆ GetAnnotation()

const PString& PEvent::GetAnnotation ( ) const

Returns the text explanation of what happened in this event.

◆ GetCertainty()

double PEvent::GetCertainty ( ) const

Returns the certainty if this event.

◆ GetComposition()

bool PEvent::GetComposition ( ) const

Does this event have any ancestors.

◆ GetDetectionTime()

const PDateTime& PEvent::GetDetectionTime ( ) const

Returns the detection time of this event, the time at which the event became known to the system.

◆ GetEventId()

const PGuid& PEvent::GetEventId ( ) const

Returns the identifier of this event.

◆ GetOccurrenceTime()

const PDateTime& PEvent::GetOccurrenceTime ( ) const

Returns the time at which the event occurred in the external system.

The precision of this timestamp is given by the event-types temporal granularity.

◆ GetPayload()

const PProperties& PEvent::GetPayload ( ) const

Gets the payload associated with this event (read-only).

◆ GetSource()

const PGuid& PEvent::GetSource ( ) const

Gets the source identifier of this event.

◆ GetSourceName()

const PString& PEvent::GetSourceName ( ) const

Get the friendly name of the source of this event.

◆ GetTimeGranularity()

EEventTimeGranularity PEvent::GetTimeGranularity ( ) const

Returns the time granularity of this event.

◆ GetType()

const PString& PEvent::GetType ( ) const

Returns the event-type of this event.

◆ GetVersion()

int PEvent::GetVersion ( ) const

Get the version number of the event format.

◆ operator=()

PEvent& PEvent::operator= ( const PEvent other)

Performs a shared copy of other to this object.

◆ operator==()

bool PEvent::operator== ( const PEvent other) const

Returns true if this object is the same instance than other, false otherwise.

◆ SetAnnotation()

void PEvent::SetAnnotation ( const PString eventAnnotation)

Sets the event annotation which is a free text explanation of what happened in this event.

◆ SetCertainty()

void PEvent::SetCertainty ( double  eventCertainty)

Sets the event certainty which is an estimate of certainty of this event.

◆ SetComposition()

void PEvent::SetComposition ( bool  eventComposition)

Set if this event is composed or not.

◆ SetDetectionTime()

void PEvent::SetDetectionTime ( const PDateTime detectionTime)

Sets the detection time, the time at which the event became known to the system.

◆ SetEventId()

void PEvent::SetEventId ( const PGuid eventId)

Sets the event identifier.

Should be a system-generated unique ID for this event.

◆ SetOccurrenceTime()

void PEvent::SetOccurrenceTime ( const PDateTime occurrenceTime)

Sets the time at which the event occurred in the external system.

The precision of this timestamp is given by the event-types temporal granularity.

◆ SetPayload()

PProperties& PEvent::SetPayload ( ) const

Returns the internal payload of this event; can be used to store any event specific information here.

◆ SetSource()

void PEvent::SetSource ( const PGuid sourceId)

Sets the source identifier of this event.

◆ SetSourceName()

void PEvent::SetSourceName ( const PString sourceName)

Set a friendly name for the source of this event.

◆ SetTimeGranularity()

void PEvent::SetTimeGranularity ( EEventTimeGranularity  eventGranularity)

Sets the precision of the any date/times in this event.

◆ SetType()

void PEvent::SetType ( const PString eventType) const

Sets the event-type of this event.

The event-type uniquely identifies the type of event we are dealing with.

◆ ToJSON()

PString PEvent::ToJSON ( const PStringList includeKeysFromPayload = PStringList()) const

Get the event as a JSON string.

The schema of the JSON is defined Event Schema. The schema has two parts a header and payload. The payload of events can store any Papillon object. When converting the payload to JSON the following rules are applied.

  • PBool mapped to JSON boolean,
  • PInt8, PUInt8, PInt16, PUInt16, PInt32, PUInt32, PInt64, PUInt64 are mapped to JSON integer
  • PFloat and PDouble are mapped to JSON number
  • PString are mapped are mapped to JSON string

All other Papillon objects are stored as JSON objects, with two fields. A type which is the Papillon class-name and a value which is a representation of that object. Note, the following rules are applied when saving the objects to the value field.

  • PImage is saved as base-64 encoded JPG string - using PImage::ToJpegBase64()
  • PDate and PDateTime are saved as a string in ISO 8601 format and UTC
  • PGuid is saved as a string
  • All other Papillon Objects are stored as base-64 encoded binary serialisation strings.

See mirror function PEvent::FromJson()

Parameters
includeKeysFromPayloadIf this is specified, only include the data from the specified keys in the payload. If it is not specified, all keys are saved.
Returns
PString A string in JSON format

Friends And Related Function Documentation

◆ PEventBuilder

friend class PEventBuilder
friend

Definition at line 303 of file PEvent.h.

◆ PEventImpl

friend class PEventImpl
friend

Definition at line 304 of file PEvent.h.