feabas-workbench 0.3.2__py3-none-any.whl

feabas_workbench/__init__.py

@@ -0,0 +1,9 @@
+"""FEABAS Workbench: a desktop front end around FEABAS for serial-section EM."""
+
+__version__ = "0.3.2"
+APP_NAME = "FEABAS Workbench"
+ORG_NAME = "FeabasWorkbench"
+WORKBENCH_REPO = "https://github.com/georgkislinger/feabas-workbench"
+FEABAS_REPO = "https://github.com/YuelongWu/feabas"
+# Wu, Y. & Lichtman, J. W. (2026). FEABAS: A Stitching and Alignment Tool for Serial EM Data. bioRxiv.
+FEABAS_PAPER = "https://doi.org/10.64898/2026.06.07.730510"

feabas_workbench/__main__.py

@@ -0,0 +1,4 @@
+from feabas_workbench.app import main
+
+if __name__ == "__main__":
+    main()

feabas_workbench/app.py

@@ -0,0 +1,165 @@
+"""Application entry point."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import traceback
+from pathlib import Path
+
+
+def _excepthook_factory(window_getter):
+    def hook(exc_type, exc, tb):
+        text = "".join(traceback.format_exception(exc_type, exc, tb))
+        sys.__stderr__.write(text)
+        try:
+            w = window_getter()
+            if w is not None:
+                w.ctx.log("Unhandled error:\n" + text, "error")
+                from PySide6.QtWidgets import QMessageBox
+                QMessageBox.critical(w, "Unexpected error", text[-2000:])
+        except Exception:  # noqa: BLE001
+            pass
+    return hook
+
+
+def selfcheck(out: Path) -> int:
+    """
+    Verify the installation without opening a window and write a JSON report: package root,
+    vendored FEABAS scripts and configs, the bundled fold checkpoint, and that the worker
+    package can be staged for the other interpreters. For CI on the frozen build and for
+    bug reports. Exit code 0 when everything is in place.
+    """
+    import json
+    from . import __version__
+    from .core.jobs import package_root, worker_package_root, WORKER_PACKAGE_PARTS
+    from .core.masks import bundled_fold_checkpoint
+    from .core.project import VENDOR_DIR, DEFAULT_CONFIG_NAMES
+    from .core.envs import Settings, settings_dir
+    rep: dict = {"version": __version__, "frozen": bool(getattr(sys, "frozen", False)), "python": sys.executable,
+                 "package_root": str(package_root()), "settings_dir": str(settings_dir()), "problems": []}
+    for name in ("scripts/stitch_main.py", "scripts/thumbnail_main.py", "scripts/align_main.py"):
+        if not (VENDOR_DIR / name).is_file():
+            rep["problems"].append(f"vendored FEABAS script missing: {VENDOR_DIR / name}")
+    for name in DEFAULT_CONFIG_NAMES:
+        if not (VENDOR_DIR / "configs" / name).is_file():
+            rep["problems"].append(f"vendored default config missing: {name}")
+    if not (VENDOR_DIR.parent / "winfix" / "sitecustomize.py").is_file():
+        rep["problems"].append("vendor/winfix/sitecustomize.py missing (FEABAS run-time fixes)")
+    ck = bundled_fold_checkpoint()
+    rep["fold_checkpoint"] = str(ck)
+    if not ck.is_file():
+        rep["problems"].append(f"bundled fold checkpoint missing: {ck}")
+    try:
+        staged = worker_package_root() / "feabas_workbench"
+        rep["worker_package"] = str(staged)
+        missing = [part for part in WORKER_PACKAGE_PARTS if not (staged / part).exists()]
+        if missing:
+            rep["problems"].append(f"worker package staging incomplete, missing {missing}")
+        if not (staged / "workers" / "fold_predict.py").is_file():
+            rep["problems"].append("worker package has no workers/fold_predict.py")
+    except Exception as e:  # noqa: BLE001
+        rep["problems"].append(f"worker package staging failed: {e}")
+    try:
+        s = Settings.load()
+        rep["settings"] = {"feabas_python": s.feabas_python, "dl_python": s.dl_python}
+    except Exception as e:  # noqa: BLE001
+        rep["problems"].append(f"settings unreadable: {e}")
+    rep["ok"] = not rep["problems"]
+    out = Path(out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(rep, indent=2), encoding="utf-8")
+    return 0 if rep["ok"] else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="feabas-workbench")
+    ap.add_argument("--project", help="project folder to open")
+    ap.add_argument("--page", type=int, default=None, help="page index to show")
+    ap.add_argument("--screenshot", help="render every page to PNG files in this folder and exit (debug)")
+    ap.add_argument("--offscreen", action="store_true", help="use the offscreen Qt platform (debug)")
+    ap.add_argument("--selfcheck", metavar="REPORT.json",
+                    help="verify the installation (vendored FEABAS, checkpoint, worker staging) without opening a "
+                         "window, write a JSON report and exit 0/1")
+    args = ap.parse_args(argv)
+
+    if args.selfcheck:
+        return selfcheck(Path(args.selfcheck))
+
+    if args.offscreen or args.screenshot:
+        os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
+    os.environ.setdefault("QT_ENABLE_HIGHDPI_SCALING", "1")
+
+    from PySide6.QtWidgets import QApplication
+    from PySide6.QtCore import QTimer
+    from . import APP_NAME, ORG_NAME
+    from .ui.theme import QSS
+    from .ui.main_window import MainWindow
+    from .core.envs import Settings
+
+    app = QApplication(sys.argv[:1])
+    app.setApplicationName(APP_NAME)
+    app.setOrganizationName(ORG_NAME)
+    app.setStyle("Fusion")
+    app.setStyleSheet(QSS)
+
+    settings = Settings.load()
+    holder = {"w": None}
+    prev_excepthook = sys.excepthook
+    sys.excepthook = _excepthook_factory(lambda: holder["w"])
+    win = MainWindow(settings)
+    holder["w"] = win
+    win.resize(1500, 950)
+    win.show()
+    # Never open larger than the screen: a laptop panel (often HiDPI, so a small logical
+    # size) can be narrower than 1500 px, and a window wider than its screen pushes the
+    # right-hand controls out of reach. Only after show() does win.screen() report the
+    # screen the window actually landed on, so shrink here and only when it is needed -
+    # on a large monitor the full size is kept. The offscreen platform reports an
+    # arbitrary 800x800 virtual screen, so leave --screenshot alone there.
+    if app.platformName() != "offscreen":
+        avail = win.screen().availableGeometry()
+        if win.width() > avail.width() or win.height() > avail.height():
+            win.resize(min(win.width(), avail.width()), min(win.height(), avail.height()))
+
+    if args.project:
+        win.open_project(Path(args.project))
+    if args.page is not None:
+        win.show_page(args.page)
+
+    if args.screenshot:
+        out = Path(args.screenshot)
+        out.mkdir(parents=True, exist_ok=True)
+
+        def shoot():
+            for i in range(win.page_count()):
+                win.show_page(i)
+                app.processEvents()
+                win.grab().save(str(out / f"page{i}.png"))
+            app.quit()
+
+        QTimer.singleShot(1500, shoot)
+
+    code = app.exec()
+
+    # Teardown, in this order:
+    # 1. Pages start QThreads (environment probing, tile scanning). Qt aborts the process
+    #    if one is still running when it is destroyed. closeEvent does not fire when the
+    #    app quits without the window being closed (--screenshot), so stop them here.
+    win.shutdown()
+    # 2. Drop every reference that would outlive `app`. The excepthook closes over
+    #    `holder`, so leaving it installed keeps the window alive past the end of this
+    #    function - and a widget destroyed after its QApplication crashes the process.
+    sys.excepthook = prev_excepthook
+    holder["w"] = None
+    # 3. Destroy the window while the QApplication is still there.
+    win.close()
+    win.deleteLater()
+    app.processEvents()
+    win = None
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

feabas_workbench/core/__init__.py

@@ -0,0 +1 @@
+"""Qt-free core: project model, tile discovery, configs, pipeline state, jobs."""

feabas_workbench/core/configs.py

@@ -0,0 +1,332 @@
+"""
+FEABAS YAML configuration handling.
+
+FEABAS merges ``default_<name>.yaml`` (from its default configuration folder)
+with ``<workdir>/configs/<name>.yaml`` (user overrides, may be partial). This
+module gives the GUI one merged view, tracks which keys are overridden, saves
+back only the differences, and harvests the inline comments of the default
+files as per-key hints so the settings editor can explain every field.
+"""
+
+from __future__ import annotations
+
+import copy
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+CONFIG_FILES = {
+    "stitching": "stitching_configs.yaml",
+    "thumbnail": "thumbnail_configs.yaml",
+    "alignment": "alignment_configs.yaml",
+    "material": "material_table.yaml",
+}
+
+
+class ConfigError(RuntimeError):
+    pass
+
+
+# ----------------------------------------------------------------------
+# yaml helpers
+# ----------------------------------------------------------------------
+
+def load_yaml(path: Path) -> dict:
+    path = Path(path)
+    if not path.is_file():
+        return {}
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as e:
+        raise ConfigError(f"{path.name}: {e}") from e
+    return data if isinstance(data, dict) else {}
+
+
+def dump_yaml(path: Path, data: dict, header: str | None = None) -> None:
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    text = yaml.safe_dump(data, sort_keys=False, default_flow_style=None, allow_unicode=True)
+    if header:
+        text = "".join(f"# {ln}\n" for ln in header.splitlines()) + text
+    path.write_text(text, encoding="utf-8")
+
+
+def deep_merge(base: dict, over: dict) -> dict:
+    out = copy.deepcopy(base)
+    for k, v in (over or {}).items():
+        if isinstance(v, dict) and isinstance(out.get(k), dict):
+            out[k] = deep_merge(out[k], v)
+        else:
+            out[k] = copy.deepcopy(v)
+    return out
+
+
+def deep_diff(base: dict, current: dict) -> dict:
+    """Keys in *current* that differ from *base* (nested)."""
+    out: dict = {}
+    for k, v in current.items():
+        if k not in base:
+            out[k] = copy.deepcopy(v)
+        elif isinstance(v, dict) and isinstance(base[k], dict):
+            sub = deep_diff(base[k], v)
+            if sub:
+                out[k] = sub
+        elif v != base[k]:
+            out[k] = copy.deepcopy(v)
+    return out
+
+
+def flatten(data: dict, prefix: str = "") -> list[tuple[str, Any]]:
+    out = []
+    for k, v in data.items():
+        key = f"{prefix}.{k}" if prefix else str(k)
+        if isinstance(v, dict):
+            out.extend(flatten(v, key))
+        else:
+            out.append((key, v))
+    return out
+
+
+def get_dotted(data: dict, dotted: str, default=None):
+    cur = data
+    for part in dotted.split("."):
+        if not isinstance(cur, dict) or part not in cur:
+            return default
+        cur = cur[part]
+    return cur
+
+
+def set_dotted(data: dict, dotted: str, value) -> None:
+    parts = dotted.split(".")
+    cur = data
+    for p in parts[:-1]:
+        if not isinstance(cur.get(p), dict):
+            cur[p] = {}
+        cur = cur[p]
+    cur[parts[-1]] = value
+
+
+def del_dotted(data: dict, dotted: str) -> None:
+    parts = dotted.split(".")
+    cur = data
+    stack = []
+    for p in parts[:-1]:
+        if not isinstance(cur, dict) or p not in cur:
+            return
+        stack.append((cur, p))
+        cur = cur[p]
+    if isinstance(cur, dict):
+        cur.pop(parts[-1], None)
+    # prune empty parents
+    for parent, key in reversed(stack):
+        if isinstance(parent.get(key), dict) and not parent[key]:
+            del parent[key]
+
+
+# ----------------------------------------------------------------------
+# hints from comments in the default yaml files
+# ----------------------------------------------------------------------
+
+def harvest_hints(path: Path) -> dict[str, str]:
+    """Map dotted key -> inline/preceding comment from a YAML file."""
+    hints: dict[str, str] = {}
+    if not Path(path).is_file():
+        return hints
+    stack: list[tuple[int, str]] = []   # (indent, key)
+    pending: list[str] = []
+    for raw in Path(path).read_text(encoding="utf-8").splitlines():
+        if not raw.strip():
+            pending = []
+            continue
+        stripped = raw.lstrip()
+        indent = len(raw) - len(stripped)
+        if stripped.startswith("#"):
+            pending.append(stripped.lstrip("#").strip())
+            continue
+        m = re.match(r"([A-Za-z0-9_\-]+)\s*:\s*(.*)$", stripped)
+        if not m:
+            continue
+        key, rest = m.group(1), m.group(2)
+        while stack and stack[-1][0] >= indent:
+            stack.pop()
+        dotted = ".".join([k for _, k in stack] + [key])
+        comment = ""
+        if "#" in rest:
+            comment = rest.split("#", 1)[1].strip()
+        text = " ".join([c for c in pending if c] + ([comment] if comment else []))
+        if text:
+            hints[dotted] = text
+        pending = []
+        stack.append((indent, key))
+    return hints
+
+
+# curated hints for keys whose default comments are terse or missing
+EXTRA_HINTS = {
+    "stitching.section_thickness": "Section thickness in nm. Used to pick working mip levels so xy resolution is close to z.",
+    "stitching.matching.num_workers": "Parallel processes for tile matching. Each caches images; lower if RAM is tight.",
+    "stitching.rendering.driver": "'image' writes PNG tiles per section (simple, VAST-friendly); 'neuroglancer_precomputed' writes a TensorStore volume (faster downstream).",
+    "stitching.rendering.loader_settings.apply_CLAHE": "Contrast-limited histogram equalisation during rendering. Usually leave on; turn off if you did your own histogram matching and want the raw look.",
+    "stitching.rendering.loader_settings.inverse": "Invert grey values while rendering (BSE images are often acquired inverted).",
+    "thumbnail.thumbnail_mip_level": "Mip level of thumbnails (each level halves resolution). Aim for roughly 500-2000 px thumbnails; larger ones make coarse matching very slow.",
+    "thumbnail.downsample.thumbnail_highpass": "High-pass before downsampling to enhance somata. Rule of thumb: on for SE images, off for BSE images or very small mip levels.",
+    "thumbnail.alignment.compare_distance": "How many neighbouring sections to match (1 = immediate neighbours only). 2 makes the stack more robust to a bad section.",
+    "alignment.matching.working_mip_level": "Resolution for fine matching. Pick the mip whose xy pixel size is closest to the section thickness.",
+    "alignment.meshing.mesh_size": "Mesh spacing at mip0 pixels. Finer meshes follow local distortions but can overfit real z change.",
+    "alignment.meshing.mask_mip_level": "Mip level of the masks in align/material_masks (the fold/tissue masks written by the Masks step).",
+    "alignment.optimization.chunk_settings.chunked_to_depth": "0 = sliding window over the whole stack; >0 = align chunks first, then chunks against each other.",
+    "alignment.rendering.tile_size": "Output tile size (px) for PNG rendering. 4096 is fine for VAST.",
+    "alignment.tensorstore_rendering.driver": "Neuroglancer precomputed is the recommended big-data output.",
+}
+
+
+# ----------------------------------------------------------------------
+# config store
+# ----------------------------------------------------------------------
+
+@dataclass
+class ConfigDoc:
+    kind: str                      # stitching | thumbnail | alignment | material
+    default_path: Path
+    user_path: Path
+    defaults: dict = field(default_factory=dict)
+    overrides: dict = field(default_factory=dict)
+    hints: dict = field(default_factory=dict)
+
+    @property
+    def merged(self) -> dict:
+        return deep_merge(self.defaults, self.overrides)
+
+    def is_overridden(self, dotted: str) -> bool:
+        return get_dotted(self.overrides, dotted, _MISSING) is not _MISSING
+
+    def set(self, dotted: str, value) -> None:
+        if value == get_dotted(self.defaults, dotted, _MISSING):
+            del_dotted(self.overrides, dotted)
+        else:
+            set_dotted(self.overrides, dotted, value)
+
+    def reset(self, dotted: str) -> None:
+        del_dotted(self.overrides, dotted)
+
+    def hint(self, dotted: str) -> str:
+        return EXTRA_HINTS.get(f"{self.kind}.{dotted}") or self.hints.get(dotted, "")
+
+
+_MISSING = object()
+
+
+class ConfigStore:
+    """All four FEABAS config documents of a project."""
+
+    def __init__(self, configs_dir: Path):
+        self.configs_dir = Path(configs_dir)
+        self.docs: dict[str, ConfigDoc] = {}
+        self.reload()
+
+    def reload(self) -> None:
+        self.docs = {}
+        for kind, name in CONFIG_FILES.items():
+            dpath = self.configs_dir / f"default_{name}"
+            upath = self.configs_dir / name
+            doc = ConfigDoc(kind, dpath, upath)
+            doc.defaults = load_yaml(dpath)
+            doc.overrides = load_yaml(upath)
+            doc.hints = harvest_hints(dpath)
+            self.docs[kind] = doc
+
+    def __getitem__(self, kind: str) -> ConfigDoc:
+        return self.docs[kind]
+
+    def save(self, kind: str | None = None) -> None:
+        for k, doc in self.docs.items():
+            if kind and k != kind:
+                continue
+            if doc.overrides:
+                dump_yaml(doc.user_path, doc.overrides,
+                          header=f"Project overrides for {doc.default_path.name}; unspecified keys use the defaults.")
+            elif doc.user_path.is_file():
+                doc.user_path.unlink()
+
+    def get(self, kind: str, dotted: str, default=None):
+        return get_dotted(self.docs[kind].merged, dotted, default)
+
+    def set(self, kind: str, dotted: str, value) -> None:
+        self.docs[kind].set(dotted, value)
+
+    def modified_time(self, kind: str) -> float:
+        p = self.docs[kind].user_path
+        return p.stat().st_mtime if p.is_file() else 0.0
+
+
+# ----------------------------------------------------------------------
+# convenience: resolutions and mips
+# ----------------------------------------------------------------------
+
+def mip_resolution(pixel_size_nm: float, mip: int) -> float:
+    return float(pixel_size_nm) * (2 ** int(mip))
+
+
+def suggest_working_mip(pixel_size_nm: float, section_thickness_nm: float) -> int:
+    """FEABAS rule: mip whose xy resolution is closest to (but not above) the section thickness."""
+    import math
+    if pixel_size_nm <= 0 or section_thickness_nm <= 0:
+        return 2
+    return max(0, int(math.floor(math.log2(section_thickness_nm / pixel_size_nm))))
+
+
+def suggest_thumbnail_mip(section_w_px: float, section_h_px: float, target_px: float = 1000.0) -> int:
+    """Mip level that brings the longer section side to about target_px."""
+    import math
+    longest = max(float(section_w_px), float(section_h_px), 1.0)
+    return max(0, int(round(math.log2(longest / target_px))))
+
+
+def set_thumbnail_mip(cs: "ConfigStore", mip: int, highpass: bool | None = None) -> bool:
+    """
+    Set the thumbnail mip level (and the mask mip level that goes with it) consistently.
+
+    FEABAS builds high-pass filtered thumbnails from a coarser intermediate mip level and asserts
+    that this level is *below* the thumbnail mip (``highpass_inter_mip_lvl < thumbnail_mip_lvl``).
+    At mip 0 no such level exists and the thumbnail step dies with an AssertionError, so the
+    high-pass is switched off there. Returns True when it had to be switched off.
+    """
+    mip = int(mip)
+    cs.set("thumbnail", "thumbnail_mip_level", mip)
+    cs.set("alignment", "meshing.mask_mip_level", mip)
+    if highpass is None:
+        highpass = bool(cs.get("thumbnail", "downsample.thumbnail_highpass", True))
+    forced_off = mip <= 0 and highpass
+    cs.set("thumbnail", "downsample.thumbnail_highpass", False if forced_off else bool(highpass))
+    return forced_off
+
+
+def parse_value(text: str, like):
+    """Parse an edited string using the type of the current value."""
+    t = text.strip()
+    if isinstance(like, bool):
+        return t.lower() in ("1", "true", "yes", "on")
+    if like is None:
+        if t.lower() in ("", "null", "none", "~"):
+            return None
+        return yaml.safe_load(t)
+    if isinstance(like, int) and not isinstance(like, bool):
+        try:
+            return int(t)
+        except ValueError:
+            return yaml.safe_load(t)
+    if isinstance(like, float):
+        try:
+            return float(t)
+        except ValueError:
+            return yaml.safe_load(t)
+    if isinstance(like, (list, tuple, dict)):
+        return yaml.safe_load(t)
+    # a string-valued key keeps strings: 'NONE' is a real FEABAS value (e.g. the
+    # rendering blend mode), so only the YAML null spellings clear such a key.
+    if t.lower() in ("null", "~"):
+        return None
+    return t