discface 0.1.0__py3-none-any.whl

discface/__init__.py

@@ -0,0 +1,17 @@
+"""discface: from a photo of a CD / DVD to the flat, upright disc.
+
+    import discface
+
+    disc = discface.extract('photo.jpg')                 # locate, rectify, turn upright
+    disc.save('disc.png')                                # 2048 x 2048 RGBA, transparent outside the rim and in the hole
+
+    geometry = discface.locate('photo.jpg')              # the single steps
+    flat = discface.rectify('photo.jpg', geometry)
+    o = discface.orient(flat, enhance='always')
+    upright = flat.rotate(o.rotation)
+"""
+from .api import Disc, DiscGeometry, DiscNotFound, Orientation, extract, load_detector, locate, orient, rectify
+
+__version__ = '0.1.0'
+__all__ = ['Disc', 'DiscGeometry', 'DiscNotFound', 'Orientation', 'extract', 'load_detector', 'locate', 'orient',
+           'rectify', '__version__']

discface/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

discface/_disc.py

@@ -0,0 +1,210 @@
+"""Finding the disc in a photo and rectifying it (pure geometry, no learning).
+
+1. Edges of the image (difference to the background colour + grey-level Canny) at half resolution.
+2. Ellipse candidates from the edge contours; the rim is the large, well-supported one, the hub rings are the
+   small ones near its centre.
+3. The true disc centre is extrapolated from the hub ellipses: centres of projected concentric circles drift
+   linearly with r^2.
+4. The exact homography maps the rim conic to a circle: the polar of the centre w.r.t. the rim is the vanishing
+   line of the disc plane; the remaining affine part is a Cholesky factor of the conic.
+5. The centre hole is the innermost ring covered over at least half its circumference in the rectified plane.
+6. Lanczos4 resampling of the disc annulus into a square image with an anti-aliased alpha mask.
+"""
+import numpy as np
+
+from ._imaging import (resize_linear, normalize_minmax_u8, gaussian_blur, canny, rgb2gray, find_contours,
+                       fit_ellipse, ellipse_pixels, warp_perspective)
+
+
+def filter_and_detect_edges(img, scale=0.5):
+    small = resize_linear(img, scale)
+    bg = np.median(np.concatenate([
+        small[:20, :].reshape(-1, 3),
+        small[-20:, :].reshape(-1, 3),
+        small[:, :20].reshape(-1, 3),
+        small[:, -20:].reshape(-1, 3)
+    ]), axis=0)
+    diff = np.linalg.norm(small.astype(np.float32) - bg, axis=2)
+    diff_norm = normalize_minmax_u8(diff)
+    blurred_diff = gaussian_blur(diff_norm, 9, 2)
+    edges_diff = canny(blurred_diff, 30, 80)
+
+    gray = rgb2gray(small)
+    blurred_gray = gaussian_blur(gray, 5, 1.2)
+    edges_gray = canny(blurred_gray, 20, 60)
+
+    combined_edges = np.maximum(edges_diff, edges_gray)
+    return combined_edges, small
+
+
+def detect_candidate_ellipses(edges):
+    sh, sw = edges.shape[:2]
+    cnts = find_contours(edges)
+    candidates = []
+    for c in cnts:
+        if len(c) >= 30:
+            box = fit_ellipse(c)
+            if box is None:
+                continue
+            (cx, cy), (d1, d2), ang = box
+            a, b = max(d1, d2) / 2.0, min(d1, d2) / 2.0
+            if a > 15 and b > 15 and (b / a) > 0.7:
+                if 0.15 * sw < cx < 0.85 * sw and 0.15 * sh < cy < 0.85 * sh:
+                    py, px = ellipse_pixels(box, (sh, sw), thickness=2)
+                    votes = np.count_nonzero(edges[py, px])
+                    perim = 2 * np.pi * np.sqrt((a**2 + b**2) / 2.0)
+                    score = votes / (perim + 1e-5)
+                    if score > 0.25:
+                        candidates.append({
+                            'box': box,
+                            'cx': cx,
+                            'cy': cy,
+                            'a': a,
+                            'b': b,
+                            'ang': ang,
+                            'score': score
+                        })
+    return candidates
+
+
+def ellipse_to_conic(box):
+    (cx, cy), (d1, d2), ang = box
+    t = np.radians(ang)
+    R = np.array([[np.cos(t), -np.sin(t)], [np.sin(t), np.cos(t)]])
+    A = np.eye(3)
+    A[:2, :2] = R.T
+    A[:2, 2] = -R.T @ np.array([cx, cy])
+    return A.T @ np.diag([4.0 / d1**2, 4.0 / d2**2, -1.0]) @ A
+
+
+def homography_from_rim_and_center(outer_box, center, size=2048, margin=32):
+    (cx, cy), (d1, d2), _ = outer_box
+    s = 2.0 / (d1 + d2)
+    N = np.array([[s, 0, -s * cx], [0, s, -s * cy], [0, 0, 1.0]])
+    Ni = np.linalg.inv(N)
+    C = Ni.T @ ellipse_to_conic(outer_box) @ Ni
+    C /= np.abs(C).max()
+    c = N @ np.array([center[0], center[1], 1.0])
+
+    # the polar of the disc centre w.r.t. the rim conic is the vanishing line of the disc plane
+    l = C @ c
+    l /= l[2]
+    H_proj = np.array([[1, 0, 0], [0, 1, 0], [l[0], l[1], 1.0]])
+    Hpi = np.linalg.inv(H_proj)
+    C_aff = Hpi.T @ C @ Hpi
+
+    # remaining affine ellipse -> unit circle
+    M, m, k = C_aff[:2, :2], C_aff[:2, 2], C_aff[2, 2]
+    x0 = -np.linalg.solve(M, m)
+    L = np.linalg.cholesky(M / (m @ np.linalg.solve(M, m) - k))
+    H_aff = np.eye(3)
+    H_aff[:2, :2] = L.T
+    H_aff[:2, 2] = -L.T @ x0
+    H_unit = H_aff @ H_proj @ N
+
+    # in-plane rotation: keep the image "down" direction pointing down
+    c_img = np.linalg.inv(H_unit) @ np.array([0, 0, 1.0])
+    c_img /= c_img[2]
+    q = H_unit @ np.array([c_img[0], c_img[1] + 0.3 * (d1 + d2) / 2.0, 1.0])
+    q /= q[2]
+    phi = np.arctan2(q[0], q[1])
+    R = np.array([[np.cos(phi), -np.sin(phi), 0], [np.sin(phi), np.cos(phi), 0], [0, 0, 1.0]])
+
+    tc = size / 2.0
+    tr = tc - margin
+    S = np.array([[tr, 0, tc], [0, tr, tc], [0, 0, 1.0]])
+    H = S @ R @ H_unit
+    return H / H[2, 2]
+
+
+def select_hole_ring(edges, outer_box, center, size=2048, margin=32, min_coverage=0.5):
+    # Hough-like radius accumulator around the consensus centre in the rectified plane:
+    # a real ring must be covered over at least half of its circumference; the hole is the innermost one
+    # inside the search window given by the disc standard (15 mm hole on a 120 mm disc -> 0.125 * r)
+    H = homography_from_rim_and_center(outer_box, center, size, margin)
+    tc = size / 2.0
+    tr = tc - margin
+    ys, xs = np.nonzero(edges)
+    P = H @ np.stack([xs.astype(np.float64), ys.astype(np.float64), np.ones(len(xs))])
+    x, y = P[0] / P[2] - tc, P[1] / P[2] - tc
+    r = np.hypot(x, y)
+    ang_bin = ((np.arctan2(y, x) + np.pi) / (2 * np.pi) * 360).astype(int) % 360
+
+    radii = np.arange(0.10 * tr, 0.15 * tr, 0.5)
+    coverage = np.array([len(np.unique(ang_bin[np.abs(r - R) < 1.5])) / 360.0 for R in radii])
+    for i in range(1, len(radii) - 1):
+        if coverage[i] >= min_coverage and coverage[i] >= coverage[i - 1] and coverage[i] >= coverage[i + 1]:
+            t = np.linspace(0, 2 * np.pi, 360, endpoint=False)
+            Q = np.linalg.inv(H) @ np.stack([tc + radii[i] * np.cos(t), tc + radii[i] * np.sin(t), np.ones_like(t)])
+            return fit_ellipse(np.stack([Q[0] / Q[2], Q[1] / Q[2]], 1))
+    return None
+
+
+def select_outer_and_inner_ellipses(candidates, edges):
+    sh, sw = edges.shape[:2]
+    cd_cands = [c for c in candidates if c['a'] >= 45.0]
+    outers = [c for c in cd_cands if c['a'] > 0.25 * min(sw, sh)]
+    if not outers:
+        outers = [max(cd_cands, key=lambda c: c['a'])]
+    best_outer = max(outers, key=lambda c: (c['score'], c['a']))
+
+    inners = [
+        c for c in cd_cands 
+        if 0.08 * best_outer['a'] <= c['a'] <= 0.40 * best_outer['a']
+        and np.hypot(c['cx'] - best_outer['cx'], c['cy'] - best_outer['cy']) < 85.0
+    ]
+
+    for c in inners:
+        close_members = [o for o in inners if np.hypot(c['cx'] - o['cx'], c['cy'] - o['cy']) < 18.0]
+        c['consensus_weight'] = sum(o['score'] for o in close_members)
+        c['consensus_members'] = close_members
+
+    best_inner_anchor = max(inners, key=lambda c: c['consensus_weight'])
+    consensus_inners = best_inner_anchor['consensus_members']
+
+    shared_cx = float(np.median([c['cx'] for c in consensus_inners]))
+    shared_cy = float(np.median([c['cy'] for c in consensus_inners]))
+
+    # projected ellipse centres of concentric circles drift linearly with r^2 -> extrapolate to r = 0
+    rho2 = (float(np.median([c['a'] for c in consensus_inners])) / best_outer['a']) ** 2
+    center = (
+        (shared_cx - rho2 * best_outer['cx']) / (1.0 - rho2),
+        (shared_cy - rho2 * best_outer['cy']) / (1.0 - rho2)
+    )
+
+    outer_box = best_outer['box']
+    inner_box = select_hole_ring(edges, outer_box, center)
+    if inner_box is None:
+        hole_cands = [c for c in consensus_inners if c['a'] < 0.16 * best_outer['a']]
+        if hole_cands:
+            innermost = min(hole_cands, key=lambda c: c['a'])
+        else:
+            innermost = min(consensus_inners, key=lambda c: c['a'])
+        inner_box = innermost['box']
+    return outer_box, inner_box, center
+
+
+def rectify_and_project_to_circle(img, outer_box, inner_box, center, scale=0.5, size=2048, margin=32):
+    up = lambda b: ((b[0][0] / scale, b[0][1] / scale), (b[1][0] / scale, b[1][1] / scale), b[2])
+    outer_box, inner_box = up(outer_box), up(inner_box)
+    center = (center[0] / scale, center[1] / scale)
+
+    H = homography_from_rim_and_center(outer_box, center, size, margin)
+
+    tc = size / 2.0
+    tr = tc - margin
+    t = np.linspace(0, 2 * np.pi, 360, endpoint=False)
+    (icx, icy), (id1, id2), iang = inner_box
+    ia = np.radians(iang)
+    ex, ey = id1 / 2.0 * np.cos(t), id2 / 2.0 * np.sin(t)
+    hole = H @ np.stack([icx + ex * np.cos(ia) - ey * np.sin(ia), icy + ex * np.sin(ia) + ey * np.cos(ia), np.ones_like(t)])
+    hole_r = float(np.median(np.hypot(hole[0] / hole[2] - tc, hole[1] / hole[2] - tc)))
+
+    # analytic anti-aliased annulus (1px ramp) instead of a blurred hard mask
+    yy, xx = np.mgrid[0:size, 0:size].astype(np.float32)
+    d = np.hypot(xx - tc, yy - tc)
+    alpha = np.clip(tr - d + 0.5, 0, 1) * np.clip(d - hole_r + 0.5, 0, 1)
+
+    # only the visible disc is resampled; fully transparent pixels stay black
+    warped = warp_perspective(img, H, size, mask=alpha > 0)
+    return np.dstack([warped, (alpha * 255 + 0.5).astype(np.uint8)])

discface/_enhance.py

@@ -0,0 +1,62 @@
+"""Edge enhancement for faint print (grey on silver, print under rainbow reflections).
+
+Two complementary views of the disc, both multi-scale band-passes (differences of Gaussians) on the luminance:
+they keep stroke-sized detail with its polarity (dark print stays dark) and remove smooth shading and reflections,
+each band normalised by its local energy. The second view first normalises the local contrast (local mean / local
+standard deviation) and maps the result through a soft S-curve, which pulls very faint print further up. Their
+errors differ, so their words vote together (evaluated on real discs reduced to 8-20 % contrast with reflections,
+blur and JPEG: 18 of 19 correct, against 17 for either view alone)."""
+import numpy as np
+from PIL import Image
+
+_BANDS = ((0.8, 3.0), (1.5, 6.0), (3.0, 12.0))
+
+
+def _box(a, r, axis):
+    """Mean over a window of 2r+1 along axis (edge-replicated), via cumulative sums."""
+    if r < 1:
+        return a
+    pad = [(0, 0)] * a.ndim
+    pad[axis] = (r + 1, r)
+    c = np.cumsum(np.pad(a, pad, mode='edge'), axis=axis, dtype=np.float64)
+    n = a.shape[axis]
+    hi = np.take(c, np.arange(2 * r + 1, 2 * r + 1 + n), axis=axis)
+    lo = np.take(c, np.arange(0, n), axis=axis)
+    return ((hi - lo) / (2 * r + 1)).astype(np.float32)
+
+
+def _blur(a, sigma):
+    """Gaussian of std sigma, approximated by three box filters per axis."""
+    r = max(0, int(round((np.sqrt(4.0 * sigma * sigma + 1.0) - 1.0) / 2.0)))
+    a = a.astype(np.float32)
+    for axis in (0, 1):
+        for _ in range(3):
+            a = _box(a, r, axis)
+    return a
+
+
+def _bands(lum):
+    acc = np.zeros_like(lum)
+    for s1, s2 in _BANDS:
+        d = _blur(lum, s1) - _blur(lum, s2)
+        acc += d / (np.sqrt(_blur(d * d, 4.0 * s2)) + 1.5)
+    return acc
+
+
+def _grey(v, alpha):
+    g = np.clip(v, 0, 255).astype(np.uint8)
+    g[alpha == 0] = 200
+    return Image.fromarray(np.repeat(g[..., None], 3, -1))
+
+
+def enhanced_views(rgba: Image.Image, size: int = 1024):
+    """The disc at ``size`` px as grey images in which the print stands out (outside the disc: light grey):
+    [band-pass, local-contrast-normalised band-pass with S-curve]."""
+    a = np.asarray(rgba.convert('RGBA').resize((size, size), Image.LANCZOS)).astype(np.float32)
+    alpha = a[..., 3]
+    lum = 0.299 * a[..., 0] + 0.587 * a[..., 1] + 0.114 * a[..., 2]
+    plain = _grey(128.0 + 40.0 * _bands(lum), alpha)
+    m = _blur(lum, 16.0)
+    lcn = 40.0 * (lum - m) / (np.sqrt(_blur((lum - m) ** 2, 16.0)) + 2.0)
+    curved = _grey(128.0 + 127.0 * np.tanh(0.45 * _bands(lcn)), alpha)
+    return [plain, curved]

discface/_imaging.py

@@ -0,0 +1,362 @@
+"""Image primitives in numpy + Pillow (no OpenCV). Images are RGB uint8 (H x W x 3).
+
+Grey conversion, resize, 8-bit Gaussian and Canny reproduce OpenCV's fixed-point arithmetic bit-exactly,
+find_contours is the same Suzuki-Abe border following, fit_ellipse the same estimator as cv.fitEllipse.
+"""
+import os
+from concurrent.futures import ThreadPoolExecutor
+
+import numpy as np
+from PIL import Image, ImageOps
+
+# ------------------------------------------------------------------ I/O
+def imread_rgb(path):
+    """Any format Pillow can decode -> RGB uint8. EXIF orientation is applied (as cv2.imread does);
+    16-bit, greyscale, palette, CMYK and alpha images are converted."""
+    im = ImageOps.exif_transpose(Image.open(path))
+    if im.mode in ('I;16', 'I;16B', 'I;16L', 'I'):
+        a = np.asarray(im, np.float64)
+        im = Image.fromarray(np.clip(a / (257.0 if a.max() > 255 else 1.0) + 0.5, 0, 255).astype(np.uint8))
+    if im.mode in ('RGBA', 'LA', 'PA') or (im.mode == 'P' and 'transparency' in im.info):
+        im = im.convert('RGBA').convert('RGB')     # alpha is dropped, like cv2.IMREAD_COLOR
+    return np.asarray(im.convert('RGB'))
+
+
+# ------------------------------------------------------------------ basic filters
+def rgb2gray(rgb):
+    """OpenCV's 8-bit fixed-point conversion: 0.299 R + 0.587 G + 0.114 B in 15-bit fixed point (bit-exact)."""
+    a = rgb.astype(np.int32)
+    return ((a[..., 0] * 9798 + a[..., 1] * 19235 + a[..., 2] * 3735 + (1 << 14)) >> 15).astype(np.uint8)
+
+
+def resize_linear(img, scale):
+    """Bilinear resize with OpenCV's pixel-centre convention (cv.resize(..., fx=scale, fy=scale))."""
+    h, w = img.shape[:2]
+    nh, nw = int(round(h * scale)), int(round(w * scale))
+    if scale == 0.5 and h % 2 == 0 and w % 2 == 0 and img.dtype == np.uint8:
+        # exact 2x reduction: OpenCV's fixed-point bilinear equals the rounded mean of each 2x2 block
+        a = img.astype(np.uint16)
+        return ((a[0::2, 0::2] + a[0::2, 1::2] + a[1::2, 0::2] + a[1::2, 1::2] + 2) >> 2).astype(np.uint8)
+
+    def axis(n_out, n_in):
+        s = (np.arange(n_out) + 0.5) / scale - 0.5
+        s = np.clip(s, 0, n_in - 1)
+        i0 = np.floor(s).astype(np.int64)
+        i1 = np.minimum(i0 + 1, n_in - 1)
+        return i0, i1, (s - i0).astype(np.float32)
+
+    y0, y1, fy = axis(nh, h)
+    x0, x1, fx = axis(nw, w)
+    a = img.astype(np.float32)
+    rows = a[y0] * (1 - fy)[:, None, None] + a[y1] * fy[:, None, None] if a.ndim == 3 else \
+        a[y0] * (1 - fy)[:, None] + a[y1] * fy[:, None]
+    out = rows[:, x0] * (1 - fx)[None, :, None] + rows[:, x1] * fx[None, :, None] if a.ndim == 3 else \
+        rows[:, x0] * (1 - fx)[None, :] + rows[:, x1] * fx[None, :]
+    return np.clip(np.floor(out + 0.5), 0, 255).astype(np.uint8) if img.dtype == np.uint8 else out
+
+
+def _sep_filter(a, k, mode):
+    r = len(k) // 2
+    p = np.pad(a, r, mode=mode)
+    tmp = sum(k[i] * p[i:i + a.shape[0], :] for i in range(len(k)))
+    return sum(k[i] * tmp[:, i:i + a.shape[1]] for i in range(len(k)))
+
+
+def gaussian_blur(img, ksize, sigma):
+    """cv.GaussianBlur(img, (ksize, ksize), sigma) with BORDER_REFLECT_101. For uint8 input OpenCV's bit-exact
+    path is reproduced: kernel in 8.8 fixed point (taps sum to exactly 256), rounding after both passes."""
+    x = np.arange(ksize) - (ksize - 1) / 2.0
+    k = np.exp(-x ** 2 / (2 * sigma ** 2))
+    k /= k.sum()
+    if img.dtype != np.uint8:
+        return _sep_filter(img.astype(np.float32), k.astype(np.float32), 'reflect')
+    kq = np.round(k * 256).astype(np.int32)
+    kq[ksize // 2] += 256 - kq.sum()
+    r = ksize // 2
+    p = np.pad(img.astype(np.int32), r, mode='reflect')
+    h = sum(kq[i] * p[:, i:i + img.shape[1]] for i in range(ksize))
+    v = sum(kq[i] * h[i:i + img.shape[0], :] for i in range(ksize))
+    return ((v + (1 << 15)) >> 16).astype(np.uint8)
+
+
+def normalize_minmax_u8(a):
+    """cv.normalize(a, None, 0, 255, cv.NORM_MINMAX).astype(np.uint8)  (float result, then truncated)."""
+    a = a.astype(np.float32)
+    lo, hi = float(a.min()), float(a.max())
+    scale = np.float32(255.0 / max(hi - lo, 1e-12))
+    return np.clip(a * scale + np.float32(-lo * scale), 0, 255).astype(np.uint8)
+
+
+# ------------------------------------------------------------------ connected components (8-neighbourhood)
+def label_pixels(mask):
+    """Connected components of the True pixels (8-connectivity).
+    Returns (ys, xs, labels) with labels in 0..n-1 for every True pixel."""
+    ys, xs = np.nonzero(mask)
+    n = len(ys)
+    if n == 0:
+        return ys, xs, np.zeros(0, np.int64)
+    h, w = mask.shape
+    idx = np.full((h + 2, w + 2), -1, np.int64)
+    idx[ys + 1, xs + 1] = np.arange(n)
+    a_list, b_list = [], []
+    for dy, dx in ((0, 1), (1, -1), (1, 0), (1, 1)):
+        nb = idx[ys + 1 + dy, xs + 1 + dx]
+        ok = nb >= 0
+        a_list.append(np.nonzero(ok)[0])
+        b_list.append(nb[ok])
+    a = np.concatenate(a_list)
+    b = np.concatenate(b_list)
+    parent = np.arange(n)
+    while True:
+        pa, pb = parent[a], parent[b]
+        lo, hi = np.minimum(pa, pb), np.maximum(pa, pb)
+        changed = lo != hi
+        if not changed.any():
+            break
+        np.minimum.at(parent, hi[changed], lo[changed])
+        while True:                                   # pointer jumping
+            nxt = parent[parent]
+            if np.array_equal(nxt, parent):
+                break
+            parent = nxt
+    _, labels = np.unique(parent, return_inverse=True)
+    return ys, xs, labels
+
+
+# ------------------------------------------------------------------ Canny (OpenCV semantics, L1 gradient, aperture 3)
+def canny(img, low, high):
+    a = np.pad(img.astype(np.int32), 1, mode='edge')            # Sobel with BORDER_REPLICATE
+    dx = (a[:-2, 2:] + 2 * a[1:-1, 2:] + a[2:, 2:]) - (a[:-2, :-2] + 2 * a[1:-1, :-2] + a[2:, :-2])
+    dy = (a[2:, :-2] + 2 * a[2:, 1:-1] + a[2:, 2:]) - (a[:-2, :-2] + 2 * a[:-2, 1:-1] + a[:-2, 2:])
+    mag = np.abs(dx) + np.abs(dy)
+    low, high = int(np.floor(low)), int(np.floor(high))
+    h, w = img.shape
+    m = np.zeros((h + 2, w + 2), np.int32)                       # outside the image the magnitude is 0
+    m[1:-1, 1:-1] = mag
+    ys, xs = np.nonzero(mag > low)                               # non-maximum suppression only where needed
+    c = mag[ys, xs]
+    gx, gy = dx[ys, xs], dy[ys, xs]
+    ax, ay = np.abs(gx), np.abs(gy) << 15
+    tg22 = ax * 13573                                            # tan(22.5 deg) * 2^15
+    tg67 = tg22 + (ax << 16)
+    Y, X = ys + 1, xs + 1
+    horiz = ay < tg22
+    vert = ~horiz & (ay > tg67)
+    diag = ~horiz & ~vert
+    keep = np.zeros(len(c), bool)
+    keep[horiz] = (c[horiz] > m[Y[horiz], X[horiz] - 1]) & (c[horiz] >= m[Y[horiz], X[horiz] + 1])
+    keep[vert] = (c[vert] > m[Y[vert] - 1, X[vert]]) & (c[vert] >= m[Y[vert] + 1, X[vert]])
+    s_ = np.where((gx[diag] ^ gy[diag]) < 0, -1, 1)
+    Yd, Xd = Y[diag], X[diag]
+    keep[diag] = (c[diag] > m[Yd - 1, Xd - s_]) & (c[diag] > m[Yd + 1, Xd + s_])
+    cand = np.zeros((h, w), bool)
+    cand[ys[keep], xs[keep]] = True
+    strong = np.zeros((h, w), bool)
+    sk = keep & (c > high)
+    strong[ys[sk], xs[sk]] = True
+    # hysteresis: keep the 8-connected candidate chains that contain a strong pixel
+    cy, cx, lab = label_pixels(cand)
+    good = np.zeros(lab.max() + 1 if len(lab) else 0, bool)
+    good[lab[strong[cy, cx]]] = True
+    out = np.zeros((h, w), np.uint8)
+    sel = good[lab]
+    out[cy[sel], cx[sel]] = 255
+    return out
+
+
+# ------------------------------------------------------------------ contours / ellipses
+# 8-neighbourhood in counter-clockwise order (image coordinates, y down): E, NE, N, NW, W, SW, S, SE
+_DY = (0, -1, -1, -1, 0, 1, 1, 1)
+_DX = (1, 1, 0, -1, -1, -1, 0, 1)
+
+
+def find_contours(binary):
+    """Suzuki-Abe border following (RETR_LIST, CHAIN_APPROX_NONE): every outer and hole border of the
+    8-connected foreground as an array of (x, y) points, like cv.findContours."""
+    h, w = binary.shape
+    f = np.zeros((h + 2, w + 2), np.int32)
+    f[1:-1, 1:-1] = binary != 0
+    W = w + 2
+    fl = f.ravel().tolist()                         # python list: fast scalar access in the tracing loop
+    offs = [dy * W + dx for dy, dx in zip(_DY, _DX)]
+    contours = []
+    nbd = 1
+    starts = np.flatnonzero(f.ravel())
+    for p in starts.tolist():
+        v = fl[p]
+        if v == 0:
+            continue
+        if v == 1 and fl[p - 1] == 0:
+            nbd += 1
+            from_dir = 4                            # came from the west neighbour
+        elif v >= 1 and fl[p + 1] == 0:
+            nbd += 1
+            from_dir = 0                            # came from the east neighbour
+        else:
+            continue
+        # 3.1: clockwise from the "from" neighbour, find the first non-zero pixel
+        d1 = -1
+        for k in range(8):
+            d = (from_dir - k) % 8
+            if fl[p + offs[d]] != 0:
+                d1 = d
+                break
+        if d1 < 0:                                  # isolated pixel
+            fl[p] = -nbd
+            contours.append([p])
+            continue
+        pts = []
+        p2 = p + offs[d1]
+        p3 = p
+        d2 = d1                                     # direction from p3 to p2
+        while True:
+            pts.append(p3)
+            # 3.3: counter-clockwise from the element after p2, find first non-zero neighbour p4
+            east_zero_examined = False
+            k = (d2 + 1) % 8
+            while True:
+                q = p3 + offs[k]
+                if fl[q] != 0:
+                    break
+                if k == 0:
+                    east_zero_examined = True
+                k = (k + 1) % 8
+            p4, d4 = q, k
+            # 3.4
+            if east_zero_examined:
+                fl[p3] = -nbd
+            elif fl[p3] == 1:
+                fl[p3] = nbd
+            # 3.5
+            if p4 == p and p3 == p + offs[d1]:
+                break
+            # next step: new p2 is old p3, seen from p4
+            d2 = (d4 + 4) % 8
+            p3 = p4
+        contours.append(pts)
+    out = []
+    for c in contours:
+        c = np.asarray(c, np.int64)
+        out.append(np.stack([c % W - 1, c // W - 1], 1))
+    return out
+
+
+def fit_ellipse(points):
+    """Least-squares ellipse fit with the same estimator as cv.fitEllipse (general conic fit for the centre,
+    then a centred re-fit of the quadratic form; algorithm by D. Weiss). Axes and angle come from the
+    eigen-decomposition of the quadratic form, which is also correct where OpenCV 4.13 reports angle 0.
+    Returns ((cx, cy), (w, h), angle) with w <= h and w lying along the angle; None if not an ellipse."""
+    p = np.asarray(points, np.float64).reshape(-1, 2)
+    n = len(p)
+    if n < 5:
+        return None
+    c = p.mean(0)
+    q = p - c
+    s = np.abs(q).sum()
+    scale = 100.0 / max(s, np.finfo(np.float32).eps)
+    px, py = q[:, 0] * scale, q[:, 1] * scale
+    A = np.stack([-px * px, -py * py, -px * py, px, py], 1)
+    try:
+        gfp = np.linalg.solve(A.T @ A, A.T @ np.full(n, 10000.0))
+        r0 = np.linalg.solve(np.array([[2 * gfp[0], gfp[2]], [gfp[2], 2 * gfp[1]]]), gfp[3:5])
+        dx, dy = px - r0[0], py - r0[1]
+        B = np.stack([dx * dx, dy * dy, dx * dy], 1)
+        g = np.linalg.solve(B.T @ B, B.sum(0))
+    except np.linalg.LinAlgError:
+        return None
+    lam, vec = np.linalg.eigh(np.array([[g[0], g[2] / 2.0], [g[2] / 2.0, g[1]]]))
+    if not np.all(lam > 0):
+        return None
+    semi = 1.0 / np.sqrt(lam) / scale                 # lam ascending -> semi descending
+    w, h = 2 * semi[1], 2 * semi[0]
+    v = vec[:, 1]                                     # direction of the shorter axis
+    angle = float(np.degrees(np.arctan2(v[1], v[0])) % 180.0)
+    return ((float(r0[0] / scale + c[0]), float(r0[1] / scale + c[1])), (float(w), float(h)), angle)
+
+
+def ellipse_pixels(box, shape, thickness=2):
+    """Pixels of an ellipse outline drawn with the given line thickness (pixel centres within thickness * 0.75
+    of the curve, which matches the coverage of cv.ellipse(..., thickness))."""
+    (cx, cy), (d1, d2), ang = box
+    a, b = d1 / 2.0, d2 / 2.0
+    half = 0.75 * thickness
+    t = np.linspace(0, 2 * np.pi, int(np.ceil(2 * np.pi * max(a, b) * 2)) + 16, endpoint=False)
+    th = np.radians(ang)
+    ex, ey = a * np.cos(t), b * np.sin(t)
+    px, py = cx + ex * np.cos(th) - ey * np.sin(th), cy + ex * np.sin(th) + ey * np.cos(th)
+    r = int(np.ceil(half)) + 1
+    oy, ox = np.mgrid[-r:r + 1, -r:r + 1]
+    near = (np.abs(ox) - 1) ** 2 + (np.abs(oy) - 1) ** 2 <= half * half   # offsets that can lie within reach
+    ox, oy = ox[near], oy[near]
+    X = (np.floor(px)[:, None] + ox[None]).astype(np.int64)
+    Y = (np.floor(py)[:, None] + oy[None]).astype(np.int64)
+    ok = ((X - px[:, None]) ** 2 + (Y - py[:, None]) ** 2 <= half * half) & (X >= 0) & (X < shape[1]) & (Y >= 0) & (Y < shape[0])
+    lin = np.unique(Y[ok] * shape[1] + X[ok])
+    return lin // shape[1], lin % shape[1]
+
+
+# ------------------------------------------------------------------ perspective warp (Lanczos4)
+def _lanczos4_weights(f):
+    """(N,) fractional offsets -> (N, 8) Lanczos4 weights for taps -3..4 (normalised like OpenCV)."""
+    k = np.arange(-3, 5, dtype=np.float32)
+    x = (f[:, None] - k[None, :]).astype(np.float32)
+    px = np.float32(np.pi) * x
+    with np.errstate(divide='ignore', invalid='ignore'):
+        w = np.where(np.abs(x) < 1e-6, np.float32(1.0), 4.0 * np.sin(px) * np.sin(px / 4.0) / (px * px))
+    return (w / w.sum(1, keepdims=True)).astype(np.float32)
+
+
+def warp_perspective(img, H, size, mask=None, rows_per_chunk=32, workers=None):
+    """dst(x, y) = src(H^-1 (x, y)), Lanczos4 interpolation, constant 0 outside the source.
+    mask (bool size x size, optional): only these destination pixels are computed, the rest stay 0."""
+    h, w = img.shape[:2]
+    Hi = np.linalg.inv(H)
+    # source bounding box actually needed (+ kernel support)
+    ys, xs = (np.nonzero(mask) if mask is not None else np.mgrid[0:size:16, 0:size:16].reshape(2, -1))
+    if mask is not None and len(ys) > 200000:
+        sel = np.linspace(0, len(ys) - 1, 200000).astype(np.int64)
+        ys, xs = ys[sel], xs[sel]
+    den = Hi[2, 0] * xs + Hi[2, 1] * ys + Hi[2, 2]
+    sx = (Hi[0, 0] * xs + Hi[0, 1] * ys + Hi[0, 2]) / den
+    sy = (Hi[1, 0] * xs + Hi[1, 1] * ys + Hi[1, 2]) / den
+    x0 = int(max(0, np.floor(sx.min()) - 8)); x1 = int(min(w, np.ceil(sx.max()) + 9))
+    y0 = int(max(0, np.floor(sy.min()) - 8)); y1 = int(min(h, np.ceil(sy.max()) + 9))
+    pad = 4
+    cw, ch = x1 - x0 + 2 * pad, y1 - y0 + 2 * pad
+    packed = np.zeros((ch, cw, 4), np.uint8)
+    packed[pad:pad + y1 - y0, pad:pad + x1 - x0, :3] = img[y0:y1, x0:x1]
+    flat = packed.view(np.uint32).reshape(-1)
+    out = np.zeros((size, size, 3), np.uint8)
+
+    def rows(r0):
+        r1 = min(size, r0 + rows_per_chunk)
+        yy, xx = np.mgrid[r0:r1, 0:size]
+        m = mask[r0:r1] if mask is not None else np.ones(yy.shape, bool)
+        X, Y = xx[m].astype(np.float64), yy[m].astype(np.float64)
+        if len(X) == 0:
+            return
+        den = Hi[2, 0] * X + Hi[2, 1] * Y + Hi[2, 2]
+        sx = (Hi[0, 0] * X + Hi[0, 1] * Y + Hi[0, 2]) / den - x0 + pad
+        sy = (Hi[1, 0] * X + Hi[1, 1] * Y + Hi[1, 2]) / den - y0 + pad
+        ix, iy = np.floor(sx).astype(np.int64), np.floor(sy).astype(np.int64)
+        wx = _lanczos4_weights((sx - ix).astype(np.float32))
+        wy = _lanczos4_weights((sy - iy).astype(np.float32))
+        ix = np.clip(ix, 3, cw - 5)
+        iy = np.clip(iy, 3, ch - 5)
+        base = iy * cw + ix
+        acc = np.zeros((len(X), 3), np.float32)
+        for j in range(8):
+            rowacc = np.zeros((len(X), 3), np.float32)
+            rb = base + (j - 3) * cw
+            for i in range(8):
+                v = flat[rb + (i - 3)].view(np.uint8).reshape(-1, 4)[:, :3]
+                rowacc += wx[:, i:i + 1] * v
+            acc += wy[:, j:j + 1] * rowacc
+        blk = np.zeros(yy.shape + (3,), np.uint8)
+        blk[m] = np.clip(acc + 0.5, 0, 255).astype(np.uint8)
+        out[r0:r1] = blk
+
+    # numpy releases the GIL in gathers and arithmetic, so row blocks run in parallel in plain threads
+    with ThreadPoolExecutor(workers or min(4, os.cpu_count() or 1)) as ex:
+        list(ex.map(rows, range(0, size, rows_per_chunk)))
+    return out

discface/_orient.py

@@ -0,0 +1,95 @@
+"""Turning a rectified disc upright from the reading direction of its text (doritex)."""
+import math
+from typing import Optional, Sequence
+
+import numpy as np
+
+
+def is_rim_text(word, center, radius, zone=0.8, max_cos=0.35) -> bool:
+    """Text running round the disc near its rim: in the outer ring (beyond ``zone`` of the radius) and tangential,
+    i.e. its reading direction nearly perpendicular to the radius. Such text occurs at every angle, so it says
+    nothing about which way the design is up."""
+    r = np.asarray(word.center, np.float64) - center
+    dist = float(np.linalg.norm(r))
+    if dist <= zone * radius:
+        return False
+    return abs(float(np.dot(word.direction, r / max(dist, 1e-9)))) < max_cos
+
+
+def disc_vote(words: Sequence, center=None, radius=None):
+    """(angle, support): rotation of the disc's printing (counter-clockwise degrees, like ``doritex.Word.angle``) and
+    the summed weight of the words that agree with it; (None, 0.0) without words.
+
+    Text running round the rim is left out (given ``center`` and ``radius``) unless there is nothing else, because it
+    points in every direction. Of the rest, the most common reading direction wins, not the mean: each word weighs
+    by its size in px (titles define "up" more than small print), detection score and direction confidence; the
+    peak of the angle distribution is refined by the weighted mean of the words within 20 degrees of it."""
+    if not words:
+        return None, 0.0
+    if center is not None and radius is not None:
+        inner = [wd for wd in words if not is_rim_text(wd, np.asarray(center, np.float64), radius)]
+        words = inner or words
+    w = np.array([wd.score * max(2.0 * wd.direction_confidence - 1.0, 1e-3) * wd.height for wd in words])
+    a = np.radians([wd.angle for wd in words])
+    grid = np.radians(np.arange(0.0, 360.0, 1.0))
+    density = (w[None] * np.exp(8.0 * (np.cos(grid[:, None] - a[None]) - 1.0))).sum(1)     # von Mises kernel
+    peak = grid[int(np.argmax(density))]
+    near = np.cos(a - peak) > math.cos(math.radians(20.0))
+    angle = math.degrees(math.atan2(float((w[near] * np.sin(a[near])).sum()), float((w[near] * np.cos(a[near])).sum())))
+    return float(angle), float(w[near].sum())
+
+
+def disc_angle(words: Sequence, center=None, radius=None) -> Optional[float]:
+    """The angle of ``disc_vote``, or None without words."""
+    return disc_vote(words, center, radius)[0]
+
+
+def rotate_points(points: np.ndarray, angle: float, center) -> np.ndarray:
+    """Points (x right, y down) rotated counter-clockwise on screen by ``angle`` degrees about ``center``,
+    the same motion as ``PIL.Image.rotate(angle)``."""
+    t = math.radians(angle)
+    c, s = math.cos(t), math.sin(t)
+    d = np.asarray(points, np.float64) - center
+    return np.stack([center[0] + c * d[..., 0] + s * d[..., 1], center[1] - s * d[..., 0] + c * d[..., 1]], -1)
+
+
+def _polygon_area(p):
+    x, y = p[:, 0], p[:, 1]
+    return 0.5 * float(np.dot(x, np.roll(y, -1)) - np.dot(y, np.roll(x, -1)))
+
+
+def _clip(subject, a, b):
+    out = []
+    side = lambda p: (b[0] - a[0]) * (p[1] - a[1]) - (b[1] - a[1]) * (p[0] - a[0])
+    for i in range(len(subject)):
+        cur, nxt = subject[i], subject[(i + 1) % len(subject)]
+        sc, sn = side(cur), side(nxt)
+        if sc >= 0:
+            out.append(cur)
+        if (sc >= 0) != (sn >= 0):
+            out.append(cur + sc / (sc - sn) * (nxt - cur))
+    return out
+
+
+def _iou(a, b) -> float:
+    a = np.asarray(a, np.float64)
+    b = np.asarray(b, np.float64)
+    a = a if _polygon_area(a) >= 0 else a[::-1]
+    b = b if _polygon_area(b) >= 0 else b[::-1]
+    inter = list(a)
+    for i in range(len(b)):
+        if not inter:
+            break
+        inter = _clip(inter, b[i], b[(i + 1) % len(b)])
+    ia = abs(_polygon_area(np.array(inter))) if len(inter) >= 3 else 0.0
+    union = abs(_polygon_area(a)) + abs(_polygon_area(b)) - ia
+    return ia / union if union > 1e-9 else 0.0
+
+
+def dedupe(words, iou=0.4):
+    """Merge two readings of the same disc: of overlapping boxes (IoU >= iou) keep the more confident one."""
+    kept = []
+    for w in sorted(words, key=lambda w: -w.score):
+        if all(_iou(w.quad, k.quad) < iou for k in kept):
+            kept.append(w)
+    return kept

discface/api.py

@@ -0,0 +1,201 @@
+"""Public API: from a photo of a CD / DVD to the flat, upright disc.
+
+The pipeline has three steps, each callable on its own:
+    locate(photo)               -> DiscGeometry (rim, hole, true centre in the photo)
+    rectify(photo, geometry)    -> the flat disc (square RGBA, transparent outside the rim and in the hole)
+    orient(flat_disc)           -> Orientation (how far to turn it so that its printing reads upright)
+``extract`` runs all three.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple, Union
+
+import numpy as np
+from PIL import Image
+
+from ._imaging import imread_rgb
+from ._disc import filter_and_detect_edges, detect_candidate_ellipses, select_outer_and_inner_ellipses, \
+    rectify_and_project_to_circle
+from ._orient import disc_vote, rotate_points, dedupe
+from ._enhance import enhanced_views
+
+ImageLike = Union[str, os.PathLike, Image.Image, np.ndarray]
+Ellipse = Tuple[Tuple[float, float], Tuple[float, float], float]     # ((cx, cy), (w, h), angle in degrees)
+ENHANCE_MODES = ('auto', 'always', 'off')
+
+
+class DiscNotFound(ValueError):
+    """No disc rim / centre hole could be found in the image."""
+
+
+@dataclass
+class DiscGeometry:
+    """Where the disc lies in the photo (pixels): rim and centre hole as ellipses ``((cx, cy), (w, h), angle)``
+    and the true disc centre, which under perspective is not the centre of the rim ellipse."""
+
+    rim: Ellipse
+    hole: Ellipse
+    center: Tuple[float, float]
+
+
+@dataclass
+class Orientation:
+    """How far to turn a flat disc so that its printing reads upright.
+
+    ``rotation``: counter-clockwise degrees (the convention of ``PIL.Image.rotate``); 0 if the text was too weak.
+    ``support``: weight of the text that agreed on the direction (sum of word size x confidence).
+    ``turned``: whether the support reached the threshold. ``enhanced``: whether faint print was also read from
+    edge-enhanced views. ``words``: the words read (``doritex.Word``), in coordinates of the image passed in."""
+
+    rotation: float
+    support: float
+    turned: bool
+    enhanced: bool
+    words: List = field(default_factory=list)
+
+
+@dataclass
+class Disc:
+    """A disc cut out of a photo.
+
+    ``image``: the disc seen from straight above, square RGBA, transparent outside the rim and in the centre hole.
+    ``rotation``: counter-clockwise degrees by which it was turned to make its printing upright (0 if not turned).
+    ``orientation_support`` / ``enhanced``: see ``Orientation``. ``words``: words read on the disc, in ``image``
+    coordinates. ``rim``, ``hole``, ``center``: where the disc lies in the photo."""
+
+    image: Image.Image
+    rotation: float
+    words: List = field(default_factory=list)
+    rim: Optional[Ellipse] = None
+    hole: Optional[Ellipse] = None
+    center: Optional[Tuple[float, float]] = None
+    orientation_support: float = 0.0
+    enhanced: bool = False
+
+    def to_image(self, background=None) -> Image.Image:
+        """``image``; with ``background`` (a colour such as ``"white"`` or ``(32, 32, 32)``) the transparent parts
+        are filled and an RGB image is returned."""
+        if background is None:
+            return self.image
+        bg = Image.new('RGBA', self.image.size, background)
+        return Image.alpha_composite(bg, self.image.convert('RGBA')).convert('RGB')
+
+    def save(self, path, background=None, **kwargs):
+        """Save the disc. PNG / WebP keep the transparency; formats without alpha (JPEG) get a white background
+        unless ``background`` is given."""
+        if background is None and os.path.splitext(str(path))[1].lower() in ('.jpg', '.jpeg', '.bmp'):
+            background = 'white'
+        self.to_image(background).save(path, **kwargs)
+
+
+# ----------------------------------------------------------------------------------------------- steps
+
+def _photo_rgb(image: ImageLike) -> np.ndarray:
+    if isinstance(image, (str, os.PathLike)):
+        return imread_rgb(image)                      # applies the EXIF orientation
+    if isinstance(image, Image.Image):
+        return np.asarray(image.convert('RGB'))
+    a = np.asarray(image)
+    if a.dtype != np.uint8:
+        a = np.clip(a * 255.0 if a.max() <= 1.0 else a, 0, 255).astype(np.uint8)
+    if a.ndim == 2:
+        a = np.repeat(a[..., None], 3, -1)
+    return np.ascontiguousarray(a[..., :3])
+
+
+def _scale(box, s):
+    (cx, cy), (w, h), ang = box
+    return ((cx * s, cy * s), (w * s, h * s), ang)
+
+
+def locate(image: ImageLike) -> DiscGeometry:
+    """Find the disc in a photo. Raises ``DiscNotFound`` if no disc is visible."""
+    return _locate(_photo_rgb(image))
+
+
+def _locate(rgb: np.ndarray) -> DiscGeometry:
+    edges, _ = filter_and_detect_edges(rgb)           # at half resolution
+    candidates = detect_candidate_ellipses(edges)
+    try:
+        outer, inner, center = select_outer_and_inner_ellipses(candidates, edges)
+    except (ValueError, IndexError) as exc:
+        raise DiscNotFound('no disc found in the image') from exc
+    return DiscGeometry(_scale(outer, 2.0), _scale(inner, 2.0), (center[0] * 2.0, center[1] * 2.0))
+
+
+def rectify(image: ImageLike, geometry: Optional[DiscGeometry] = None, size: int = 2048, margin: int = 32) -> Image.Image:
+    """The disc as seen from straight above: ``size`` x ``size`` RGBA, the rim at ``margin`` px from the border,
+    transparent outside the rim and in the hole. Locates the disc first if no ``geometry`` is given."""
+    rgb = _photo_rgb(image)
+    g = geometry or _locate(rgb)
+    return Image.fromarray(rectify_and_project_to_circle(rgb, g.rim, g.hole, g.center, scale=1.0, size=size,
+                                                         margin=margin), 'RGBA')
+
+
+def orient(disc: Image.Image, enhance: str = 'auto', min_support: float = 40.0, margin: int = 32,
+           detector=None, device: str = 'auto') -> Orientation:
+    """How far to turn a flat disc (as from ``rectify``) so that its printing reads upright.
+
+    Every word votes for its reading direction, weighted by size and confidence; text running round the rim is
+    left out; the most common direction wins. The disc counts as decided when the agreeing words weigh at least
+    ``min_support`` (for a 2048 px disc, scaled with its size).
+    ``enhance``: 'auto' reads faint print a second time from edge-enhanced views, only when the plain reading is
+    too weak (discs that read well are not affected); 'always' always adds those views; 'off' never.
+    ``detector``: a ``doritex.Detector`` to reuse; otherwise the cached one for ``device`` ('auto': an OpenCL GPU
+    if present, else the CPU; 'cpu': always the CPU)."""
+    if enhance not in ENHANCE_MODES:
+        raise ValueError(f'enhance must be one of {ENHANCE_MODES}, not {enhance!r}')
+    det = detector or load_detector(device)
+    size = disc.size[0]
+    work = min(size, 1024)
+    words = det.detect(disc, input_size=work)
+    vote = lambda ws: disc_vote(ws, center=(size / 2.0, size / 2.0), radius=size / 2.0 - margin)
+    angle, support = vote(words)
+    threshold = min_support * size / 2048.0
+    enhanced = False
+    if enhance == 'always' or (enhance == 'auto' and (angle is None or support < threshold)):
+        k = size / float(work)
+        for view in enhanced_views(disc, work):
+            words += [type(w)(quad=w.quad * k, score=w.score, direction_confidence=w.direction_confidence)
+                      for w in det.detect(view, input_size=work)]
+        words, enhanced = dedupe(words), True
+        angle, support = vote(words)
+    turned = angle is not None and support >= threshold
+    return Orientation(rotation=-angle if turned else 0.0, support=float(support), turned=turned, enhanced=enhanced,
+                       words=words)
+
+
+def extract(image: ImageLike, size: int = 2048, margin: int = 32, autorotate: bool = True, enhance: str = 'auto',
+            min_support: float = 40.0, detector=None, device: str = 'auto') -> Disc:
+    """Find the disc in a photo, rectify it and (``autorotate=True``) turn it so that its printing reads upright.
+    See ``rectify`` (``size``, ``margin``) and ``orient`` (``enhance``, ``min_support``, ``detector``, ``device``).
+    Raises ``DiscNotFound`` if no disc is visible."""
+    rgb = _photo_rgb(image)
+    geometry = _locate(rgb)
+    flat = rectify(rgb, geometry, size=size, margin=margin)
+    if not autorotate:
+        return Disc(flat, 0.0, [], geometry.rim, geometry.hole, geometry.center)
+    o = orient(flat, enhance=enhance, min_support=min_support, margin=margin, detector=detector, device=device)
+    if not o.turned:
+        return Disc(flat, 0.0, o.words, geometry.rim, geometry.hole, geometry.center, o.support, o.enhanced)
+    c = np.array([size / 2.0, size / 2.0])
+    words = [type(w)(quad=rotate_points(w.quad, o.rotation, c), score=w.score, direction_confidence=w.direction_confidence)
+             for w in o.words]
+    return Disc(flat.rotate(o.rotation, resample=Image.BICUBIC), o.rotation, words, geometry.rim, geometry.hole,
+                geometry.center, o.support, o.enhanced)
+
+
+_DETECTORS = {}
+
+
+def load_detector(device: str = 'auto'):
+    """The doritex detector used for reading the text (cached per device): 'auto' (OpenCL GPU if present) or 'cpu'."""
+    if device not in ('auto', 'cpu'):
+        raise ValueError(f"device must be 'auto' or 'cpu', not {device!r}")
+    if device not in _DETECTORS:
+        import doritex
+        _DETECTORS[device] = doritex.load(device=device)
+    return _DETECTORS[device]
+

discface/cli.py

@@ -0,0 +1,96 @@
+"""Command line: discface PHOTO_OR_DIR... [-o OUT_DIR] [options]"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import List
+
+from .api import ENHANCE_MODES, DiscNotFound, extract, load_detector
+
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.tif', '.tiff', '.bmp', '.webp', '.heic'}
+
+
+def _inputs(paths: List[str]) -> List[str]:
+    files = []
+    for p in paths:
+        if os.path.isdir(p):
+            files += sorted(os.path.join(p, f) for f in os.listdir(p) if os.path.splitext(f)[1].lower() in IMAGE_EXTENSIONS)
+        else:
+            files.append(p)
+    return files
+
+
+def _r2(v):
+    return [_r2(x) for x in v] if isinstance(v, (tuple, list)) else round(float(v), 2)
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog='discface', description='Cut CDs / DVDs out of photos: flat, upright, '
+                                 'transparent outside the rim and in the centre hole.')
+    ap.add_argument('inputs', nargs='+', help='photos or folders of photos')
+    ap.add_argument('-o', '--output', default='.', help='output folder (default: current folder)')
+    ap.add_argument('--size', type=int, default=2048, help='side of the output image in px (default: 2048)')
+    ap.add_argument('--margin', type=int, default=32, help='px between the rim and the image border (default: 32)')
+    ap.add_argument('--no-autorotate', action='store_true', help='only rectify, do not turn the printing upright')
+    ap.add_argument('--enhance', choices=ENHANCE_MODES, default='auto',
+                    help="faint print: 'auto' reads it from edge-enhanced views only when the plain reading is too weak "
+                         "(default), 'always' always adds them, 'off' never")
+    ap.add_argument('--min-support', type=float, default=40.0,
+                    help='how much agreeing text is needed to turn a disc (default: 40, for 2048 px)')
+    ap.add_argument('--background', default=None,
+                    help="fill the transparent parts with a colour, e.g. white or '#202020' (default: transparent)")
+    ap.add_argument('--format', choices=('png', 'jpg', 'webp'), default='png',
+                    help='output format (default: png; jpg gets a white background unless --background is given)')
+    ap.add_argument('--suffix', default='', help="appended to the output file names, e.g. '_disc'")
+    ap.add_argument('--device', choices=('auto', 'cpu'), default='auto', help="text reading on an OpenCL GPU ('auto') or the CPU")
+    ap.add_argument('--draw', action='store_true', help='also save <name>_words.png with the words read on the disc')
+    ap.add_argument('--json', action='store_true', help='print one JSON object per photo instead of a summary line')
+    ap.add_argument('-q', '--quiet', action='store_true', help='print nothing except errors')
+    args = ap.parse_args(argv)
+
+    files = _inputs(args.inputs)
+    if not files:
+        ap.error('no input images')
+    os.makedirs(args.output, exist_ok=True)
+    detector = None if args.no_autorotate else load_detector(args.device)
+
+    failed = 0
+    for path in files:
+        name = os.path.splitext(os.path.basename(path))[0] + args.suffix
+        out = os.path.join(args.output, f'{name}.{args.format}')
+        try:
+            disc = extract(path, size=args.size, margin=args.margin, autorotate=not args.no_autorotate,
+                           enhance=args.enhance, min_support=args.min_support, detector=detector)
+        except (DiscNotFound, OSError) as exc:
+            failed += 1
+            err = 'no disc found' if isinstance(exc, DiscNotFound) else str(exc)
+            if args.json:
+                print(json.dumps({'input': path, 'error': err}))
+            else:
+                print(f'{path}: {err}', file=sys.stderr)
+            continue
+        disc.save(out, background=args.background)
+        if args.draw:
+            import doritex
+            doritex.draw(disc.to_image(args.background or (200, 200, 200)), disc.words).save(
+                os.path.join(args.output, f'{name}_words.png'))
+        if args.json:
+            print(json.dumps({'input': path, 'output': out, 'rotation': round(disc.rotation, 2),
+                              'oriented': disc.rotation != 0.0, 'orientation_support': round(disc.orientation_support, 1),
+                              'enhanced': disc.enhanced, 'words': len(disc.words), 'rim': _r2(disc.rim),
+                              'hole': _r2(disc.hole), 'center': _r2(disc.center)}))
+        elif not args.quiet:
+            if args.no_autorotate:
+                note = 'rectified'
+            elif disc.rotation != 0.0:
+                note = f'turned {disc.rotation:.1f}°  {len(disc.words)} words' + ('  (faint print, edge-enhanced)' if disc.enhanced else '')
+            else:
+                note = 'not turned: too little readable text, kept as photographed'
+            print(f'{path} -> {out}  {note}')
+    return 1 if failed else 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

discface-0.1.0.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: discface
+Version: 0.1.0
+Summary: From a photo of a CD or DVD to the flat, upright disc image
+Author: discface contributors
+License: MIT
+Project-URL: Homepage, https://github.com/GodOfLores/discface
+Project-URL: Source, https://github.com/GodOfLores/discface
+Project-URL: Issues, https://github.com/GodOfLores/discface/issues
+Keywords: CD,DVD,disc,rectification,perspective,orientation,doritex
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: doritex>=0.1.0
+Requires-Dist: numpy>=1.23
+Requires-Dist: Pillow>=9.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# discface
+
+Transforms photos of CDs and DVDs into flat, top-down disc images. It removes perspective distortion, cuts out the disc with a transparent outer rim and centre hole, and rotates it so printed text reads upright. The disc boundary is detected geometrically, while text is read with [doritex](https://pypi.org/project/doritex/).
+
+```bash
+pip install discface
+```
+
+## Example
+
+```python
+import discface
+
+disc = discface.extract("blank_dvd.jpg")       # photo of a blank DVD+R on a light table
+print(disc.image.size, disc.image.mode)
+print(f"turned by {disc.rotation:.1f}°, faint print enhanced: {disc.enhanced}")
+disc.save("blank_dvd_disc.png")
+```
+
+Output:
+
+```
+(2048, 2048) RGBA
+turned by -17.7°, faint print enhanced: True
+```
+
+<table>
+  <tr>
+    <td align="center"><img src="https://raw.githubusercontent.com/GodOfLores/discface/main/blank_dvd.jpg" alt="photo of a blank DVD lying on a table" width="420"><br><code>blank_dvd.jpg</code></td>
+    <td align="center"><img src="https://raw.githubusercontent.com/GodOfLores/discface/main/blank_dvd.png" alt="the same disc, flat, cut out and upright" width="300"><br><code>blank_dvd_disc.png</code></td>
+  </tr>
+</table>
+
+Perspective distortion is removed, leaving the disc neatly cut out with a transparent outer rim and centre hole. The image was rotated by −17.7° so that "Verbatim" reads horizontally. Because grey print on silver is often faint, it was also detected via edge-enhanced views (`enhanced: True`).
+
+## Taking the photo
+
+discface is designed for discs placed on a **plain, uniform background** and photographed from roughly above. A sheet of white paper or a light grey tabletop works best, which is how all reference test photos were taken.
+
+- Keep the entire disc in frame with some surrounding margin, ensuring the centre hole is visible.
+- Shoot from roughly above. Moderate tilt is corrected automatically, and perspective is rectified precisely.
+- Ensure even lighting. Moderate reflections are tolerated, and faint print benefits from enabling `enhance`.
+- Capture a single disc per photo, keeping other circular objects out of frame.
+
+In a benchmark where backgrounds around real discs were replaced while keeping the discs intact, rim detection rates were as follows:
+
+| background | rim found |
+|---|---|
+| light, uniform (all real photos) | 7/7 |
+| dark, uniform | 6/7 |
+| mid grey, uniform | 6/7 |
+| busy (photos, printed paper, noise) | 5/35 |
+
+On dark backgrounds, centre hole detection is less reliable (4/7). Patterned or cluttered backgrounds are not currently supported.
+
+## Command line
+
+```bash
+discface photos/ -o discs/
+```
+
+```
+photos/IMG_4097.JPG -> discs/IMG_4097.png  turned 39.2°  59 words
+photos/IMG_4100.JPG -> discs/IMG_4100.png  turned -1.7°  80 words
+blank_dvd.jpg -> discs/blank_dvd.png  turned -17.7°  71 words  (faint print, edge-enhanced)
+```
+
+Inputs can be individual photos, directories, or a mix of both. Each disc is saved as `<photo name><suffix>.<format>` in the output folder.
+
+| option | meaning |
+|---|---|
+| `-o DIR` | output folder (default: current folder) |
+| `--size N` | output image dimension in px (default 2048) |
+| `--margin N` | margin between the rim and the image border in px (default 32) |
+| `--no-autorotate` | rectify perspective only, without rotating text upright |
+| `--enhance auto\|always\|off` | edge enhancement for faint print, detailed below (default `auto`) |
+| `--min-support X` | minimum text agreement score required to rotate a disc (default 40) |
+| `--background COLOR` | fill transparent areas with a solid colour, e.g. `white` or `'#202020'` |
+| `--format png\|jpg\|webp` | output format; `jpg` defaults to a white background unless `--background` is specified |
+| `--suffix TEXT` | string appended to output filenames |
+| `--device auto\|cpu` | device used for text recognition (OpenCL GPU or CPU) |
+| `--draw` | also save `<name>_words.png` visualizing detected words |
+| `--json` | print one JSON line per photo containing detection metadata |
+| `-q` | quiet mode, suppressing all output except errors |
+
+Photos without a detectable disc are reported and skipped, returning exit code 1. You can also run the tool via `python -m discface`.
+
+## API
+
+**`discface.extract(image, size=2048, margin=32, autorotate=True, enhance="auto", min_support=40, device="auto", detector=None) -> Disc`**
+Runs the three steps below in sequence. `image` can be a file path (with automatic EXIF orientation handling), a `PIL.Image`, or an RGB NumPy array. `device` selects the text recognition backend: `"auto"` uses an OpenCL GPU if present and falls back to CPU, while `"cpu"` forces CPU execution. Raises `discface.DiscNotFound` if no disc is detected.
+
+The individual steps can also be called directly:
+
+```python
+geometry = discface.locate("photo.jpg")                       # DiscGeometry: rim, hole, center in the photo
+flat = discface.rectify("photo.jpg", geometry, size=2048)      # flat disc, RGBA, not turned
+o = discface.orient(flat, enhance="always")                   # Orientation: rotation, support, turned, enhanced, words
+upright = flat.rotate(o.rotation)
+```
+
+| | |
+|---|---|
+| `Disc.image` | Rectified disc as a `PIL.Image` (RGBA, `size × size`) with transparency outside the rim and inside the centre hole |
+| `Disc.rotation` | Counter-clockwise rotation in degrees applied to align text upright (`0` if unrotated) |
+| `Disc.orientation_support` | Cumulative score of agreeing text; below `min_support`, the disc is left unrotated |
+| `Disc.enhanced` | `True` if faint text was detected using edge-enhanced views |
+| `Disc.words` | Words detected on the disc (`doritex.Word`: `quad`, `angle360`, `score`, …) in `image` coordinates |
+| `Disc.rim`, `.hole`, `.center` | Disc geometry in the input photo: fitted ellipses `((cx, cy), (width, height), angle)` and true centre coordinates |
+| `Disc.save(path, background=None)` | Saves the image to disk. PNG and WebP preserve transparency, while JPEG defaults to a white background |
+| `Disc.to_image(background=None)` | Returns the `PIL.Image`, optionally composited over a solid background colour |
+| `discface.load_detector(device="auto")` | Returns a cached doritex detector instance; pass via `detector=` to reuse across calls |
+
+## How upright orientation is decided
+
+Every word detected on the disc votes for its reading direction. Large words carry more weight than fine print, and high-confidence detections outweigh uncertain ones. The dominant direction wins, so a few words printed sideways do not skew the result. Small text running circular along the rim is excluded, as it points in every direction. If too little text agrees (`min_support`), the disc retains its original orientation from the photo.
+
+Faint print, such as grey text on a silver disc or lettering obscured by rainbow reflections, can also be read from two edge-enhanced views. These views emphasize character strokes, boost local contrast, and suppress smooth shading and reflections. The `enhance` option controls this behavior:
+
+- `auto` (default): applies edge enhancement only when standard detection yields insufficient confidence. Discs that read well are processed without extra overhead.
+- `always`: processes edge-enhanced views for every disc, adding roughly 1 to 2 seconds per image.
+- `off`: never applies edge enhancement.
+
+## Performance
+
+Benchmark times for a 24-megapixel photo after the initial warmup run (which compiles GPU kernels on first execution):
+
+| step | GPU (`device="auto"`) | CPU (`device="cpu"`) |
+|---|---|---|
+| read the photo | 0.2 s | 0.2 s |
+| `locate` | 1.1 s | 1.1 s |
+| `rectify` | 0.8 s | 0.8 s |
+| `orient` | 0.3 s | 1.9 s |
+| `orient`, `enhance="always"` | 3.1 s | 8.6 s |
+| **total per photo** | **≈ 2.4 s** | **≈ 4.1 s** |
+
+Both devices produce identical results. Only text recognition runs on the GPU; locating and rectifying the disc always run on the CPU.
+
+## License
+
+MIT

discface-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+discface/__init__.py,sha256=cKfP3KI6iLjqmc32nWRPHZStnd9kogsbbQG28XgtA-0,803
+discface/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+discface/_disc.py,sha256=2ar9fwJE9f92P3EU82yCjjblW0ZDk1QHGHpC5RDMuHQ,9077
+discface/_enhance.py,sha256=vkNeVCUoy1jOy4QQ90bAAZAyW8NFe4eYE6mjsrJCjkk,2599
+discface/_imaging.py,sha256=S_fLKOePr_IxkT-nsa1GHBcDjc8r6MlFwb1riwWbC1Y,16331
+discface/_orient.py,sha256=WtvW-w93t-Monnz6l9mUIFhtEaijiJGsTj3cfDiobZI,4264
+discface/api.py,sha256=E6JlDDc0zJGVp-iNj6OYFszdaoT251y13f9OdA_hjnI,9502
+discface/cli.py,sha256=yvvmh5eIRgM2qRmklTGB4enM365s9geaqEgc5SPRe6w,4999
+discface/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+discface-0.1.0.dist-info/METADATA,sha256=WmRBNW5EMaiYjnk5Vd8DnKhMHLtUwSnJguTvluEYUSY,8758
+discface-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+discface-0.1.0.dist-info/entry_points.txt,sha256=sk-Pquw4vGTaOtV9CKd8Rno701VOn1DwNAhV092pU2c,47
+discface-0.1.0.dist-info/top_level.txt,sha256=knxNzh5NWQwZcU2_Y0FC73gCIG8g0YP1FGqN6-WQV_E,9
+discface-0.1.0.dist-info/RECORD,,

discface-0.1.0.dist-info/WHEEL

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

discface-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+discface = discface.cli:main

discface-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+discface