DDDDOCR

Common errors

• Initialization speed is slow when creating DdddOcr objects.

  cause The `DdddOcr` model is loaded during initialization, and repeated instantiation in a loop causes this overhead for each image.
  fix Initialize the `ddddocr.DdddOcr()` object once outside any loops and reuse it for all subsequent recognition calls. Example: `ocr = ddddocr.DdddOcr(); for img in images: result = ocr.classification(img_bytes)`

• ModuleNotFoundError: No module named 'ddddocr' (or similar import errors) OR unexpected behavior when importing ddddocr.

  cause Your project directory, or a directory in your `PYTHONPATH`, is likely named `ddddocr`, which conflicts with the installed library package name.
  fix Rename your project directory to something other than `ddddocr`. This ensures that Python correctly imports the installed package.

• OCR recognition accuracy is not as expected for specific CAPTCHAs.

  cause The default OCR model might not be optimized for all types of complex or custom CAPTCHAs.
  fix Try using the Beta model by initializing with `ocr = ddddocr.DdddOcr(beta=True)`. For very specific cases, consider using the color filtering feature or importing a custom-trained model.

• ddddocr uses too much memory when multiple functionalities are needed.

  cause Initializing multiple `DdddOcr` instances with different functional parameters (e.g., one for OCR, another for detection) simultaneously.
  fix Initialize only the specific `DdddOcr` instance(s) needed for the current task. For example, if you only need OCR, use `ocr = ddddocr.DdddOcr(ocr=True, det=False)` and avoid initializing a separate detection object if not immediately required.

• Error: 'cuda may painc (exit code: 0xc000007b)' or missing DLL errors when using GPU acceleration.

  cause This typically indicates an incompatibility between your CUDA/cuDNN installation and `onnxruntime`, or issues with `onnxruntime` dynamic link library (DLL) loading paths.
  fix Verify your CUDA and cuDNN versions are compatible with your `onnxruntime-gpu` installation. Ensure the `onnxruntime` DLLs are accessible to your application (e.g., in the system's PATH, or application's running directory). For specific cases, especially with static linking, you might need to manually place or configure the `onnxruntime` library path.

Warnings

• gotcha Initializing the `DdddOcr` object repeatedly (e.g., inside a loop) will significantly slow down performance due to model loading overhead.
  Fix: Initialize the `ddddocr.DdddOcr()` object only once and reuse the instance for multiple recognition tasks.
• gotcha When using `ddddocr` in a multi-threaded environment, each thread must create its own independent `DdddOcr` instance to prevent recognition errors or inconsistent results.
  Fix: Ensure that `ddddocr.DdddOcr()` is instantiated within each thread that requires OCR capabilities.
• gotcha If your project directory (or a parent directory) is named `ddddocr`, you might encounter import conflicts, leading to `ModuleNotFoundError` or unexpected behavior.
  Fix: Rename your project directory to anything other than `ddddocr` to avoid conflicts with the installed package name.
• gotcha When initializing `DdddOcr`, if both `ocr=True` and `det=True` are set, the object detection mode (`det`) takes precedence. Similarly, `beta=True` overrides `old=True` if both are specified.
  Fix: Explicitly set only the desired mode (e.g., `ddddocr.DdddOcr(ocr=True, det=False)` for OCR or `ddddocr.DdddOcr(ocr=False, det=True)` for detection) to avoid unintended behavior.
• gotcha Enabling GPU acceleration (`use_gpu=True`) requires a compatible CUDA setup and `onnxruntime-gpu`. Incorrect CUDA/cuDNN versions or missing ONNX Runtime dynamic link libraries can lead to errors.
  Fix: Install the correct versions of CUDA and cuDNN matching your `onnxruntime-gpu` requirements. For static linking issues, manually place `onnxruntime` DLLs in the program's running directory or use `Ddddocr::set_onnxruntime_path` if using dynamic linking.

Install

• pip install ddddocr Standard Installation
• pip install "ddddocr[api]" Installation with API Server Dependencies

Imports

• DdddOcr
  wrong:

  from ddddocr import DdddOcr # (if current directory is 'ddddocr')

  correct:

  import ddddocr
  ocr = ddddocr.DdddOcr()

  Avoid direct `from ddddocr import ...` or having a local directory named `ddddocr` to prevent import conflicts.

Quickstart

This quickstart demonstrates basic text recognition using the DdddOcr class. It initializes the OCR engine once and then processes an image from bytes. Remember to initialize the `DdddOcr` object only once for performance.

import ddddocr
import os

# Create a dummy image file for demonstration
dummy_image_path = 'captcha_example.png'
from PIL import Image, ImageDraw, ImageFont

# Create a simple image with text
img = Image.new('RGB', (120, 40), color = (255, 255, 255))
d = ImageDraw.Draw(img)
try:
    # Try to use a common system font
    font = ImageFont.truetype('arial.ttf', 24)
except IOError:
    # Fallback if arial.ttf is not found
    font = ImageFont.load_default()
d.text((10,5), "test123", fill=(0,0,0), font=font)
img.save(dummy_image_path)

# Initialize DdddOcr for OCR recognition
# It's recommended to initialize the object once, not in a loop.
ocr = ddddocr.DdddOcr()

# Read the image bytes
with open(dummy_image_path, 'rb') as f:
    image_bytes = f.read()

# Perform OCR classification
result = ocr.classification(image_bytes)
print(f"OCR Result: {result}")

# Clean up the dummy image
os.remove(dummy_image_path)