descriptron-core 2.1.1__tar.gz → 2.1.2__tar.gz

descriptron_core-2.1.2/NOTICE

@@ -0,0 +1,59 @@
+Descriptron
+Copyright 2024-2026 Alex R. Van Dam (ORCID 0000-0002-1966-0338)
+
+This product includes software developed by Alex R. Van Dam
+https://github.com/alexrvandam/Descriptron
+
+Licensed under the Apache License, Version 2.0 (see LICENSE). Under Section
+4(d) of that licence, this NOTICE file must be included with any
+redistribution of this software or of any work derived from it.
+
+REQUIRED CITATION
+-----------------
+Anyone who uses Descriptron, or any software derived from it (including
+descriptron-core, descriptron-vision, descriptron-gui and descriptron-mcp), in
+work that is published, presented or distributed must cite:
+
+  1. The software (Descriptron v2), by the DOI of the version used:
+     Van Dam, A. R. (2026). Descriptron: morphology-driven species descriptions,
+     keys and delimitation for dark taxa (Version 2.1.1). Zenodo.
+     https://doi.org/10.5281/zenodo.22958109
+     (all versions: https://doi.org/10.5281/zenodo.17077224;
+      repository: https://github.com/alexrvandam/Descriptron)
+
+  2. The first Descriptron paper:
+     Van Dam, A. R. & Štarhová Serbina, L. (2026). Descriptron: Artificial
+     intelligence for automating taxonomic species descriptions with a
+     user-friendly software package. Systematic Entomology, 51(1), e70005.
+     https://doi.org/10.1111/syen.70005
+
+  3. Once it is published, the Descriptron v2 paper as well. Its reference
+     will be added here and in CITATION.cff on publication.
+
+BibTeX:
+
+@software{vandam_2026_descriptron_v211,
+  author    = {Van Dam, Alex R.},
+  title     = {Descriptron: morphology-driven species descriptions, keys and
+               delimitation for dark taxa},
+  version   = {v2.1.1},
+  year      = {2026},
+  publisher = {Zenodo},
+  doi       = {10.5281/zenodo.22958109},
+  url       = {https://doi.org/10.5281/zenodo.22958109}
+}
+
+@article{vandam2026descriptron,
+  author  = {Van Dam, Alex R. and Štarhová Serbina, Liliya},
+  title   = {Descriptron: Artificial intelligence for automating taxonomic species
+             descriptions with a user-friendly software package},
+  journal = {Systematic Entomology},
+  volume  = {51},
+  number  = {1},
+  pages   = {e70005},
+  year    = {2026},
+  doi     = {10.1111/syen.70005}
+}
+
+The same information is in CITATION.cff, which GitHub shows as
+"Cite this repository".

{descriptron_core-2.1.1 → descriptron_core-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: descriptron-core
-Version: 2.1.1
+Version: 2.1.2
 Summary: Evidence-tiered species descriptions, keys and audits from phenomic matrices
 Project-URL: Homepage, https://github.com/alexrvandam/Descriptron
 Project-URL: Repository, https://github.com/alexrvandam/Descriptron
@@ -9,6 +9,7 @@ Author: Alex R. Van Dam
 License: Apache-2.0
 License-File: LICENSE
 License-File: NOTICE
+License-File: NOTICE.bak_pre_212_20260929_1100
 Keywords: COCO,morphometrics,phenomics,species description,taxonomy
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: Apache Software License

{descriptron_core-2.1.1 → descriptron_core-2.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "descriptron-core"
-version = "2.1.1"
+version = "2.1.2"
 description = "Evidence-tiered species descriptions, keys and audits from phenomic matrices"
 readme = "README.md"
 requires-python = ">=3.9"

descriptron_core-2.1.2/src/descriptron_core/tools/validate_centerline_lengths.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Centre-line length on shapes of known length (straight bar, arcs of increasing bend, an S-curve), at several
+widths, against the straight measurement a length-along-the-main-axis would give. Writes a CSV and prints a summary;
+the numbers quoted in the paper and README come from this script.
+
+  python validate_centerline_lengths.py --out_csv centerline_validation.csv
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+import descriptron_centerline as dc  # noqa: E402
+
+
+def mask(pts, width, size=1000):
+    m = np.zeros((size, size), np.uint8)
+    cv2.polylines(m, [np.round(pts).astype(np.int32)], False, 1, width)
+    return m.astype(bool)
+
+
+def arclen(p):
+    return float(np.hypot(*np.diff(p, axis=0).T).sum())
+
+
+def axis_extent(m):
+    ys, xs = np.nonzero(m)
+    P = np.stack([xs, ys], 1).astype(float); P -= P.mean(0)
+    pr = P @ np.linalg.svd(P, full_matrices=False)[2][0]
+    return float(pr.max() - pr.min())
+
+
+T = np.linspace(0, 1, 4000)
+SHAPES = {"straight": np.stack([200 + 346.4 * T, 300 + 200 * T], 1)}
+for deg in (60, 90, 120):
+    a = np.radians(-90 - deg / 2 + deg * T)
+    SHAPES[f"arc_{deg}deg"] = np.stack([500 + 300 * np.cos(a), 700 + 300 * np.sin(a)], 1)
+SHAPES["s_curve"] = np.stack([150 + 700 * T, 500 + 120 * np.sin(2 * np.pi * T)], 1)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--out_csv", required=True)
+    a = ap.parse_args()
+    rows = []
+    for name, pts in SHAPES.items():
+        for w in (6, 10, 20, 30):
+            m = mask(pts, w)
+            true = arclen(pts) + w                     # round caps add w/2 at each end
+            r = dc.centerline(m)
+            rows.append(dict(shape=name, width_px=w, true_length_px=round(true, 1),
+                             centerline_px=round(r["length_px"], 1),
+                             centerline_err_pct=round(100 * (r["length_px"] - true) / true, 2),
+                             straight_axis_px=round(axis_extent(m), 1),
+                             straight_err_pct=round(100 * (axis_extent(m) - true) / true, 2)))
+    with open(a.out_csv, "w", newline="") as fh:
+        wr = csv.DictWriter(fh, fieldnames=list(rows[0])); wr.writeheader(); wr.writerows(rows)
+    ce = np.abs([r["centerline_err_pct"] for r in rows])
+    print(f"centre line: |error| median {np.median(ce):.2f}%, max {ce.max():.2f}% over {len(rows)} shape x width cases")
+    for name in SHAPES:
+        s = [r["straight_err_pct"] for r in rows if r["shape"] == name]
+        c = [r["centerline_err_pct"] for r in rows if r["shape"] == name]
+        print(f"  {name:12s} straight axis {min(s):+.1f} to {max(s):+.1f}%   centre line {min(c):+.2f} to {max(c):+.2f}%")
+
+
+if __name__ == "__main__":
+    main()

descriptron_core-2.1.2/src/descriptron_core/tools/validate_texture_glcm.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""Checks of Descriptron's texture features (texture_phenomics_homology.py).
+
+1. Masked GLCM against scikit-image: pixels outside the mask get an extra 'outside' grey level, scikit-image builds
+   the symmetric GLCM, and that level's row and column are dropped; what remains is exactly the 'both pixels in the
+   mask' matrix Descriptron computes. (scikit-image names the two diagonals the other way round; Descriptron averages
+   the four directions, so its features are unaffected.)
+2. Grey-level invariance: the same image quantised to 8 and 32 levels; ratio of the feature values (1 = invariant),
+   for Descriptron's invariant Haralick formulas and the standard ones.
+
+  python validate_texture_glcm.py --image_glob "<dir>/*.png" --texture_script <texture_phenomics_homology.py> --out_csv out.csv
+"""
+import argparse
+import csv
+import glob
+import importlib.util
+
+import cv2
+import numpy as np
+from skimage.feature import graycomatrix
+
+ANGLES = (0, np.pi / 4, np.pi / 2, 3 * np.pi / 4)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--image_glob", required=True); ap.add_argument("--texture_script", required=True)
+    ap.add_argument("--n_images", type=int, default=15); ap.add_argument("--out_csv", required=True)
+    a = ap.parse_args()
+    spec = importlib.util.spec_from_file_location("tx", a.texture_script)
+    tx = importlib.util.module_from_spec(spec); spec.loader.exec_module(tx)
+    imgs = sorted(glob.glob(a.image_glob))[: a.n_images]
+    rows = []
+    worst, n = 0.0, 0
+    for f in imgs:
+        g = cv2.imread(f, 0); q = (g // 16).astype(np.uint8)
+        h, w = q.shape; yy, xx = np.mgrid[:h, :w]
+        for s in range(3):
+            cy, cx, ry, rx = h * (0.3 + 0.2 * s), w * (0.3 + 0.2 * s), h * 0.25, w * 0.2
+            m = ((yy - cy) / ry) ** 2 + ((xx - cx) / rx) ** 2 < 1
+            for ang in ANGLES:
+                ours = tx._masked_glcm_single(q, m, 3, ang, levels=16)
+                sk = {np.pi / 4: 3 * np.pi / 4, 3 * np.pi / 4: np.pi / 4}.get(ang, ang)
+                R = graycomatrix(np.where(m, q, 16).astype(np.uint8), [3], [sk], levels=17,
+                                 symmetric=True, normed=False)[:16, :16, 0, 0].astype(float)
+                R /= R.sum()
+                worst = max(worst, float(np.abs(ours - R).max())); n += 1
+        full = np.ones(g.shape, bool); gf = g.astype(float); vals = {}
+        for L in (8, 32):
+            ql = np.clip((gf - gf.min()) / (gf.max() - gf.min()) * (L - 1), 0, L - 1).astype(np.uint8)
+            G = np.mean([tx._masked_glcm_single(ql, full, 3, an, levels=L) for an in ANGLES], axis=0)
+            I, J = np.meshgrid(np.arange(L), np.arange(L), indexing="ij")
+            vals[L] = (tx._haralick_invariant(G, levels=L),
+                       [float((G * (I - J) ** 2).sum()), float((G / (1 + (I - J) ** 2)).sum()), float((G ** 2).sum())])
+        for k, name in enumerate(("contrast", "homogeneity", "energy")):
+            rows.append(dict(image=f, feature=name, invariant_ratio_32_vs_8=vals[32][0][k] / vals[8][0][k],
+                             standard_ratio_32_vs_8=vals[32][1][k] / vals[8][1][k]))
+    with open(a.out_csv, "w", newline="") as fh:
+        wr = csv.DictWriter(fh, fieldnames=list(rows[0])); wr.writeheader(); wr.writerows(rows)
+    print(f"masked GLCM vs scikit-image: max |difference| {worst:.2e} over {n} matrices")
+    for name in ("contrast", "homogeneity", "energy"):
+        r = [x for x in rows if x["feature"] == name]
+        print(f"{name:12s} ratio 32/8 levels, median: invariant {np.median([x['invariant_ratio_32_vs_8'] for x in r]):.2f}"
+              f"   standard {np.median([x['standard_ratio_32_vs_8'] for x in r]):.2f}")
+
+
+if __name__ == "__main__":
+    main()