signa-core 0.1.0__tar.gz

signa_core-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.pytest_cache/

signa_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Leiverkus
+
+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.

signa_core-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: signa-core
+Version: 0.1.0
+Summary: Reusable, GUI-free ArUco marker detection core for the Signa/Evidentia pipeline (OpenCV).
+Project-URL: Repository, https://github.com/leiverkus/signa
+Author-email: Patrick Leiverkus <leiverkus@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: archaeology,aruco,evidentia,marker-detection,opencv,photogrammetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: opencv-contrib-python-headless>=4.7
+Description-Content-Type: text/markdown
+
+# signa-core
+
+**Reusable, GUI-free ArUco marker detection for the Evidentia pipeline.**
+
+`signa-core` is the pure OpenCV/numpy detection layer extracted from the
+[Signa WebODM plugin](../README.md). It detects ArUco markers in images and
+returns their ids, corners and centers — leaving the *interpretation* to the
+caller:
+
+- **Signa** (WebODM plugin) matches markers against surveyed coordinates → `gcp_list.txt`.
+- **Mensura** matches markers against their known physical size → metric scale constraints.
+
+Both share this one detection implementation instead of duplicating it (or
+depending on `find-gcp`).
+
+## Install / use
+
+```bash
+pip install signa-core   # or: pip install -e signa-core
+```
+
+```python
+from signa_core import detect_markers
+
+# dict_id 1 = DICT_4X4_100 (see DICT_CHOICES)
+result = detect_markers(["img1.jpg", "img2.jpg"], dict_id=1, minrate=0.01, ignore=0.33)
+# {'img1.jpg': [{'id': 7, 'corners': [[x, y], ...4], 'center': (cx, cy)}, ...], ...}
+```
+
+## Licence
+
+**MIT** — `signa-core` is the permissive, reusable core. The surrounding
+**Signa WebODM plugin is AGPL-3.0** (WebODM-forced). This split mirrors the
+Itinera pattern (MIT core + copyleft plugin).
+
+## Note on the Signa worker
+
+WebODM runs Signa's GCP detection by serializing a single self-contained
+function into a Celery worker, so the plugin keeps its own inlined copy of the
+detection primitive for that path. `signa-core` is the canonical, importable
+version for all non-worker consumers; the two are kept behaviourally identical.
+
+## Releasing (PyPI)
+
+Published via **PyPI Trusted Publishing** (OIDC) — no API token is stored. See
+[`.github/workflows/publish-signa-core.yml`](../.github/workflows/publish-signa-core.yml)
+and its header for the one-time pypi.org publisher setup. To release:
+
+```bash
+# bump version in pyproject.toml, then:
+git tag signa-core-v0.1.0 && git push origin signa-core-v0.1.0
+```
+
+The workflow runs the tests, builds the sdist + wheel, and publishes them.

signa_core-0.1.0/README.md

@@ -0,0 +1,54 @@
+# signa-core
+
+**Reusable, GUI-free ArUco marker detection for the Evidentia pipeline.**
+
+`signa-core` is the pure OpenCV/numpy detection layer extracted from the
+[Signa WebODM plugin](../README.md). It detects ArUco markers in images and
+returns their ids, corners and centers — leaving the *interpretation* to the
+caller:
+
+- **Signa** (WebODM plugin) matches markers against surveyed coordinates → `gcp_list.txt`.
+- **Mensura** matches markers against their known physical size → metric scale constraints.
+
+Both share this one detection implementation instead of duplicating it (or
+depending on `find-gcp`).
+
+## Install / use
+
+```bash
+pip install signa-core   # or: pip install -e signa-core
+```
+
+```python
+from signa_core import detect_markers
+
+# dict_id 1 = DICT_4X4_100 (see DICT_CHOICES)
+result = detect_markers(["img1.jpg", "img2.jpg"], dict_id=1, minrate=0.01, ignore=0.33)
+# {'img1.jpg': [{'id': 7, 'corners': [[x, y], ...4], 'center': (cx, cy)}, ...], ...}
+```
+
+## Licence
+
+**MIT** — `signa-core` is the permissive, reusable core. The surrounding
+**Signa WebODM plugin is AGPL-3.0** (WebODM-forced). This split mirrors the
+Itinera pattern (MIT core + copyleft plugin).
+
+## Note on the Signa worker
+
+WebODM runs Signa's GCP detection by serializing a single self-contained
+function into a Celery worker, so the plugin keeps its own inlined copy of the
+detection primitive for that path. `signa-core` is the canonical, importable
+version for all non-worker consumers; the two are kept behaviourally identical.
+
+## Releasing (PyPI)
+
+Published via **PyPI Trusted Publishing** (OIDC) — no API token is stored. See
+[`.github/workflows/publish-signa-core.yml`](../.github/workflows/publish-signa-core.yml)
+and its header for the one-time pypi.org publisher setup. To release:
+
+```bash
+# bump version in pyproject.toml, then:
+git tag signa-core-v0.1.0 && git push origin signa-core-v0.1.0
+```
+
+The workflow runs the tests, builds the sdist + wheel, and publishes them.

signa_core-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "signa-core"
+version = "0.1.0"
+description = "Reusable, GUI-free ArUco marker detection core for the Signa/Evidentia pipeline (OpenCV)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Patrick Leiverkus", email = "leiverkus@gmail.com" },
+]
+keywords = ["aruco", "opencv", "marker-detection", "photogrammetry", "archaeology", "evidentia"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = [
+    "numpy>=1.24",
+    "opencv-contrib-python-headless>=4.7",
+]
+
+[project.urls]
+Repository = "https://github.com/leiverkus/signa"
+
+[tool.hatch.build.targets.wheel]
+packages = ["signa_core"]

signa_core-0.1.0/signa_core/__init__.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+"""signa-core — reusable ArUco marker detection for the Evidentia pipeline.
+
+GUI-/WebODM-free OpenCV detection shared by the Signa WebODM plugin (GCP
+detection) and Mensura (metric scale calibration).
+"""
+from .detect import corner_center, detect_markers, prepare_image
+from .dictionaries import (
+    DICT_CHOICES,
+    VALID_DICTS,
+    load_aruco,
+    make_detector,
+    make_dictionary,
+    make_parameters,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "detect_markers",
+    "corner_center",
+    "prepare_image",
+    "make_dictionary",
+    "make_parameters",
+    "make_detector",
+    "load_aruco",
+    "DICT_CHOICES",
+    "VALID_DICTS",
+    "__version__",
+]

signa_core-0.1.0/signa_core/detect.py

@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: MIT
+"""Reusable ArUco marker detection (GUI-free, OpenCV).
+
+The function mirrors the detection behaviour of the Signa WebODM plugin's
+self-contained worker detector, but as a normal importable module so consumers
+like Mensura (scale calibration) can reuse it. It returns per-image marker
+detections (id, corners, center) and leaves the *interpretation* of those
+markers — GCP matching (Signa) vs. metric scaling (Mensura) — to the caller.
+"""
+import os
+
+from .dictionaries import load_aruco, make_detector, make_dictionary, make_parameters
+
+
+def prepare_image(frame, cv2, enhance_contrast=True):
+    """BGR frame -> grayscale, with an optional conservative equalization pass."""
+    gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+    if enhance_contrast and hasattr(cv2, "equalizeHist"):
+        return cv2.equalizeHist(gray)
+    return gray
+
+
+def corner_center(corner_set):
+    """Mean of a marker's four corners as integer pixel coordinates."""
+    import numpy as np
+    pts = np.asarray(corner_set, dtype=float).reshape(-1, 2)
+    return (
+        int(round(float(np.mean(pts[:, 0])))),
+        int(round(float(np.mean(pts[:, 1])))),
+    )
+
+
+def detect_markers(image_paths, *, dict_id=1, minrate=0.01, ignore=0.33, adjust=True):
+    """Detect ArUco markers across one or more images.
+
+    Parameters mirror the Signa detector: ``dict_id`` selects the ArUco
+    dictionary (see ``DICT_CHOICES``), ``minrate`` is the minimum marker
+    perimeter rate, ``ignore`` the ignored-margin-per-cell, ``adjust`` toggles
+    grayscale equalization.
+
+    Returns ``{image_basename: detections}`` where ``detections`` is a list of
+    ``{'id': int, 'corners': [[x, y], ...4], 'center': (x, y)}`` — or ``None``
+    for an unreadable image.
+    """
+    cv2, aruco = load_aruco()
+    dictionary = make_dictionary(dict_id, aruco)
+    detect = make_detector(dictionary, make_parameters(minrate, ignore, aruco), aruco)
+
+    results = {}
+    for path in image_paths:
+        frame = cv2.imread(path)
+        base = os.path.basename(path)
+        if frame is None:
+            results[base] = None
+            continue
+        gray = prepare_image(frame, cv2, adjust)
+        corners, ids, _ = detect(gray)
+        dets = []
+        if ids is not None:
+            for i in range(len(ids)):
+                marker_id = int(ids[i][0])
+                pts = corners[i].reshape(-1, 2)
+                dets.append({
+                    "id": marker_id,
+                    "corners": pts.tolist(),
+                    "center": corner_center(corners[i]),
+                })
+        results[base] = dets
+    return results

signa_core-0.1.0/signa_core/dictionaries.py

@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: MIT
+"""ArUco dictionary and detector-parameter helpers (OpenCV-version compatible).
+
+Pure OpenCV/numpy — no WebODM/Django. These are the shared, reusable detection
+primitives extracted from the Signa WebODM plugin's self-contained worker
+detector, so other consumers (e.g. Mensura's scale calibration) can reuse the
+exact same detection behaviour without duplicating it.
+
+The OpenCV ArUco API changed across versions (4.6 vs 4.7+); every helper here
+handles both the legacy free-function form and the newer object-oriented form.
+"""
+
+# Single source of truth for the offered ArUco dictionaries, as (value, label)
+# pairs. Ids 0..20 are OpenCV's predefined dictionaries; 99 is a legacy custom
+# 3x3 dictionary built with extendDictionary for existing Signa marker sheets.
+DICT_CHOICES = [
+    ("0", "0 — DICT_4X4_50"),
+    ("1", "1 — DICT_4X4_100"),
+    ("2", "2 — DICT_4X4_250"),
+    ("3", "3 — DICT_4X4_1000"),
+    ("4", "4 — DICT_5X5_50"),
+    ("5", "5 — DICT_5X5_100"),
+    ("6", "6 — DICT_5X5_250"),
+    ("7", "7 — DICT_5X5_1000"),
+    ("8", "8 — DICT_6X6_50"),
+    ("9", "9 — DICT_6X6_100"),
+    ("10", "10 — DICT_6X6_250"),
+    ("11", "11 — DICT_6X6_1000"),
+    ("12", "12 — DICT_7X7_50"),
+    ("13", "13 — DICT_7X7_100"),
+    ("14", "14 — DICT_7X7_250"),
+    ("15", "15 — DICT_7X7_1000"),
+    ("16", "16 — DICT_ARUCO_ORIGINAL"),
+    ("17", "17 — DICT_APRILTAG_16h5"),
+    ("18", "18 — DICT_APRILTAG_25h9"),
+    ("19", "19 — DICT_APRILTAG_36h10"),
+    ("20", "20 — DICT_APRILTAG_36h11"),
+    ("99", "99 — legacy custom 3×3"),
+]
+
+VALID_DICTS = {int(value) for value, _label in DICT_CHOICES}
+
+
+def load_aruco():
+    """Return ``(cv2, cv2.aruco)`` or raise a clear error if aruco is missing."""
+    import cv2  # noqa: PLC0415 — lazy: keeps import optional for non-detect consumers
+    try:
+        from cv2 import aruco
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "OpenCV with the ArUco module (cv2.aruco) is required — install "
+            "opencv-contrib-python(-headless)."
+        ) from exc
+    return cv2, aruco
+
+
+def make_dictionary(dict_id, aruco=None):
+    if aruco is None:
+        _, aruco = load_aruco()
+    dict_id = int(dict_id)
+    if dict_id == 99:
+        if hasattr(aruco, "extendDictionary"):
+            return aruco.extendDictionary(32, 3)
+        return aruco.Dictionary_create(32, 3)
+    if hasattr(aruco, "getPredefinedDictionary"):
+        return aruco.getPredefinedDictionary(dict_id)
+    return aruco.Dictionary_get(dict_id)
+
+
+def make_parameters(minrate, ignore, aruco=None):
+    if aruco is None:
+        _, aruco = load_aruco()
+    if hasattr(aruco, "DetectorParameters"):
+        params = aruco.DetectorParameters()
+    else:
+        params = aruco.DetectorParameters_create()
+    params.minMarkerPerimeterRate = float(minrate)
+    params.perspectiveRemoveIgnoredMarginPerCell = float(ignore)
+    return params
+
+
+def make_detector(dictionary, params, aruco=None):
+    """Return ``detect(gray) -> (corners, ids, rejected)`` across OpenCV versions."""
+    if aruco is None:
+        _, aruco = load_aruco()
+    if hasattr(aruco, "ArucoDetector"):
+        detector = aruco.ArucoDetector(dictionary, params)
+        return lambda gray: detector.detectMarkers(gray)
+    return lambda gray: aruco.detectMarkers(gray, dictionary, parameters=params)

signa_core-0.1.0/tests/test_detect.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: MIT
+"""Synthetic round-trip: render an ArUco marker, then detect it back."""
+import numpy as np
+import pytest
+
+cv2 = pytest.importorskip("cv2")
+aruco = pytest.importorskip("cv2.aruco")
+
+from signa_core import detect_markers, make_dictionary  # noqa: E402
+
+
+def _render_marker(dict_id, marker_id, side=240, pad=80):
+    d = make_dictionary(dict_id, aruco)
+    if hasattr(aruco, "generateImageMarker"):
+        marker = aruco.generateImageMarker(d, marker_id, side)
+    else:  # older OpenCV
+        marker = aruco.drawMarker(d, marker_id, side)
+    canvas = np.full((side + 2 * pad, side + 2 * pad), 255, dtype=np.uint8)
+    canvas[pad:pad + side, pad:pad + side] = marker
+    return cv2.cvtColor(canvas, cv2.COLOR_GRAY2BGR)
+
+
+def test_detect_synthetic_marker(tmp_path):
+    img_path = tmp_path / "marker.png"
+    cv2.imwrite(str(img_path), _render_marker(dict_id=1, marker_id=7))
+
+    result = detect_markers([str(img_path)], dict_id=1, minrate=0.01, ignore=0.33)
+    dets = result["marker.png"]
+
+    assert dets, "no markers detected"
+    ids = {d["id"] for d in dets}
+    assert 7 in ids
+    det = next(d for d in dets if d["id"] == 7)
+    assert len(det["corners"]) == 4
+    cx, cy = det["center"]
+    # marker is centered on the canvas (side 240, pad 80 -> center at 200,200)
+    assert abs(cx - 200) <= 5 and abs(cy - 200) <= 5
+
+
+def test_unreadable_image_is_none(tmp_path):
+    bad = tmp_path / "nope.png"
+    bad.write_bytes(b"not an image")
+    result = detect_markers([str(bad)], dict_id=1)
+    assert result["nope.png"] is None