trekr 0.1.0__tar.gz

trekr-0.1.0/LICENSE

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

trekr-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: trekr
+Version: 0.1.0
+Summary: Checks for pose tracking: a window to find and fix label errors in DeepLabCut projects, the GPU against the PyTorch build, whether OpenCV decodes camera video with the right colours, and whether a video file changed.
+Author: Koen Freerks
+License-Expression: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: opencv-python-headless>=4.8
+Requires-Dist: PySide6>=6.5
+Requires-Dist: pyyaml>=6
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# trekr
+
+An early, small release of **TREKR**, a pose-tracking tool in development. This
+release holds three checks that are useful on their own.
+
+```bash
+pip install trekr
+trekr labels PROJECT          # check and fix DeepLabCut labels (a window)
+trekr check
+trekr videocheck VIDEO [--save REF.json | --against REF.json]
+```
+
+## `trekr labels`: find and fix label errors in a DeepLabCut project
+
+```bash
+trekr labels path/to/my-dlc-project      # the folder with config.yaml and labeled-data/
+```
+
+A wrong label -- a leg point on the neighbour, two points swapped, a point dropped in
+the background -- trains a network to be wrong, and among hundreds of labelled animals
+it is hard to find by eye. Such an error is almost always one point while the rest of
+the animal is right. `trekr labels` compares each point with the rest of its animal
+through the distances between them (which do not change when the animal turns, or is
+seen upside down), against the usual distances in your own labels, and lists the
+animals with the point that fits worst first.
+
+- **To check:** click an animal: the image opens on it with its worst point selected.
+  A score is in units of the labels' own spread: right points score about 1; errors
+  stand far above (on a tested project, most animals above about 10 had a wrong point).
+- **Hover** a point to see which keypoint of which animal it is, and its score.
+- **Editing:** drag a point to move it, right-click to remove it; pick a keypoint in
+  the list and click to place it; Ctrl+Z / Ctrl+Y. F5 checks again after edits.
+- **Saving** (Ctrl+S) writes the edited points into `CollectedData_<scorer>.csv`;
+  every other byte of the file stays as it was, and the original is kept beside it
+  (`.orig`). DeepLabCut trains from the `.h5` file, which you make again from the CSV:
+
+  ```python
+  import deeplabcut
+  deeplabcut.convertcsv2h5("path/to/my-dlc-project/config.yaml", userfeedback=False)
+  ```
+
+One kind of animal per project (DeepLabCut's unique bodyparts are kept as they are and
+not checked); single- and multi-animal projects; the labelled frames are the PNG images
+in `labeled-data/`, so no videos are needed. The skeleton is drawn from `config.yaml`.
+
+## `trekr check`: is this computer ready?
+
+Every line says **OK**, **NOTE** (works, with a caveat) or **FAIL** (why, and what to
+install); the exit status is 1 when anything fails.
+
+- **The GPU against the PyTorch build** (if PyTorch is installed). A PyTorch build
+  carries compiled code for some GPU generations only, so a new card -- for example
+  the RTX 50 series -- can need a build for a newer CUDA. The check names the GPU's
+  architecture and the build's, and says which to install.
+- **The NVIDIA driver against that CUDA version.**
+- **Video decoding.** A tiny stored H.264 clip, encoded the way cameras write video
+  (BT.709 colour matrix, TV range), is decoded with the installed OpenCV and compared
+  with the frames a correct decoder gives. OpenCV 4.11 and 4.12 apply the wrong colour
+  matrix to such video: on the clip, red is off by 5.4 and blue by 2.5 grey levels on
+  average, up to 22. Every colour or brightness measured from video decoded that way
+  is shifted. OpenCV 4.13 and newer decode it exactly.
+
+## `trekr videocheck`: is a video file still the one you recorded?
+
+```bash
+trekr videocheck run1.mp4 --save run1.fingerprint.json     # once, next to your data
+trekr videocheck run1.mp4 --against run1.fingerprint.json  # later: the same file? (exit 2 if not)
+```
+
+The fingerprint is the file's size and a SHA-256 of its first and last megabyte (fast
+for any size; nothing is decoded), with the frame count, frame rate and size as OpenCV
+reads them. A re-encode, a cut or a different file under the same name shows up, with
+what changed.
+
+## Licence
+
+MIT (see LICENSE).

trekr-0.1.0/README.md

@@ -0,0 +1,77 @@
+# trekr
+
+An early, small release of **TREKR**, a pose-tracking tool in development. This
+release holds three checks that are useful on their own.
+
+```bash
+pip install trekr
+trekr labels PROJECT          # check and fix DeepLabCut labels (a window)
+trekr check
+trekr videocheck VIDEO [--save REF.json | --against REF.json]
+```
+
+## `trekr labels`: find and fix label errors in a DeepLabCut project
+
+```bash
+trekr labels path/to/my-dlc-project      # the folder with config.yaml and labeled-data/
+```
+
+A wrong label -- a leg point on the neighbour, two points swapped, a point dropped in
+the background -- trains a network to be wrong, and among hundreds of labelled animals
+it is hard to find by eye. Such an error is almost always one point while the rest of
+the animal is right. `trekr labels` compares each point with the rest of its animal
+through the distances between them (which do not change when the animal turns, or is
+seen upside down), against the usual distances in your own labels, and lists the
+animals with the point that fits worst first.
+
+- **To check:** click an animal: the image opens on it with its worst point selected.
+  A score is in units of the labels' own spread: right points score about 1; errors
+  stand far above (on a tested project, most animals above about 10 had a wrong point).
+- **Hover** a point to see which keypoint of which animal it is, and its score.
+- **Editing:** drag a point to move it, right-click to remove it; pick a keypoint in
+  the list and click to place it; Ctrl+Z / Ctrl+Y. F5 checks again after edits.
+- **Saving** (Ctrl+S) writes the edited points into `CollectedData_<scorer>.csv`;
+  every other byte of the file stays as it was, and the original is kept beside it
+  (`.orig`). DeepLabCut trains from the `.h5` file, which you make again from the CSV:
+
+  ```python
+  import deeplabcut
+  deeplabcut.convertcsv2h5("path/to/my-dlc-project/config.yaml", userfeedback=False)
+  ```
+
+One kind of animal per project (DeepLabCut's unique bodyparts are kept as they are and
+not checked); single- and multi-animal projects; the labelled frames are the PNG images
+in `labeled-data/`, so no videos are needed. The skeleton is drawn from `config.yaml`.
+
+## `trekr check`: is this computer ready?
+
+Every line says **OK**, **NOTE** (works, with a caveat) or **FAIL** (why, and what to
+install); the exit status is 1 when anything fails.
+
+- **The GPU against the PyTorch build** (if PyTorch is installed). A PyTorch build
+  carries compiled code for some GPU generations only, so a new card -- for example
+  the RTX 50 series -- can need a build for a newer CUDA. The check names the GPU's
+  architecture and the build's, and says which to install.
+- **The NVIDIA driver against that CUDA version.**
+- **Video decoding.** A tiny stored H.264 clip, encoded the way cameras write video
+  (BT.709 colour matrix, TV range), is decoded with the installed OpenCV and compared
+  with the frames a correct decoder gives. OpenCV 4.11 and 4.12 apply the wrong colour
+  matrix to such video: on the clip, red is off by 5.4 and blue by 2.5 grey levels on
+  average, up to 22. Every colour or brightness measured from video decoded that way
+  is shifted. OpenCV 4.13 and newer decode it exactly.
+
+## `trekr videocheck`: is a video file still the one you recorded?
+
+```bash
+trekr videocheck run1.mp4 --save run1.fingerprint.json     # once, next to your data
+trekr videocheck run1.mp4 --against run1.fingerprint.json  # later: the same file? (exit 2 if not)
+```
+
+The fingerprint is the file's size and a SHA-256 of its first and last megabyte (fast
+for any size; nothing is decoded), with the frame count, frame rate and size as OpenCV
+reads them. A re-encode, a cut or a different file under the same name shows up, with
+what changed.
+
+## Licence
+
+MIT (see LICENSE).

trekr-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trekr"
+version = "0.1.0"
+description = "Checks for pose tracking: a window to find and fix label errors in DeepLabCut projects, the GPU against the PyTorch build, whether OpenCV decodes camera video with the right colours, and whether a video file changed."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Koen Freerks" }]
+requires-python = ">=3.10"
+dependencies = ["numpy>=1.26", "opencv-python-headless>=4.8", "PySide6>=6.5", "pyyaml>=6"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Environment :: X11 Applications :: Qt",
+    "Intended Audience :: Science/Research",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Scientific/Engineering",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.scripts]
+trekr = "trekr.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+trekr = ["data/*"]

trekr-0.1.0/setup.cfg

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

trekr-0.1.0/src/trekr/__init__.py

@@ -0,0 +1,3 @@
+"""TREKR, early release: checks for a computer, its video files, and pose labels."""
+
+__version__ = "0.1.0"

trekr-0.1.0/src/trekr/__main__.py

@@ -0,0 +1,5 @@
+"""python -m trekr <command>: see cli.py."""
+
+from .cli import main
+
+raise SystemExit(main())

trekr-0.1.0/src/trekr/cli.py

@@ -0,0 +1,44 @@
+"""
+    trekr check                                is this computer ready for GPU video analysis?
+    trekr videocheck VIDEO [--save REF.json | --against REF.json]
+                                               a video file's fingerprint; is it still the same?
+    trekr labels DLC_PROJECT                   check and edit DeepLabCut labels (a window)
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from . import __version__
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="trekr", description="TREKR (early release): checks for a computer, its "
+                                                           "video files, and pose labels.")
+    ap.add_argument("--version", action="version", version=f"trekr {__version__}")
+    sub = ap.add_subparsers(dest="command", required=True, metavar="command")
+    sub.add_parser("check", help="the GPU against the PyTorch build, the driver, and whether OpenCV decodes camera "
+                                 "video with the right colours")
+    v = sub.add_parser("videocheck", help="a video file's fingerprint (size, SHA-256 of both ends, stream facts); "
+                                          "save it, or compare the file with a saved one")
+    v.add_argument("video")
+    g = v.add_mutually_exclusive_group()
+    g.add_argument("--save", metavar="REF.json", help="write the fingerprint to this file")
+    g.add_argument("--against", metavar="REF.json", help="compare with a saved fingerprint (exit 2 if changed)")
+    lab = sub.add_parser("labels", help="find and fix label errors in a DeepLabCut project: every labelled "
+                                        "animal by how well its points fit together, worst first (a window)")
+    lab.add_argument("project", help="a DeepLabCut project folder (with config.yaml and labeled-data/), or one "
+                                     "labeled-data folder")
+    args = ap.parse_args(argv)
+    if args.command == "labels":
+        from .labels.app import run
+        return run(args.project)
+    if args.command == "check":
+        from . import envcheck
+        return envcheck.run()
+    from . import videocheck
+    return videocheck.run(args.video, save=args.save, against=args.against)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

trekr-0.1.0/src/trekr/envcheck.py

@@ -0,0 +1,174 @@
+"""
+`trekr check`: is this computer ready for GPU video analysis? Every line says
+
+    OK     fine
+    NOTE   works, with a caveat (what, and by how much)
+    FAIL   will not work, or not correctly (why, and what to install)
+
+1. Python, NumPy, OpenCV and (if installed) PyTorch: their versions.
+2. Each GPU against the PyTorch build: a build carries code for some GPU generations
+   only, so a new card (e.g. the RTX 50 series) can need a newer build. And the NVIDIA
+   driver against the CUDA version the build was made for.
+3. Video decoding: a stored H.264 clip encoded as cameras write it (BT.709 colours,
+   TV range) against the frames a correct decoder gives. OpenCV 4.11 and 4.12 decode
+   such video with the wrong colour matrix: on the stored clip red is off by 5.4 and blue
+   by 2.5 grey levels on average, up to 22 (measured 2026-10-07; 4.13 and 5.0 decode it
+   exactly). That shifts every colour measured from the video.
+
+The exit status is 1 when anything fails.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import platform
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+import numpy as np
+
+DATA = Path(__file__).parent / "data"
+CLIP = DATA / "clip.mp4"
+CLIP_EXPECTED = DATA / "clip.expected.npz"
+SAME_PIXELS = 0.5                 # mean grey levels up to which a decoded frame counts as the same
+
+OK, NOTE, FAIL = "OK", "NOTE", "FAIL"
+
+
+def driver():
+    """(the NVIDIA driver's version, the newest CUDA it runs), each None if unknown."""
+    ver = cuda = None
+    try:                                                   # Linux: no program to start
+        m = re.search(r"Kernel Module(?: for \S+)?\s+(\d+(?:\.\d+)+)", Path("/proc/driver/nvidia/version").read_text())
+        ver = m.group(1) if m else None
+    except OSError:
+        pass
+    if ver is None:
+        try:
+            out = subprocess.run(["nvidia-smi", "--query-gpu=driver_version", "--format=csv,noheader"],
+                                 capture_output=True, text=True, timeout=10)
+            ver = (out.stdout.strip().splitlines() or [None])[0]
+        except (OSError, subprocess.SubprocessError):
+            pass
+    try:
+        lib = ctypes.CDLL("nvcuda.dll" if sys.platform == "win32" else "libcuda.so.1")
+        v = ctypes.c_int()
+        if lib.cuDriverGetVersion(ctypes.byref(v)) == 0 and v.value:
+            cuda = f"{v.value // 1000}.{v.value % 1000 // 10}"
+    except (OSError, AttributeError):
+        pass
+    return ver, cuda
+
+
+def arch_support(capability, archs):
+    """How a PyTorch build (its arch list, e.g. ["sm_80", "sm_86", "compute_90"]) runs on a
+    GPU of this compute capability ((8, 9)): "native" (code for it, or for an earlier
+    minor of the same major), "jit" (only PTX of an earlier architecture: compiled when
+    first used), or None (it cannot run there)."""
+    major, minor = capability
+    native = jit = False
+    for a in archs:
+        m = re.fullmatch(r"(sm|compute)_(\d+)(\d)([a-z]?)", a)
+        if not m:
+            continue
+        kind, big, small, suffix = m.group(1), int(m.group(2)), int(m.group(3)), m.group(4)
+        if kind == "sm" and big == major and (small == minor or (small < minor and not suffix)):
+            native = True
+        elif kind == "compute" and not suffix and (big, small) <= (major, minor):
+            jit = True
+    return "native" if native else "jit" if jit else None
+
+
+def _span(archs):
+    sm = sorted((a for a in archs if a.startswith("sm_")), key=lambda a: int(re.sub(r"\D", "", a)))
+    return f"{sm[0]}-{sm[-1]}" if sm else "no GPU"
+
+
+def decoding():
+    """The stored clip as OpenCV decodes it here, against a correct decoder's frames:
+    {"frames" (None: cannot be read), "mean" (per channel, R G B), "max", "opencv", "reference"}."""
+    import cv2
+    e = np.load(CLIP_EXPECTED)
+    out = {"opencv": cv2.__version__, "reference": str(e["opencv"]), "frames": None, "mean": None, "max": None}
+    cap = cv2.VideoCapture(str(CLIP))
+    frames = []
+    try:
+        while len(frames) < len(e["frames"]):
+            ok, f = cap.read()
+            if not ok:
+                break
+            frames.append(cv2.cvtColor(f, cv2.COLOR_BGR2RGB))
+    finally:
+        cap.release()
+    if len(frames) != len(e["frames"]) or any(f.shape != e["frames"][0].shape for f in frames):
+        return out
+    d = np.abs(np.stack(frames).astype(int) - e["frames"].astype(int))
+    out.update(frames=len(frames), mean=d.mean((0, 1, 2)), max=int(d.max()))
+    return out
+
+
+def run(out=None):
+    """Print the check; 0 when nothing fails, else 1."""
+    out = out or sys.stdout
+    fails = []
+
+    def say(level, text):
+        print(f"{level:5s} {text}", file=out)
+        if level == FAIL:
+            fails.append(text)
+
+    import cv2
+    say(OK, f"Python {platform.python_version()}, NumPy {np.__version__}, OpenCV {cv2.__version__}")
+    try:
+        import torch
+    except ImportError:
+        torch = None
+        say(NOTE, "PyTorch is not installed: the GPU check is skipped (pytorch.org, a build for your GPU's CUDA)")
+    if torch is not None:
+        if not torch.cuda.is_available():
+            say(FAIL, f"PyTorch {torch.__version__} sees no GPU it can use (built for "
+                      f"{'CUDA ' + torch.version.cuda if torch.version.cuda else 'the CPU only'})")
+        else:
+            archs = torch.cuda.get_arch_list()
+            for i in range(torch.cuda.device_count()):
+                cap = torch.cuda.get_device_capability(i)
+                name = (f"GPU {i}: {torch.cuda.get_device_name(i)} (sm_{cap[0]}{cap[1]}, "
+                        f"{torch.cuda.get_device_properties(i).total_memory / 2 ** 30:.0f} GB)")
+                how = arch_support(cap, archs)
+                if how == "native":
+                    say(OK, f"{name}; PyTorch {torch.__version__} has code for {_span(archs)}")
+                elif how == "jit":
+                    say(NOTE, f"{name}: this PyTorch has code for {_span(archs)} only; it is compiled for this "
+                              f"GPU when first used (a slow start)")
+                else:
+                    say(FAIL, f"{name}: this PyTorch has code for {_span(archs)} only. Install a PyTorch build "
+                              f"whose architecture list includes sm_{cap[0]}{cap[1]} (pytorch.org; newer GPUs "
+                              f"need builds for newer CUDA)")
+            ver, dcuda = driver()
+            rt = torch.version.cuda
+            if ver is None or dcuda is None or rt is None:
+                say(NOTE, f"NVIDIA driver {ver or 'unknown'}: the CUDA it runs is unknown")
+            else:
+                d, r = tuple(map(int, dcuda.split("."))), tuple(map(int, rt.split(".")))
+                if d[0] < r[0]:
+                    say(FAIL, f"NVIDIA driver {ver} runs CUDA up to {dcuda}; this PyTorch is built for CUDA {rt}: "
+                              f"update the driver, or install a PyTorch build for CUDA {d[0]}")
+                else:
+                    say(OK, f"NVIDIA driver {ver} (CUDA {dcuda}); PyTorch built for CUDA {rt}"
+                            + (" runs on it by CUDA minor-version compatibility" if d < r else ""))
+    dec = decoding()
+    if dec["frames"] is None:
+        say(FAIL, f"OpenCV {dec['opencv']} cannot decode H.264 video (the stored test clip): install "
+                  f"opencv-python-headless from PyPI, which brings its own decoder")
+    elif dec["mean"].max() <= SAME_PIXELS:
+        say(OK, f"OpenCV {dec['opencv']} decodes camera video (H.264, BT.709) with the right colours")
+    else:
+        m = dec["mean"]
+        say(FAIL, f"OpenCV {dec['opencv']} decodes camera video (H.264 tagged BT.709) with other colours than a "
+                  f"correct decoder (OpenCV {dec['reference']}): R {m[0]:.1f}, G {m[1]:.1f}, B {m[2]:.1f} grey "
+                  f"levels off on average, up to {dec['max']}. OpenCV 4.11 and 4.12 apply the wrong colour "
+                  f"matrix; use 4.13 or newer")
+    print(f"\nNot ready: {len(fails)} problem(s) above (FAIL)." if fails else "\nReady.", file=out)
+    return 1 if fails else 0

trekr-0.1.0/src/trekr/labels/__init__.py

@@ -0,0 +1 @@
+"""`trekr labels`: find and fix label errors in a DeepLabCut project."""