sherd 0.1.0__py3-none-any.whl

sherd/__init__.py

@@ -0,0 +1,6 @@
+"""Sherd — Pottery Profile Vectoriser.
+
+Automated SVG pottery profile drawings from photographs.
+"""
+
+__version__ = "0.1.0"

sherd/__main__.py

@@ -0,0 +1,7 @@
+"""Sherd — CLI entry point for ``python -m sherd``."""
+
+import sys
+
+from sherd.main import main
+
+sys.exit(main())

sherd/core/__init__.py

@@ -0,0 +1 @@
+"""Core image processing pipeline modules."""

sherd/core/axis.py

@@ -0,0 +1,89 @@
+"""Profile axis detection — centring axis, rim, and base estimation."""
+
+import cv2
+import numpy as np
+
+
+class ProfileAxis:
+    """Detect and manage the vertical centring axis and vertical extents.
+
+    The centring axis is the axis of rotational symmetry for a pottery
+    vessel. Rim = topmost point, base = bottommost point.
+
+    Detection strategy:
+    1. Fit ellipse to the top 30% of contour points (rim region).
+    2. Use ellipse centre x as the candidate axis.
+    3. Fallback to bounding-rect centre x if ellipse fit fails.
+
+    Parameters
+    ----------
+    centring_x : float or None
+        Pixel x-coordinate of the vertical centring axis.
+    rim_y : float or None
+        Pixel y-coordinate of the rim (topmost).
+    base_y : float or None
+        Pixel y-coordinate of the base (bottommost).
+    is_manual : bool
+        True if the user has manually overridden any value.
+    """
+
+    def __init__(self) -> None:
+        self.centring_x: float | None = None
+        self.rim_y: float | None = None
+        self.base_y: float | None = None
+        self.is_manual: bool = False
+
+    def detect(
+        self, contour: np.ndarray, image_shape: tuple[int, int]
+    ) -> None:
+        """Run auto-detection on a contour.
+
+        Parameters
+        ----------
+        contour : np.ndarray
+            Contour array of shape (N, 1, 2).
+        image_shape : tuple[int, int]
+            (height, width) of the source image.
+        """
+        h, w = image_shape[:2]
+        x, y, bw, bh = cv2.boundingRect(contour)
+        self.rim_y = float(y)
+        self.base_y = float(y + bh)
+
+        # Attempt ellipse fit on top 30% of points for better axis
+        pts = contour.reshape(-1, 2)
+        rim_pts = pts[pts[:, 1] < (y + bh * 0.30)]
+        if len(rim_pts) >= 5:
+            rim_pts_cv = rim_pts[:, np.newaxis, :]
+            try:
+                ellipse = cv2.fitEllipse(rim_pts_cv)
+                self.centring_x = ellipse[0][0]
+            except cv2.error:
+                self.centring_x = float(x + bw / 2)
+        else:
+            self.centring_x = float(x + bw / 2)
+
+    def override(
+        self,
+        centring_x: float | None = None,
+        rim_y: float | None = None,
+        base_y: float | None = None,
+    ) -> None:
+        """Manually override detected axis values.
+
+        Parameters
+        ----------
+        centring_x : float or None
+            New centring axis x-coordinate, or None to keep existing.
+        rim_y : float or None
+            New rim y-coordinate, or None to keep existing.
+        base_y : float or None
+            New base y-coordinate, or None to keep existing.
+        """
+        if centring_x is not None:
+            self.centring_x = centring_x
+        if rim_y is not None:
+            self.rim_y = rim_y
+        if base_y is not None:
+            self.base_y = base_y
+        self.is_manual = True

sherd/core/batch_processor.py

@@ -0,0 +1,202 @@
+"""Batch processor — run the full CV pipeline on a folder of images.
+
+Each image is loaded, segmented, cleaned, axis-detected, profiled,
+and exported as SVG + JSON sidecar. Calibration and smoothing config
+are shared across the batch.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+import cv2
+
+from sherd.core.axis import ProfileAxis
+from sherd.core.calibration import ScaleCalibration
+from sherd.core.exporter import SVGExporter
+from sherd.core.profile import march_profile
+from sherd.core.segmentation import (
+    clean_mask,
+    extract_main_contour,
+    segment_adaptive,
+    segment_grabcut,
+    segment_otsu,
+)
+from sherd.utils.image_io import load_image
+from sherd.utils.sidecar import write_sidecar
+
+SUPPORTED_EXTENSIONS: set[str] = {
+    ".jpg", ".jpeg", ".png", ".tif", ".tiff",
+}
+
+
+@dataclass
+class BatchJob:
+    """Configuration for a batch processing run.
+
+    Parameters
+    ----------
+    input_dir : Path
+        Directory containing sherd photographs.
+    output_dir : Path
+        Directory to write SVG + JSON output files.
+    calibration : ScaleCalibration
+        Calibration to use for all images (set from a reference image).
+    segmentation_method : str
+        ``"otsu"``, ``"adaptive"``, or ``"grabcut"``.
+    smoothing_level : str
+        ``"fine"``, ``"medium"``, or ``"coarse"``.
+    metadata_defaults : dict
+        Shared metadata fields (site_code, operator, etc.).
+    """
+
+    input_dir: Path
+    output_dir: Path
+    calibration: ScaleCalibration = field(default_factory=ScaleCalibration)
+    segmentation_method: str = "otsu"
+    smoothing_level: str = "medium"
+    metadata_defaults: dict = field(default_factory=dict)
+
+
+@dataclass
+class BatchResult:
+    """Outcome of processing a single image.
+
+    Parameters
+    ----------
+    image_path : Path
+        Input image path.
+    status : str
+        ``"ok"``, ``"failed"``, or ``"skipped"``.
+    svg_path : Path or None
+        Path to generated SVG (None on failure).
+    error : str or None
+        Error message if failed.
+    """
+
+    image_path: Path
+    status: str = "ok"
+    svg_path: Path | None = None
+    error: str | None = None
+
+
+class BatchProcessor:
+    """Process a folder of sherd photographs with a shared config.
+
+    Parameters
+    ----------
+    job : BatchJob
+        Batch configuration.
+    progress_callback : Callable[[int, int], None] or None
+        Called with ``(current, total)`` after each image.
+    cancel_check : Callable[[], bool] or None
+        Called before each image; return True to abort.
+    """
+
+    def __init__(
+        self,
+        job: BatchJob,
+        progress_callback: Callable[[int, int], None] | None = None,
+        cancel_check: Callable[[], bool] | None = None,
+    ) -> None:
+        self._job = job
+        self._progress = progress_callback or (lambda a, b: None)
+        self._cancel = cancel_check or (lambda: False)
+
+    def run(self) -> list[BatchResult]:
+        """Process all images in the input directory.
+
+        Returns a list of ``BatchResult``, one per image.
+        """
+        # Ensure output dir exists
+        self._job.output_dir.mkdir(parents=True, exist_ok=True)
+
+        images = sorted(
+            p for p in self._job.input_dir.iterdir()
+            if p.suffix.lower() in SUPPORTED_EXTENSIONS
+        )
+        if not images:
+            return []
+
+        results: list[BatchResult] = []
+        for i, img_path in enumerate(images):
+            if self._cancel():
+                break
+            self._progress(i + 1, len(images))
+            result = self._process_one(img_path)
+            results.append(result)
+        return results
+
+    # ── Single image pipeline ─────────────────────────────────
+
+    def _process_one(self, img_path: Path) -> BatchResult:
+        """Run the full pipeline on a single image."""
+        try:
+            bgr = load_image(str(img_path))
+            gray = cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY)
+        except Exception as exc:
+            return BatchResult(img_path, "failed", None, str(exc))
+
+        # Segmentation
+        try:
+            if self._job.segmentation_method == "otsu":
+                mask = segment_otsu(gray)
+            elif self._job.segmentation_method == "adaptive":
+                mask = segment_adaptive(gray)
+            else:
+                h, w = gray.shape[:2]
+                rect = (int(w * 0.05), int(h * 0.05),
+                        int(w * 0.9), int(h * 0.9))
+                mask = segment_grabcut(bgr, rect)
+
+            cleaned = clean_mask(mask)
+            contour = extract_main_contour(cleaned)
+            if contour is None:
+                return BatchResult(
+                    img_path, "failed", None,
+                    "No contour found after segmentation",
+                )
+        except Exception as exc:
+            return BatchResult(img_path, "failed", None, str(exc))
+
+        # Axis detection
+        axis = ProfileAxis()
+        axis.detect(contour, gray.shape)
+
+        # Profile
+        profile = march_profile(contour, axis, mode="exterior_only")
+
+        # Build output filename
+        stem = img_path.stem.replace(" ", "_")
+        svg_name = f"{stem}_profile.svg"
+        svg_path = self._job.output_dir / svg_name
+
+        # Metadata
+        metadata = dict(self._job.metadata_defaults)
+        metadata["source_image"] = str(img_path.name)
+        if self._job.calibration.is_calibrated():
+            metadata["pixels_per_mm"] = self._job.calibration.pixels_per_mm
+        metadata["profile_mode"] = "exterior_only"
+
+        # Export
+        try:
+            if self._job.calibration.is_calibrated():
+                cal = self._job.calibration
+            else:
+                # Unity calibration for pixel-coordinate export
+                cal = ScaleCalibration()
+                cal.set_points((0, 0), (1, 0))
+                cal.set_real_distance(1.0)
+
+            exporter = SVGExporter(
+                cal, axis,
+                settings={"smoothingLevel": self._job.smoothing_level},
+            )
+            exporter.export(profile, metadata, str(svg_path))
+            write_sidecar(str(svg_path), metadata)
+        except Exception as exc:
+            return BatchResult(img_path, "failed", None, str(exc))
+
+        return BatchResult(img_path, "ok", svg_path, None)

sherd/core/calibration.py

@@ -0,0 +1,109 @@
+"""Scale calibration — compute pixels-per-mm from a known reference."""
+
+import math
+
+
+class ScaleCalibration:
+    """Compute and apply pixel-to-mm conversion from user-defined reference points.
+
+    The user clicks two points on a known scale reference (ruler, coin,
+    calibration tile) and enters the real-world distance. The calibration
+    persists for the session and is used for SVG output coordinates and
+    scale bar generation.
+
+    Parameters
+    ----------
+    point_a : (float, float) or None
+        First calibration point in pixel coordinates.
+    point_b : (float, float) or None
+        Second calibration point in pixel coordinates.
+    real_world_mm : float or None
+        Known real-world distance between point_a and point_b in mm.
+    pixels_per_mm : float or None
+        Computed calibration factor (px / mm).
+    """
+
+    def __init__(self) -> None:
+        self.point_a: tuple[float, float] | None = None
+        self.point_b: tuple[float, float] | None = None
+        self.real_world_mm: float | None = None
+        self.pixels_per_mm: float | None = None
+
+    def set_points(self, a: tuple[float, float], b: tuple[float, float]) -> None:
+        """Set the two pixel-coordinate reference points."""
+        self.point_a = a
+        self.point_b = b
+        if self.real_world_mm is not None:
+            self._compute()
+
+    def set_real_distance(self, mm: float) -> None:
+        """Set the known real-world distance and compute calibration."""
+        self.real_world_mm = mm
+        if self.point_a is not None and self.point_b is not None:
+            self._compute()
+
+    def _compute(self) -> None:
+        """Compute pixels_per_mm from points and real distance."""
+        if self.point_a is None or self.point_b is None:
+            return
+        px_dist = math.dist(self.point_a, self.point_b)
+        if self.real_world_mm and self.real_world_mm > 0:
+            self.pixels_per_mm = px_dist / self.real_world_mm
+
+    def px_to_mm(self, pixels: float) -> float:
+        """Convert pixel distance to mm.
+
+        Raises
+        ------
+        RuntimeError
+            If calibration has not been set.
+        """
+        if self.pixels_per_mm is None:
+            raise RuntimeError("Calibration not set")
+        return pixels / self.pixels_per_mm
+
+    def mm_to_px(self, mm: float) -> float:
+        """Convert mm to pixel distance.
+
+        Raises
+        ------
+        RuntimeError
+            If calibration has not been set.
+        """
+        if self.pixels_per_mm is None:
+            raise RuntimeError("Calibration not set")
+        return mm * self.pixels_per_mm
+
+    def is_calibrated(self) -> bool:
+        """Return True if calibration has been computed successfully."""
+        return self.pixels_per_mm is not None
+
+    def scale_bar_svg(self, length_mm: int = 50) -> str:
+        """Return SVG markup for a scale bar of given length in mm.
+
+        Parameters
+        ----------
+        length_mm : int
+            Length of the scale bar in mm (default 50).
+
+        Returns
+        -------
+        str
+            SVG ``<g>`` element containing the scale bar.
+        """
+        if not self.is_calibrated():
+            raise RuntimeError("Calibration not set")
+        bar_px = self.mm_to_px(length_mm)
+        tick_h = 4  # px
+        return (
+            f'<g id="scale-bar" class="scale-bar">'
+            f'<line x1="0" y1="{tick_h}" x2="0" y2="0" '
+            f'stroke="black" stroke-width="0.5pt" vector-effect="non-scaling-stroke"/>'
+            f'<line x1="0" y1="{tick_h / 2}" x2="{bar_px}" y2="{tick_h / 2}" '
+            f'stroke="black" stroke-width="0.5pt" vector-effect="non-scaling-stroke"/>'
+            f'<line x1="{bar_px}" y1="{tick_h}" x2="{bar_px}" y2="0" '
+            f'stroke="black" stroke-width="0.5pt" vector-effect="non-scaling-stroke"/>'
+            f'<text x="{bar_px / 2}" y="{tick_h + 8}" text-anchor="middle" '
+            f'font-size="8" font-family="Arial">{length_mm} mm</text>'
+            f'</g>'
+        )

sherd/core/contour.py

@@ -0,0 +1,90 @@
+"""Contour smoothing and SVG path generation."""
+
+import cv2
+import numpy as np
+from scipy.interpolate import splev, splprep
+
+SMOOTHING_EPSILON = {
+    "fine": 0.0005,   # Very close to original
+    "medium": 0.002,  # Good balance — default
+    "coarse": 0.008,  # Fewer nodes, more generalised
+}
+
+SUPPORTED_LEVELS = frozenset(SMOOTHING_EPSILON.keys())
+
+
+def smooth_contour(
+    contour: np.ndarray,
+    level: str = "medium",
+    closed: bool = True,
+) -> np.ndarray:
+    """Smooth a contour using approxPolyDP followed by parametric B-spline.
+
+    Parameters
+    ----------
+    contour : np.ndarray
+        Input contour array of shape (N, 1, 2).
+    level : str
+        Smoothing level: ``"fine"``, ``"medium"`` (default), or ``"coarse"``.
+    closed : bool
+        Whether the contour is closed (default True).
+
+    Returns
+    -------
+    np.ndarray
+        Smoothed (x, y) point array of shape (M, 2).
+    """
+    if level not in SUPPORTED_LEVELS:
+        opts = sorted(SUPPORTED_LEVELS)
+        msg = f"Unknown smoothing level '{level}'; choose from {opts}"
+        raise ValueError(msg)
+
+    # OpenCV requires int32 or float32 for arcLength/approxPolyDP
+    if contour.dtype not in (np.int32, np.float32):
+        contour = contour.astype(np.float32)
+
+    # Handle (N, 2) shape by adding channel dim for OpenCV
+    if contour.ndim == 2:
+        contour = contour.reshape(-1, 1, 2)
+
+    arc_len = cv2.arcLength(contour, closed)
+    epsilon = SMOOTHING_EPSILON[level] * arc_len
+    poly = cv2.approxPolyDP(contour, epsilon, closed)
+    pts = poly.reshape(-1, 2).astype(float)
+
+    if len(pts) < 4:
+        return pts  # Not enough points to spline
+
+    x, y = pts[:, 0], pts[:, 1]
+    if closed:
+        x = np.append(x, x[0])
+        y = np.append(y, y[0])
+
+    # Parametric B-spline through the points
+    tck, _ = splprep([x, y], s=0, per=closed, k=3)
+    n_out = max(200, len(pts) * 4)
+    u_new = np.linspace(0, 1, n_out)
+    xn, yn = splev(u_new, tck)
+    return np.column_stack([xn, yn])
+
+
+def contour_to_svg_path(points: np.ndarray) -> str:
+    """Convert an Nx2 point array to an SVG path ``d``-attribute string.
+
+    Parameters
+    ----------
+    points : np.ndarray
+        Array of (x, y) coordinates, shape (N, 2).
+
+    Returns
+    -------
+    str
+        SVG path data string ending with ``Z`` (closed path).
+    """
+    if len(points) == 0:
+        return ""
+    coords = " ".join(
+        f"{'M' if i == 0 else 'L'}{p[0]:.2f},{p[1]:.2f}"
+        for i, p in enumerate(points)
+    )
+    return coords + " Z"