Processors are software modules that work inside a processing pipeline and do various transformations of the frame or its meta-data. The standard processing modules are listed here.

Crop

The crop processor takes a frame, crops the area inside blue rectangle and passes the cropped image to the next processing module. User can define the rectangle area by drawing on a sample frame or set exact values of (x1, y1) - upper left corner and (x2, y2) - lower right corner. Values are in percents of the frame dimensions.

Crop processor

Circle detector basic

This processor locates circles in the frame.

Circle detector basic

The parameters are:

  • Min confidence: If detection confidence is below this value, object will be skipped. Values between 0.1 - 1.

  • Object name: Custom object name.

  • Resize factor: Original image's resolution will be divided by this value before processing to reduce load on CPU. Values between 1 - 20.

  • Min radius: Minimal circle's radius in pixels.

  • Min radius: Maximal circle's radius in pixels.

  • Min distance: Minimal distance between circles' centers in pixels.

  • False circles filter: The higher value, the more circles will be filtered out. Values between 1 - 200.

Equalizer

This filter's purpose is to improve the quality of the image. It normalizes the images by correcting the over- and under-exposed areas and improves the sharpness. The filter can be applied to the whole frame, to the user-defined area or to individual objects.

Equalizer processor

The parameters are:

  • Sharpen amount: This defines amount of sharpening. If the source is sharp enough user can set 0 - the processor will apply normalization only.
  • Sharpen threshold: This parameter limits maximal sharpness of certain areas to avoid oversharpening.
  • Use square area: If filter is applied to the objects only, the area can follow the object's bounding box or always to have a shape of a square around object's bounding box.
  • Box margin: If the filter is applied to the objects only, user can expand area by this number of pixels.
  • Apply to objects: If switched on, the filter will be applied to the area inside objects' bounding boxes. If switched off - to the area inside rectangle defined by x1,y1,x2,y2.
  • Custom active area: User can define the rectangle area by drawing on a sample frame or set exact values of x1, y1 (upper left corner) and x2, y2 (lower right corner). Filter will be applied to the area inside this rectangle.

Event trigger

This processor triggers a custom event if a condition meets.

Event trigger

The parameters are:

  • Event name: Name of the triggered event.
  • Event property: Property format: {property_name: property_value}')
  • Value to check: The name of the filed in meta-data to check.
  • Value suffix: This suffix is added to the end of main value, for example: suffix 'color' results in 'event.properties.color'.
  • Condition function: Formula
  • Reference value: Check the value against this number or string.

Expression

This processor provides direct access to frames’ and detected objects’ meta data. There’re two fields condition and expression. User writes an IF condition and if this condition is true, processor executes the expression.

General expressions processor

Conditions examples:

  • objects.object_name == 'car' This condition returns true, if a detected object’s name is 'car'.

  • objects.properties.heght > 50 This condition returns true for the objects in frame, whose height is higher than 50 pixels

  • frame.properties.objects_in_frame > 3 This condition returns, true for the frame, where the static_counter found more than 3 objects.

  • event.event_name == ‘face_match’ This condition returns true, if an event face_match triggered.

Basically you can check or compare any frames', object's or event's property.

Expression are the actions. They rely on the available functions, that can modify meta-data. Expression examples:

  • add_property(objects.properties, ‘automated_check’, ‘check_passed’) This will add a property to the detected object with the key name 'automated_check' and value 'check_passed'

  • update_value(objects, 'object_name', 'new name') This expression will replace existing object name with the 'new name'

  • add_event(‘custom_event’, confidence=0.8) This expression will add new event with the name 'custom event' and confidence 0.8 (80%).

Expression filter is a simple, yet powerful tool, which allows a user design system’s complex rule-based behavior.

Warning

Don't forget to specify field names and string values within brackets. Correct: objects.object_name == 'car'. Incorrect: objects.object_name == car. In contrast, the paths should be used without brackets. Correct: objects.object_name == 'car'. Incorrect: 'objects.object_name' == 'car'.

General events generator

General events generator

General meter

This processor calculates basic object's parameters and saves them to object's properties.

Measurement of general parameters of an object

General_meter saves following parameters:

  • height: the height of the object's bounding box in pixels

  • width: the width of the object's bounding box in pixels

  • area: height x width

  • brightness: average brightness of the object. 0 meas black and 1 means white

  • speed: average speed of the object in pixels per second

These parameters as stored at object's properties, like objects.properties.height. They are typically used in the expression processor's scripts or for filtering target objects in reports.

Line cross detector

The line_cross tool is an important processor for objects counting, wrong way detection, restricted area protection and similar use cases. User can draw a line right on a sample frame or set exact values for the line: x1, y1 (line beginning) and x2, y2 (line end). Values are in percents of the frame dimensions.

Line cross processor

There can be arbitrary number of lines in one pipeline. User can define a name for a line: line_name, which will be used as a filter or an additional parameter in the reports.

The parameter zone_width shows how wide should be the neutral zone. The processor will register a line_cross event only when an objects crosses this neutral zone completely.

The processor also saves information about the direction. It can be forward or backward and available through reports as events.direction parameter.

Important

The line_cross processor should go after the tracker, because it detects the events when tracking path crosses the line. If line_cross goes before a tracker, there will be no path in meta-data, therefore no line_cross event will be detected.

Object color

The object_color processor extracts major colors of each previously detected object. Information is saved to object's meta-data as properties.colors

Parameter min_color_area defines what area (in percents to the total) should a color take to be recorded as an object's property. For example, if this parameter is 0.3, it means, that if red color takes just 20% of the object's total area, the processor will ignore it. If a color takes 40% - it will save this color as the object's property.

Object color recognition processor

Detected colors are:

black
blue
green
purple
red
white
yellow

The processor can detect and save several colors for a single object.

Object in area

Object in area

Objects filter

This processor allows filtering out unwanted objects using various parameters.

OSD settings module

There are following parameters allows adjusting behaviour of the objects filter processor:

  • min_detection_confidence: Objects with the recognition confidence lower than this value will be dropped.

  • object_max_size: This parameter allows filtering out too big objects. If sum of an object's height and width (in pixels) exceeds this value it will be dropped. 0 means no restrictions.

  • object_min_size: This parameter allows filtering out too small objects. If sum of an object's height and width (in pixels) falls below this value the object will be dropped. 0 means the filter is off.

  • objects_to_exclude: List here unwanted objects' classes using ; and they will be removed from further processing.

  • objects_to_include: Instead of exclude some certain objects you can include only the target object classes and all the rest will be filtered out. Use ; to specify several objects.

  • overlap_suppression_degree: This parameter allows removing overlapping detections, keeping the only one with the highest confidence. Degree defines how close objects intersect to be filtered out. 0.1 means: object needs to intersect slightly another object to be filtered out. And 0.9 means that that object needs to be almost of the same size and at the same location before it will be filtered out.

Rename object

This processor takes names of detected objects and change their names according to the rename_rule. The format should be: original_name > new_name. If there're multiple rules, separate them with ;. Example: name_1 > new_name_1; name_2 > new_name_2.

Object rename processor

Speedometer

Speedometer

Static counter

This processor counts objects within defined rectangle. This number is recoded as a frame's property: frame.properties.objects_in_frame.

Static counter

objects_to_count accepts an object name or a number of object names separated by ;. In this case, the counter will count only the objects with the defined names, ignoring any other object.

Static object generator

Static object generator

General objects tracker

After a new object is detected, the tracking processor assigns a fresh track ID and tracks it across the subsequent frames. Without tracking processor an object detected in each subsequent frame will be saved as a new object.

General tracker

There are following parameters allows adjusting behaviour of the tracking processor:

  • confidence_degrade_rate: If an object is not found in the current frame (occluded, for example), the tracking processor will wait for the next frames, but will reduce the confidence of the track. The higher confidence_degrade_rate parameter, the quicker the confidence drops down, when detector doesn't see the object in the actual frame. As soon as the confidence drops down below the min_confidence, the object's track is finished.

  • max_distance: If an object has moved too far away from the previously detected location, the tracking processor will take that new detection, not as the same object, but as a new one and start new track for it. If you know for sure that an object in your scene can't move faster than a certain speed, you can adjust the max_distance to force the processor to consider two detections in subsequent frames as independent objects, if the distance between them is greater than this value. (Measured as a fraction of frame's width).

  • max_size_difference: If the size of detected object has changed too much from one frame to a subsequent frame, the tracking processor will consider these two detections as two independent objects. With the max_size_difference parameter you define the max possible changes of object's area. (Measured as a ratio of two areas)

  • min_confidence: The track confidence shows how confident the system is that the detection is made correctly. As soon as the confidence drops below this value, the processor closes the track. Usually the confidence drops below this value when system doesn't see the object for certain amount of time. The lower the min_confidence and the lower confidence_degrade_rate, the longer the processor will keep waiting for the object before closing the track.

  • track_length: This parameter defines how long will be an object's track.


Info

This is the list of common processors. BitRefine offers customized processors for solving clients' specific tasks. Custom processors are supplied as separate .zip libraries. Click on the Upload .zip button next to the processor's dropdown list and choose the zipped module. This module will appear in the dropdown list immediately after the upload completed.

Wait for motion

Wait for motion