discface 0.1.0__tar.gz

discface-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 discface contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

discface-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+prune tests
+prune docs

discface-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,141 @@
+# 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/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-0.1.0/discface/__main__.py

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

discface-0.1.0/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-0.1.0/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]