seedbuddy 0.2.0__tar.gz

seedbuddy-0.2.0/.gitignore

@@ -0,0 +1,23 @@
+.DS_Store
+.env
+.env.*
+!.env.example
+!web/.env.example
+.cursor/
+.claude/settings.local.json
+.codex/
+.mcp.json
+.agents/
+.lody/
+skills-lock.json
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.py[cod]
+/build/
+/dist/
+*.egg-info/
+/output/
+/data/
+/tests/fixtures/images/

seedbuddy-0.2.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: seedbuddy
+Version: 0.2.0
+Summary: Prepare culture-dish photographs for a SeedBuddy workbench
+Project-URL: Repository, https://github.com/i-richardwang/SeedBuddy
+Project-URL: Issues, https://github.com/i-richardwang/SeedBuddy/issues
+Author: Richard Wang
+License-Expression: MIT
+Keywords: culture-dish,focus,photography,plant-tissue-culture
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.11
+Requires-Dist: numpy>=2.0
+Requires-Dist: opencv-python-headless>=5.0
+Description-Content-Type: text/markdown
+
+# seedbuddy
+
+Prepare culture-dish photographs for a [SeedBuddy](https://github.com/i-richardwang/SeedBuddy) workbench.
+
+A dish is often photographed several times in a row. `seedbuddy photos sort` sorts a folder of photographs into dishes, puts the photograph whose seeds are sharpest first for each dish, and says whether the seeds in each photograph can be counted. `seedbuddy photos review` then serves a page on which a person confirms, dish by dish, which photograph to use.
+
+```bash
+uvx seedbuddy photos sort ~/plates -o ~/plates/plates.json
+uvx seedbuddy photos review ~/plates/plates.json
+```
+
+`python -m seedbuddy` is the module entry point and accepts the same commands.
+
+`sort` reads the folder's JPEG, PNG and TIFF files, prints JSON, writes the same JSON to the file given with `-o`, and leaves every photograph where it is:
+
+```json
+{
+  "dishes": [
+    {
+      "shots": [
+        {
+          "path": "/home/lab/plates/plate-02.jpg",
+          "sharpness": 0.0,
+          "suitable": true,
+          "reason": null,
+          "alignment": [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]]
+        },
+        {
+          "path": "/home/lab/plates/plate-01.jpg",
+          "sharpness": -0.4,
+          "suitable": false,
+          "reason": "seeds are out of focus",
+          "alignment": [[0.998, 0.052, -41.3], [-0.052, 0.998, 96.8]]
+        }
+      ]
+    }
+  ],
+  "skipped": [
+    { "path": "/home/lab/plates/notes.png", "reason": "no dish found" }
+  ]
+}
+```
+
+Each entry of `dishes` is one dish, and `shots` lists its photographs sharpest first. The first shot is the suggestion.
+
+- `sharpness` is the natural log of how sharply a photograph renders the seeds relative to the first one, so `-0.4` is about a third less fine detail. A dish photographed once has a `sharpness` of `null`.
+- `suitable` says whether the seeds can be counted, and `reason` says why not.
+- `alignment` is the camera motion that carries the photograph onto the first one of its dish, as the two rows of an affine matrix in pixels.
+
+`skipped` lists files that could not be read or that show no dish.
+
+## How photographs are matched
+
+Photographs show the same dish when one movement of the camera carries the layout of the whole dish, seeds, substrate outline and lid labels alike, from one photograph onto the other. Agreement in one small region, such as a date label that every dish of a batch carries, is not enough. The decision depends on the share of features that agree and the area they cover, not on how many seeds a dish holds, and the handwriting on labels is never read.
+
+## How focus is judged
+
+Two photographs of one dish are compared at the same physical points within the central 60% of the dish's radius, where the seeds lie and the lid labels do not reach. At each point the finest detail is weighed against the seed's outline, which cancels exposure, so a photograph focused on the labels rather than the seeds ranks low.
+
+## Whether a photograph can be counted
+
+Each photograph is judged on its own, so the sharpest photograph of a dish can still be one that cannot be counted. The seeds lie on the filter paper, inside the rim, where the lid labels do not reach. They can be counted when their own mark is crisp against the paper. `suitable` is false when that mark has gone soft (`seeds are out of focus`), or when tiny gray droplets are spread across the paper and the seeds themselves are not a crisp colored mark (`paper covered by droplets`). A small seed that is still a separate mark can be counted, and so can a germinated seed.
+
+## Confirming the suggestions
+
+The first shot and its `suitable` are a suggestion, and the person who will count the dish has the last word. `review` prints the address of a page on the local computer. The page lists the dishes and shows every photograph of the one in view. Changing between the photographs of a dish keeps each seed in place, so focus can be compared at one spot.
+
+For each dish, accept the suggestion, or bring up the photograph to use and mark its seeds as countable, not countable, or not sure. A decision moves on to the next dish that still has none. A note can be kept with the confirmation. Accept remaining suggestions confirms the suggestion for every dish that still has none, and leaves a correction that is already there as it is. Worth a look shows the dishes whose suggested photograph cannot be counted, or that have another photograph about as sharp.
+
+The confirmation is stored in the same file, beside the dish's shots:
+
+```json
+{
+  "shots": [...],
+  "decision": {
+    "chosen": "/home/lab/plates/plate-01.jpg",
+    "suitable": true,
+    "note": "thin, but each seed is separate"
+  }
+}
+```
+
+`decision.chosen` is the photograph to use. `decision.suitable` is `true` when its seeds can be counted, `false` when they cannot, and `null` when the person was not sure. Sorting into the same file again is refused once any confirmation is present.
+
+## Publishing
+
+The package version is in `packages/seedbuddy/pyproject.toml`. From the repository root, build into an empty `dist/` and publish:
+
+```bash
+uv build --package seedbuddy
+uv publish
+```
+
+The publishing credential is described in the repository environment example. The release tag matches the package version.

seedbuddy-0.2.0/README.md

@@ -0,0 +1,94 @@
+# seedbuddy
+
+Prepare culture-dish photographs for a [SeedBuddy](https://github.com/i-richardwang/SeedBuddy) workbench.
+
+A dish is often photographed several times in a row. `seedbuddy photos sort` sorts a folder of photographs into dishes, puts the photograph whose seeds are sharpest first for each dish, and says whether the seeds in each photograph can be counted. `seedbuddy photos review` then serves a page on which a person confirms, dish by dish, which photograph to use.
+
+```bash
+uvx seedbuddy photos sort ~/plates -o ~/plates/plates.json
+uvx seedbuddy photos review ~/plates/plates.json
+```
+
+`python -m seedbuddy` is the module entry point and accepts the same commands.
+
+`sort` reads the folder's JPEG, PNG and TIFF files, prints JSON, writes the same JSON to the file given with `-o`, and leaves every photograph where it is:
+
+```json
+{
+  "dishes": [
+    {
+      "shots": [
+        {
+          "path": "/home/lab/plates/plate-02.jpg",
+          "sharpness": 0.0,
+          "suitable": true,
+          "reason": null,
+          "alignment": [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]]
+        },
+        {
+          "path": "/home/lab/plates/plate-01.jpg",
+          "sharpness": -0.4,
+          "suitable": false,
+          "reason": "seeds are out of focus",
+          "alignment": [[0.998, 0.052, -41.3], [-0.052, 0.998, 96.8]]
+        }
+      ]
+    }
+  ],
+  "skipped": [
+    { "path": "/home/lab/plates/notes.png", "reason": "no dish found" }
+  ]
+}
+```
+
+Each entry of `dishes` is one dish, and `shots` lists its photographs sharpest first. The first shot is the suggestion.
+
+- `sharpness` is the natural log of how sharply a photograph renders the seeds relative to the first one, so `-0.4` is about a third less fine detail. A dish photographed once has a `sharpness` of `null`.
+- `suitable` says whether the seeds can be counted, and `reason` says why not.
+- `alignment` is the camera motion that carries the photograph onto the first one of its dish, as the two rows of an affine matrix in pixels.
+
+`skipped` lists files that could not be read or that show no dish.
+
+## How photographs are matched
+
+Photographs show the same dish when one movement of the camera carries the layout of the whole dish, seeds, substrate outline and lid labels alike, from one photograph onto the other. Agreement in one small region, such as a date label that every dish of a batch carries, is not enough. The decision depends on the share of features that agree and the area they cover, not on how many seeds a dish holds, and the handwriting on labels is never read.
+
+## How focus is judged
+
+Two photographs of one dish are compared at the same physical points within the central 60% of the dish's radius, where the seeds lie and the lid labels do not reach. At each point the finest detail is weighed against the seed's outline, which cancels exposure, so a photograph focused on the labels rather than the seeds ranks low.
+
+## Whether a photograph can be counted
+
+Each photograph is judged on its own, so the sharpest photograph of a dish can still be one that cannot be counted. The seeds lie on the filter paper, inside the rim, where the lid labels do not reach. They can be counted when their own mark is crisp against the paper. `suitable` is false when that mark has gone soft (`seeds are out of focus`), or when tiny gray droplets are spread across the paper and the seeds themselves are not a crisp colored mark (`paper covered by droplets`). A small seed that is still a separate mark can be counted, and so can a germinated seed.
+
+## Confirming the suggestions
+
+The first shot and its `suitable` are a suggestion, and the person who will count the dish has the last word. `review` prints the address of a page on the local computer. The page lists the dishes and shows every photograph of the one in view. Changing between the photographs of a dish keeps each seed in place, so focus can be compared at one spot.
+
+For each dish, accept the suggestion, or bring up the photograph to use and mark its seeds as countable, not countable, or not sure. A decision moves on to the next dish that still has none. A note can be kept with the confirmation. Accept remaining suggestions confirms the suggestion for every dish that still has none, and leaves a correction that is already there as it is. Worth a look shows the dishes whose suggested photograph cannot be counted, or that have another photograph about as sharp.
+
+The confirmation is stored in the same file, beside the dish's shots:
+
+```json
+{
+  "shots": [...],
+  "decision": {
+    "chosen": "/home/lab/plates/plate-01.jpg",
+    "suitable": true,
+    "note": "thin, but each seed is separate"
+  }
+}
+```
+
+`decision.chosen` is the photograph to use. `decision.suitable` is `true` when its seeds can be counted, `false` when they cannot, and `null` when the person was not sure. Sorting into the same file again is refused once any confirmation is present.
+
+## Publishing
+
+The package version is in `packages/seedbuddy/pyproject.toml`. From the repository root, build into an empty `dist/` and publish:
+
+```bash
+uv build --package seedbuddy
+uv publish
+```
+
+The publishing credential is described in the repository environment example. The release tag matches the package version.

seedbuddy-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "seedbuddy"
+version = "0.2.0"
+description = "Prepare culture-dish photographs for a SeedBuddy workbench"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Richard Wang" }]
+keywords = ["plant-tissue-culture", "culture-dish", "photography", "focus"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Image Recognition",
+]
+requires-python = ">=3.11"
+dependencies = [
+  "numpy>=2.0",
+  "opencv-python-headless>=5.0",
+]
+
+[project.scripts]
+seedbuddy = "seedbuddy.cli:main"
+
+[project.urls]
+Repository = "https://github.com/i-richardwang/SeedBuddy"
+Issues = "https://github.com/i-richardwang/SeedBuddy/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/seedbuddy"]

seedbuddy-0.2.0/src/seedbuddy/__init__.py

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

seedbuddy-0.2.0/src/seedbuddy/__main__.py

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

seedbuddy-0.2.0/src/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-0.2.0/src/seedbuddy/photos/__init__.py

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

seedbuddy-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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
+    )