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 framesusemotiondetection: Whether or not to enable motion detection on this stream
~AlprStream()
int getqueuesize()
Check the size of the video buffer
**Return**The 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 streamgstreamerpipelineformat: An optional override for the GStreamer format. Use {url} for a marker to substitude the url value
std::string getstreamurl()
Get the stream URL.
**Return**the 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
**Return**True 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 imageframeepochtime: 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 channelsbytesPerPixel: Number of bytes for each pixel (e.g., 3)imgWidth: Width of the image in pixelsimgHeight: Height of the image in pixelsframeepochtime: 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
**Return**a 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.
**Return**a 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 valuelongitude: 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 disabledmaxstoragesize_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
