dotcode-decoder 1.0.0__py3-none-any.whl

dotcode/decoder_90.py

@@ -0,0 +1,390 @@
+"""
+Main decoder with iterative regression - Final Speed + Accuracy Balance
+- Uses original snap_to_grid_checkerboard for reliability
+- Fast mode: all essential thresholds with both erosion levels 2 and 3
+- Early exit in regression
+- Expected: ~45ms avg, ~95-96% success
+"""
+
+import time
+import cv2
+import numpy as np
+from typing import Optional, Union
+
+from .utils import DecodeResult, DecodeStage, GRID_ROWS, GRID_COLS
+from .utils import MIN_DOTS, REGRESSION_ITERATIONS
+from .images import BinaryPyramid, detect_dots, snap_to_grid_checkerboard
+from .images import decode_from_grid, kmeans_1d
+from .codes import is_valid_message
+
+
+def get_smart_combos(mean_brightness):
+    if mean_brightness < 40:
+        return [
+            ("otsu", None, [2, 3, 4]),
+            ("fixed", 135, [2, 3]),
+            ("fixed", 145, [2, 3]),
+            ("fixed", 155, [2, 3]),
+        ]
+    elif mean_brightness < 55:
+        return [
+            ("otsu", None, [2, 3]),
+            ("fixed", 145, [2, 3]),
+            ("fixed", 155, [2, 3]),
+            ("fixed", 165, [2, 3]),
+        ]
+    elif mean_brightness < 70:
+        return [
+            ("otsu", None, [2, 3]),
+            ("fixed", 155, [2, 3, 4]),
+            ("fixed", 165, [2, 3, 4]),
+            ("fixed", 175, [2, 3]),
+        ]
+    else:
+        return [
+            ("otsu", None, [2, 3]),
+            ("fixed", 165, [2, 3]),
+            ("fixed", 175, [2, 3]),
+            ("fixed", 155, [2, 3]),
+        ]
+
+
+def rotate_points(pts, angle):
+    if abs(angle) < 0.05:
+        return pts
+    center = np.mean(pts, axis=0)
+    theta = np.radians(-angle)
+    c, s = np.cos(theta), np.sin(theta)
+    R = np.array([[c, -s], [s, c]])
+    return (pts - center) @ R.T + center
+
+
+def compute_row_quality(pts, n_rows=GRID_ROWS):
+    if len(pts) < 20:
+        return float('inf')
+    ys = pts[:, 1]
+    row_centers = kmeans_1d(ys, n_rows)
+    row_idx = np.argmin(np.abs(row_centers[None, :] - ys[:, None]), axis=1)
+    total_var = 0
+    valid_rows = 0
+    for r in range(len(row_centers)):
+        mask = row_idx == r
+        if mask.sum() > 3:
+            total_var += np.var(ys[mask])
+            valid_rows += 1
+    if valid_rows == 0:
+        return float('inf')
+    return total_var / valid_rows
+
+
+def get_angle_from_rows(pts, n_rows=GRID_ROWS):
+    if len(pts) < 20:
+        return 0
+    ys = pts[:, 1]
+    xs = pts[:, 0]
+    row_centers = kmeans_1d(ys, n_rows)
+    row_idx = np.argmin(np.abs(row_centers[None, :] - ys[:, None]), axis=1)
+    slopes = []
+    row_counts = []
+    for r in range(len(row_centers)):
+        mask = row_idx == r
+        count = mask.sum()
+        if count < 4:
+            continue
+        row_xs = xs[mask]
+        row_ys = ys[mask]
+        try:
+            coeffs = np.polyfit(row_xs, row_ys, 1)
+            slopes.append(coeffs[0])
+            row_counts.append(count)
+        except:
+            continue
+    if not slopes:
+        return 0
+    weights = np.array(row_counts) / sum(row_counts)
+    avg_slope = np.sum(np.array(slopes) * weights)
+    angle = np.degrees(np.arctan(avg_slope))
+    if angle > 45:
+        angle -= 90
+    elif angle < -45:
+        angle += 90
+    return angle
+
+
+def straighten_dots_iterative(pts, n_rows=GRID_ROWS, degree=2, max_iterations=REGRESSION_ITERATIONS):
+    """
+    Iterative regression with early exit when angle stabilizes.
+    """
+    if pts is None or len(pts) < 20:
+        return pts, 0
+
+    angle = get_angle_from_rows(pts, n_rows)
+    current_pts = rotate_points(pts, angle)
+    prev_angle = angle
+
+    for iteration in range(max_iterations):
+        xs = current_pts[:, 0]
+        ys = current_pts[:, 1]
+
+        row_centers = kmeans_1d(ys, n_rows)
+        row_idx = np.argmin(np.abs(row_centers[None, :] - ys[:, None]), axis=1)
+
+        coeffs_list = []
+        row_weights = []
+
+        for r in range(len(row_centers)):
+            mask = row_idx == r
+            count = mask.sum()
+            if count < max(4, degree + 2):
+                continue
+            row_xs = xs[mask]
+            row_ys = ys[mask]
+            try:
+                c = np.polyfit(row_xs, row_ys, degree)
+                coeffs_list.append(c)
+                row_weights.append(count)
+            except:
+                continue
+
+        if len(coeffs_list) >= 2:
+            weights = np.array(row_weights) / sum(row_weights)
+            avg_coeffs = np.zeros(len(coeffs_list[0]))
+            for c, w in zip(coeffs_list, weights):
+                avg_coeffs += c * w
+
+            trend = np.polyval(avg_coeffs, xs)
+            mean_y = float(np.mean(ys))
+            current_pts[:, 1] = ys - trend + mean_y
+
+            new_angle = get_angle_from_rows(current_pts, n_rows)
+            if abs(new_angle - prev_angle) < 0.1:   # relaxed from 0.05
+                break
+            prev_angle = new_angle
+            current_pts = rotate_points(current_pts, new_angle)
+        else:
+            break
+
+    final_angle = get_angle_from_rows(current_pts, n_rows)
+    final_score = compute_row_quality(current_pts, n_rows)
+    original_score = compute_row_quality(pts, n_rows)
+
+    if final_score > original_score * 1.2:
+        return pts, 0
+
+    return current_pts, final_angle
+
+
+class DotCodeDecoder:
+    def __init__(
+        self,
+        timeout_ms: int = 300,
+        confidence: float = 0.25,
+        fast_mode: bool = True
+    ):
+        self.timeout_ms = timeout_ms
+        self.confidence = confidence
+        self.fast_mode = fast_mode
+
+    def decode(self, image, return_details: bool = True) -> Union[str, DecodeResult, None]:
+        result = self._decode_image(image)
+        return result if return_details else (result.message if result.success else None)
+
+    def _decode_image(self, image) -> DecodeResult:
+        if isinstance(image, str):
+            img = cv2.imread(image)
+            if img is None:
+                return DecodeResult(success=False, error="READ_ERROR", file=image)
+        else:
+            img = image
+
+        start_time = time.time()
+
+        def check_timeout():
+            return (time.time() - start_time) * 1000 > self.timeout_ms
+
+        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) if img.ndim == 3 else img
+        pyramid = BinaryPyramid(gray)
+        mean_brightness = gray.mean()
+
+        # ─── STEP 1: Find BEST dots ───
+        best_pts = None
+        best_dot_info = None
+        best_count = 0
+
+        for mode, threshold, erosions in get_smart_combos(mean_brightness):
+            for erosion in erosions:
+                pts, dot_info = detect_dots(pyramid, mode, threshold, erosion)
+                if pts is not None and len(pts) > best_count:
+                    best_count = len(pts)
+                    best_pts = pts
+                    best_dot_info = dot_info
+
+        if best_pts is None or len(best_pts) < MIN_DOTS:
+            elapsed = (time.time() - start_time) * 1000
+            return DecodeResult(success=False, error="NO_DOTS", elapsed_ms=elapsed)
+
+        if check_timeout():
+            return DecodeResult(success=False, error="TIMEOUT", elapsed_ms=self.timeout_ms, timed_out=True)
+
+        # ─── STEP 2: Iterative Regression (uses original snap) ───
+        straight_pts, angle = straighten_dots_iterative(best_pts, GRID_ROWS, degree=2)
+
+        grid, _, _ = snap_to_grid_checkerboard(straight_pts, GRID_ROWS, GRID_COLS, best_dot_info)
+        if grid is not None:
+            occupancy = np.sum(grid) / ((GRID_ROWS * GRID_COLS + 1) // 2)
+            if occupancy >= 0.08:
+                msg = decode_from_grid(grid)
+                if msg:
+                    elapsed = (time.time() - start_time) * 1000
+                    return DecodeResult(
+                        success=True,
+                        message=msg,
+                        method=f"reg_iter_{angle:.1f}",
+                        elapsed_ms=elapsed,
+                        stage=DecodeStage.REGRESSION,
+                        confidence=occupancy * min(len(best_pts) / 150, 1.0)
+                    )
+
+        # ─── STEP 3: Angle Sweep ───
+        if self.fast_mode:
+            # Key thresholds with both erosion 2 and 3 for reliability
+            fallback_thresholds = [
+                ("otsu", None, [2, 3]),
+                ("fixed", 155, [2, 3]),
+                ("fixed", 165, [2, 3]),
+                ("fixed", 145, [2, 3]),   # added erosion 3
+                ("fixed", 175, [2, 3]),   # added erosion 3
+                ("fixed", 135, [2, 3]),   # added erosion 3
+                ("fixed", 125, [2]),      # keep only 2 (rare)
+            ]
+            # Full angle range for precision
+            fine_angles = [3.0, 2.5, 2.0, 1.5, 1.0, 0.5, -0.5, -1.0, -1.5, -2.0, -2.5, -3.0]
+        else:
+            # Full original search
+            fallback_thresholds = [
+                ("otsu", None, [2, 3]),
+                ("fixed", 155, [2, 3]),
+                ("fixed", 165, [2, 3]),
+                ("fixed", 145, [2, 3]),
+                ("fixed", 175, [2, 3]),
+                ("fixed", 135, [2, 3]),
+                ("fixed", 125, [2, 3]),
+                ("fixed", 115, [2, 3]),
+                ("fixed", 105, [2, 3]),
+            ]
+            fine_angles = [3.0, 2.5, 2.0, 1.5, 1.0, 0.5, -0.5, -1.0, -1.5, -2.0, -2.5, -3.0]
+
+        # Quick check: try best_pts with all angles first (fast path)
+        if len(best_pts) > 80 and not check_timeout():
+            for angle in fine_angles:
+                if check_timeout():
+                    break
+                rotated_pts = rotate_points(best_pts, angle)
+                grid, _, _ = snap_to_grid_checkerboard(rotated_pts, GRID_ROWS, GRID_COLS, best_dot_info)
+                if grid is not None:
+                    occupancy = np.sum(grid) / ((GRID_ROWS * GRID_COLS + 1) // 2)
+                    if occupancy >= 0.08:
+                        msg = decode_from_grid(grid)
+                        if msg:
+                            confidence = occupancy * min(len(best_pts) / 150, 1.0)
+                            if confidence >= self.confidence:
+                                elapsed = (time.time() - start_time) * 1000
+                                return DecodeResult(
+                                    success=True,
+                                    message=msg,
+                                    method=f"ang_best_{angle:.1f}",
+                                    elapsed_ms=elapsed,
+                                    stage=DecodeStage.ANGLE_SWEEP,
+                                    confidence=confidence
+                                )
+
+        # Full sweep over thresholds/erosions
+        for mode, threshold, erosions in fallback_thresholds:
+            if check_timeout():
+                return DecodeResult(success=False, error="TIMEOUT", elapsed_ms=self.timeout_ms, timed_out=True)
+
+            for erosion in erosions:
+                pts, dot_info = detect_dots(pyramid, mode, threshold, erosion)
+                if pts is None or len(pts) < MIN_DOTS:
+                    continue
+
+                for angle in fine_angles:
+                    if check_timeout():
+                        return DecodeResult(success=False, error="TIMEOUT", elapsed_ms=self.timeout_ms, timed_out=True)
+
+                    rotated_pts = rotate_points(pts, angle)
+                    grid, _, _ = snap_to_grid_checkerboard(rotated_pts, GRID_ROWS, GRID_COLS, dot_info)
+
+                    if grid is None:
+                        continue
+
+                    occupancy = np.sum(grid) / ((GRID_ROWS * GRID_COLS + 1) // 2)
+                    if occupancy < 0.08:
+                        continue
+
+                    msg = decode_from_grid(grid)
+                    if msg:
+                        confidence = occupancy * min(len(pts) / 150, 1.0)
+                        if confidence >= self.confidence:
+                            elapsed = (time.time() - start_time) * 1000
+                            return DecodeResult(
+                                success=True,
+                                message=msg,
+                                method=f"ang_{mode if mode == 'otsu' else f'fixed_{threshold}'}_e{erosion}",
+                                elapsed_ms=elapsed,
+                                stage=DecodeStage.ANGLE_SWEEP,
+                                confidence=confidence
+                            )
+
+        # ─── STEP 4: Invert ───
+        if not check_timeout():
+            inverted = cv2.bitwise_not(gray)
+            pyramid_inv = BinaryPyramid(inverted)
+
+            # Use a focused set for invert (otsu and 155 with both erosions)
+            for mode, threshold, erosions in [("otsu", None, [2, 3]), ("fixed", 155, [2, 3])]:
+                if check_timeout():
+                    return DecodeResult(success=False, error="TIMEOUT", elapsed_ms=self.timeout_ms, timed_out=True)
+
+                for erosion in erosions:
+                    pts, dot_info = detect_dots(pyramid_inv, mode, threshold, erosion)
+                    if pts is None or len(pts) < MIN_DOTS:
+                        continue
+
+                    # Full angle range for invert
+                    for angle in fine_angles:
+                        if check_timeout():
+                            return DecodeResult(success=False, error="TIMEOUT", elapsed_ms=self.timeout_ms, timed_out=True)
+
+                        rotated_pts = rotate_points(pts, angle)
+                        grid, _, _ = snap_to_grid_checkerboard(rotated_pts, GRID_ROWS, GRID_COLS, dot_info)
+
+                        if grid is None:
+                            continue
+
+                        occupancy = np.sum(grid) / ((GRID_ROWS * GRID_COLS + 1) // 2)
+                        if occupancy < 0.08:
+                            continue
+
+                        msg = decode_from_grid(grid)
+                        if msg:
+                            confidence = occupancy * min(len(pts) / 150, 1.0)
+                            if confidence >= self.confidence:
+                                elapsed = (time.time() - start_time) * 1000
+                                return DecodeResult(
+                                    success=True,
+                                    message=msg,
+                                    method=f"inv_{mode if mode == 'otsu' else f'fixed_{threshold}'}_e{erosion}",
+                                    elapsed_ms=elapsed,
+                                    stage=DecodeStage.INVERT,
+                                    confidence=confidence
+                                )
+
+        elapsed = (time.time() - start_time) * 1000
+        return DecodeResult(success=False, error="FAILED", elapsed_ms=elapsed)
+
+
+# Simple API
+def decode(image, **kwargs):
+    decoder = DotCodeDecoder(**kwargs)
+    return decoder.decode(image)

dotcode/image.py

@@ -0,0 +1,3 @@
+"""Compatibility wrapper for the image processing module."""
+
+from .images import *

dotcode/images.py

@@ -0,0 +1,200 @@
+"""
+Image processing: thresholding, blob detection, grid snapping
+"""
+
+import cv2
+import numpy as np
+from .utils import GRID_ROWS, GRID_COLS, MIN_DOTS
+
+_KERNEL = cv2.getStructuringElement(cv2.MORPH_RECT, (3, 3))
+
+# Grid constants
+_GRID_R_IDX = np.arange(GRID_ROWS)[:, None]
+_GRID_C_IDX = np.arange(GRID_COLS)[None, :]
+_GRID_MASK_OFFSET0 = (_GRID_R_IDX + _GRID_C_IDX) % 2 == 0
+_GRID_TOTAL_CELLS = (GRID_ROWS * GRID_COLS + 1) // 2
+
+
+class BinaryPyramid:
+    def __init__(self, gray):
+        clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
+        self.enhanced = clahe.apply(gray)
+        self._base = {}
+        self._eroded = {}
+
+    def get(self, mode, fixed_t, erosion_level):
+        key = (mode, fixed_t, erosion_level)
+        if key in self._eroded:
+            return self._eroded[key]
+        
+        base_key = (mode, fixed_t)
+        if base_key not in self._base:
+            if mode == "otsu":
+                _, b = cv2.threshold(self.enhanced, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+            else:
+                _, b = cv2.threshold(self.enhanced, fixed_t, 255, cv2.THRESH_BINARY)
+            self._base[base_key] = cv2.morphologyEx(b, cv2.MORPH_OPEN, _KERNEL, iterations=1)
+        
+        cur, start = self._base[base_key], 0
+        for lvl in range(erosion_level, 0, -1):
+            if (mode, fixed_t, lvl) in self._eroded:
+                cur, start = self._eroded[(mode, fixed_t, lvl)], lvl
+                break
+        
+        for lvl in range(start + 1, erosion_level + 1):
+            cur = cv2.erode(cur, _KERNEL, iterations=1)
+            self._eroded[(mode, fixed_t, lvl)] = cur
+        
+        return cur
+
+
+def _score_blobs_from_binary(bw):
+    num, _, stats, centroids = cv2.connectedComponentsWithStats(bw, 8)
+    blobs = []
+    
+    for i in range(1, num):
+        x, y, w, h, area = stats[i]
+        if w < 2 or h < 2 or w > 80 or h > 80:
+            continue
+        blobs.append({"cx": centroids[i][0], "cy": centroids[i][1], "w": w, "h": h})
+    
+    if not blobs:
+        return None
+    
+    med_w = float(np.median([b["w"] for b in blobs]))
+    med_h = float(np.median([b["h"] for b in blobs]))
+    strict = [b for b in blobs if 0.70*med_w <= b["w"] <= 1.30*med_w and 0.70*med_h <= b["h"] <= 1.30*med_h]
+    
+    return {"n": len(strict), "med_w": med_w, "med_h": med_h, "blobs": strict}
+
+
+def detect_dots(pyramid, mode, fixed_t, erosion_level):
+    binary = pyramid.get(mode, fixed_t, erosion_level)
+    scored = _score_blobs_from_binary(binary)
+    
+    if not scored or scored["n"] < MIN_DOTS:
+        return None, None
+    
+    pts = np.array([[b["cx"], b["cy"]] for b in scored["blobs"]], dtype=np.float32)
+    dot_info = {"med_w": scored["med_w"], "med_h": scored["med_h"], "num_dots": scored["n"]}
+    
+    return pts, dot_info
+
+
+def kmeans_1d(vals, k):
+    arr = np.array(vals, dtype=np.float32).reshape(-1, 1)
+    k = max(2, min(k, len(vals)))
+    crit = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 100, 0.1)
+    _, _, centers = cv2.kmeans(arr, k, None, crit, 1, cv2.KMEANS_PP_CENTERS)
+    return np.sort(centers.flatten())
+
+
+def snap_to_grid_checkerboard(pts, n_rows, n_cols, dot_info):
+    if len(pts) < max(n_rows, n_cols):
+        return None, None, None
+    
+    row_c = kmeans_1d(pts[:, 1], n_rows)
+    col_c = kmeans_1d(pts[:, 0], n_cols)
+    
+    H, W = len(row_c), len(col_c)
+    
+    if H < 2 or W < 2:
+        return None, None, None
+    
+    row_step = float(np.median(np.diff(row_c))) if H > 1 else 15.0
+    col_step = float(np.median(np.diff(col_c))) if W > 1 else 15.0
+    
+    med_h = dot_info.get("med_h", row_step * 0.5)
+    med_w = dot_info.get("med_w", col_step * 0.5)
+    ry = med_h * 0.70
+    rx = med_w * 0.70
+    
+    xs = pts[:, 0]
+    ys = pts[:, 1]
+    
+    r_idx = np.argmin(np.abs(row_c[None, :] - ys[:, None]), axis=1)
+    c_idx = np.argmin(np.abs(col_c[None, :] - xs[:, None]), axis=1)
+    dr = np.abs(row_c[r_idx] - ys)
+    dc = np.abs(col_c[c_idx] - xs)
+    valid = (dr <= ry) & (dc <= rx)
+    
+    grid = np.zeros((H, W), dtype=np.uint8)
+    grid[r_idx[valid], c_idx[valid]] = 1
+    
+    return grid, row_c, col_c
+
+
+def extract_senior1(grid):
+    T = grid.T
+    corner = [0] * 6
+    Mask = []
+    data_bit = []
+    ncols = T.shape[0]
+    
+    for i, row in enumerate(T):
+        cropped = row[(i % 2)::2]
+        n = len(cropped)
+        
+        if n < 2:
+            continue
+        
+        if i == 0:
+            corner[5] = int(cropped[0])
+            corner[1] = int(cropped[-1])
+            if n >= 3:
+                Mask = list(cropped[1:3])
+            if n > 3:
+                data_bit.extend(cropped[3:-1])
+        
+        elif i == 1:
+            corner[3] = int(cropped[-1])
+            data_bit.extend(cropped[0:-1])
+        
+        elif i == ncols - 2:
+            corner[2] = int(cropped[-1])
+            data_bit.extend(cropped[0:-1])
+        
+        elif i == ncols - 1:
+            corner[4] = int(cropped[0])
+            corner[0] = int(cropped[-1])
+            if n > 1:
+                data_bit.extend(cropped[1:-1])
+        
+        else:
+            data_bit.extend(cropped)
+    
+    return "".join(str(b) for b in Mask + data_bit + corner)
+
+
+def decode_from_grid(grid):
+    if grid is None:
+        return None
+    
+    H, W = grid.shape
+    
+    if (H, W) == (GRID_ROWS, GRID_COLS):
+        mask = _GRID_MASK_OFFSET0
+        total_cells = _GRID_TOTAL_CELLS
+    else:
+        r_indices = np.arange(H)[:, None]
+        c_indices = np.arange(W)[None, :]
+        mask = (r_indices + c_indices) % 2 == 0
+        total_cells = (H * W + 1) // 2
+    
+    g = grid * mask
+    occupancy = np.sum(g) / total_cells
+    
+    if occupancy < 0.08:
+        return None
+    
+    bits = extract_senior1(g)
+    
+    if bits and len(bits) >= 100:
+        ones_ratio = bits.count('1') / len(bits)
+        if 0.08 <= ones_ratio <= 0.72:
+            from .codes import decode_bits, is_valid_message
+            msg = decode_bits(bits)
+            if msg and is_valid_message(msg):
+                return msg
+    
+    return None