seedbuddy 0.2.0__py3-none-any.whl

seedbuddy/__init__.py

@@ -0,0 +1 @@
+"""Prepare culture-dish photographs for a SeedBuddy workbench."""

seedbuddy/__main__.py

@@ -0,0 +1,3 @@
+from seedbuddy.cli import main
+
+raise SystemExit(main())

seedbuddy/cli.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from seedbuddy.photos.record import (
+    has_confirmations,
+    load_record,
+    record_of,
+    save_record,
+)
+from seedbuddy.photos.review import serve_review
+from seedbuddy.photos.sorting import sort_photographs
+
+
+def _sort(args: argparse.Namespace) -> int:
+    folder = Path(args.folder).expanduser().resolve()
+    if not folder.is_dir():
+        raise ValueError(f"{folder} is not a folder")
+    output = _unconfirmed(args.output)
+    record = record_of(sort_photographs(folder, progress=_progress))
+    if output is not None:
+        save_record(output, record)
+    json.dump(record, sys.stdout, indent=2, ensure_ascii=False)
+    sys.stdout.write("\n")
+    return 0
+
+
+def _review(args: argparse.Namespace) -> int:
+    path = Path(args.file).expanduser()
+    if not path.is_file():
+        raise ValueError(f"{path} is not a file")
+    serve_review(path)
+    return 0
+
+
+def _unconfirmed(output: str | None) -> Path | None:
+    """Where the record may be written: a file that holds no confirmation."""
+    if output is None:
+        return None
+    path = Path(output).expanduser()
+    if path.is_file() and has_confirmations(load_record(path)):
+        raise ValueError(f"{path} already holds confirmations")
+    return path
+
+
+def _progress(line: str) -> None:
+    print(line, file=sys.stderr)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="seedbuddy",
+        description="Prepare culture-dish photographs for a SeedBuddy workbench.",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    photos = commands.add_parser("photos", help="Work with a folder of photographs")
+    photo_commands = photos.add_subparsers(dest="photos_command", required=True)
+    sorting = photo_commands.add_parser(
+        "sort",
+        help="Sort the photographs into dishes and suggest one to use for each",
+        description=(
+            "Sort the photographs in FOLDER by the dish they show, the one whose "
+            "seeds are sharpest first, and say whether the seeds in each can be "
+            "told apart well enough to count. Prints JSON; files are left "
+            "untouched."
+        ),
+    )
+    sorting.add_argument("folder", metavar="FOLDER")
+    sorting.add_argument(
+        "-o",
+        "--output",
+        metavar="FILE",
+        help=(
+            "also write the JSON to FILE; refused when FILE already holds confirmations"
+        ),
+    )
+    sorting.set_defaults(handler=_sort)
+    reviewing = photo_commands.add_parser(
+        "review",
+        help="Confirm which photograph of each dish to use",
+        description=(
+            "Serve a page to confirm or correct the suggestions in FILE. "
+            "Confirmations are written back into FILE. The photographs stay "
+            "where they are."
+        ),
+    )
+    reviewing.add_argument("file", metavar="FILE")
+    reviewing.set_defaults(handler=_review)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        return args.handler(args)
+    except (OSError, ValueError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 2

seedbuddy/photos/__init__.py

@@ -0,0 +1 @@
+"""Sort a folder of dish photographs and confirm which of each dish to use."""

seedbuddy/photos/dish-recipe.json

@@ -0,0 +1,12 @@
+{
+  "thumbnailLongEdge": 1200,
+  "sigma": 3,
+  "dp": 1.2,
+  "edgeThreshold": 80,
+  "centerThreshold": 45,
+  "minRadiusFraction": 0.32,
+  "maxRadiusFraction": 0.49,
+  "radiusPreference": 0.15,
+  "coverageMargin": 0.15,
+  "radiusTolerancePixels": 1
+}

seedbuddy/photos/dish.py

@@ -0,0 +1,58 @@
+"""Locate the dish circle in a grayscale photograph.
+
+The dish recipe is byte-identical to the workbench recipe.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass
+from importlib.resources import files
+
+import cv2
+import numpy as np
+
+RECIPE = json.loads(files("seedbuddy.photos").joinpath("dish-recipe.json").read_text())
+
+
+@dataclass(frozen=True)
+class DishCircle:
+    x: float
+    y: float
+    radius: float
+
+
+def locate_dish(gray: np.ndarray) -> DishCircle | None:
+    height, width = gray.shape
+    scale = min(1.0, RECIPE["thumbnailLongEdge"] / max(width, height))
+    size = (
+        max(1, math.floor(width * scale + 0.5)),
+        max(1, math.floor(height * scale + 0.5)),
+    )
+    small = cv2.resize(gray, size, interpolation=cv2.INTER_AREA)
+    small = cv2.GaussianBlur(small, (0, 0), RECIPE["sigma"])
+    side = min(small.shape)
+    circles = cv2.HoughCircles(
+        small,
+        cv2.HOUGH_GRADIENT,
+        dp=RECIPE["dp"],
+        minDist=side // 2,
+        param1=RECIPE["edgeThreshold"],
+        param2=RECIPE["centerThreshold"],
+        minRadius=int(side * RECIPE["minRadiusFraction"]),
+        maxRadius=int(side * RECIPE["maxRadiusFraction"]),
+    )
+    if circles is None:
+        return None
+    # The dish is the large circle near the middle of the frame.
+    centre = np.array([small.shape[1] / 2.0, small.shape[0] / 2.0])
+    x, y, radius = min(
+        circles[0],
+        key=lambda c: (
+            np.linalg.norm(c[:2] - centre) - RECIPE["radiusPreference"] * c[2]
+        ),
+    )
+    return DishCircle(
+        x=float(x / scale), y=float(y / scale), radius=float(radius / scale)
+    )

seedbuddy/photos/features.py

@@ -0,0 +1,57 @@
+"""Distinctive points of a dish photograph and their counterparts in another."""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+from seedbuddy.photos.dish import DishCircle
+
+# Features are found at a resolution where the dish has this radius, so every
+# threshold expressed in dish radii holds for any camera.
+WORKING_RADIUS = 700.0
+# Removes fine periodic texture, such as a woven filter paper, whose repeats
+# match anywhere; seeds are several times larger and survive.
+TEXTURE_SIGMA = 1.0
+CONTRAST_THRESHOLD = 0.02
+RATIO_TEST = 0.75
+
+
+def features(
+    gray: np.ndarray, dish: DishCircle, radius: float, limit: int = 0
+) -> tuple[np.ndarray, np.ndarray]:
+    """Points within ``radius`` dish radii of the centre, in full-resolution pixels.
+
+    ``limit`` keeps only the strongest features; 0 keeps them all.
+    """
+    scale = min(1.0, WORKING_RADIUS / dish.radius)
+    small = cv2.resize(gray, None, fx=scale, fy=scale, interpolation=cv2.INTER_AREA)
+    small = cv2.GaussianBlur(small, (0, 0), TEXTURE_SIGMA)
+    mask = np.zeros_like(small)
+    cv2.circle(
+        mask,
+        (round(dish.x * scale), round(dish.y * scale)),
+        round(dish.radius * scale * radius),
+        255,
+        -1,
+    )
+    sift = cv2.SIFT.create(nfeatures=limit, contrastThreshold=CONTRAST_THRESHOLD)
+    keypoints, descriptors = sift.detectAndCompute(small, mask)
+    points = np.array([keypoint.pt for keypoint in keypoints], np.float32)
+    if descriptors is None:
+        descriptors = np.empty((0, 128), np.float32)
+    return points.reshape(-1, 2) / scale, descriptors
+
+
+def matches(
+    descriptors_a: np.ndarray, descriptors_b: np.ndarray
+) -> list[tuple[int, int]]:
+    """Index pairs of features that resemble each other and nothing else."""
+    if len(descriptors_a) < 2 or len(descriptors_b) < 2:
+        return []
+    pairs = cv2.BFMatcher().knnMatch(descriptors_a, descriptors_b, k=2)
+    return [
+        (pair[0].queryIdx, pair[0].trainIdx)
+        for pair in pairs
+        if len(pair) == 2 and pair[0].distance < RATIO_TEST * pair[1].distance
+    ]

seedbuddy/photos/fingerprint.py

@@ -0,0 +1,74 @@
+"""Recognize two photographs of one dish by the layout of everything in it.
+
+Seeds, the substrate's outline and the lid's labels together form a layout no
+other dish shares. Two photographs show the same dish when one rigid motion of
+the camera carries that layout from one onto the other across the whole dish;
+a patch that agrees alone, such as a date label every dish of a batch carries,
+does not.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+from seedbuddy.photos.dish import DishCircle
+from seedbuddy.photos.features import features, matches
+
+FEATURE_RADIUS = 0.95
+MAX_FEATURES = 4000
+# The lid sits above the seeds, so a change of camera height moves the two by
+# slightly different amounts; the tolerance absorbs that parallax.
+REPROJECTION_TOLERANCE = 0.014
+MIN_INLIERS = 8
+MIN_INLIER_SHARE = 0.5
+MAX_SCALE_ERROR = 0.1
+MIN_COVERAGE = 0.05
+
+
+@dataclass(frozen=True)
+class Survey:
+    path: Path
+    dish: DishCircle
+    points: np.ndarray
+    """Feature locations in full-resolution pixels."""
+    descriptors: np.ndarray
+
+
+def survey(path: Path, gray: np.ndarray, dish: DishCircle) -> Survey:
+    points, descriptors = features(gray, dish, FEATURE_RADIUS, MAX_FEATURES)
+    return Survey(path, dish, points, descriptors)
+
+
+def dish_motion(a: Survey, b: Survey) -> np.ndarray | None:
+    """The camera motion carrying a onto b, when they show the same dish."""
+    paired = matches(a.descriptors, b.descriptors)
+    if len(paired) < MIN_INLIERS:
+        return None
+    points_a = a.points[[i for i, _ in paired]]
+    points_b = b.points[[j for _, j in paired]]
+    motion, inliers = cv2.estimateAffinePartial2D(
+        points_a,
+        points_b,
+        method=cv2.RANSAC,
+        ransacReprojThreshold=REPROJECTION_TOLERANCE * b.dish.radius,
+    )
+    if motion is None or inliers is None:
+        return None
+    agreed = inliers.ravel().astype(bool)
+    count = int(agreed.sum())
+    if count < MIN_INLIERS or count / len(paired) < MIN_INLIER_SHARE:
+        return None
+
+    scale = float(np.hypot(motion[0, 0], motion[1, 0]))
+    expected = b.dish.radius / a.dish.radius
+    if scale <= 0 or abs(np.log(scale / expected)) > MAX_SCALE_ERROR:
+        return None
+
+    spread = cv2.contourArea(cv2.convexHull(points_b[agreed]))
+    if spread / (np.pi * b.dish.radius**2) < MIN_COVERAGE:
+        return None
+    return motion

seedbuddy/photos/photographs.py

@@ -0,0 +1,27 @@
+"""The photograph files a command is asked to read."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+PHOTO_SUFFIXES = {".jpg", ".jpeg", ".png", ".tif", ".tiff"}
+
+Progress = Callable[[str], None]
+
+
+@dataclass(frozen=True)
+class Skipped:
+    path: Path
+    reason: str
+
+
+def photographs_in(folder: Path) -> list[Path]:
+    return sorted(
+        path
+        for path in folder.iterdir()
+        if path.is_file()
+        and not path.name.startswith(".")
+        and path.suffix.lower() in PHOTO_SUFFIXES
+    )

seedbuddy/photos/record.py

@@ -0,0 +1,177 @@
+"""The record of a sorted folder: each dish's photographs, and what a person confirmed.
+
+Sorting suggests the first photograph of a dish and says whether its seeds can
+be counted. A person's confirmation is kept beside that suggestion as the
+dish's ``decision``, which names the photograph to use and whether it can be
+counted.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from seedbuddy.photos.photographs import PHOTO_SUFFIXES
+from seedbuddy.photos.sorting import Sorted
+
+
+def record_of(result: Sorted) -> dict:
+    return {
+        "dishes": [
+            {
+                "shots": [
+                    {
+                        "path": str(shot.path),
+                        "sharpness": None
+                        if shot.sharpness is None
+                        else round(shot.sharpness, 3),
+                        "suitable": shot.suitable,
+                        "reason": shot.reason,
+                        "alignment": [
+                            [round(value, 5) for value in row] for row in shot.alignment
+                        ],
+                    }
+                    for shot in dish.shots
+                ],
+            }
+            for dish in result.dishes
+        ],
+        "skipped": [
+            {"path": str(item.path), "reason": item.reason} for item in result.skipped
+        ],
+    }
+
+
+def load_record(path: Path) -> dict:
+    try:
+        record = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as error:
+        raise ValueError(f"{path} is not a record of sorted photographs") from error
+    if not _is_record(record):
+        raise ValueError(f"{path} is not a record of sorted photographs")
+    return record
+
+
+def save_record(path: Path, record: dict) -> None:
+    descriptor, temporary = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}-")
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(json.dumps(record, indent=2, ensure_ascii=False) + "\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    finally:
+        Path(temporary).unlink(missing_ok=True)
+
+
+def has_confirmations(record: dict) -> bool:
+    return any(dish.get("decision") is not None for dish in record["dishes"])
+
+
+def confirm(
+    record: dict, dish: int, shot: int, suitable: bool | None, note: str
+) -> None:
+    """Use one photograph of a dish, and say whether its seeds can be counted."""
+    entry = record["dishes"][dish]
+    entry["decision"] = _decision(entry["shots"][shot], suitable, note)
+
+
+def clear_confirmation(record: dict, dish: int) -> None:
+    record["dishes"][dish].pop("decision", None)
+
+
+def accept_remaining(record: dict) -> None:
+    """Confirm the suggestion for every dish that has no confirmation yet."""
+    for dish in record["dishes"]:
+        if dish.get("decision") is not None:
+            continue
+        suggested = dish["shots"][0]
+        dish["decision"] = _decision(suggested, suggested["suitable"], "")
+
+
+def is_verdict(value: object) -> bool:
+    """Whether a value says the seeds can be counted, cannot, or left unsure."""
+    return value is True or value is False or value is None
+
+
+def _decision(shot: dict, suitable: bool | None, note: str) -> dict:
+    return {"chosen": shot["path"], "suitable": suitable, "note": note}
+
+
+def _is_record(record: object) -> bool:
+    if not isinstance(record, dict):
+        return False
+    dishes, skipped = record.get("dishes"), record.get("skipped")
+    return (
+        isinstance(dishes, list)
+        and all(_is_dish(dish) for dish in dishes)
+        and isinstance(skipped, list)
+        and all(_is_skipped(item) for item in skipped)
+    )
+
+
+def _is_dish(dish: object) -> bool:
+    if not isinstance(dish, dict):
+        return False
+    shots = dish.get("shots")
+    if not isinstance(shots, list) or not shots:
+        return False
+    if not all(_is_shot(shot) for shot in shots):
+        return False
+    return _is_decision(dish.get("decision"), {shot["path"] for shot in shots})
+
+
+def _is_shot(shot: object) -> bool:
+    if not isinstance(shot, dict):
+        return False
+    sharpness, reason = shot.get("sharpness"), shot.get("reason")
+    return (
+        _is_photograph(shot.get("path"))
+        and (sharpness is None or _is_number(sharpness))
+        and isinstance(shot.get("suitable"), bool)
+        and (reason is None or isinstance(reason, str))
+        and _is_alignment(shot.get("alignment"))
+    )
+
+
+def _is_photograph(path: object) -> bool:
+    return isinstance(path, str) and Path(path).suffix.lower() in PHOTO_SUFFIXES
+
+
+def _is_alignment(alignment: object) -> bool:
+    return (
+        isinstance(alignment, list)
+        and len(alignment) == 2
+        and all(
+            isinstance(row, list)
+            and len(row) == 3
+            and all(_is_number(value) for value in row)
+            for row in alignment
+        )
+    )
+
+
+def _is_number(value: object) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _is_decision(decision: object, paths: set[str]) -> bool:
+    if decision is None:
+        return True
+    if not isinstance(decision, dict):
+        return False
+    return (
+        decision.get("chosen") in paths
+        and is_verdict(decision.get("suitable"))
+        and isinstance(decision.get("note"), str)
+    )
+
+
+def _is_skipped(item: object) -> bool:
+    return (
+        isinstance(item, dict)
+        and isinstance(item.get("path"), str)
+        and isinstance(item.get("reason"), str)
+    )