sherd 0.1.0__tar.gz

sherd-0.1.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: sherd
+Version: 0.1.0
+Summary: Pottery Profile Vectoriser — automated SVG pottery profile drawings from photographs
+Author: Mark Bouck
+License: MIT
+Project-URL: Homepage, https://github.com/mabo-du/sherd
+Requires-Python: >=3.12
+Requires-Dist: opencv-python>=4.10
+Requires-Dist: PyQt6>=6.7
+Requires-Dist: svgwrite>=1.4
+Requires-Dist: scipy>=1.13
+Requires-Dist: numpy>=1.26
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-qt; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pyinstaller; extra == "dev"

sherd-0.1.0/README.md

@@ -0,0 +1,227 @@
+# Sherd — Pottery Profile Vectoriser
+
+[![CI](https://github.com/mabo-du/sherd/actions/workflows/ci.yml/badge.svg)](https://github.com/mabo-du/sherd/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/sherd)](https://pypi.org/project/sherd/)
+[![Python](https://img.shields.io/pypi/pyversions/sherd)](https://pypi.org/project/sherd/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Automated publication-ready SVG pottery profile drawings from photographs.
+Replaces manual tracing on light tables and Illustrator/Inkscape workflows.
+
+Place a sherd on white paper with a scale reference, photograph it, and
+receive a clean SVG conforming to international archaeological ceramic
+illustration conventions.
+
+---
+
+## Features
+
+- **Three segmentation methods** — Otsu, Adaptive, and GrabCut for standard, textured, and low-contrast sherds
+- **Interactive axis overlay** — drag the centring axis, rim line, and base line to align with your piece
+- **Scale calibration** — click two points on a ruler in the photograph to set the real-world mm scale
+- **Manual correction tools** — paint mask additions and erasures with 50-level undo/redo
+- **Full cross-section mode** — draw the interior wall curve for complete archaeological profiles
+- **Publication-ready SVG** — `vector-effect="non-scaling-stroke"`, 45° hatch fill, scale bar, and embedded metadata
+- **JSON sidecar** — machine-readable metadata compatible with Cache & Carry and HOARD pipelines
+- **Batch processing** — process a whole folder of photographs with shared calibration
+- **Dark archaeological theme** — low-eye-strain interface designed for long drawing sessions
+
+## Screenshots
+
+> _Screenshots coming soon — contributions welcome._
+
+---
+
+## Quick Start
+
+### Standalone Binary (recommended)
+
+Download the latest release for your platform from the
+[Releases page](https://github.com/mabo-du/sherd/releases).
+No Python installation required — just unzip and run.
+
+### From PyPI
+
+```bash
+pip install sherd
+python -m sherd
+```
+
+### From Source
+
+```bash
+git clone https://github.com/mabo-du/sherd.git
+cd sherd
+python3 -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+python -m sherd
+```
+
+---
+
+## Workflow
+
+```
+1.  Open a sherd photograph          Ctrl+O
+2.  Adjust threshold slider          ← / → drag
+3.  Accept Contour                   click button
+4.  Drag axis lines if needed        click + drag
+5.  Calibrate scale                  Calibrate button
+6.  (Optional) Correct mask          B / E keys
+7.  Switch profile mode              Exterior / Full
+8.  Export SVG + JSON sidecar        Ctrl+E
+```
+
+See the full **[User Guide](docs/UserGuide.md)** for detailed instructions,
+photography tips, and troubleshooting.
+
+---
+
+## Requirements
+
+| Component | Minimum |
+|-----------|---------|
+| Python    | 3.12    |
+| OpenCV    | 4.10    |
+| PyQt6     | 6.7     |
+| SciPy     | 1.13    |
+| NumPy     | 1.26    |
+
+---
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+O` | Open image |
+| `Ctrl+E` | Export SVG |
+| `Ctrl+B` | Batch process folder |
+| `Ctrl+Z` | Undo correction |
+| `Ctrl+Shift+Z` | Redo correction |
+| `B` | Brush mode |
+| `E` | Eraser mode |
+| `[` / `]` | Decrease / increase brush size |
+| `Ctrl+0` | Fit image to view |
+| `Ctrl+Q` | Exit |
+
+---
+
+## SVG Output Convention
+
+All exported SVGs follow this structure and are compatible with Illustrator,
+Inkscape, and CAD workflows:
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:sherd="…">
+  <metadata>
+    <sherd:metadata accession_number="…" site_code="…" …/>
+  </metadata>
+  <defs>
+    <pattern id="hatch-45">…</pattern>
+  </defs>
+  <g id="profile">
+    <path id="exterior" vector-effect="non-scaling-stroke" …/>
+    <path id="interior" vector-effect="non-scaling-stroke" …/>
+    <path id="wall-section" fill="url(#hatch-45)" …/>
+    <line id="centring-axis" stroke-dasharray="6,3" …/>
+    <g id="scale-bar">…</g>
+  </g>
+</svg>
+```
+
+Stroke weights are in `pt` units with `vector-effect="non-scaling-stroke"` for
+zoom-independent rendering at any print size.
+
+---
+
+## Project Structure
+
+```
+sherd/
+├── sherd/
+│   ├── core/                # Computer vision pipeline
+│   │   ├── segmentation.py  # Otsu, Adaptive, GrabCut
+│   │   ├── calibration.py   # Pixels-per-mm computation
+│   │   ├── contour.py       # B-spline smoothing, SVG path gen
+│   │   ├── axis.py          # Centring axis detection
+│   │   ├── profile.py       # Half-profile construction
+│   │   ├── exporter.py      # SVG + metadata generation
+│   │   └── batch_processor.py
+│   ├── ui/                  # PyQt6 interface
+│   │   ├── main_window.py   # Three-panel layout
+│   │   ├── image_panel.py   # Photo + overlay display
+│   │   ├── tools_panel.py   # Controls sidebar
+│   │   ├── preview_panel.py # SVG preview
+│   │   ├── correction_scene.py  # Mask painting
+│   │   ├── axis_items.py    # Draggable axis lines
+│   │   ├── calibration_dialog.py
+│   │   ├── export_dialog.py
+│   │   ├── batch_dialog.py
+│   │   ├── shortcuts_dialog.py
+│   │   ├── workers.py       # Background threads
+│   │   └── theme.py         # Dark archaeological theme
+│   ├── utils/
+│   │   ├── image_io.py
+│   │   ├── svg_utils.py
+│   │   └── sidecar.py       # JSON sidecar writer
+│   └── models/
+│       ├── sherd_state.py   # Central data model
+│       └── settings.py      # Persistent preferences
+├── tests/                   # 122 tests (core + UI smoke)
+├── scripts/
+│   └── poc_pipeline.py      # CLI pipeline validator
+├── docs/
+│   └── UserGuide.md
+└── pyproject.toml
+```
+
+---
+
+## Development
+
+### Run tests
+
+```bash
+pytest --tb=short
+```
+
+### Lint
+
+```bash
+ruff check sherd/ tests/
+```
+
+### Build standalone binary
+
+```bash
+pip install pyinstaller
+pyinstaller sherd.spec --clean
+# Output: dist/sherd/
+```
+
+---
+
+## Ecosystem Integration
+
+Sherd is part of the open-source heritage science toolkit:
+
+| Project | What Sherd provides |
+|---------|-------------------|
+| **Cache & Carry** | SVG + JSON as media attachment |
+| **Trowel** | SVG embeds in Finds Catalogue plate |
+| **HOARD** | SVG + JSON sidecar for finds appendix |
+| **Chroma** | Munsell fabric colour cross-reference |
+
+---
+
+## Contributing
+
+Contributions, bug reports, and feature requests are welcome.
+Please open an issue before submitting a pull request so we can discuss the approach.
+
+---
+
+## Licence
+
+MIT — see [LICENCE](LICENCE) for details.

sherd-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sherd"
+version = "0.1.0"
+description = "Pottery Profile Vectoriser — automated SVG pottery profile drawings from photographs"
+requires-python = ">=3.12"
+license = {text = "MIT"}
+authors = [
+    {name = "Mark Bouck"},
+]
+dependencies = [
+    "opencv-python>=4.10",
+    "PyQt6>=6.7",
+    "svgwrite>=1.4",
+    "scipy>=1.13",
+    "numpy>=1.26",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-qt",
+    "ruff",
+    "pyinstaller",
+]
+
+[project.urls]
+Homepage = "https://github.com/mabo-du/sherd"
+
+[tool.setuptools.packages.find]
+include = ["sherd*"]
+
+[tool.setuptools.package-data]
+sherd = ["py.typed"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.coverage.run]
+source = ["sherd"]
+omit = ["tests/*"]

sherd-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sherd-0.1.0/sherd/__init__.py

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

sherd-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-0.1.0/sherd/core/__init__.py

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

sherd-0.1.0/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-0.1.0/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)