captcha-url-reader 1.0.0__py3-none-any.whl

captcha_image_reader/__init__.py

@@ -0,0 +1,3 @@
+from .reader import read_captcha_from_url
+
+__all__ = ["read_captcha_from_url"]

captcha_image_reader/cli.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import argparse
+
+from .reader import read_captcha_from_url
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Read CAPTCHA text from an image URL")
+    parser.add_argument("image_url", help="Captcha image URL")
+    parser.add_argument("--cpu-only", action="store_true", help="Disable GPU and force CPU OCR")
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    text = read_captcha_from_url(args.image_url, prefer_gpu=not args.cpu_only)
+    if text:
+        print(text)
+    else:
+        print("No text extracted")
+
+
+if __name__ == "__main__":
+    main()

captcha_image_reader/reader.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from io import BytesIO
+from itertools import product
+from typing import Any
+
+import cv2
+import easyocr
+import numpy as np
+import requests
+from PIL import Image
+
+_READER_CACHE: dict[bool, Any] = {}
+_ALLOWLIST = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+_AMBIGUOUS_TO_DIGITS: dict[str, tuple[str, ...]] = {
+    "O": ("9", "0"),
+    "Q": ("0",),
+    "S": ("5",),
+}
+
+
+def _get_reader(prefer_gpu: bool = True, languages: list[str] | None = None) -> Any:
+    langs = languages or ["en"]
+    if prefer_gpu:
+        try:
+            key = True
+            if key not in _READER_CACHE:
+                _READER_CACHE[key] = easyocr.Reader(langs, gpu=True)
+            return _READER_CACHE[key]
+        except Exception:
+            pass
+
+    key = False
+    if key not in _READER_CACHE:
+        _READER_CACHE[key] = easyocr.Reader(langs, gpu=False)
+    return _READER_CACHE[key]
+
+
+def _build_variants(gray: np.ndarray, threshold: int) -> list[np.ndarray]:
+    variants: list[np.ndarray] = [gray]
+
+    # Upscale to reduce overlap impact on OCR detection.
+    up2 = cv2.resize(gray, None, fx=2.0, fy=2.0, interpolation=cv2.INTER_CUBIC)
+    up3 = cv2.resize(gray, None, fx=3.0, fy=3.0, interpolation=cv2.INTER_CUBIC)
+    variants.extend([up2, up3])
+
+    # Contrast normalization.
+    clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
+    clahe_gray = clahe.apply(gray)
+    variants.append(clahe_gray)
+
+    # Threshold-based binarizations.
+    for src in (gray, clahe_gray, up2):
+        _, thr = cv2.threshold(src, threshold, 255, cv2.THRESH_BINARY)
+        variants.append(thr)
+        variants.append(cv2.bitwise_not(thr))
+
+        _, otsu = cv2.threshold(src, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+        variants.append(otsu)
+        variants.append(cv2.bitwise_not(otsu))
+
+        adp = cv2.adaptiveThreshold(
+            src, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 21, 7
+        )
+        variants.append(adp)
+        variants.append(cv2.bitwise_not(adp))
+
+    kernel = np.ones((2, 2), np.uint8)
+    variants.append(cv2.dilate(up2, kernel, iterations=1))
+    variants.append(cv2.erode(up2, kernel, iterations=1))
+    variants.append(cv2.morphologyEx(up2, cv2.MORPH_CLOSE, kernel))
+    variants.append(cv2.medianBlur(up2, 3))
+    sharpened = cv2.addWeighted(
+        cv2.GaussianBlur(up3, (0, 0), 1.2),
+        1.3,
+        cv2.GaussianBlur(up3, (0, 0), 2.4),
+        -0.3,
+        0,
+    )
+    variants.append(np.clip(sharpened, 0, 255).astype(np.uint8))
+
+    return variants
+
+
+def _detect_overlap_risk(gray: np.ndarray) -> bool:
+    # Approximate overlap/noise risk by blob count and ink density.
+    blur = cv2.GaussianBlur(gray, (3, 3), 0)
+    _, bin_inv = cv2.threshold(blur, 0, 255, cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU)
+    bin_inv = cv2.morphologyEx(
+        bin_inv,
+        cv2.MORPH_CLOSE,
+        cv2.getStructuringElement(cv2.MORPH_RECT, (2, 2)),
+    )
+
+    num_labels, _, stats, _ = cv2.connectedComponentsWithStats(bin_inv, connectivity=8)
+    min_area = max(12, int(gray.size * 0.001))
+    max_area = int(gray.size * 0.65)
+    blob_count = 0
+    for i in range(1, num_labels):
+        area = int(stats[i, cv2.CC_STAT_AREA])
+        if min_area <= area <= max_area:
+            blob_count += 1
+
+    ink_density = float(np.count_nonzero(bin_inv)) / float(bin_inv.size)
+    return blob_count <= 3 and 0.03 <= ink_density <= 0.45
+
+
+def _candidate_score(text: str, confidence: float) -> float:
+    length_bonus = 0.3 if 4 <= len(text) <= 8 else 0.0
+    alpha_num_bonus = 0.1 if text.isalnum() else 0.0
+    mixed_bonus = 0.22 if any(ch.isalpha() for ch in text) and any(ch.isdigit() for ch in text) else 0.0
+    return confidence + length_bonus + alpha_num_bonus + mixed_bonus
+
+
+def _readtext_with_fallback(reader: Any, arr: np.ndarray, **kwargs: Any) -> list[Any]:
+    try:
+        return reader.readtext(arr, **kwargs)
+    except TypeError:
+        detail = kwargs.get("detail", 1)
+        try:
+            return reader.readtext(arr, detail)
+        except TypeError:
+            return reader.readtext(arr)
+
+
+def _bbox_x(item: Any) -> float:
+    try:
+        bbox = item[0]
+        return float(min(point[0] for point in bbox))
+    except Exception:
+        return 0.0
+
+
+def _extract_text_conf(result: list[Any]) -> tuple[str, float] | None:
+    if not result:
+        return None
+
+    ordered = sorted(result, key=_bbox_x)
+    texts: list[str] = []
+    confs: list[float] = []
+    for item in ordered:
+        if isinstance(item, (tuple, list)) and len(item) >= 2:
+            texts.append(str(item[1]))
+            if len(item) >= 3:
+                try:
+                    confs.append(float(item[2]))
+                except Exception:
+                    pass
+        else:
+            texts.append(str(item))
+
+    text = "".join(texts).strip()
+    cleaned = "".join(ch for ch in text if ch.isalnum())
+    if not cleaned:
+        return None
+
+    conf = float(np.mean(confs)) if confs else 0.5
+    return cleaned, conf
+
+
+def _iter_digit_variants(text: str, max_replacements: int = 2) -> list[tuple[str, int]]:
+    options_by_idx: list[tuple[int, tuple[str, ...]]] = []
+    for idx, ch in enumerate(text):
+        repl = _AMBIGUOUS_TO_DIGITS.get(ch.upper())
+        if repl:
+            options_by_idx.append((idx, repl))
+
+    if not options_by_idx:
+        return []
+
+    variants: list[tuple[str, int]] = []
+    for idx, replacements in options_by_idx:
+        for repl in replacements:
+            chars = list(text)
+            chars[idx] = repl
+            variants.append(("".join(chars), 1))
+
+    if len(options_by_idx) >= 2 and max_replacements >= 2:
+        for (idx1, repls1), (idx2, repls2) in product(options_by_idx, options_by_idx):
+            if idx1 >= idx2:
+                continue
+            for repl1 in repls1:
+                for repl2 in repls2:
+                    chars = list(text)
+                    chars[idx1] = repl1
+                    chars[idx2] = repl2
+                    variants.append(("".join(chars), 2))
+
+    return variants
+
+
+def _extract_best_text(reader: Any, variants: list[np.ndarray], *, overlap_risk: bool = False) -> str | None:
+    candidates: dict[str, dict[str, float]] = defaultdict(
+        lambda: {"votes": 0.0, "conf_sum": 0.0}
+    )
+    raw_candidates: list[tuple[str, float, float]] = []
+
+    for arr in variants:
+        for decoder in ("greedy", "beamsearch"):
+            result = _readtext_with_fallback(
+                reader,
+                arr,
+                detail=1,
+                paragraph=False,
+                allowlist=_ALLOWLIST,
+                decoder=decoder,
+                beamWidth=5,
+            )
+            parsed = _extract_text_conf(result)
+            if not parsed:
+                continue
+            cleaned, conf = parsed
+
+            score = _candidate_score(cleaned, conf)
+            candidates[cleaned]["votes"] += score
+            candidates[cleaned]["conf_sum"] += conf
+            raw_candidates.append((cleaned, conf, score))
+
+    saw_digit = any(any(ch.isdigit() for ch in text) for text, _, _ in raw_candidates)
+    if saw_digit and overlap_risk:
+        for text, conf, score in raw_candidates:
+            for transformed, replacements in _iter_digit_variants(text):
+                adjusted_score = score - (0.12 * replacements)
+                candidates[transformed]["votes"] += adjusted_score
+                candidates[transformed]["conf_sum"] += max(0.0, conf - (0.06 * replacements))
+
+    if not candidates:
+        return None
+
+    best_text = max(
+        candidates.items(),
+        key=lambda kv: (kv[1]["votes"], kv[1]["conf_sum"], len(kv[0])),
+    )[0]
+
+    if overlap_risk and not any(ch.isdigit() for ch in best_text):
+        replacements = _iter_digit_variants(best_text, max_replacements=2)
+        best_votes = candidates[best_text]["votes"]
+        best_conf = candidates[best_text]["conf_sum"]
+        for transformed, replacement_count in replacements:
+            if transformed == best_text or not any(ch.isdigit() for ch in transformed):
+                continue
+            # In overlap-heavy captchas, OCR often reads 9/5 as O/S.
+            if replacement_count >= 2:
+                factor = 1.08
+                conf_factor = 0.92
+            else:
+                factor = 0.56
+                conf_factor = 0.52
+            inherited = best_votes * factor
+            candidates[transformed]["votes"] += max(0.0, inherited)
+            candidates[transformed]["conf_sum"] += max(0.0, best_conf * conf_factor)
+
+        best_text = max(
+            candidates.items(),
+            key=lambda kv: (kv[1]["votes"], kv[1]["conf_sum"], len(kv[0])),
+        )[0]
+
+    return best_text
+
+
+def read_captcha_from_url(
+    image_url: str,
+    *,
+    prefer_gpu: bool = True,
+    timeout: int = 20,
+    threshold: int = 150,
+    force_overlap_risk: bool | None = None,
+) -> str | None:
+    """Download CAPTCHA image URL and return extracted text."""
+    try:
+        response = requests.get(image_url, timeout=timeout)
+        response.raise_for_status()
+
+        gray = np.array(Image.open(BytesIO(response.content)).convert("L"))
+        variants = _build_variants(gray, threshold=threshold)
+        overlap_risk = (
+            _detect_overlap_risk(gray)
+            if force_overlap_risk is None
+            else bool(force_overlap_risk)
+        )
+        reader = _get_reader(prefer_gpu=prefer_gpu)
+        return _extract_best_text(reader, variants, overlap_risk=overlap_risk)
+    except Exception:
+        return None

captcha_url_reader-1.0.0.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: captcha-url-reader
+Version: 1.0.0
+Summary: Simple Python package: pass CAPTCHA image URL and get extracted text
+Author: Arif Shah
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: easyocr>=1.7.1
+Requires-Dist: opencv-python>=4.9.0
+Requires-Dist: Pillow>=10.2.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+
+# captcha-url-reader
+
+Simple package: user passes captcha image URL, package reads and returns text.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+from captcha_image_reader import read_captcha_from_url
+
+# Default mode (recommended for Amazon-style captchas)
+captcha_text = read_captcha_from_url("https://images-na.ssl-images-amazon.com/captcha/sgkknrsj/Captcha_iwrdailhkf.jpg")
+if captcha_text:
+    print(f"CAPTCHA text extracted: {captcha_text}")
+else:
+    print("No text extracted from image URL.")
+```
+
+## Overlap-heavy captcha mode
+
+Use forced overlap mode only when text is merged/overlapping and default mode is not accurate.
+
+```python
+from captcha_image_reader import read_captcha_from_url
+
+captcha_text = read_captcha_from_url(
+    "https://2captcha.com/dist/web/assets/captcha-rn1S3orp.jpg",
+    force_overlap_risk=True,
+)
+```
+
+## When to use which mode
+
+- Use default mode for clean or mostly non-overlapping text (for example, most Amazon captchas).
+- Use `force_overlap_risk=True` only when characters are merged and default extraction is wrong.
+
+## Example scripts
+
+- Default/Amazon style: `/Users/arif.shah/PycharmProjects/captcha-url-reader/examples/read_amazon_default.py`
+- Overlap-heavy style: `/Users/arif.shah/PycharmProjects/captcha-url-reader/examples/read_overlap_captcha.py`
+
+Run them directly:
+
+```bash
+./.venv/bin/python /Users/arif.shah/PycharmProjects/captcha-url-reader/examples/read_amazon_default.py
+./.venv/bin/python /Users/arif.shah/PycharmProjects/captcha-url-reader/examples/read_overlap_captcha.py
+```
+
+## GPU behavior
+
+- Uses GPU first by default.
+- If GPU is not available or fails, automatically falls back to CPU.

captcha_url_reader-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+captcha_image_reader/__init__.py,sha256=55imgvNhUXSFyNsvKh_Z1Iiu3qwrIIvZ1j0vXyhotGY,79
+captcha_image_reader/cli.py,sha256=8whVxkDOjc7TDD-3G31zR4DcArcstiNNC-t5sKEm0c0,688
+captcha_image_reader/reader.py,sha256=fxjtWBy7dpHRcvI46Cn8wOmlGpxu1aBGjZggXpQchcA,9600
+captcha_url_reader-1.0.0.dist-info/METADATA,sha256=rc3r1XiSf9YNNBe97Vd5XI7cm-G9C1RoU8LZXaSmHv0,2131
+captcha_url_reader-1.0.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+captcha_url_reader-1.0.0.dist-info/entry_points.txt,sha256=NpOle_Ounm2mpcsF5ahUOMsvA3VaYh1IiQpiv8-EILM,69
+captcha_url_reader-1.0.0.dist-info/top_level.txt,sha256=WmV9_fWsM4xvIm19nfgR_HFVVt0k2hK1mnDGAwfMLkM,21
+captcha_url_reader-1.0.0.dist-info/RECORD,,

captcha_url_reader-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

captcha_url_reader-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+captcha-url-reader = captcha_image_reader.cli:main

captcha_url_reader-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+captcha_image_reader