dotcode-decoder 1.0.0__py3-none-any.whl

dotcode/decoder.py

@@ -0,0 +1,953 @@
+# """
+# Main decoder with iterative regression - Single image only (conveyor ready)
+# """
+
+# 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, iterations=REGRESSION_ITERATIONS):
+#     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)
+#     best_angle = angle
+    
+#     for iteration in range(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
+            
+#             if iteration < iterations - 1:
+#                 angle = get_angle_from_rows(current_pts, n_rows)
+#                 current_pts = rotate_points(current_pts, angle)
+#                 best_angle = 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]:
+#         """Decode a single image - conveyor ready"""
+#         result = self._decode_image(image)
+        
+#         if return_details:
+#             return result
+        
+#         return 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 ───
+#         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 (FAST MODE) ───
+#         if self.fast_mode:
+#             # Fast: 3 thresholds × 6 angles = 18 attempts
+#             fallback_thresholds = [
+#                 ("otsu", None, [2]),
+#                 ("fixed", 155, [2]),
+#                 ("fixed", 165, [2]),
+#             ]
+#             fine_angles = [2.0, 1.0, -1.0, -2.0, 0.5, -0.5]
+#         else:
+#             # Slow: 9 thresholds × 12 angles = 108 attempts
+#             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]
+        
+#         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)
+            
+#             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
+                    
+#                     for angle in fine_angles[:5]:
+#                         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 - Single image only (conveyor ready)
+# def decode(image, **kwargs):
+#     """Decode a single image - for conveyor belt use"""
+#     decoder = DotCodeDecoder(**kwargs)
+#     return decoder.decode(image)
+
+
+
+
+
+
+
+"""
+Main decoder with iterative regression - Speed + Accuracy Hybrid
+- Primary: original k-means snap (fast and proven)
+- Fallback: Procrustes + RANSAC for difficult images (only when needed)
+- Sauvola optional (disabled by default to keep speed)
+- Expected: ~40ms avg, ~95-96% success
+"""
+
+import time
+import cv2
+import numpy as np
+from typing import Optional, Union, Tuple
+from scipy.spatial import KDTree
+from scipy.linalg import svd
+
+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, _KERNEL
+from .codes import is_valid_message
+
+
+# ----------------------------------------------------------------------
+# Grid fitting via Procrustes (fast, reduced iterations)
+# ----------------------------------------------------------------------
+
+def generate_ideal_grid(n_rows: int = GRID_ROWS, n_cols: int = GRID_COLS) -> np.ndarray:
+    rows, cols = np.meshgrid(np.arange(n_rows), np.arange(n_cols), indexing='ij')
+    mask = (rows + cols) % 2 == 0
+    grid_points = np.column_stack([cols.ravel(), rows.ravel()])
+    grid_points = grid_points[mask.ravel()]
+    return grid_points
+
+
+def fit_procrustes(obs_pts: np.ndarray, model_pts: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+    mean_obs = np.mean(obs_pts, axis=0)
+    mean_model = np.mean(model_pts, axis=0)
+    obs_centered = obs_pts - mean_obs
+    model_centered = model_pts - mean_model
+    H = obs_centered.T @ model_centered
+    U, _, Vt = svd(H)
+    R = Vt.T @ U.T
+    if np.linalg.det(R) < 0:
+        Vt[-1, :] *= -1
+        R = Vt.T @ U.T
+    t = mean_obs - R @ mean_model
+    return R, t
+
+
+def ransac_grid_fit_fast(pts: np.ndarray, n_rows: int = GRID_ROWS, n_cols: int = GRID_COLS,
+                         iterations: int = 15, threshold: float = 4.0) -> Optional[Tuple[np.ndarray, np.ndarray]]:
+    """Fast RANSAC with fewer iterations, only for fallback."""
+    if len(pts) < 20:
+        return None
+
+    grid_model = generate_ideal_grid(n_rows, n_cols)
+    best_inlier_count = 0
+    best_R = None
+    best_t = None
+    best_inlier_indices = None
+    best_inlier_mask = None
+    tree = KDTree(pts)
+
+    for _ in range(iterations):
+        if len(pts) < 4:
+            break
+        sample_idx = np.random.choice(len(pts), 4, replace=False)
+        sample_pts = pts[sample_idx]
+        try:
+            R, t = fit_procrustes(sample_pts, grid_model[:4])
+        except:
+            continue
+        transformed = (grid_model @ R.T) + t
+        distances, indices = tree.query(transformed)
+        inlier_mask = distances < threshold
+        inlier_count = np.sum(inlier_mask)
+        if inlier_count > best_inlier_count:
+            best_inlier_count = inlier_count
+            best_R = R
+            best_t = t
+            best_inlier_indices = indices[inlier_mask]
+            best_inlier_mask = inlier_mask
+
+    if best_inlier_count > 10 and best_R is not None and best_inlier_indices is not None:
+        inlier_pts = pts[best_inlier_indices]
+        model_matched = grid_model[best_inlier_mask]
+        if len(inlier_pts) >= 4:
+            try:
+                R_refined, t_refined = fit_procrustes(inlier_pts, model_matched)
+                return R_refined, t_refined
+            except:
+                return best_R, best_t
+        else:
+            return best_R, best_t
+    return None
+
+
+def snap_to_grid_procrustes_fast(pts: np.ndarray, n_rows: int = GRID_ROWS, n_cols: int = GRID_COLS) -> Optional[np.ndarray]:
+    """Fast fallback snap using Procrustes."""
+    if len(pts) < 20:
+        return None
+    transform = ransac_grid_fit_fast(pts, n_rows, n_cols, iterations=15, threshold=4.0)
+    if transform is None:
+        return None
+    R, t = transform
+    grid_model = generate_ideal_grid(n_rows, n_cols)
+    transformed = (grid_model @ R.T) + t
+    tree = KDTree(transformed)
+    distances, indices = tree.query(pts)
+    valid = distances < 4.0
+    valid_indices = indices[valid]
+    row_col = grid_model[valid_indices]
+    rows = row_col[:, 1].astype(int)
+    cols = row_col[:, 0].astype(int)
+    grid = np.zeros((n_rows, n_cols), dtype=np.uint8)
+    valid_rows = (rows >= 0) & (rows < n_rows)
+    valid_cols = (cols >= 0) & (cols < n_cols)
+    valid_cells = valid_rows & valid_cols
+    grid[rows[valid_cells], cols[valid_cells]] = 1
+    return grid
+
+
+# ----------------------------------------------------------------------
+# Sauvola (optional, disabled by default)
+# ----------------------------------------------------------------------
+
+def sauvola_threshold(gray: np.ndarray, window_size: int = 15, k: float = 0.2, r: float = 128) -> np.ndarray:
+    gray_f = gray.astype(np.float32)
+    mean = cv2.boxFilter(gray_f, cv2.CV_32F, (window_size, window_size))
+    sqmean = cv2.boxFilter(gray_f * gray_f, cv2.CV_32F, (window_size, window_size))
+    std = np.sqrt(np.maximum(sqmean - mean * mean, 0))
+    threshold = mean * (1 + k * (std / r - 1))
+    binary = (gray_f > threshold).astype(np.uint8) * 255
+    return binary
+
+
+class BinaryPyramidSauvola(BinaryPyramid):
+    def get(self, mode, fixed_t, erosion_level):
+        if mode == "sauvola":
+            key = ("sauvola", None, erosion_level)
+            if key in self._eroded:
+                return self._eroded[key]
+            base_key = ("sauvola", None)
+            if base_key not in self._base:
+                binary = sauvola_threshold(self.enhanced)
+                self._base[base_key] = cv2.morphologyEx(binary, cv2.MORPH_OPEN, _KERNEL, iterations=1)
+            cur, start = self._base[base_key], 0
+            for lvl in range(erosion_level, 0, -1):
+                if ("sauvola", None, lvl) in self._eroded:
+                    cur, start = self._eroded[("sauvola", None, lvl)], lvl
+                    break
+            for lvl in range(start + 1, erosion_level + 1):
+                cur = cv2.erode(cur, _KERNEL, iterations=1)
+                self._eroded[("sauvola", None, lvl)] = cur
+            return cur
+        else:
+            return super().get(mode, fixed_t, erosion_level)
+
+
+def get_smart_combos(mean_brightness, use_sauvola=False):
+    combos = []
+    if use_sauvola:
+        combos.append(("sauvola", None, [2, 3]))
+    if mean_brightness < 40:
+        combos.extend([
+            ("otsu", None, [2, 3, 4]),
+            ("fixed", 135, [2, 3]),
+            ("fixed", 145, [2, 3]),
+            ("fixed", 155, [2, 3]),
+        ])
+    elif mean_brightness < 55:
+        combos.extend([
+            ("otsu", None, [2, 3]),
+            ("fixed", 145, [2, 3]),
+            ("fixed", 155, [2, 3]),
+            ("fixed", 165, [2, 3]),
+        ])
+    elif mean_brightness < 70:
+        combos.extend([
+            ("otsu", None, [2, 3]),
+            ("fixed", 155, [2, 3, 4]),
+            ("fixed", 165, [2, 3, 4]),
+            ("fixed", 175, [2, 3]),
+        ])
+    else:
+        combos.extend([
+            ("otsu", None, [2, 3]),
+            ("fixed", 165, [2, 3]),
+            ("fixed", 175, [2, 3]),
+            ("fixed", 155, [2, 3]),
+        ])
+    return combos
+
+
+# ----------------------------------------------------------------------
+# Rotation and straightening (unchanged)
+# ----------------------------------------------------------------------
+
+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):
+    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:
+                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
+
+
+# ----------------------------------------------------------------------
+# Main Decoder Class
+# ----------------------------------------------------------------------
+
+class DotCodeDecoder:
+    def __init__(
+        self,
+        timeout_ms: int = 300,
+        confidence: float = 0.25,
+        fast_mode: bool = True,
+        use_sauvola: bool = False      # disabled by default for speed
+    ):
+        self.timeout_ms = timeout_ms
+        self.confidence = confidence
+        self.fast_mode = fast_mode
+        self.use_sauvola = use_sauvola
+
+    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
+        if self.use_sauvola:
+            pyramid = BinaryPyramidSauvola(gray)
+        else:
+            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, self.use_sauvola):
+            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 ───
+        straight_pts, angle = straighten_dots_iterative(best_pts, GRID_ROWS, degree=2)
+
+        # Primary: use original fast snap
+        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:
+            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]),
+            ]
+            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:
+            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 using best_pts with original snap
+        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: primary is original snap
+        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)
+                    # Primary: original snap
+                    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:
+                        # If occupancy is low, try Procrustes fallback
+                        grid_fallback = snap_to_grid_procrustes_fast(rotated_pts, GRID_ROWS, GRID_COLS)
+                        if grid_fallback is not None:
+                            occupancy_fb = np.sum(grid_fallback) / ((GRID_ROWS * GRID_COLS + 1) // 2)
+                            if occupancy_fb > occupancy:
+                                grid = grid_fallback
+                                occupancy = occupancy_fb
+
+                    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)
+            if self.use_sauvola:
+                pyramid_inv = BinaryPyramidSauvola(inverted)
+            else:
+                pyramid_inv = BinaryPyramid(inverted)
+
+            inv_modes = [("otsu", None, [2, 3]), ("fixed", 155, [2, 3])]
+            for mode, threshold, erosions in inv_modes:
+                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
+
+                    for angle in fine_angles[:5]:
+                        if check_timeout():
+                            return DecodeResult(success=False, error="TIMEOUT", elapsed_ms=self.timeout_ms, timed_out=True)
+
+                        rotated_pts = rotate_points(pts, angle)
+                        # Primary: original snap
+                        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:
+                            grid_fallback = snap_to_grid_procrustes_fast(rotated_pts, GRID_ROWS, GRID_COLS)
+                            if grid_fallback is not None:
+                                occupancy_fb = np.sum(grid_fallback) / ((GRID_ROWS * GRID_COLS + 1) // 2)
+                                if occupancy_fb > occupancy:
+                                    grid = grid_fallback
+                                    occupancy = occupancy_fb
+
+                        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)
+
+# 10,11,161,163,174,245,290,302,303,333,357,359,373,6,79
+#10,103,11,128,133,136,161,163,171,194,201,209,245,303,333,351,357,373,6,61