# C++

**Defines**

`OPENALPRSTREAMDLLEXPORT`

***namespace***`alpr`

Enums

***enum***`EncodeJpeg`

*Values:*

***enumerator***`ENCODE_NEVER`

***enumerator***`ENCODE_PLATES`

***enumerator***`ENCODE_ALWAYS`

***class***`AlprGroupResult`

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**](http://doc.openalpr.com/api.html#_CPPv4N4alpr15AlprPlateResultE) `best_plate`

the best plate is the topNPlate with the highest confidence

**std::vector<**[**AlprPlate**](http://doc.openalpr.com/api.html#_CPPv4N4alpr9AlprPlateE)**>** `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()](http://doc.openalpr.com/api.html#classalpr_1_1AlprStream_1ae34d353568022e318be9b11cb34f5dfb)

**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**](http://doc.openalpr.com/api.html#_CPPv4N4alpr15AlprGroupResultE) `fromJson`(std::string *json\_string*)

Produces an [AlprGroupResult](http://doc.openalpr.com/api.html#classalpr_1_1AlprGroupResult) object from JSON.

***class***`AlprStream`

Public Functions

`AlprStream`(int *framequeuesize*, bool *usemotiondetection* = true)

Initialize an [AlprStream](http://doc.openalpr.com/api.html#classalpr_1_1AlprStream) object. An [AlprStream](http://doc.openalpr.com/api.html#classalpr_1_1AlprStream) 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

\*\*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 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.

\*\*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 “video*start*time” 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 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} - epoch*ms time the image was received {frame} - Frame number (starts at 0) {camera}, {company*uuid}, {agent*uid} - Any of the values specified in set*env\_parameters {random} - a 16 character random string

**Parameters**

* `format`: A string containing the UUID format

[**RecognizedFrame**](http://doc.openalpr.com/api.html#_CPPv4N4alpr15RecognizedFrameE) `process_frame`([Alpr](http://doc.openalpr.com/api.html#_CPPv4N4alpr4AlprE) \**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](http://doc.openalpr.com/api.html#classalpr_1_1Alpr) instance that you wish to use for processing the images

**std::vector<**[**RecognizedFrame**](http://doc.openalpr.com/api.html#_CPPv4N4alpr15RecognizedFrameE)**>** `process_batch`([Alpr](http://doc.openalpr.com/api.html#_CPPv4N4alpr4AlprE) \**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](http://doc.openalpr.com/api.html#classalpr_1_1AlprStream) 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](http://doc.openalpr.com/api.html#classalpr_1_1Alpr) instance that you wish to use for processing the images

[**RecognizedFrame**](http://doc.openalpr.com/api.html#_CPPv4N4alpr15RecognizedFrameE) `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**](http://doc.openalpr.com/api.html#_CPPv4N4alpr15AlprGroupResultE)**>** `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**](http://doc.openalpr.com/api.html#_CPPv4N4alpr15AlprGroupResultE)**>** `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](http://doc.openalpr.com/api.html#_CPPv4N4alpr10AlprStreamE) \**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](http://doc.openalpr.com/api.html#classalpr_1_1AlprStream) pointer for the grouping to be combined

**void** `recognize_vehicle`([AlprGroupResult](http://doc.openalpr.com/api.html#_CPPv4N4alpr15AlprGroupResultE) \**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()](http://doc.openalpr.com/api.html#classalpr_1_1Alpr_1a6fa6879edb1bb62ebb3623cd108823b8)

**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](http://doc.openalpr.com/api.html#_CPPv4N4alpr10EncodeJpegE) *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**](http://doc.openalpr.com/api.html#_CPPv4N4alpr14StreamStatDataE) `getStats`()

Get the latest statistic data for this stream.

**std::string** `toJson`(*const* [AlprResults](http://doc.openalpr.com/api.html#_CPPv4N4alpr11AlprResultsE) *plate\_read*, std::string *agent\_type* = "alprd", bool *serialize\_crop* = false)

Convert the [AlprResults](http://doc.openalpr.com/api.html#classalpr_1_1AlprResults) to JSON and include extended attributes such as company*id, agent*uid, 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`

***struct***`RecognizedFrame`

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**](http://doc.openalpr.com/api.html#_CPPv4N4alpr11AlprResultsE) `results`

ALPR recognition results for the frame.

***struct***`StreamStatData`\
\&#xNAN;*#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`