SimpleLPR Python API Reference Guide

Table of Contents

1. Overview
2. Installation and Setup
3. Core Classes
   • SimpleLPR (Engine)
   • Processor
   • ProcessorPool
4. Video Processing
   • VideoSource
   • VideoFrame
5. Plate Tracking
   • PlateCandidateTracker
   • TrackedPlateCandidate
   • PlateCandidateTrackerResult
6. Data Structures
   • Candidate
   • Match (CountryMatch)
   • Element
7. Configuration Classes
   • EngineSetupParms
   • PlateCandidateTrackerSetupParms
8. Utility Classes
   • Point
   • Rectangle
   • VersionNumber
   • ErrorInfo
9. Enumerations
   • FrameFormat
   • VideoSourceState
10. Constants
11. Error Handling
12. Threading Considerations

Overview

SimpleLPR is an Automatic Number Plate Recognition (ANPR) library that provides powerful license plate detection and recognition capabilities. The Python wrapper pySimpleLPR3 exposes the full functionality of the native SimpleLPR library through a clean, Pythonic interface.

Key Features

• Real-time license plate detection and recognition
• Support for multiple countries and plate formats
• Video stream processing (files, RTSP streams, cameras)
• Multi-threaded processing with processor pools
• Plate tracking across video frames
• Confidence scoring and character-level analysis

Installation and Setup

SimpleLPR can be easily installed from PyPI:

pip install simplelpr

Requirements

• 64-bit Python 3.8, 3.9, 3.10, 3.11, or 3.12
• Windows (x64) or Linux (x64)
• Valid license key for production use (60-day evaluation period available)

Basic Usage

import simplelpr

# Basic engine setup
setup_params = simplelpr.EngineSetupParms()
engine = simplelpr.SimpleLPR(setup_params)

# Set license key
engine.set_productKey("path/to/license.xml")
# or from bytes
# with open("license.xml", "rb") as f:
#     engine.set_productKey(f.read())

Note: The PyPI version (pip install simplelpr) does not include CUDA GPU acceleration support. For CUDA support, use the SDK version with the pySimpleLPR3 module.

Core Classes

SimpleLPR (Engine)

The main engine class that serves as the entry point for all SimpleLPR functionality.

Constructor

SimpleLPR(parms: EngineSetupParms)
SimpleLPR(parms: EngineSetupParms, nativeFolderPath: str)

Parameters:

• parms: Engine setup parameters
• nativeFolderPath: Optional path to native library folder

Properties

versionNumber: VersionNumber (read-only)

Returns the version number of the SimpleLPR library.

numSupportedCountries: int (read-only)

Returns the number of supported countries for license plate recognition.

Methods

set_productKey(productKeyPath: str) -> None

set_productKey(productKey: bytes) -> None

Sets the product key from a file path or byte array.

Parameters:

• productKeyPath: Path to the license file
• productKey: License data as bytes

get_countryCode(id: int) -> str

Returns the string identifier for a country by its index.

Parameters:

• id: Country index (0 to numSupportedCountries-1)

Returns: Country string identifier (e.g., "Spain", "Germany")

get_countryWeight(id: int) -> float

get_countryWeight(id: str) -> float

Gets the relative weight of a country used for breaking ties when a candidate matches multiple countries.

Parameters:

• id: Country index or string identifier

Returns: Country weight (0.0 to disable, higher values for preference)

set_countryWeight(id: int, weight: float) -> None

set_countryWeight(id: str, weight: float) -> None

Sets the relative weight of a country.

Parameters:

• id: Country index or string identifier
• weight: Country weight (≥ 0.0, use 0.0 to disable)

realizeCountryWeights() -> None

Builds internal country verification lookup tables. Call after configuring country weights.

Note: This method can be time-consuming depending on countries selected.

openVideoSource(uri: str, format: FrameFormat, maxWidthCap: int = -1, maxHeightCap: int = -1) -> VideoSource

Opens a video source from URI with optional frame rescaling.

Parameters:

• uri: Video source location (file path, RTSP URL, etc.)
• format: Desired color format for frames
• maxWidthCap: Maximum frame width (-1 for no limit)
• maxHeightCap: Maximum frame height (-1 for no limit)

Returns: VideoSource object for frame access

createProcessor() -> Processor

Creates a new processor for license plate recognition.

Returns: Processor instance

Note: Each thread should use its own processor instance.

createProcessorPool(cProcessors: int = 0) -> ProcessorPool

Creates a processor pool for concurrent processing.

Parameters:

• cProcessors: Number of processors (0 = auto-detect based on CPU cores)

Returns: ProcessorPool instance

createPlateCandidateTracker(parms: PlateCandidateTrackerSetupParms) -> PlateCandidateTracker

Creates a plate candidate tracker for video processing.

Parameters:

• parms: Tracker configuration parameters

Returns: PlateCandidateTracker instance

Processor

Provides license plate recognition functionality for single-threaded processing.

Properties

numSupportedCountries: int (read-only)

Number of supported countries.

contrastSensitivityFactor: float (read/write)

Contrast sensitivity factor (0.0-1.0). Lower values help with shadows, higher values for normal conditions.

plateRegionDetectionEnabled: bool (read/write)

Enables/disables plate region detection and extraction.

cropToPlateRegionEnabled: bool (read/write)

Enables/disables cropping results to detected plate region.

Methods

analyze(imgPath: str) -> List[Candidate]

Analyzes an image file for license plates.

Parameters:

• imgPath: Path to image file (.jpg, .png, .tif)

Returns: List of detected license plate candidates

analyze(imgBuf: buffer) -> List[Candidate]

Analyzes an image from memory buffer.

Parameters:

• imgBuf: Image data supporting Python buffer protocol (numpy array, bytes, etc.)

Returns: List of detected license plate candidates

Country Management Methods

Same as SimpleLPR engine:

• get_countryCode(id: int) -> str
• get_countryWeight(id: int) -> float
• set_countryWeight(id: int, weight: float) -> None
• realizeCountryWeights() -> None

ProcessorPool

Provides multi-threaded license plate recognition using a pool of processors.

Properties

numSupportedCountries: int (read-only)

Number of supported countries.

contrastSensitivityFactor: float (read/write)

Contrast sensitivity factor for all processors in the pool.

plateRegionDetectionEnabled: bool (read/write)

Enables/disables plate region detection for all processors.

cropToPlateRegionEnabled: bool (read/write)

Enables/disables crop to plate region for all processors.

Methods

launchAnalyze(streamId: int, requestId: int, timestampInSec: float, timeoutInMs: int, imgPath: str) -> bool

Launches asynchronous analysis of an image file.

Parameters:

• streamId: Stream identifier for grouping related requests
• requestId: Unique request identifier
• timestampInSec: Image timestamp in seconds
• timeoutInMs: Timeout for getting an available processor
• imgPath: Path to image file

Returns: True if analysis launched successfully

launchAnalyze(streamId: int, requestId: int, timeoutInMs: int, frame: VideoFrame) -> bool

launchAnalyze(streamId: int, requestId: int, timeoutInMs: int, frame: VideoFrame, roi: Rectangle) -> bool

Launches asynchronous analysis of a video frame.

Parameters:

• streamId: Stream identifier
• requestId: Unique request identifier
• timeoutInMs: Timeout for getting processor
• frame: VideoFrame to analyze
• roi: Optional region of interest

Returns: True if analysis launched successfully

launchAnalyze(streamId: int, requestId: int, timestampInSec: float, timeoutInMs: int, imgBuf: buffer) -> bool

Launches asynchronous analysis of image from buffer.

Parameters:

• streamId: Stream identifier
• requestId: Unique request identifier
• timestampInSec: Image timestamp
• timeoutInMs: Timeout for getting processor
• imgBuf: Image buffer

Returns: True if analysis launched successfully

pollNextResult(streamId: int, timeoutInMs: int) -> ProcessorPoolResult | None

Retrieves the next available analysis result.

Parameters:

• streamId: Stream ID to get results for (STREAM_ID_ANY for any stream)
• timeoutInMs: Timeout for waiting for result

Returns: ProcessorPoolResult or None if timeout

ongoingRequestCount_get(streamId: int) -> int

Gets the number of ongoing analysis requests.

Parameters:

• streamId: Stream ID to count (STREAM_ID_ANY for all streams)

Returns: Number of ongoing requests

Country Management Methods

Same as SimpleLPR engine and Processor.

Video Processing

VideoSource

Provides access to video frames from various sources (files, streams, cameras).

Properties

isLiveSource: bool (read-only)

Indicates if the source is a live stream (True) or file (False).

state: VideoSourceState (read-only)

Current state of the video source.

Methods

nextFrame() -> VideoFrame | None

Retrieves the next video frame.

Returns: VideoFrame object or None if no frame available

reconnect() -> None

Attempts to reconnect live sources in error states. No effect on file sources.

VideoFrame

Represents a single video frame with metadata and pixel data.

Properties

sequenceNumber: int (read-only)

Unique sequential number of the frame within the video stream.

timestamp: float (read-only)

Frame timestamp in seconds since video start.

format: FrameFormat (read-only)

Color format of the video frame.

width: int (read-only)

Frame width in pixels.

height: int (read-only)

Frame height in pixels.

widthStep: int (read-only)

Number of bytes between consecutive row starts.

data: capsule (read-only)

Pointer to raw pixel data.

Methods

saveAsJPEG(imgPath: str, quality: int = -1) -> None

Saves the frame as a JPEG file.

Parameters:

• imgPath: Output file path
• quality: JPEG quality (-1 for default, 0-100)

Buffer Protocol Support

VideoFrame supports Python's buffer protocol, allowing direct access to pixel data:

import numpy as np
frame_array = np.array(video_frame, copy=False)

Plate Tracking

PlateCandidateTracker

Tracks license plate candidates across multiple video frames, providing temporal correlation resistant to OCR errors.

Methods

processFrameCandidates(frameId: int, timestampInSec: float, processorPoolResult: ProcessorPoolResult) -> PlateCandidateTrackerResult

Processes candidates from a frame without image data.

Parameters:

• frameId: Unique frame identifier
• timestampInSec: Frame timestamp
• processorPoolResult: Result from ProcessorPool.pollNextResult()

Returns: Tracking results with new and closed tracks

processFrameCandidates(processorPoolResult: ProcessorPoolResult, frame: VideoFrame) -> PlateCandidateTrackerResult

Processes candidates with video frame for thumbnail extraction.

Parameters:

• processorPoolResult: Result from ProcessorPool.pollNextResult()
• frame: Video frame for thumbnail extraction

Returns: Tracking results with new and closed tracks

processFrameCandidates(frameId: int, timestampInSec: float, processorPoolResult: ProcessorPoolResult, format: FrameFormat, imgBuf: buffer) -> PlateCandidateTrackerResult

Processes candidates with raw image data for thumbnail extraction.

Parameters:

• frameId: Unique frame identifier
• timestampInSec: Frame timestamp
• processorPoolResult: Result from ProcessorPool.pollNextResult()
• format: Image format specification
• imgBuf: Raw image data buffer

Returns: Tracking results with new and closed tracks

flush() -> PlateCandidateTrackerResult

Forces tracker to close all active tracks.

Returns: Results containing all closed tracks

TrackedPlateCandidate

Represents a license plate tracked across multiple video frames.

Properties

firstDetectionFrameId: int

Frame ID of the first detection.

firstDetectionTimestamp: float

Timestamp of the first detection in seconds.

newestDetectionFrameId: int

Frame ID of the most recent detection.

newestDetectionTimestamp: float

Timestamp of the most recent detection in seconds.

representativeFrameId: int

Frame ID of the representative detection.

representativeTimestamp: float

Timestamp of the representative frame in seconds.

representativeCandidate: Candidate

Best license plate candidate from this track.

representativeThumbnail: VideoFrame | None

Thumbnail image of the plate from representative frame.

PlateCandidateTrackerResult

Contains the results of plate tracking operations.

Properties

newTracks: List[TrackedPlateCandidate]

Collection of new tracks that met trigger criteria.

closedTracks: List[TrackedPlateCandidate]

Collection of tracks closed due to inactivity or other criteria.

Data Structures

Candidate

Represents a detected license plate candidate.

Properties

darkOnLight: bool

True if plate has dark text on light background.

plateDetectionConfidence: float

Confidence that candidate is a license plate vs. scene text (-1 if detection disabled).

boundingBox: Rectangle

Bounding box of the text in pixel coordinates.

plateRegionVertices: List[Point]

Four vertices of detected plate region (or -1 coordinates if not detected).

matches: List[Match]

List of possible country matches. Last entry is raw text before country validation.

Match (CountryMatch)

Represents a possible country match for a license plate candidate.

Properties

country: str

Country code string.

countryISO: str

Country ISO Alpha-2 code.

text: str

Unicode representation of the license plate string.

confidence: float

Overall recognition confidence (product of element confidences).

boundingBox: Rectangle

Bounding box of the text in pixel coordinates.

elements: List[Element]

Information about individual characters in reading order.

Element

Represents a candidate character in a license plate.

Properties

glyph: str

Unicode representation of the character.

confidence: float

Recognition confidence (0-1 range, not a probability).

boundingBox: Rectangle

Bounding box of the character in pixel coordinates.

Configuration Classes

EngineSetupParms

Configuration parameters for SimpleLPR engine initialization.

Properties

cudaDeviceId: int

CUDA device identifier (-1 for CPU mode).

Note: CUDA support is only available in the SDK version, not the PyPI package.

enableImageProcessingWithGPU: bool

Enable GPU for image processing tasks.

Note: GPU features are only available in the SDK version, not the PyPI package.

enableClassificationWithGPU: bool

Enable GPU for candidate classification.

Note: GPU features are only available in the SDK version, not the PyPI package.

maxConcurrentImageProcessingOps: int

Maximum concurrent image processing operations (0 for automatic).

Recommended values:

• CPU mode: 1-2 concurrent operations (PyPI version)
• GPU mode: 4+ concurrent operations (SDK version only)

PlateCandidateTrackerSetupParms

Configuration parameters for plate candidate tracking.

Constructor

PlateCandidateTrackerSetupParms(
    triggerWindowInSec: float = 3.0,
    maxIdleTimeInSec: float = 3.5, 
    minTriggerFrameCount: int = 3,
    thumbnailWidth: int = 256,
    thumbnailHeight: int = 128
)

Properties

triggerWindowInSec: float

Time window for track triggering (default: 3.0 seconds).

maxIdleTimeInSec: float

Maximum idle time before track closure (default: 3.5 seconds).

minTriggerFrameCount: int

Minimum detections needed to trigger track (default: 3).

thumbnailWidth: int

Target thumbnail width in pixels (default: 256, -1 for uncapped).

thumbnailHeight: int

Target thumbnail height in pixels (default: 128, -1 for uncapped).

Utility Classes

Point

Represents a 2D point with integer coordinates.

Properties

• x: int - X coordinate
• y: int - Y coordinate

Rectangle

Represents a rectangle with integer coordinates.

Properties

• left: int - Left edge X coordinate
• top: int - Top edge Y coordinate
• width: int - Rectangle width
• height: int - Rectangle height

VersionNumber

Represents a version number with four components.

Properties

• A: int - Generation number
• B: int - Major version
• C: int - Minor version
• D: int - Patch version

ErrorInfo

Contains error information when operations fail.

Properties

errorCode: int (read-only)

HRESULT-style error code.

description: str (read-only)

Textual error description.

ProcessorPoolResult

Contains the result of an asynchronous processor pool operation.

Properties

streamId: int (read-only)

Stream identifier for the request.

requestId: int (read-only)

Unique request identifier.

timestamp: float (read-only)

Timestamp of the analyzed image/frame.

errorInfo: ErrorInfo | None (read-only)

Error information if analysis failed.

candidates: List[Candidate] (read-only)

Detected license plate candidates if analysis succeeded.

Enumerations

FrameFormat

Specifies video frame color formats.

• FRAME_FORMAT_GRAY8 - 8-bit grayscale
• FRAME_FORMAT_BGR24 - 24-bit Blue-Green-Red

VideoSourceState

Represents video source states.

• VIDEO_SOURCE_STATE_INIT - Initial state
• VIDEO_SOURCE_STATE_OPEN - Successfully opened
• VIDEO_SOURCE_STATE_EOF - End of file/stream reached
• VIDEO_SOURCE_STATE_IO_ERROR - Input/output error
• VIDEO_SOURCE_STATE_ERROR - General error

Constants

Processor Pool Constants

• TIMEOUT_INFINITE = -1 - Wait indefinitely
• TIMEOUT_IMMEDIATE = 0 - Return immediately (non-blocking)
• STREAM_ID_ANY = -1 - Match any stream ID

Error Handling

SimpleLPR uses exceptions for error handling. Common scenarios:

try:
    engine = pySimpleLPR3.SimpleLPR(setup_params)
    engine.set_productKey("license.xml")
    processor = engine.createProcessor()
    candidates = processor.analyze("image.jpg")
except Exception as e:
    print(f"SimpleLPR error: {e}")

For ProcessorPool operations, check the errorInfo property of results:

result = pool.pollNextResult(0, pySimpleLPR3.TIMEOUT_INFINITE)
if result.errorInfo:
    print(f"Analysis failed: {result.errorInfo.description}")
else:
    print(f"Found {len(result.candidates)} plates")

Threading Considerations

Thread Safety

• SimpleLPR engine: Thread-safe for most operations
• Processor: Not thread-safe - each thread needs its own instance
• ProcessorPool: Thread-safe, designed for concurrent use
• VideoSource: Not thread-safe - use one per thread
• PlateCandidateTracker: Not thread-safe - use one per thread

Best Practices

• Create one SimpleLPR engine per application
• Use ProcessorPool for multi-threaded scenarios
• Create separate Processor instances for each thread in single-threaded scenarios
• Configure country weights at the engine level when possible (more efficient than per-processor)

Memory Management

All objects use automatic memory management through reference counting. No manual cleanup required in Python.

Performance Tips

1. Country Selection: Disable unused countries with set_countryWeight(country, 0.0) to improve performance
2. Region of Interest: Use ROI in video processing to focus on relevant areas
3. Concurrent Processing: Use ProcessorPool for processing multiple images simultaneously
4. Image Preprocessing: Consider resizing very large images before analysis
5. Batch Processing: Process multiple images through ProcessorPool rather than sequential Processor calls

This completes the SimpleLPR Python API Reference Guide. The next step would be creating a Quick Start Guide with tutorials and practical examples.