Update

Author: yushulx

README.md

@@ -1,5 +1,5 @@
 # Python 1D/2D Barcode SDK
-A Python wrapper for the [Dynamsoft Barcode Reader SDK](https://www.dynamsoft.com/barcode-reader/overview/), providing user-friendly APIs across **Windows**, **Linux**, and **macOS**. Compatible with desktop PCs, embedded devices, **Raspberry Pi**, and **Jetson Nano**.
+A Python wrapper for the [Dynamsoft Barcode Reader SDK](https://www.dynamsoft.com/barcode-reader/overview/), providing simple and user-friendly APIs across **Windows**, **Linux**, and **macOS**. Compatible with desktop PCs, embedded devices, **Raspberry Pi**, and **Jetson Nano**.
 
 > **Note**: This is an unofficial, community-maintained wrapper. For official support and full feature coverage, consider the [Dynamsoft Capture Vision Bundle](https://pypi.org/project/dynamsoft-capture-vision-bundle/) on PyPI.
 
@@ -14,10 +14,11 @@ A Python wrapper for the [Dynamsoft Barcode Reader SDK](https://www.dynamsoft.co
 | Feature | Community Wrapper | Official Dynamsoft SDK |
 |---------|------------------|------------------------|
 | **Support** | Community-driven | ✅ Official Dynamsoft support |
-| **Documentation** | Basic README | ✅ Comprehensive online docs |
-| **API Coverage** | Essential features | ✅ Complete API access |
-| **Updates** | May lag behind | ✅ Latest features first |
-| **Testing** | Limited environments | ✅ Thoroughly tested |
+| **Documentation** | Basic README and limited examples | ✅ Comprehensive online documentation |
+| **API Coverage** | Core features only | ✅ Full API coverage |
+| **Updates** | May lag behind | ✅ Always includes the latest features |
+| **Testing** | Tested in limited environments | ✅ Thoroughly tested |
+| **API Usage** | ✅ Simple and intuitive | More complex and verbose|
 
 ## 🔧 Installation
 

barcodeQrSDK/__init__.py

@@ -35,6 +35,8 @@
     BarcodeReaderModule
 )
 import time
+from typing import List, Tuple, Callable, Union, Optional, Any
+import numpy as np
 
 __version__ = BarcodeReaderModule.get_version()
 
@@ -55,7 +57,7 @@ def has_next_image_to_fetch(self) -> bool:
         """
         return True
 
-    def add_frame(self, imageData):
+    def add_frame(self, imageData: ImageData) -> None:
         """
         Adds a new image frame to the processing buffer.
         
@@ -74,7 +76,7 @@ class MyCapturedResultReceiver(CapturedResultReceiver):
     to BarcodeResult objects before passing to the user-defined listener.
     """
 
-    def __init__(self, listener):
+    def __init__(self, listener: Callable[[List['BarcodeResult']], None]) -> None:
         """
         Initialize the result receiver with a callback listener.
         
@@ -86,7 +88,7 @@ def __init__(self, listener):
         super().__init__()
         self.listener = listener
 
-    def on_captured_result_received(self, result):
+    def on_captured_result_received(self, result: Any) -> None:
         """
         Called when barcode detection results are received.
         
@@ -97,7 +99,7 @@ def on_captured_result_received(self, result):
             result: The captured result from the SDK containing detected items.
         """
         items = result.get_items()
-        output = []
+        output: List['BarcodeResult'] = []
         for item in items:
             barcode = BarcodeResult(item)
             output.append(barcode)
@@ -118,15 +120,15 @@ class BarcodeResult:
                                                 location as four corner points
     """
 
-    def __init__(self, item):
+    def __init__(self, item: Any) -> None:
         """
         Initialize a BarcodeResult from an SDK barcode item.
         
         Args:
             item: The barcode item from the SDK containing detection results.
         """
-        self.text = item.get_text()
-        self.format = item.get_format_string()
+        self.text: str = item.get_text()
+        self.format: str = item.get_format_string()
 
         # Extract location coordinates (four corner points)
         location = item.get_location()
@@ -139,14 +141,14 @@ def __init__(self, item):
         x4 = location.points[3].x
         y4 = location.points[3].y
 
-        self.x1 = x1
-        self.y1 = y1
-        self.x2 = x2
-        self.y2 = y2
-        self.x3 = x3
-        self.y3 = y3
-        self.x4 = x4
-        self.y4 = y4
+        self.x1: float = x1
+        self.y1: float = y1
+        self.x2: float = x2
+        self.y2: float = y2
+        self.x3: float = x3
+        self.y3: float = y3
+        self.x4: float = x4
+        self.y4: float = y4
 
 class BarcodeReader:
     """
@@ -163,7 +165,7 @@ class BarcodeReader:
             print(f"Found: {barcode.text} ({barcode.format})")
     """
 
-    def __init__(self):
+    def __init__(self) -> None:
         """
         Initialize the barcode reader with default settings.
         
@@ -173,12 +175,12 @@ def __init__(self):
         cvr_instance = CaptureVisionRouter()
         error_code, settings, error_message = cvr_instance.output_settings(EnumPresetTemplate.PT_READ_BARCODES.value)
         cvr_instance.init_settings(settings)
-        self.fetcher = FrameFetcher()
+        self.fetcher: FrameFetcher = FrameFetcher()
         cvr_instance.set_input(self.fetcher)
-        self.cvr_instance = cvr_instance
-        self.receiver = None
+        self.cvr_instance: CaptureVisionRouter = cvr_instance
+        self.receiver: Optional[MyCapturedResultReceiver] = None
 
-    def getParameters(self):
+    def getParameters(self) -> str:
         """
         Get the current detection parameters/settings.
         
@@ -189,7 +191,7 @@ def getParameters(self):
         error_code, settings, error_message = self.cvr_instance.output_settings(EnumPresetTemplate.PT_READ_BARCODES.value)
         return settings
 
-    def setParameters(self, params):
+    def setParameters(self, params: str) -> Tuple[int, str]:
         """
         Set custom detection parameters/settings.
         
@@ -203,7 +205,7 @@ def setParameters(self, params):
         error_code, error_message = self.cvr_instance.init_settings(params)
         return error_code, error_message
 
-    def addAsyncListener(self, listener):
+    def addAsyncListener(self, listener: Callable[[List[BarcodeResult]], None]) -> None:
         """
         Start asynchronous barcode detection with a callback listener.
         
@@ -226,7 +228,7 @@ def on_barcode_detected(barcodes):
         self.cvr_instance.add_result_receiver(self.receiver)
         error_code, error_message = self.cvr_instance.start_capturing('')
 
-    def clearAsyncListener(self):
+    def clearAsyncListener(self) -> None:
         """
         Stop asynchronous barcode detection and remove the listener.
         
@@ -238,7 +240,7 @@ def clearAsyncListener(self):
             self.receiver = None
         self.cvr_instance.stop_capturing()
 
-    def decode(self, input):
+    def decode(self, input: Union[str, ImageData]) -> List[BarcodeResult]:
         """
         Core decode method that handles various input types.
         
@@ -252,7 +254,7 @@ def decode(self, input):
         """
         result = self.cvr_instance.capture(input, '')
 
-        output = []
+        output: List[BarcodeResult] = []
 
         if result.get_error_code() != EnumErrorCode.EC_OK:
             print("Error:", result.get_error_code(),
@@ -265,7 +267,7 @@ def decode(self, input):
 
         return output
 
-    def decodeFile(self, file_path: str):
+    def decodeFile(self, file_path: str) -> List[BarcodeResult]:
         """
         Decode barcodes from an image file.
         
@@ -283,7 +285,7 @@ def decodeFile(self, file_path: str):
         """
         return self.decode(file_path)
 
-    def decodeMat(self, mat):
+    def decodeMat(self, mat: np.ndarray) -> List[BarcodeResult]:
         """
         Decode barcodes from an OpenCV image matrix.
         
@@ -301,7 +303,7 @@ def decodeMat(self, mat):
         """
         return self.decode(convertMat2ImageData(mat))
 
-    def decodeBytes(self, bytes, width, height, stride, pixel_format):
+    def decodeBytes(self, bytes: bytes, width: int, height: int, stride: int, pixel_format: EnumImagePixelFormat) -> List[BarcodeResult]:
         """
         Decode barcodes from raw image bytes.
         
@@ -325,7 +327,7 @@ def decodeBytes(self, bytes, width, height, stride, pixel_format):
         imagedata = ImageData(bytes, width, height, stride, pixel_format)
         return self.decode(imagedata)
 
-    def decodeMatAsync(self, mat):
+    def decodeMatAsync(self, mat: np.ndarray) -> None:
         """
         Add an OpenCV matrix to the async processing queue.
         
@@ -343,7 +345,7 @@ def decodeMatAsync(self, mat):
         """
         self.fetcher.add_frame(convertMat2ImageData(mat))
 
-    def decodeBytesAsync(self, bytes, width, height, stride, pixel_format):
+    def decodeBytesAsync(self, bytes: bytes, width: int, height: int, stride: int, pixel_format: EnumImagePixelFormat) -> None:
         """
         Add raw image bytes to the async processing queue.
         
@@ -361,7 +363,7 @@ def decodeBytesAsync(self, bytes, width, height, stride, pixel_format):
         self.fetcher.add_frame(imagedata)
 
 
-def initLicense(licenseKey: str):
+def initLicense(licenseKey: str) -> Tuple[int, str]:
     """
     Initialize the Dynamsoft license for barcode detection.
     
@@ -382,7 +384,7 @@ def initLicense(licenseKey: str):
     errorCode, errorMsg = LicenseManager.init_license(licenseKey)
     return errorCode, errorMsg
 
-def createInstance():
+def createInstance() -> BarcodeReader:
     """
     Create a new BarcodeReader instance.
     
@@ -399,7 +401,7 @@ def createInstance():
     """
     return BarcodeReader()
 
-def convertMat2ImageData(mat):
+def convertMat2ImageData(mat: np.ndarray) -> ImageData:
     """
     Convert an OpenCV matrix to Dynamsoft ImageData format.
     
@@ -429,3 +431,30 @@ def convertMat2ImageData(mat):
     stride = width * channels
     imagedata = ImageData(mat.tobytes(), width, height, stride, pixel_format)
     return imagedata
+
+def wrapImageData(width: int, height: int, stride: int, pixel_format: EnumImagePixelFormat, bytes: bytes) -> ImageData:
+    """
+    Create an ImageData object from raw image parameters.
+    
+    This utility function creates a properly formatted ImageData object
+    from raw image specifications and byte data.
+    
+    Args:
+        width (int): Image width in pixels
+        height (int): Image height in pixels
+        stride (int): Number of bytes per image row
+        pixel_format: EnumImagePixelFormat specifying the pixel layout
+        bytes: Raw image data as bytes
+    
+    Returns:
+        ImageData: Formatted image data ready for SDK processing.
+    
+    Example:
+        image_data = wrapImageData(
+            640, 480, 1920, 
+            EnumImagePixelFormat.IPF_RGB_888, 
+            raw_bytes
+        )
+    """
+    imagedata = ImageData(bytes, width, height, stride, pixel_format)
+    return imagedata