screengraft 0.13.1 → 0.20.4

package/scripts/preflight.py

@@ -87,7 +87,19 @@ def report():
         "install_command": f"{sys.executable} {os.path.abspath(__file__)} --install",
         "install_does": f"Creates a virtualenv at {VENV} (nothing touches system Python) and pip-installs "
                         f"{', '.join(pkg for _, pkg, _ in REQUIRED)} into it (~60 MB download).",
+        # Optional, and deliberately NOT part of `ready`. A missing ffmpeg
+        # stops video renders and nothing else; making it a hard requirement
+        # would fail preflight for every user who only ever injects a
+        # screenshot, which is most of them.
         "optional": [
+            {"name": "ffmpeg (video)", "package": "imageio-ffmpeg",
+             "status": "installed" if _have_ffmpeg() else "missing",
+             "needed_for": "rendering a video; stills do not use it",
+             "install_command": f"{sys.executable} {os.path.abspath(__file__)} --install-ffmpeg",
+             "install_size": "~25 MB, a wheel with a static binary; nothing system-wide",
+             "why": "Encodes video renders. Ships as a wheel with a static binary, "
+                    "so it lands in the same venv and nothing is installed "
+                    "system-wide. Stills do not need it."},
             {"name": "SAM 2 (M4)", "status": "not yet used by the plugin",
              "why": "Better screen detection on photos where tone-based detection fails. Optional; results are worse without it, not absent."}
         ],
@@ -95,6 +107,23 @@ def report():
     }
 
 
+def _have_ffmpeg() -> bool:
+    """Is the ffmpeg wheel importable IN THE VENV (not in whatever Python runs this)?"""
+    code = ("import json\n"
+            "try:\n"
+            "    import imageio_ffmpeg, os\n"
+            "    p = imageio_ffmpeg.get_ffmpeg_exe()\n"
+            "    print(json.dumps(bool(p and os.path.exists(p))))\n"
+            "except Exception:\n"
+            "    print('false')\n")
+    try:
+        r = subprocess.run([VENV_PY, "-c", code], capture_output=True, text=True,
+                           timeout=60, check=False)
+        return r.stdout.strip() == "true"
+    except Exception:
+        return False
+
+
 def install():
     os.makedirs(os.path.dirname(VENV), exist_ok=True)
     if not os.path.exists(VENV_PY):
@@ -103,12 +132,31 @@ def install():
     subprocess.check_call([VENV_PY, "-m", "pip", "install", "-q", "-r", REQ])
 
 
+def install_ffmpeg():
+    """Add just the video encoder to an existing venv.
+
+    A separate entry point because of who needs it: someone who installed
+    screengraft before video existed has a perfectly good venv with OpenCV in
+    it, `ready` is true, and nothing tells them anything is missing until a
+    render fails at the end of the job. This adds the one wheel, so the ask is
+    "~25 MB for video" rather than "reinstall everything".
+    """
+    if not os.path.exists(VENV_PY):
+        install()
+        return
+    subprocess.check_call([VENV_PY, "-m", "pip", "install", "-q", "imageio-ffmpeg"])
+
+
 def main():
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("--install", action="store_true", help="Create the venv and install requirements (ask the user first)")
+    ap.add_argument("--install-ffmpeg", action="store_true",
+                    help="Add just the video encoder to an existing venv (ask the user first)")
     args = ap.parse_args()
     if args.install:
         install()
+    elif args.install_ffmpeg:
+        install_ffmpeg()
     rep = report()
     print(json.dumps(rep, indent=1))
     sys.exit(0 if rep["ready"] else 1)

package/scripts/requirements.txt

@@ -1,2 +1,3 @@
 opencv-python-headless>=4.9
 numpy>=1.26
+imageio-ffmpeg>=0.4

package/scripts/ui.py

@@ -168,6 +168,69 @@ def _read_image(path: str):
     return im, p
 
 
+VIDEO_EXT = (".mp4", ".mov", ".m4v", ".webm", ".avi", ".mkv")
+
+
+def _have_ffmpeg() -> bool:
+    try:
+        W.ffmpeg_exe()
+        return True
+    except RuntimeError:
+        return False
+
+
+def _is_video(path: str) -> bool:
+    return str(path).lower().endswith(VIDEO_EXT)
+
+
+def _read_source(path: str):
+    """Read the screen source, which may be a still OR a video.
+
+    Returns (frame, real_path, meta). For a video the frame is the poster —
+    the frame the designer fits on — and `meta` carries what the page needs to
+    show a scrubber. Everything downstream of this point treats that frame
+    exactly like a screenshot, which is the point: the fit, the loupe, the
+    compare view and the preview are all unchanged by video.
+    """
+    real = _safe_local_path(path)
+    if not _is_video(real):
+        im, rp = _read_image(real)
+        return im, rp, {"video": False}
+    n, fps, vw, vh = W.probe_video(real)
+    frame = W.read_frame_at(real, 0)
+    # Report the encoder's absence HERE, when the clip is chosen, rather than
+    # letting the render fail at the end of the job. Someone who installed
+    # screengraft before video existed has a working venv with no ffmpeg in it,
+    # and nothing else would tell them until they had done all the fitting.
+    return frame, real, {"video": True, "frames": n, "fps": fps, "size": [vw, vh],
+                         "ffmpeg": _have_ffmpeg()}
+
+
+# Render progress, read by /api/render_status. A ten-second clip is a few
+# hundred frames and a good few seconds of work, which is far too long to hold
+# an HTTP request open — so the render runs on its own thread and the page
+# polls. ThreadingHTTPServer is already the server class, so this needs no
+# other machinery.
+RENDER = {"state": "idle", "done": 0, "total": 0, "output": None, "message": None}
+RENDER_LOCK = threading.Lock()
+
+
+def _render_worker(photo, video_path, corners, dest, radius_px, gr, grain, preset, fit_frame):
+    def progress(done, total):
+        with RENDER_LOCK:
+            RENDER["done"], RENDER["total"] = done, total
+    try:
+        info = W.compose_video(photo, video_path, corners, dest,
+                               corner_radius=radius_px, grade=gr, grain=grain,
+                               preset=preset, fit_frame=fit_frame, progress=progress)
+        with RENDER_LOCK:
+            RENDER.update(state="done", output=dest, info=info,
+                          done=info["frames"], total=info["frames"], message=None)
+    except Exception as e:                     # noqa: BLE001 - surfaced to the page
+        with RENDER_LOCK:
+            RENDER.update(state="error", message=str(e))
+
+
 def _guess_type(corners):
     c = np.array(corners, dtype=float)
     w = (np.linalg.norm(c[1] - c[0]) + np.linalg.norm(c[2] - c[3])) / 2
@@ -259,6 +322,12 @@ class Handler(BaseHTTPRequestHandler):
                     if time.time() >= deadline:
                         return self._json({"status": "pending", "waited": True})
                     time.sleep(0.15)
+            if u.path == "/api/render_status":
+                # A poll, so a GET: no body, safe to repeat, and the page hits
+                # it once a second while a render runs.
+                with RENDER_LOCK:
+                    return self._json(dict(RENDER))
+
             return self._json({"error": "no such route"}, 404)
         except (PermissionError, FileNotFoundError, KeyError, ValueError) as e:
             return self._json({"error": str(e)}, 400)
@@ -274,17 +343,26 @@ class Handler(BaseHTTPRequestHandler):
                 dest = os.path.join(SESSION.dir, f"{role}-{int(time.time())}-{name}")
                 with open(dest, "wb") as f:
                     f.write(self._body())
-                im, real = _read_image(dest)
+                # A video is only ever a screen source; a photo must be a still.
+                if role == "screenshot":
+                    im, real, meta = _read_source(dest)
+                else:
+                    im, real = _read_image(dest)
+                    meta = {"video": False}
                 SESSION.update(**{role: real})
-                return self._json({"path": real, "size": [im.shape[1], im.shape[0]]})
+                return self._json({"path": real, "size": [im.shape[1], im.shape[0]], **meta})
 
             b = self._jbody()
 
             if u.path == "/api/use":
                 role = b["role"]
-                im, real = _read_image(b["path"])
+                if role == "screenshot":
+                    im, real, meta = _read_source(b["path"])
+                else:
+                    im, real = _read_image(b["path"])
+                    meta = {"video": False}
                 SESSION.update(**{role: real})
-                return self._json({"path": real, "size": [im.shape[1], im.shape[0]]})
+                return self._json({"path": real, "size": [im.shape[1], im.shape[0]], **meta})
 
             if u.path == "/api/figma":
                 return self._json(SESSION.enqueue({
@@ -322,12 +400,24 @@ class Handler(BaseHTTPRequestHandler):
             if u.path == "/api/detect":
                 photo, _ = _read_image(SESSION.state["photo"])
                 gray = cv2.cvtColor(photo, cv2.COLOR_BGR2GRAY)
-                res = D.detect(gray, None)
+                # `color` gives detect() the saturation detector — devices are
+                # neutral, furniture is not, and grayscale throws that away.
+                res = D.detect(gray, None, color=photo)
                 if res is None:
                     return self._json({"found": False,
                                        "message": "Neither detector could find a screen here "
                                                   "(nothing separable by tone, no screen-shaped "
                                                   "boundary). Place the four corners by hand."})
+                # An abstention is a miss, and must reach the page as one. On
+                # 7 Sep 2026 a quad on a table was shown as a checkable guess
+                # with two corners off the canvas, which cannot be dragged back
+                # — worse than no guess at all. detect() keeps the
+                # quad for inspection; the page gets the default rectangle.
+                if res.get("abstained"):
+                    return self._json({"found": False,
+                                       "message": res["abstain_reason"],
+                                       "abstained": True,
+                                       "inspect": res["corners"]})
                 res.pop("_corners_np", None)
                 res["found"] = True
                 # How much the page should trust this. Both detectors agreeing is
@@ -338,9 +428,72 @@ class Handler(BaseHTTPRequestHandler):
                 res["type_guess"] = _guess_type(res["corners"])
                 return self._json(res)
 
+            if u.path == "/api/frame":
+                # One frame of the source video as a PNG the page can show — the
+                # poster, or whichever frame the scrubber is on. The fit, the
+                # loupe and the compare view all work on this exactly as they
+                # work on a screenshot, which is why none of them needed
+                # changing for video.
+                spath = _safe_local_path(SESSION.state["screenshot"])
+                if not _is_video(spath):
+                    return self._json({"error": "the screen source is not a video"}, 400)
+                idx = int(b.get("index") or 0)
+                frame = W.read_frame_at(spath, idx)
+                dest = os.path.join(SESSION.dir, f"frame-{idx:06d}.png")
+                cv2.imwrite(dest, frame, [cv2.IMWRITE_PNG_COMPRESSION, 1])
+                return self._json({"path": dest, "index": idx,
+                                   "size": [frame.shape[1], frame.shape[0]]})
+
+            if u.path == "/api/render":
+                # Video: same fit, same geometry, N frames instead of one.
+                photo, ppath = _read_image(SESSION.state["photo"])
+                spath = _safe_local_path(SESSION.state["screenshot"])
+                if not _is_video(spath):
+                    return self._json({"error": "the screen source is not a video"}, 400)
+                if not _have_ffmpeg():
+                    return self._json({"error": "ffmpeg is not installed",
+                                       "needs_ffmpeg": True}, 400)
+                with RENDER_LOCK:
+                    if RENDER["state"] == "running":
+                        return self._json({"error": "a render is already running"}, 409)
+                    RENDER.update(state="running", done=0, total=0,
+                                  output=None, message=None)
+                corners = b["corners"]
+                frac = float(b.get("radius_frac") or 0.0)
+                fit_frame = int(b.get("fit_frame") or 0)
+                first = W.read_frame_at(spath, fit_frame)
+                radius_px = frac * first.shape[1]
+                gr = float(b.get("grade") if b.get("grade") is not None else 0.0)
+                grain = bool(b.get("grain", gr > 0))
+                preset = "prores" if b.get("preset") == "prores" else "web"
+                ext = ".mov" if preset == "prores" else ".mp4"
+                os.makedirs(OUT_DIR, exist_ok=True)
+                stem = (f"{os.path.splitext(os.path.basename(ppath))[0]}__"
+                        f"{os.path.splitext(os.path.basename(spath))[0]}")
+                dest = os.path.join(OUT_DIR, stem + ext)
+                i = 2
+                while os.path.exists(dest):
+                    dest = os.path.join(OUT_DIR, f"{stem}-{i}{ext}"); i += 1
+                SESSION.update(corners=corners, radius_frac=frac,
+                               device=b.get("device"), grade=gr)
+                # Everything that changes the output goes in the sidecar, for the
+                # third time of asking (radius_px, then grade/grain, now the video
+                # fields). A render that cannot be reproduced from its own sidecar
+                # undercuts the determinism claim.
+                result = {"output": dest, "photo": ppath, "screenshot": spath,
+                          "corners": corners, "radius_frac": frac, "radius_px": radius_px,
+                          "device": b.get("device"), "grade": gr, "grain": grain,
+                          "video": True, "preset": preset, "fit_frame": fit_frame,
+                          "saved": time.time()}
+                _write_json_atomic(SESSION.result_path, result)
+                threading.Thread(target=_render_worker, daemon=True,
+                                 args=(photo, spath, corners, dest, radius_px,
+                                       gr, grain, preset, fit_frame)).start()
+                return self._json({"started": True, "output": dest, "preset": preset})
+
             if u.path in ("/api/preview", "/api/save"):
                 photo, ppath = _read_image(SESSION.state["photo"])
-                shot, spath = _read_image(SESSION.state["screenshot"])
+                shot, spath, _meta = _read_source(SESSION.state["screenshot"])
                 corners = b["corners"]
                 frac = float(b.get("radius_frac") or 0.0)
                 radius_px = frac * shot.shape[1]