openfcd 0.0.1__py3-none-any.whl

openfcd/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

openfcd/__main__.py

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

openfcd/cli/__init__.py

@@ -0,0 +1,242 @@
+"""OpenFCD CLI entry point."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+app = typer.Typer(name="openfcd", help="Fast Checkerboard Demodulation pipeline", no_args_is_help=True)
+
+
+# ---------------------------------------------------------------------------
+# Version
+# ---------------------------------------------------------------------------
+
+@app.command()
+def version() -> None:
+    """Print version."""
+    import openfcd
+
+    typer.echo(openfcd.__version__)
+
+
+# ---------------------------------------------------------------------------
+# New
+# ---------------------------------------------------------------------------
+
+@app.command()
+def new(
+    name: str = typer.Argument(..., help="Project name"),
+    path: Path = typer.Argument(..., help="Directory path for new .ofcd project"),
+) -> None:
+    """Create a new .ofcd project directory."""
+    from openfcd.io.store import FileSessionStore
+
+    FileSessionStore.new(path, name)
+    typer.echo(f"Created project '{name}' at {path}")
+
+
+# ---------------------------------------------------------------------------
+# Open
+# ---------------------------------------------------------------------------
+
+@app.command()
+def open(
+    project_path: Path = typer.Argument(..., help="Path to .ofcd project directory"),
+) -> None:
+    """Load and print project summary."""
+    from openfcd.io.store import FileSessionStore
+
+    store = FileSessionStore.open(project_path)
+    project = store.project
+    typer.echo(f"Name: {project.name}")
+    typer.echo(f"Created: {project.created}")
+    typer.echo(f"Format version: {project.format_version}")
+    typer.echo(f"Geometry preset: {project.geometry.optical_stack.preset}")
+    typer.echo(f"Frames dir: {project.data.frames_dir}")
+    typer.echo(f"Pattern: {project.data.pattern}")
+    store.close()
+
+
+# ---------------------------------------------------------------------------
+# Validate
+# ---------------------------------------------------------------------------
+
+@app.command()
+def validate(
+    project_path: Path = typer.Argument(..., help="Path to .ofcd project directory"),
+) -> None:
+    """Validate project.yaml schema. Exit 0 if OK, exit 2 if invalid."""
+    from openfcd.io.project import ProjectModel
+
+    try:
+        ProjectModel.from_yaml(project_path / "project.yaml")
+        typer.echo("Project schema is valid.")
+    except Exception as exc:
+        typer.echo(f"Validation error: {exc}", err=True)
+        raise typer.Exit(code=2)
+
+
+# ---------------------------------------------------------------------------
+# Run
+# ---------------------------------------------------------------------------
+
+@app.command()
+def run(
+    project_path: Path = typer.Argument(..., help="Path to .ofcd project directory"),
+    workers: int = typer.Option(-1, help="Parallel workers (-1=auto)"),
+    frames: str | None = typer.Option(None, help="Frame range filter (e.g. '0:100' or 'Img200*.jpg')"),
+    run_id: str | None = typer.Option(None, help="Run ID (default: run-YYYYMMDD-HHMMSS)"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON lines"),
+) -> None:
+    """Run the FCD pipeline on a project. Writes runs/{id}/results.h5."""
+    # Delegate to cmd_run module to avoid circular imports
+    from openfcd.cli.cmd_run import run_cmd as _run_impl
+
+    _run_impl(project_path=project_path, workers=workers, frames=frames, run_id=run_id, json_output=json_output)
+
+
+# ---------------------------------------------------------------------------
+# Replay
+# ---------------------------------------------------------------------------
+
+@app.command()
+def replay(
+    project_path: Path = typer.Argument(..., help="Path to .ofcd project directory"),
+    run: str | None = typer.Option(None, help="Run ID (default: latest)"),
+    figure: str | None = typer.Option(None, help="Figure ID to render (eta_heatmap, etc.)"),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Figure output path"),
+    json_output: bool = typer.Option(False, "--json", help="Output results as JSON"),
+) -> None:
+    """Replay a previous run's results (no recomputation)."""
+    from openfcd.cli.cmd_replay import replay_cmd as _replay_impl
+
+    _replay_impl(project_path=project_path, run=run, figure=figure, output=output, json_output=json_output)
+
+
+# ---------------------------------------------------------------------------
+# Manual grid calibration
+# ---------------------------------------------------------------------------
+
+@app.command("calibrate-grid")
+def calibrate_grid(
+    image: Path = typer.Argument(..., help="Checkerboard/reference image to mark"),
+    cells: float = typer.Option(..., "--cells", help="Number of checker cells between the two marked endpoints"),
+    cell_mm: float = typer.Option(1.2, "--cell-mm", help="Physical checker cell size in mm"),
+    points: str | None = typer.Option(None, "--points", help="Non-interactive endpoints: x1,y1,x2,y2"),
+    compare_px_per_mm: float | None = typer.Option(
+        None,
+        "--compare-px-per-mm",
+        help="Optional existing px/mm value to compare against",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Measure pixel/mm by marking a known checkerboard span."""
+    from openfcd.cli.cmd_calibrate import calibrate_grid_cmd
+
+    try:
+        calibrate_grid_cmd(
+            image=image,
+            cells=cells,
+            cell_mm=cell_mm,
+            points=points,
+            compare_px_per_mm=compare_px_per_mm,
+            json_output=json_output,
+        )
+    except Exception as exc:
+        typer.echo(f"Calibration error: {exc}", err=True)
+        raise typer.Exit(code=2)
+
+
+# ---------------------------------------------------------------------------
+# QC diagnostics
+# ---------------------------------------------------------------------------
+
+@app.command("qc-summary")
+def qc_summary(
+    project_path: Path = typer.Argument(..., help="Path to .ofcd project directory"),
+    run: str | None = typer.Option(None, help="Run ID (default: latest)"),
+    frame: int | None = typer.Option(None, help="Frame ID (default: first frame)"),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Single-frame QC PNG output"),
+    output_dir: Path | None = typer.Option(None, "--output-dir", help="Directory for --all QC PNGs"),
+    all_frames: bool = typer.Option(False, "--all", help="Render QC summary PNGs for all frames"),
+) -> None:
+    """Render QC summary figures from an existing run."""
+    from openfcd.cli.cmd_qc import qc_summary_cmd
+
+    try:
+        qc_summary_cmd(project_path, run, frame, output, output_dir, all_frames)
+    except Exception as exc:
+        typer.echo(f"QC summary error: {exc}", err=True)
+        raise typer.Exit(code=2)
+
+
+@app.command("noise-floor")
+def noise_floor(
+    project_path: Path = typer.Argument(..., help="Path to flat-water .ofcd project directory"),
+    frames: str | None = typer.Option(None, help="Frame range/filter for the flat-water run"),
+    run_id: str | None = typer.Option(None, help="Run ID for a new flat-water run"),
+    workers: int = typer.Option(-1, help="Parallel workers (-1=auto)"),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Noise-floor JSON summary path"),
+    hdf5_output: Path | None = typer.Option(None, "--hdf5-output", help="Noise-floor HDF5 summary path"),
+    from_run: str | None = typer.Option(None, "--from-run", help="Analyze an existing run instead of recomputing"),
+) -> None:
+    """Run or analyze a flat-water sequence and write noise-floor summary stats."""
+    from openfcd.cli.cmd_qc import noise_floor_cmd
+
+    try:
+        noise_floor_cmd(project_path, frames, run_id, workers, output, hdf5_output, from_run)
+    except Exception as exc:
+        typer.echo(f"Noise-floor error: {exc}", err=True)
+        raise typer.Exit(code=2)
+
+
+@app.command("sensitivity")
+def sensitivity(
+    project_path: Path = typer.Argument(..., help="Path to .ofcd project directory"),
+    run: str | None = typer.Option(None, help="Run ID (default: latest)"),
+    frame: int | None = typer.Option(None, help="Frame ID (default: first frame)"),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Sensitivity JSON output"),
+) -> None:
+    """Estimate eta amplitude sensitivity to calibration parameter perturbations."""
+    from openfcd.cli.cmd_qc import sensitivity_cmd
+
+    try:
+        sensitivity_cmd(project_path, run, frame, output)
+    except Exception as exc:
+        typer.echo(f"Sensitivity error: {exc}", err=True)
+        raise typer.Exit(code=2)
+
+
+# ---------------------------------------------------------------------------
+# Project subcommand group
+# ---------------------------------------------------------------------------
+
+project_app = typer.Typer(name="project", help="Project management")
+
+
+@project_app.command("info")
+def project_info(project_path: Path = typer.Argument(...)) -> None:
+    """Print project.yaml summary."""
+    from openfcd.cli.cmd_project import project_info_cmd as _info_impl
+
+    _info_impl(project_path=project_path)
+
+
+@project_app.command("runs")
+def project_runs(project_path: Path = typer.Argument(...)) -> None:
+    """List all runs with STALE status."""
+    from openfcd.cli.cmd_project import project_runs_cmd as _runs_impl
+
+    _runs_impl(project_path=project_path)
+
+
+@project_app.command("fingerprint")
+def project_fingerprint(project_path: Path = typer.Argument(...)) -> None:
+    """Print current config_fingerprint."""
+    from openfcd.cli.cmd_project import project_fingerprint_cmd as _fp_impl
+
+    _fp_impl(project_path=project_path)
+
+
+app.add_typer(project_app)

openfcd/cli/_output.py

@@ -0,0 +1,42 @@
+"""StageEvent serialization and display helpers."""
+from __future__ import annotations
+
+import json
+
+from openfcd.pipeline.base import StageEvent
+
+
+def stage_event_to_json(event: StageEvent) -> str:
+    """Serialize a StageEvent to a single-line JSON string with all 12 fields."""
+    data: dict[str, object] = {
+        "kind": event.kind,
+        "stage": event.stage,
+        "batch": event.batch,
+        "frame_idx": event.frame_idx,
+        "substage": event.substage,
+        "progress": event.progress,
+        "total": event.total,
+        "completed": event.completed,
+        "metrics": event.metrics,
+        "run_id": event.run_id,
+        "seq": event.seq,
+        "timestamp": event.timestamp,
+    }
+    return json.dumps(data)
+
+
+def format_progress(event: StageEvent) -> str:
+    """Human-readable progress string for non-JSON mode."""
+    if event.kind == "progress":
+        pct = f"{event.progress:.0%}" if event.progress is not None else "??"
+        frame = f"frame {event.frame_idx}" if event.frame_idx is not None else ""
+        batch = f"[{event.batch}]" if event.batch else ""
+        return f"[{event.stage}] {pct} {batch} {frame}"
+    elif event.kind == "finish":
+        return f"[{event.stage}] DONE"
+    elif event.kind == "error":
+        return f"[{event.stage}] ERROR: {event.metrics.get('message', 'unknown')}"
+    elif event.kind == "cancel":
+        return f"[{event.stage}] CANCELLED"
+    else:
+        return f"[{event.stage}] {event.kind}"

openfcd/cli/cmd_calibrate.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+
+import typer
+
+
+Point = tuple[float, float]
+
+
+def parse_point_pair(value: str) -> tuple[Point, Point]:
+    """Parse 'x1,y1,x2,y2' into two image points."""
+    parts = [p.strip() for p in value.split(",")]
+    if len(parts) != 4:
+        raise ValueError("points must be formatted as x1,y1,x2,y2")
+    try:
+        x1, y1, x2, y2 = (float(p) for p in parts)
+    except ValueError as exc:
+        raise ValueError("points must contain numeric coordinates") from exc
+    return (x1, y1), (x2, y2)
+
+
+def grid_pixel_calibration(
+    p0: Point,
+    p1: Point,
+    *,
+    cells: float,
+    cell_mm: float,
+) -> dict[str, float]:
+    """Calculate pixel/mm from two manually marked endpoints."""
+    cells = float(cells)
+    cell_mm = float(cell_mm)
+    if cells <= 0:
+        raise ValueError("cells must be positive")
+    if cell_mm <= 0:
+        raise ValueError("cell_mm must be positive")
+    dx = float(p1[0]) - float(p0[0])
+    dy = float(p1[1]) - float(p0[1])
+    pixel_distance = math.hypot(dx, dy)
+    if pixel_distance <= 0:
+        raise ValueError("marked points must not be identical")
+    length_mm = cells * cell_mm
+    return {
+        "pixel_distance": pixel_distance,
+        "cells": cells,
+        "cell_mm": cell_mm,
+        "length_mm": length_mm,
+        "pixel_per_mm": pixel_distance / length_mm,
+    }
+
+
+def _pick_points_interactive(image_path: Path) -> tuple[Point, Point]:
+    import matplotlib.pyplot as plt
+    from matplotlib.image import imread
+
+    img = imread(str(image_path))
+    fig, ax = plt.subplots()
+    ax.imshow(img, cmap="gray")
+    ax.set_title("Click the two endpoints of a known checkerboard span")
+    ax.set_axis_off()
+    typer.echo("Click two endpoints in the image window, then close is not needed.")
+    pts = plt.ginput(2, timeout=0)
+    plt.close(fig)
+    if len(pts) != 2:
+        raise RuntimeError("expected exactly two clicked points")
+    return (float(pts[0][0]), float(pts[0][1])), (float(pts[1][0]), float(pts[1][1]))
+
+
+def _format_report(result: dict[str, float], compare_px_per_mm: float | None) -> list[str]:
+    lines = [
+        f"pixel_distance_px: {result['pixel_distance']:.3f}",
+        f"physical_length_mm: {result['length_mm']:.6g}",
+        f"pixel_per_mm: {result['pixel_per_mm']:.6f}",
+    ]
+    if compare_px_per_mm and compare_px_per_mm > 0:
+        measured = result["pixel_per_mm"]
+        ratio = compare_px_per_mm / measured
+        lines.extend(
+            [
+                f"compare_pixel_per_mm: {compare_px_per_mm:.6f}",
+                f"px_per_mm_ratio_compare_over_measured: {ratio:.6f}",
+                f"eta_scale_if_replace_compare_with_measured: {ratio * ratio:.6f}",
+            ]
+        )
+    return lines
+
+
+def calibrate_grid_cmd(
+    image: Path,
+    *,
+    cells: float,
+    cell_mm: float,
+    points: str | None = None,
+    compare_px_per_mm: float | None = None,
+    json_output: bool = False,
+) -> dict[str, float]:
+    if not image.exists():
+        raise FileNotFoundError(f"image not found: {image}")
+    if points:
+        p0, p1 = parse_point_pair(points)
+    else:
+        p0, p1 = _pick_points_interactive(image)
+    result = grid_pixel_calibration(p0, p1, cells=cells, cell_mm=cell_mm)
+    result["x0"] = float(p0[0])
+    result["y0"] = float(p0[1])
+    result["x1"] = float(p1[0])
+    result["y1"] = float(p1[1])
+    if compare_px_per_mm and compare_px_per_mm > 0:
+        ratio = float(compare_px_per_mm) / result["pixel_per_mm"]
+        result["compare_pixel_per_mm"] = float(compare_px_per_mm)
+        result["px_per_mm_ratio_compare_over_measured"] = ratio
+        result["eta_scale_if_replace_compare_with_measured"] = ratio * ratio
+    if json_output:
+        typer.echo(json.dumps(result, indent=2, sort_keys=True))
+    else:
+        for line in _format_report(result, compare_px_per_mm):
+            typer.echo(line)
+    return result

openfcd/cli/cmd_new.py

@@ -0,0 +1,17 @@
+"""`openfcd new` — create a new .ofcd project directory."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from openfcd.io.store import FileSessionStore
+
+
+def new_cmd(
+    name: str = typer.Argument(..., help="Project name"),
+    path: Path = typer.Argument(..., help="Directory path for new .ofcd project"),
+) -> None:
+    """Create a new .ofcd project directory."""
+    FileSessionStore.new(path, name)
+    typer.echo(f"Created project '{name}' at {path}")

openfcd/cli/cmd_project.py

@@ -0,0 +1,61 @@
+"""`openfcd project` — project management subcommand group."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from openfcd.io.store import FileSessionStore
+
+
+def project_info_cmd(
+    project_path: Path = typer.Argument(...),
+) -> None:
+    """Print project.yaml summary."""
+    store = FileSessionStore.open(project_path)
+    project = store.project
+    typer.echo(f"Name: {project.name}")
+    typer.echo(f"Created: {project.created}")
+    typer.echo("Geometry:")
+    typer.echo(f"  Checker cell side: {project.geometry.checker_cell_mm} mm")
+    typer.echo(f"  Optical stack: {project.geometry.optical_stack.preset}")
+    typer.echo("Data:")
+    typer.echo(f"  Frames dir: {project.data.frames_dir}")
+    typer.echo(f"  Pattern: {project.data.pattern}")
+    if project.data.time_step_ms is not None:
+        typer.echo(f"  Time step: {project.data.time_step_ms} ms")
+    typer.echo("Process:")
+    typer.echo(f"  Flatfield sigma: {project.process.flatfield_sigma}")
+    typer.echo(f"  Detrend: {project.process.detrend}")
+    store.close()
+
+
+def project_runs_cmd(
+    project_path: Path = typer.Argument(...),
+) -> None:
+    """List all runs with STALE status."""
+    store = FileSessionStore.open(project_path)
+    runs = store.list_runs()
+
+    if not runs:
+        typer.echo("No runs found.")
+        store.close()
+        return
+
+    for run_info in runs:
+        run_id = run_info["run_id"]
+        stale = "STALE" if store.is_stale(run_id) else "OK"
+        fingerprint = run_info.get("config_fingerprint", "unknown")[:12]
+        typer.echo(f"  {run_id} [{stale}] fingerprint={fingerprint}...")
+
+    store.close()
+
+
+def project_fingerprint_cmd(
+    project_path: Path = typer.Argument(...),
+) -> None:
+    """Print current config_fingerprint."""
+    store = FileSessionStore.open(project_path)
+    fp = store.config_fingerprint()
+    typer.echo(fp)
+    store.close()

openfcd/cli/cmd_qc.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from openfcd.io.result import HDF5ResultStore
+from openfcd.io.store import FileSessionStore
+from openfcd.pipeline.qc import (
+    eta_noise_summary,
+    parameter_sensitivity_report,
+    save_qc_summary_figure,
+    write_noise_summary,
+)
+
+
+def _latest_run_id(store: FileSessionStore) -> str:
+    runs = store.list_runs()
+    if not runs:
+        raise RuntimeError("no runs found")
+    return str(runs[-1]["run_id"])
+
+
+def _open_results(project_path: Path, run: str | None) -> tuple[FileSessionStore, HDF5ResultStore, str]:
+    store = FileSessionStore.open(project_path, read_only=True)
+    run_id = run or _latest_run_id(store)
+    h5_path = store._dir / "runs" / run_id / "results.h5"
+    if not h5_path.exists():
+        store.close()
+        raise RuntimeError(f"results not found: {h5_path}")
+    return store, HDF5ResultStore.open(h5_path, "r"), run_id
+
+
+def _frame_image(store: FileSessionStore, results: HDF5ResultStore, frame_id: int):
+    frame_path = results.read_frame_attrs("default", frame_id).get("frame_path")
+    if not frame_path:
+        return None
+    path = Path(str(frame_path))
+    if not path.is_absolute():
+        path = Path(store.project.data.frames_dir) / path
+    if not path.exists():
+        return None
+    from openfcd.pipeline.compute import load_gray
+    return load_gray(path)
+
+
+def qc_summary_cmd(
+    project_path: Path,
+    run: str | None,
+    frame: int | None,
+    output: Path | None,
+    output_dir: Path | None,
+    all_frames: bool,
+) -> None:
+    store, results, run_id = _open_results(project_path, run)
+    try:
+        frame_ids = results.list_frames("default")
+        if not frame_ids:
+            raise RuntimeError("no frame results found")
+        selected = frame_ids if all_frames else [frame if frame is not None else frame_ids[0]]
+        if all_frames:
+            out_dir = output_dir or (store._dir / "runs" / run_id / "qc")
+            out_dir.mkdir(parents=True, exist_ok=True)
+            for fid in selected:
+                save_qc_summary_figure(
+                    results,
+                    "default",
+                    fid,
+                    out_dir / f"frame_{fid:06d}_qc.png",
+                    image=_frame_image(store, results, fid),
+                )
+            typer.echo(json.dumps({"run_id": run_id, "frames": selected, "output_dir": str(out_dir)}))
+        else:
+            out = output or (store._dir / "runs" / run_id / f"frame_{selected[0]:06d}_qc.png")
+            save_qc_summary_figure(
+                results,
+                "default",
+                selected[0],
+                out,
+                image=_frame_image(store, results, selected[0]),
+            )
+            typer.echo(json.dumps({"run_id": run_id, "frame": selected[0], "output": str(out)}))
+    finally:
+        results.close()
+        store.close()
+
+
+def noise_floor_cmd(
+    project_path: Path,
+    frames: str | None,
+    run_id: str | None,
+    workers: int,
+    output: Path | None,
+    hdf5_output: Path | None,
+    from_run: str | None,
+) -> None:
+    if from_run is None:
+        from openfcd.cli.cmd_run import run_cmd
+        run_id = run_id or "flat-water-noise"
+        try:
+            run_cmd(project_path=project_path, workers=workers, frames=frames, run_id=run_id, json_output=False)
+        except typer.Exit as exc:
+            if exc.exit_code != 0:
+                raise
+        from_run = run_id
+
+    store, results, resolved = _open_results(project_path, from_run)
+    try:
+        summary = eta_noise_summary(results, "default")
+        summary["run_id"] = resolved
+        json_path = output or (store._dir / "runs" / resolved / "noise_floor_summary.json")
+        h5_path = hdf5_output or (store._dir / "runs" / resolved / "noise_floor_summary.h5")
+        write_noise_summary(summary, json_path, h5_path)
+        typer.echo(json.dumps(summary, sort_keys=True))
+    finally:
+        results.close()
+        store.close()
+
+
+def sensitivity_cmd(
+    project_path: Path,
+    run: str | None,
+    frame: int | None,
+    output: Path | None,
+) -> None:
+    store, results, run_id = _open_results(project_path, run)
+    try:
+        frame_ids = results.list_frames("default")
+        if not frame_ids:
+            raise RuntimeError("no frame results found")
+        fid = frame if frame is not None else frame_ids[0]
+        report = parameter_sensitivity_report(
+            results.read_frame("default", fid),
+            results.read_frame_attrs("default", fid),
+        )
+        report["run_id"] = run_id
+        report["frame_id"] = fid
+        out = output or (store._dir / "runs" / run_id / f"frame_{fid:06d}_sensitivity.json")
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(json.dumps(report, indent=2, sort_keys=True), encoding="utf-8")
+        typer.echo(json.dumps({"run_id": run_id, "frame": fid, "output": str(out)}))
+    finally:
+        results.close()
+        store.close()