tofscope 0.1.0__py3-none-any.whl

tofscope/application/signals.py

@@ -0,0 +1,74 @@
+"""Signal identity and view invariants, independent of readers and renderers."""
+from dataclasses import replace
+from tofscope.application.commands import AllDepth, SingleFrame, DepthWindow
+
+
+def valid_name(value):
+    value = value.strip()
+    if not 1 <= len(value) <= 128:
+        raise ValueError('Signal name must contain 1–128 characters.')
+    return value
+
+
+def get_signal(snapshot, signal_id):
+    for signal in snapshot.signals:
+        if signal.id == signal_id:
+            return signal
+    raise ValueError('Signal unavailable.')
+
+
+def image_signal(snapshot):
+    return get_signal(snapshot, snapshot.image_signal_id)
+
+
+def visible_signals(snapshot):
+    ids = set(snapshot.profile_signal_ids) | {snapshot.image_signal_id}
+    return tuple(sorted((s for s in snapshot.signals if s.id in ids and s.recipe is not None),
+                        key=lambda s: (s.id != snapshot.image_signal_id, s.style_index)))
+
+
+def usable_frames(snapshot, signal):
+    if signal.recipe is None:
+        return None
+    low = max(0, signal.recipe.frames[0])
+    high = min(snapshot.shape[0] - 1, signal.recipe.frames[1])
+    return (low, high) if low <= high else None
+
+
+def image_frames(snapshot):
+    bounds = usable_frames(snapshot, image_signal(snapshot))
+    if bounds is None:
+        raise ValueError('Image signal has no coverage in the acquisition.')
+    depth = snapshot.depth
+    if depth.mode == 'all':
+        return bounds
+    requested = (depth.index, depth.index) if depth.mode == 'frame' else (depth.first, depth.last)
+    low, high = max(bounds[0], requested[0]), min(bounds[1], requested[1])
+    return (low, high) if low <= high else (bounds[0], bounds[0])
+
+
+def normalize_view(snapshot):
+    if usable_frames(snapshot, image_signal(snapshot)) is None:
+        candidates = [s for s in snapshot.signals if usable_frames(snapshot, s)]
+        if not candidates:
+            raise ValueError('At least one ready signal must cover the acquisition.')
+        snapshot = replace(snapshot, image_signal_id=candidates[0].id)
+    low, high = image_frames(snapshot)
+    depth = snapshot.depth
+    if depth.mode == 'frame':
+        depth = SingleFrame(mode='frame', index=low)
+    elif depth.mode == 'window':
+        depth = DepthWindow(mode='window', first=low, last=high)
+    ids = tuple(dict.fromkeys((*snapshot.profile_signal_ids, snapshot.image_signal_id)))
+    return replace(snapshot, depth=depth, profile_signal_ids=ids)
+
+
+def signal_label(snapshot, signal):
+    recipe = signal.recipe
+    name = signal.name
+    if sum(r.name == name for r in snapshot.signals) > 1:
+        name += f' [{signal.id[:8]}]'
+    if recipe is None:
+        return name
+    source = 'stored' if recipe.source == 'stored' else 'raw'
+    return f'{name} · {source} · frames {recipe.frames[0]}–{recipe.frames[1]}'

tofscope/application/spatial.py

@@ -0,0 +1,78 @@
+"""Validated, durable spatial display state; numerical recipes remain signals."""
+
+from typing import Annotated, Literal
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    StrictBool,
+    StrictInt,
+    model_validator,
+)
+
+Number = Annotated[float, Field(strict=True, allow_inf_nan=False)]
+
+
+class SpatialModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class Vector(SpatialModel):
+    x: Number
+    y: Number
+    z: Number
+
+
+class Camera(SpatialModel):
+    eye: Vector = Vector(x=1.25, y=1.25, z=1.25)
+    center: Vector = Vector(x=0.0, y=0.0, z=0.0)
+    up: Vector = Vector(x=0.0, y=0.0, z=1.0)
+    projection: Literal["perspective", "orthographic"] = "perspective"
+
+    @model_validator(mode="after")
+    def nondegenerate(self):
+        if sum(v * v for v in (self.up.x, self.up.y, self.up.z)) < 1e-12:
+            raise ValueError("Camera up vector must be nonzero.")
+        if sum(v * v for v in (self.eye.x, self.eye.y, self.eye.z)) < 1e-12:
+            raise ValueError("Camera eye must be nonzero.")
+        return self
+
+
+class SpatialLayer(SpatialModel):
+    signal_id: str = Field(min_length=1, max_length=128)
+    visible: StrictBool = True
+    colorscale: Literal[
+        "Viridis", "Magma", "Plasma", "Cividis", "Reds", "Blues", "Greens", "Purples"
+    ] = "Viridis"
+    colorscale_reversed: StrictBool = False
+    opacity: Number = Field(default=0.12, ge=0, le=1)
+    percentile: Number = Field(default=70.0, ge=0, le=100)
+    camera: Camera = Camera()
+
+
+class SpatialView(SpatialModel):
+    screen: Literal["explore", "volume"] = "explore"
+    layers: tuple[SpatialLayer, ...] = Field(default=(), max_length=129)
+    mode: Literal["overlay", "tiles"] = "overlay"
+    quality: Literal["Fast", "Detailed"] = "Fast"
+    scale: Literal["independent", "shared"] = "independent"
+    linked: StrictBool = True
+    camera: Camera = Camera()
+    solo: str | None = Field(default=None, max_length=128)
+    page: StrictInt = Field(default=0, ge=0, le=128)
+    frame_stretch: Number = Field(default=1.2, ge=0.01, le=1000)
+    depth_exaggeration: Number = Field(default=1.0, ge=0.01, le=1000)
+
+    @model_validator(mode="after")
+    def references(self):
+        ids = [x.signal_id for x in self.layers]
+        if len(ids) != len(set(ids)) or self.solo is not None and self.solo not in ids:
+            raise ValueError("Invalid spatial layer references.")
+        return self
+
+
+def validate_spatial(spatial, signals):
+    ready = {s.id for s in signals if s.recipe is not None}
+    if not {x.signal_id for x in spatial.layers} <= ready:
+        raise ValueError("Spatial layers must reference ready named signals.")
+    return spatial

tofscope/cli.py

@@ -0,0 +1,157 @@
+"""One Python service/port, loopback by default; Node is build-time only."""
+
+import argparse
+from dataclasses import asdict
+import hashlib
+from importlib.resources import files
+import json
+import os
+from pathlib import Path
+import secrets
+import socket
+import sys
+import threading
+import time
+import urllib.request
+import webbrowser
+import uvicorn
+from tofscope import __version__
+from tofscope.api.app import create_app
+from tofscope.config import load_settings
+
+
+def asset_status():
+    root = files("tofscope").joinpath("static")
+    manifest = root.joinpath("manifest.json")
+    if not manifest.is_file():
+        raise ValueError(
+            "Frontend assets are missing. Run scripts/build_frontend.py before packaging."
+        )
+    value = json.loads(manifest.read_text())
+    for name, digest in value["assets"].items():
+        if hashlib.sha256(root.joinpath(name).read_bytes()).hexdigest() != digest:
+            raise ValueError("Frontend assets failed integrity verification.")
+    return value
+
+
+def open_after_ready(url, secret, stop):
+    deadline = time.monotonic() + 30
+    while not stop.is_set() and time.monotonic() < deadline:
+        try:
+            with urllib.request.urlopen(url + "/readyz", timeout=0.5) as response:
+                if response.status == 200:
+                    webbrowser.open(url + "/#bootstrap=" + secret)
+                    return
+        except OSError:
+            pass
+        stop.wait(0.1)
+
+
+def run_service(settings, browser=False):
+    asset_status()
+    secret = secrets.token_urlsafe(32)
+    url = settings.public_origin or f"http://{settings.host}:{settings.port}"
+    # Bind first so occupied ports fail before browser startup or credentials change.
+    sock = socket.socket(
+        socket.AF_INET6 if ":" in settings.host else socket.AF_INET, socket.SOCK_STREAM
+    )
+    try:
+        sock.bind((settings.host, settings.port))
+        sock.listen(128)
+    except OSError:
+        sock.close()
+        raise ValueError("Port is unavailable; select another --port.") from None
+    secret_file = settings.runtime_dir / "launch.json"
+    stop = threading.Event()
+    if settings.mode == "local":
+        descriptor = os.open(secret_file, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        os.fchmod(descriptor, 0o600)
+        with os.fdopen(descriptor, "w") as out:
+            json.dump({"url": url, "secret": secret}, out)
+    if browser and settings.mode == "local":
+        threading.Thread(
+            target=open_after_ready, args=(url, secret, stop), daemon=True
+        ).start()
+    try:
+        print(f"ToFScope Explore {__version__}: {url} (original acquisitions read only)", flush=True)
+        uvicorn.Server(
+            uvicorn.Config(
+                create_app(settings, bootstrap_secret=secret),
+                host=settings.host,
+                port=settings.port,
+                workers=1,
+                limit_concurrency=64,
+                proxy_headers=False,
+                access_log=False,
+            )
+        ).run(sockets=[sock])
+    finally:
+        stop.set()
+        sock.close()
+        if settings.mode == "local":
+            secret_file.unlink(missing_ok=True)
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(description="ToFScope Explore; original acquisitions are read only")
+    p.add_argument(
+        "command", nargs="?", choices=["serve", "doctor", "open"], default="serve"
+    )
+    p.add_argument("--config", type=Path)
+    p.add_argument("--data-root", type=Path)
+    p.add_argument("--runtime-dir", type=Path)
+    p.add_argument("--lock-dir", type=Path)
+    p.add_argument("--output-root", type=Path)
+    p.add_argument("--host")
+    p.add_argument("--port", type=int)
+    p.add_argument("--mode", choices=["local", "proxy"])
+    p.add_argument("--no-browser", action="store_true")
+    p.add_argument("--version", action="version", version=__version__)
+    a = p.parse_args(argv)
+    try:
+        settings = load_settings(
+            a.config,
+            cli={
+                k: getattr(a, k)
+                for k in (
+                    "data_root",
+                    "runtime_dir",
+                    "lock_dir",
+                    "output_root",
+                    "host",
+                    "port",
+                    "mode",
+                )
+            },
+        )
+        if a.command == "doctor":
+            assets = asset_status()
+            public = asdict(settings)
+            public.update(
+                version=__version__,
+                asset_version=assets["version"],
+                scope="Explore-only",
+                writes_available=False,
+                save_copies_available=True,
+                notes="Managed array budget excludes Python/HDF5/browser allocator overhead; one API process.",
+            )
+            print(json.dumps(public, default=str, indent=2))
+            return 0
+        if a.command == "open":
+            credential = json.loads((settings.runtime_dir / "launch.json").read_text())
+            webbrowser.open(credential["url"] + "/#bootstrap=" + credential["secret"])
+            return 0
+        # An explicit service command is browser-free; the default launch opens a browser.
+        explicit_serve = bool(
+            (argv if argv is not None else sys.argv[1:])
+            and (argv if argv is not None else sys.argv[1:])[0] == "serve"
+        )
+        run_service(settings, browser=not a.no_browser and not explicit_serve)
+        return 0
+    except (ValueError, OSError) as exc:
+        print(f"ToFScope: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tofscope/config.py

@@ -0,0 +1,139 @@
+"""Server-owned root, runtime and resource policy. CLI > environment > TOML."""
+
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+import os
+import tempfile
+import tomllib
+from typing import Mapping
+
+
+@dataclass(frozen=True)
+class Settings:
+    data_root: Path = field(default_factory=lambda: Path.cwd())
+    runtime_dir: Path = field(
+        default_factory=lambda: Path(tempfile.gettempdir()) / f"tofscope-{os.getuid()}"
+    )
+    lock_dir: Path | None = None
+    output_root: Path | None = None
+    mode: str = "local"
+    host: str = "127.0.0.1"
+    port: int = 8765
+    allow_writes: bool = False
+    allow_unverified_native: bool = False
+    initial_file: Path | None = None
+    trusted_proxies: tuple[str, ...] = ()
+    identity_header: str = "x-tofscope-user"
+    public_origin: str | None = None
+    global_bytes: int = 4 * 1024**3
+    user_bytes: int = 2 * 1024**3
+    analysis_bytes: int = 1024**3
+    response_bytes: int = 32 * 1024**2
+    analyses_per_user: int = 8
+    analyses_global: int = 32
+    jobs_per_analysis: int = 4
+    jobs_per_user: int = 8
+    jobs_global: int = 32
+    signals_per_analysis: int = 129
+    signals_per_user: int = 512
+    signals_global: int = 2048
+    workers: int = 2
+    lease_seconds: int = 45
+    reconnect_seconds: int = 120
+    idle_seconds: int = 900
+
+    def __post_init__(self):
+        root = Path(self.data_root).expanduser().resolve()
+        if not root.is_dir() or not os.access(root, os.R_OK | os.X_OK):
+            raise ValueError("Data root must be an accessible directory.")
+        object.__setattr__(self, "data_root", root)
+        runtime = Path(self.runtime_dir).expanduser().resolve()
+        runtime.mkdir(parents=True, exist_ok=True, mode=0o700)
+        lock = (
+            Path(self.lock_dir).expanduser().resolve()
+            if self.lock_dir
+            else runtime / "locks"
+        )
+        lock.mkdir(parents=True, exist_ok=True, mode=0o700)
+        if not os.access(runtime, os.W_OK) or not os.access(lock, os.W_OK):
+            raise ValueError("Runtime and lock directories must be writable.")
+        object.__setattr__(self, "runtime_dir", runtime)
+        output = Path(self.output_root).expanduser().resolve() if self.output_root else root
+        object.__setattr__(self, "output_root", output)
+        object.__setattr__(self, "lock_dir", lock)
+        if self.mode not in ("local", "proxy"):
+            raise ValueError("Mode must be local or proxy.")
+        if self.mode == "local" and self.host not in ("127.0.0.1", "::1", "localhost"):
+            raise ValueError("Local mode requires loopback binding.")
+        if self.mode == "proxy" and not self.trusted_proxies:
+            raise ValueError("Proxy mode requires trusted proxy addresses.")
+        for f in fields(self):
+            if f.type is bool and type(getattr(self, f.name)) is not bool:
+                raise ValueError(f"{f.name} must be true or false.")
+            if f.type is int and (
+                type(getattr(self, f.name)) is not int or getattr(self, f.name) <= 0
+            ):
+                raise ValueError(f"{f.name} must be a positive integer.")
+        if self.initial_file is not None:
+            p = Path(self.initial_file)
+            p = p if p.is_absolute() else root / p
+            if not p.resolve().is_relative_to(root):
+                raise ValueError("Initial acquisition must be inside data root.")
+            object.__setattr__(self, "initial_file", p.resolve())
+
+
+# Storage validators use the policy fields directly; no alternate launcher defaults.
+
+
+def load_settings(file=None, env: Mapping[str, str] | None = None, cli=None):
+    env = os.environ if env is None else env
+    values = {}
+    if file:
+        with Path(file).open("rb") as stream:
+            values = tomllib.load(stream).get("tofscope", {})
+    for f in fields(Settings):
+        key = "TOFSCOPE_" + f.name.upper()
+        if key in env:
+            v = env[key]
+            if f.type is bool:
+                if v.lower() not in ("true", "false"):
+                    raise ValueError(f"{key} must be true or false.")
+                v = v.lower() == "true"
+            elif f.type is int:
+                v = int(v)
+            elif f.name == "trusted_proxies":
+                v = tuple(x.strip() for x in v.split(",") if x.strip())
+            values[f.name] = v
+    if "TOF_FILE" in env:
+        values["initial_file"] = env["TOF_FILE"]
+    values.update({k: v for k, v in (cli or {}).items() if v is not None})
+    return Settings(**values)
+
+
+def resolve_data_path(settings, relative_path, *, require_file=False):
+    if not isinstance(relative_path, str) or "\x00" in relative_path:
+        raise ValueError("A root-relative path is required.")
+    p = Path(relative_path)
+    if p.is_absolute() or ".." in p.parts:
+        raise ValueError("Path must stay within data root.")
+    try:
+        target = (settings.data_root / p).resolve()
+    except RuntimeError:
+        raise ValueError("Invalid symbolic link.") from None
+    if not target.is_relative_to(settings.data_root) or not target.exists():
+        raise ValueError("Data path is unavailable.")
+    if require_file and not target.is_file():
+        raise ValueError("Select an acquisition file.")
+    return target
+
+
+def is_private_output_path(settings, path):
+    """Keep owner output trees private even when acquisition/output roots coincide."""
+    if not path.is_relative_to(settings.output_root):
+        return False
+    if not settings.data_root.is_relative_to(settings.output_root):
+        return True
+    parts = path.relative_to(settings.output_root).parts
+    # Owner directories use the SHA-256 identity namespace. The shared root and
+    # ordinary acquisition folders remain browsable; owner folders never do.
+    return bool(parts and len(parts[0]) == 64 and all(c in '0123456789abcdef' for c in parts[0]))

tofscope/presentation/coordinates.py

@@ -0,0 +1,31 @@
+"""Reusable, sample-preserving depth geometry for Explore and later spatial views.
+
+Coordinates describe original acquisition samples, never a resampled intensity grid.
+Unknown physical depths are omitted from physical views, but retained by CSV exports.
+Cell boundaries are display footprints, not measurements of plane thickness.
+"""
+import numpy as np
+from tofscope.science.depth_calibration import DepthCalibration, convert_depth
+
+
+def calibration(snapshot):
+    return DepthCalibration(snapshot.depth_anchors, snapshot.shape[0]) if len(snapshot.depth_anchors) > 1 else None
+
+
+def depth_samples(snapshot):
+    frames = np.arange(snapshot.shape[0])
+    active = calibration(snapshot) if snapshot.depth_coordinates == 'depth' else None
+    if active is None:
+        return frames, frames.astype(float), 'frame', 0
+    depths = active.frame_to_depth(frames)
+    known = np.isfinite(depths)
+    return frames[known], convert_depth(depths[known], 'nm', snapshot.depth_unit), ('µm' if snapshot.depth_unit == 'um' else snapshot.depth_unit), int((~known).sum())
+
+
+def block_depths(snapshot, frame_blocks):
+    """Mean each block's calibrated samples, including anchor slope changes.
+
+    A block containing unknown samples is invalid: callers must clip before pooling.
+    """
+    active = calibration(snapshot)
+    return [float(np.mean(active.frame_to_depth(block))) for block in frame_blocks]

tofscope/presentation/data.py

@@ -0,0 +1,54 @@
+from dataclasses import dataclass, field, asdict
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class Axis:
+    name: str
+    unit: str
+    values: list[float]
+    boundaries: list[float]
+
+
+@dataclass(frozen=True)
+class Curve:
+    signal_id: str
+    style_index: int
+    label: str
+    values: list[float | None]
+    coverage: list[bool]
+
+
+@dataclass(frozen=True)
+class Panel:
+    kind: Literal["image", "line"]
+    content_version: str
+    axes: list[Axis]
+    values: list[list[float | None]] = field(default_factory=list)
+    coverage: list[list[bool]] = field(default_factory=list)
+    series: list[Curve] = field(default_factory=list)
+    units: str = "intensity"
+    aggregation: str = "original"
+    intensity_range: tuple[float, float] = (0, 1)
+    palette: Literal["ion", "gray", "viridis", "magma", "cividis"] = "viridis"
+    log: bool = False
+    relative: bool = False
+    signal_id: str | None = None
+    signal_name: str | None = None
+    signal_version: int | None = None
+    frame_range: tuple[int, int] | None = None
+    acquisition_frames: list[int] = field(default_factory=list)
+    omitted_frames: int = 0
+    coordinate_kind: Literal['frame', 'depth'] = 'frame'
+
+
+
+@dataclass(frozen=True)
+class ExploreData:
+    analysis_id: str
+    revision: int
+    dataset_generation: str
+    panels: dict[str, Panel]
+
+    def to_dict(self):
+        return asdict(self)