Vehicle Recognition Stream API Setup: C++

Defines

OPENALPRSTREAMDLLEXPORT

namespacealpr

Enums

enumEncodeJpeg

Values:

enumeratorENCODE_NEVER

enumeratorENCODE_PLATES

enumeratorENCODE_ALWAYS

classAlprGroupResult

Public Functions

AlprGroupResult()

~AlprGroupResult()

std::string toJson(bool serialize_crop = false)

Convert the object to JSON

Returna string with JSON data describing the plate groupParameters

• serialize_crop: If enabled, the JPEG crop for the plate will be serialized as base64 in the JSON

void add_uuid(std::string uuid, int plate_index)

Assign a UUID to the group object. Used internally.

Public Members

int64_t epochmstime_start

The time that the first plate in the group was seen.

int64_t epochmstime_end

The time that the final plate in the group was seen.

int64_t frame_start

The first frame in the video stream when this group was active.

int64_t frame_end

The last frame in the video stream when this group was active.

int32_t bestimagewidth

The width of the image (in pixels) for the best_image referenced by this group.

int32_t bestimageheight

The height of the image (in pixels) for the best_image referenced by this group.

std::vector<std::string> image_uuids

The unique identifiers for the individual plates that are part of this group.

std::vector<int> plate_indexes

The plate index in each image.

std::string country

The country (training data code) that was used to recognize the plate.

AlprPlateResult best_plate

the best plate is the topNPlate with the highest confidence

std::vector<AlprPlate> plate_candidates

All other possible plates for this group.

float best_confidence

The ALPR result in the group that had the highest confidence.

std::vector<unsigned char> bestplatejpeg

A full image (encoded as a JPEG) for the frame in the group that had the highest confidence.

std::vector<unsigned char> vehicle_jpeg

A full image (encoded as a JPEG) for the vehicle in the group if vehicle recognition is enabled.

std::string best_uuid

The UUID for the highest confidence plate in the group.

std::string bestplatenumber

The plate number for the highest confidence plate in the group.

std::string best_region

The state/province for the highest confidence plate in the group.

float bestregionconfidence

Confidence of the region detection.

bool matches_template

Whether or not the group matches a regional pattern.

float travel_direction

Direction of motion for the license plate in degrees (clockwise with 0 degrees on top)

bool is_parked

Whether or not the plate number has been spotted recently at the same location.

VehicleResults vehicle_results

Results for vehicle body type, make, model, and color. Requires calling alpr::AlprStream::recognize_vehicle()

std::string agent_type

The type of agent that collected this data (The OpenALPR agent uses “alprd”)

std::string company_id

A unique identifier for the company.

std::string agent_uid

A unique identifier for the agent PC.

float gps_latitude

Latitude position (e.g., from GPS or static configuration)

float gps_longitude

Longitude position (e.g., from GPS or static configuration)

std::string user_data

An optional string specified by the user attached to each result.

int64_t camera_id

A unique identifier for the camera that captured the image.

Public Static Functions

AlprGroupResult fromJson(std::string json_string)

Produces an AlprGroupResult object from JSON.

classAlprStream

Public Functions

AlprStream(int framequeuesize, bool usemotiondetection = true)

Initialize an AlprStream object. An AlprStream object should be initialized for each video input source.

This object is threadsafe.

Parameters

• framequeuesize: The size of the video buffer to be filled by incoming video frames

• usemotiondetection: Whether or not to enable motion detection on this stream

~AlprStream()

int getqueuesize()

Check the size of the video buffer

ReturnThe total number of images waiting to be processed on the video buffer

void connectvideostream_url(std::string url, std::string gstreamerpipelineformat = "")

Spawns a thread that connects to the specified RTSP/MJPEG URL The thread continually fills the processing queue with images from the stream

Parameters

• url: the full URL to be used to connect to the video stream

• gstreamerpipelineformat: An optional override for the GStreamer format. Use {url} for a marker to substitude the url value

std::string getstreamurl()

Get the stream URL.

Returnthe stream URL that is currently being used to stream

void disconnectvideostream()

Disconnect the video stream if you no longer wish for it to push frames to the video buffer.

void connectvideofile(std::string videofilepath, int64_t videostarttime)

Spawns a thread that fills the processing queue with frames from a video file The thread will slow down to make sure that it does not overflow the queue The “videostarttime” is used to us with the epoch start time of of the video

Parameters

• videofilepath: The location on disk to the video file.

• videostarttime: The start time of the video in epoch ms. This time is used as an offset for identifying the epoch time for each frame in the video

void disconnectvideofile()

If you wish to stop the video, calling this function will remove it from the stream

bool videofileactive()

Check the status of the video file thread

ReturnTrue if currently active, false if inactive or complete

double getvideofile_fps()

Get the frames per second for the video file.

int push_frame(std::vector<char> imageBytes, int64_t frameepochtime = -1)

Push an encoded image (e.g., BMP, PNG, JPG, GIF etc). onto the video input buffer.

ReturnThe video input buffer size after adding this image, or -1 if an error occurred decoding the image.Parameters

• imageBytes: The image bytes for the encoded image

• frameepochtime: The time when the image was captured. If not specified current time will be used

int push_frame(unsigned char *pixelData, int bytesPerPixel, int imgWidth, int imgHeight, int64_t frameepochtime = -1)

Push raw image data onto the video input buffer.

ReturnThe video input buffer size after adding this imageParameters

• pixelData: raw image bytes for BGR channels

• bytesPerPixel: Number of bytes for each pixel (e.g., 3)

• imgWidth: Width of the image in pixels

• imgHeight: Height of the image in pixels

• frameepochtime: The time when the image was captured. If not specified current time will be used

void setuuidformat(std::string format)

Sets the format used for generating UUIDs. Default is “{time}-{random}” Valid options are: {time} - epochms time the image was received {frame} - Frame number (starts at 0) {camera}, {companyuuid}, {agentuid} - Any of the values specified in setenv_parameters {random} - a 16 character random string

Parameters

• format: A string containing the UUID format

RecognizedFrame process_frame(Alpr *alpr)

Process the image at the front of the queue and return the individual results. Aggregates the results in a group

ReturnThe results for the recognized frames that was processedParameters

• alpr: The Alpr instance that you wish to use for processing the images

std::vector<RecognizedFrame> process_batch(Alpr *alpr)

Process the image at the front of the queue and return the individual results. This function is most useful when using GPU acceleration. Processing frames in a batch more efficiently uses GPU resources.

You should make sure that the video buffer size for this AlprStream object is greater than or equal to the configured GPU batch size (in openalpr.conf).

ReturnAn array of the results for all recognized frames that were processedParameters

• alpr: The Alpr instance that you wish to use for processing the images

RecognizedFrame skip_frame(bool return_jpeg = false)

Removes a frame from the queue without processing it

ReturnA frame object for the skipped frame. If requested, it may contain the skipped frame JPEG.Parameters

• return_jpeg: Whether or not you wish to encode a JPEG for the skipped frame

std::vector<AlprGroupResult> popcompletedgroups()

If there are any groups that are complete, they will be returned in an array and removed from the grouping queue

Returna vector containing all completed plate groups

std::vector<AlprGroupResult> peekactivegroups()

Checks the grouping list for active groups. Calling this function does not remove any entries from the grouping queue.

Returna full list of all currently active groups.

void combine_grouping(AlprStream *other_stream)

Combine plate grouping across cameras. This is useful if one or more cameras are looking at roughly the same (i.e., from different angles), and you want to combine the group results.

Parameters

• other_stream: another AlprStream pointer for the grouping to be combined

void recognize_vehicle(AlprGroupResult *alpr_group, VehicleClassifier *vehicle_classifier)

Recognize a vehicle for a given group. This operation is computationally more expensive than recognizing a plate.

void setenvparameters(std::string company_id, std::string agent_uid, int camera_id)

Specify unique identifiers that are applied to the result JSON.

void setgroupparameters(int minplatesto_group, int maxplatesper_group, float min_confidence, int maxdeltatime)

Set grouping parameters that control the plate grouping sensitivity

Parameters

• minplatesto_group: A plate group must have at least this number of individual plate reads to form a group.

• maxplatesper_group: At some point, if a plate is seen more than this number of times, it is wrapped into a group and sent even if the plate is still in the frame.

• min_confidence: The plate read must have at least this confidence to be considered for grouping.

• maxdeltatime: The plate group waits this long for another plate to be identified with a similar license plate. If a matching plate is seen, this timer is reset.

void setparkedvehicledetectparams(bool enabled, int64_t maxdeltams, float maxdistancemultiplier, int maxtextdistance)

Parked car detection flags plates that have not moved as being parked. The group results will still be sent, however the group will have a “parked_car” value set to true

Parameters

• enabled: enable or disable detection.

• maxdeltams: The amount of time to wait for considering a car parked (default 120000 ms)

• maxdistancemultiplier: The relative distance from the previous position which we will consider the plate as not having moved. This is a multiplier relative to the plate width (default = 1.5)

• maxtextdistance: The levenshtein distance between plate group results to consider them the same (default = 1)

void setdetectionmask(std::vector<char> imageBytes)

Set a black/white mask to ignore content during motion detection/analysis

see also alpr::Alpr::setMask()

Parameters

• imageBytes: The bytes of an encoded (e.g., JPEG, PNG, BMP, etc) image

void setdetectionmask(unsigned char *pixelData, int bytesPerPixel, int imgWidth, int imgHeight)

void setjpegcompression(int compression_level)

Set the jpeg compression level (between 1-100) for returning images

Parameters

• compression_level: 100 is high quality with a large file size, 1 is low quality with a small file size. Default=85

void setencodejpeg(EncodeJpeg encode_jpeg)

By default, OpenALPR only encodes/returns a JPEG image if a plate is found this setting forces the JPEG encoder to always encode or never encode.

Encoding a JPEG has some performance impact. When processing on GPU, the encoding happens on CPU background threads. Disabling this setting (if the JPEG images are not used) will reduce CPU usage.

If encode_jpeg is set to never, vehicle recognition will not function correctly

This option can be toggled off and on during runtime and will immediately take effect.

Parameters

• encode_jpeg: 0=Never, 1=On Found Plates, 2=Always

void setmotionstickiness(float motion_stickiness)

Configures the motion detection to watch recently moving regions for longer. For highway traffic where vehicles are constantly moving, this should be a lower number For places where the vehicles may stop and start, a higher value will prevent duplicate plate reads

Parameters

• motion_stickiness: A percentage between 0-100 determining how sticky the motion detection should be. 100=very sticky, 0=not sticky. Default=60

int getcameraid()

Get the configured camera ID for this stream.

std::string getagentuid()

Get the configured Agent UID for this stream.

std::string getcompanyid()

Get the configured company ID for this stream.

std::string getuserdata()

Get the configured User Data string for this stream.

StreamStatData getStats()

Get the latest statistic data for this stream.

std::string toJson(const AlprResults plate_read, std::string agent_type = "alprd", bool serialize_crop = false)

Convert the AlprResults to JSON and include extended attributes such as companyid, agentuid, etc. (used internally)

void set_location(float latitude, float longitude)

Specify the current position of the camera (e.g., from GPS or static configuration) The value will be sent along with the alpr_group results

Parameters

• latitude: latitude decimal value

• longitude: longitude decimal value

void setuserdata(const std::string user_data)

Specify an optional string to be applied to every plate/group result. This value will be appended to the JSON result.

Parameters

• user_data: Arbitrary string value to be appended to plate and group results

void setrecordvideo(bool enabled, int maxstoragesize_gb, std::string rollingdbpath)

For H264 streaming video streams over RTSP, optionally record the video to a rolling buffer The camera stream must be configured with “rtsph264” gstreamer_format in order to work.

Parameters

• enabled: enable or disable video recording. Default is disabled

• maxstoragesize_gb: The maximum size of the rolling buffer (in gigabytes)

• rollingdbpath: The path on disk to store the rolling database of video clips

void setmaxfps(int framespersecond)

Specifies a max rate for incoming video. This improves efficiency if the video rate is higher than the available CPU cores can process. This is used for realtime streams, not video files or frame raw inputs. This function must be called prior to initializing the stream

Parameters

• framespersecond: an integer between 1 and 30. A value less than or equal to 0 means unlimited

Public Members

AlprStreamImpl *impl

structRecognizedFrame

Public Members

bool image_available

True if there is an encoded JPEG returned. Otherwise false.

bool queue_empty

True if we attempted to grab a frame, but none was available (empty queue)

std::vector<unsigned char> jpeg_bytes

Encoded JPEG for the frame.

int64_t frameepochtime_ms

The epoch time (in milliseconds) that the image was captured.

int64_t frame_number

A 0-indexed frame number. This count starts when the stream is initialized.

AlprResults results

ALPR recognition results for the frame.

structStreamStatData
#include <alprstream.h>

Contains statistics for measuring the performance of the stream. The values returned show the amount of video entering the stream, the amount of video that contained motion and the amount of moving video that was recognized for license plates.

Public Members

float measurementperiodseconds

The number of seconds between the now and the previous measurement.

float motion_percent

Percent of pixels that had motion compared to total video pixels.

float recognized_percent

Percent of pixels that were recognized compared to total motion pixels.

float video_fps

Average number of frames per second over the measurement period.

float motion_fps

float dropped_fps

float recognition_fps

int64_t videopixelthroughput_ps

Average number of pixels per second over the measurement period.

int64_t motionpixelthroughput_ps

int64_t droppedpixelthroughput_ps

int64_t recognitionpixelthroughput_ps

bool is_streaming

If using alprstream to pull the RTSP/MJPEG stream, this provides stats.

int64_t laststreamupdate