descriptron-vision 2.0.2__tar.gz → 2.0.4__tar.gz

{descriptron_vision-2.0.2 → descriptron_vision-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: descriptron-vision
-Version: 2.0.2
+Version: 2.0.4
 Summary: Mask and landmark prediction for Descriptron: torchvision detectors, SAM2-PAL propagation, DINOv3 landmark transfer
 Project-URL: Homepage, https://github.com/alexrvandam/Descriptron
 Author: Alex R. Van Dam
@@ -13,7 +13,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Image Recognition
 Requires-Python: >=3.9
-Requires-Dist: descriptron-core==2.0.2
+Requires-Dist: descriptron-core==2.0.4
 Requires-Dist: einops>=0.7
 Requires-Dist: timm>=0.9
 Requires-Dist: torch>=2.3

descriptron_vision-2.0.4/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "descriptron-vision"
+version = "2.0.4"
+description = "Mask and landmark prediction for Descriptron: torchvision detectors, SAM2-PAL propagation, DINOv3 landmark transfer"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Alex R. Van Dam" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Image Recognition",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+]
+
+# torch and torchvision are ordinary wheels on Linux, macOS and Windows, so this
+# installs without a compiler. On a Mac the torchvision detectors can use the
+# Apple GPU through PyTorch's MPS device; Detectron2 cannot, which is why the
+# torchvision backend exists.
+#
+# For CUDA, install torch from PyTorch's own index FIRST, then this package:
+#   pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
+dependencies = [
+  "descriptron-core==2.0.4",
+  # Capped deliberately. Unbounded, pip installs torch 2.14 with ~3 GB of CUDA 13
+  # wheels — not the torch 2.4.0+cu121 this system was validated on, and a version
+  # in which the AMP calls below are already deprecated. Raise the cap only after
+  # testing, not before.
+  "torch>=2.3",           # torch.amp.GradScaler("cuda") in tv_train_v1 needs 2.3
+  "torchvision>=0.18",
+  "transformers>=4.38",   # Florence-2 scale-bar reading
+  "timm>=0.9",
+  "einops>=0.7",
+  "tqdm>=4.65",
+]
+
+[project.optional-dependencies]
+# SAM2 is not on PyPI and PyPI rejects a git dependency in package metadata, so
+# it cannot be declared here. It is imported lazily and the error message gives
+# the install command:
+#   pip install git+https://github.com/facebookresearch/segment-anything-2
+# Detectron2 is the same story, and additionally needs a compiler; see the
+# Docker image if you would rather not build it.
+ocr = ["easyocr>=1.7"]
+dev = ["pytest>=7", "build>=1", "twine>=5"]
+
+[project.scripts]
+descriptron-train      = "descriptron_vision.cli:train"
+descriptron-predict    = "descriptron_vision.cli:predict"
+descriptron-sweep      = "descriptron_vision.cli:sweep"
+descriptron-sam2pal    = "descriptron_vision.cli:sam2_pal"
+descriptron-dinoland   = "descriptron_vision.cli:dinoland"
+descriptron-measure    = "descriptron_vision.cli:measure"
+
+[project.urls]
+Homepage = "https://github.com/alexrvandam/Descriptron"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/descriptron_vision"]

descriptron_vision-2.0.4/pyproject.toml.bak_pre_204_20260924_165335

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "descriptron-vision"
+version = "2.0.3"
+description = "Mask and landmark prediction for Descriptron: torchvision detectors, SAM2-PAL propagation, DINOv3 landmark transfer"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Alex R. Van Dam" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Image Recognition",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+]
+
+# torch and torchvision are ordinary wheels on Linux, macOS and Windows, so this
+# installs without a compiler. On a Mac the torchvision detectors can use the
+# Apple GPU through PyTorch's MPS device; Detectron2 cannot, which is why the
+# torchvision backend exists.
+#
+# For CUDA, install torch from PyTorch's own index FIRST, then this package:
+#   pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
+dependencies = [
+  "descriptron-core==2.0.3",
+  # Capped deliberately. Unbounded, pip installs torch 2.14 with ~3 GB of CUDA 13
+  # wheels — not the torch 2.4.0+cu121 this system was validated on, and a version
+  # in which the AMP calls below are already deprecated. Raise the cap only after
+  # testing, not before.
+  "torch>=2.3",           # torch.amp.GradScaler("cuda") in tv_train_v1 needs 2.3
+  "torchvision>=0.18",
+  "transformers>=4.38",   # Florence-2 scale-bar reading
+  "timm>=0.9",
+  "einops>=0.7",
+  "tqdm>=4.65",
+]
+
+[project.optional-dependencies]
+# SAM2 is not on PyPI and PyPI rejects a git dependency in package metadata, so
+# it cannot be declared here. It is imported lazily and the error message gives
+# the install command:
+#   pip install git+https://github.com/facebookresearch/segment-anything-2
+# Detectron2 is the same story, and additionally needs a compiler; see the
+# Docker image if you would rather not build it.
+ocr = ["easyocr>=1.7"]
+dev = ["pytest>=7", "build>=1", "twine>=5"]
+
+[project.scripts]
+descriptron-train      = "descriptron_vision.cli:train"
+descriptron-predict    = "descriptron_vision.cli:predict"
+descriptron-sweep      = "descriptron_vision.cli:sweep"
+descriptron-sam2pal    = "descriptron_vision.cli:sam2_pal"
+descriptron-dinoland   = "descriptron_vision.cli:dinoland"
+descriptron-measure    = "descriptron_vision.cli:measure"
+
+[project.urls]
+Homepage = "https://github.com/alexrvandam/Descriptron"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/descriptron_vision"]

descriptron_vision-2.0.4/src/descriptron_vision/cli.py

@@ -0,0 +1,66 @@
+"""
+descriptron_vision.cli — detectors, propagation and landmark transfer
+=====================================================================
+
+Same dispatch as `descriptron_core.cli`. The two dependencies that are not on
+PyPI — SAM2 and Detectron2 — are not declared anywhere: PyPI rejects a git
+dependency in package metadata. They are imported lazily by the programs that
+need them, and `require()` below turns the resulting ImportError into the exact
+command to run.
+"""
+from __future__ import annotations
+
+import sys
+
+from descriptron_core.cli import run as _run_core   # noqa: F401  (shared behaviour)
+from descriptron_core.cli import data_path          # noqa: F401
+
+import os
+import runpy
+from importlib.resources import files
+from pathlib import Path
+
+INSTALL_HINTS = {
+    "sam2": ("SAM2 is not on PyPI, so it cannot be a declared dependency.\n"
+             "  pip install git+https://github.com/facebookresearch/segment-anything-2"),
+    "detectron2": ("Detectron2 is not on PyPI and must be compiled:\n"
+                   "  pip install git+https://github.com/facebookresearch/detectron2\n"
+                   "It needs a C++/CUDA toolchain and has no macOS wheels. If you would\n"
+                   "rather not build it, the Docker image carries it ready to run, and the\n"
+                   "torchvision backend needs none of this."),
+}
+
+
+def require(module: str):
+    """Import an optional heavyweight dependency, or explain how to get it."""
+    try:
+        return __import__(module)
+    except ImportError as exc:
+        hint = INSTALL_HINTS.get(module, f"  pip install {module}")
+        raise SystemExit(f"{module} is required for this step but is not installed.\n"
+                         f"{hint}\n\n(original error: {exc})") from exc
+
+
+def tools_dir() -> Path:
+    return Path(str(files("descriptron_vision") / "tools"))
+
+
+def _run(script: str, argv: list[str], subdir: str | None = None) -> None:
+    base = tools_dir() / subdir if subdir else tools_dir()
+    path = base / script
+    if not path.exists():
+        raise SystemExit(f"{path} is missing — was sync_sources.py run before building?")
+    sys.path.insert(0, str(path.parent))
+    sys.path.insert(0, str(tools_dir()))
+    os.environ.setdefault("DESCRIPTRON_DATA", str(data_path()))
+    sys.argv = [str(path), *argv]
+    runpy.run_path(str(path), run_name="__main__")
+
+
+def train():      _run("tv_train_v1.py", sys.argv[1:], "torchvision_det")
+def predict():    _run("tv_predict_v1.py", sys.argv[1:], "torchvision_det")
+def sweep():      _run("tv_sweep_v1.py", sys.argv[1:], "torchvision_det")
+def sam2_pal():   _run("sam2_pal_batch_v21.py", sys.argv[1:])
+def dinoland():   _run("dinov3_landmark_transfer_v52.py", sys.argv[1:])   # v52 = v51 + --orientation_search
+def measure():
+    _run("measurement_script_to_try_after_kpts_prediction_measure_kpts_V35.py", sys.argv[1:])

{descriptron_vision-2.0.2 → descriptron_vision-2.0.4}/src/descriptron_vision/tools/dinov3_landmark_transfer_v51.py

@@ -639,6 +639,12 @@ def main():
                          "padding) or on the 512x512 letterboxed tensor the model saw")
     ap.add_argument("--fig_per_page", type=int, default=12,
                     help="panels per preview page; 170 targets in one figure is unusable")
+    ap.add_argument("--mirror_refs", action="store_true",
+                    help="mirror-aware transfer: add a left-right flipped copy of every reference "
+                         "(image flipped, landmark x mirrored, landmark numbers kept) and, per target, "
+                         "keep only the handedness group whose references match best (share of "
+                         "landmarks accepted). Needed when some specimens are photographed as mirror "
+                         "images; the two handednesses are never mixed in one vote.")
     ap.add_argument("--emit_refs", action="store_true",
                     help="also write one COCO file per target under <outdir>/per_image/ and "
                          "list the fully-confirmed ones in refs_confirmed.txt, so a checked "
@@ -688,6 +694,26 @@ def main():
             print(f"reference {fname}: {len(present)}/{len(ids)} landmarks present")
         print(f"{len(refs)} reference(s); landmark ids {slot_ids}")
 
+        # ---- mirror-aware mode: handedness of each reference, plus flipped copies ----
+        # Handedness = sign of the signed area (shoelace) of the landmarks in their fixed
+        # numbering order: a mirror image reverses it. A flipped reference keeps its landmark
+        # numbers, so its votes stay in the same slots.
+        def _handedness(pts):
+            x, y = pts[:, 0], pts[:, 1]
+            return 1 if 0.5 * np.sum(x * np.roll(y, -1) - np.roll(x, -1) * y) >= 0 else -1
+        ref_hand = [_handedness(r[3]) for r in refs]
+        if a.mirror_refs:
+            for (rname, _fa, mk, pts, present, im), hnd in list(zip(refs, ref_hand)):
+                im_f = im.transpose(Image.FLIP_LEFT_RIGHT)
+                pts_f = pts.copy()
+                pts_f[:, 0] = bb.img_dim - pts_f[:, 0]
+                refs.append((rname + " [flipped]", bb.embed(im_f, LAYER, "none", a.facet),
+                             mk[:, ::-1].copy(), pts_f, present, im_f))
+                ref_hand.append(-hnd)
+            print(f"mirror-aware: {len(refs)} references "
+                  f"({ref_hand.count(1)} one handedness, {ref_hand.count(-1)} the other)")
+        two_hands = a.mirror_refs and len(set(ref_hand)) == 2
+
         targets = sorted(_glob.glob(a.batch_glob))
         ref_names = {os.path.basename(r[0]).replace('_keypoints.json', '') for r in refs}
         targets = [t for t in targets if os.path.abspath(t) != os.path.abspath(a.imgA)]
@@ -701,16 +727,24 @@ def main():
                 bb, rawB, LAYER, tp, a.mask_dir)
             fb = bb.embed(imgB, LAYER, "none", a.facet)
 
-            votes = {k: [] for k in range(len(slot_ids))}   # slot -> [(xy, accepted)]
-            for rname, fa, maskA_r, pts, present, _im in refs:
+            group_votes, group_score = {}, {}
+            for gi, ((rname, fa, maskA_r, pts, present, _im), hnd) in enumerate(zip(refs, ref_hand)):
+                g = hnd if two_hands else 0
+                votes = group_votes.setdefault(g, {k: [] for k in range(len(slot_ids))})
                 A = None
                 if a.align == "feature":
                     A = feature_affine(fa, fb, maskA_r, maskB, bb.patch, bb.grid)
                 if A is None:
                     A = pca_affine(maskA_r, maskB)
                 r = transfer(fa, fb, pts, A, bb.patch, bb.grid, radius_patches=a.radius)
+                group_score.setdefault(g, []).append(float(np.mean(r.accepted)))
                 for j, slot in enumerate(present):
                     votes[slot].append((r.pred[j], bool(r.accepted[j])))
+            # RANSAC fits rotation/scale/shift only, never a reflection, so references of the
+            # wrong handedness get most landmarks rejected: the higher mean accepted share wins
+            chosen = max(group_votes, key=lambda g: np.mean(group_score[g]))
+            votes = group_votes[chosen]
+            hand_used = chosen if two_hands else None
 
             # ---- consensus: median of the votes, spread = agreement ------------
             cons = {}
@@ -726,7 +760,7 @@ def main():
 
             results.append((os.path.basename(tp).rsplit('.', 1)[0], imgB, maskB,
                             cons, (W0, H0), os.path.basename(tp),
-                            (tscale, tox, toy, tcx, tcy), tp))
+                            (tscale, tox, toy, tcx, tcy), tp, hand_used))
             agree = sum(1 for k in cons if cons[k][0] is not None and cons[k][1] > 0)
             print(f"{os.path.basename(tp)[:44]:<46} confirmed {agree}/{len(slot_ids)}")
 
@@ -745,7 +779,7 @@ def main():
             os.makedirs(per_image_dir, exist_ok=True)
         confirmed_refs = []
         anns_by_name = {}                     # name -> annotation, for the preview
-        for nm, imgB, mkB, cons, (W0, H0), fname, (tscale, tox, toy, tcx, tcy), tp in results:
+        for nm, imgB, mkB, cons, (W0, H0), fname, (tscale, tox, toy, tcx, tcy), tp, hand_used in results:
             kp, nvis, detail = [], 0, []
             xs, ys = [], []
             for k, sid in enumerate(slot_ids):
@@ -770,6 +804,7 @@ def main():
                    "bbox": bbox, "iscrowd": 0,
                    "point_order": slot_ids,
                    "n_references": len(refs),
+                   "handedness_used": hand_used,
                    "landmark_detail": detail}
             coco["images"].append(img_entry)
             coco["annotations"].append(ann)
@@ -807,7 +842,7 @@ def main():
             n = len(page); cols = min(3, n); rows = int(np.ceil(n / cols))
             fig, axes = plt.subplots(rows, cols, figsize=(4.0 * cols, 4.2 * rows), dpi=150)
             axes = np.atleast_1d(axes).ravel()
-            for ax_, (nm, imgB, mkB, cons, (W0, H0), _fn, _lb, tp) in zip(axes, page):
+            for ax_, (nm, imgB, mkB, cons, (W0, H0), _fn, _lb, tp, _hand) in zip(axes, page):
                 if a.preview == "original":
                     ax_.imshow(Image.open(tp).convert("RGB"))
                     kpx = anns_by_name[nm]["keypoints"]