screengraft 0.25.2 → 0.38.0

package/scripts/fitfile.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""The fit as a portable file — written beside the mockup, loaded by dropping it in.
+
+`fits.py` already remembers a fit automatically, keyed by the photograph's own
+pixels. That covers "same photo, same machine, later" and nothing else. Three
+things it cannot do, and all three are in the request this exists for:
+
+  * there is no artefact to find, name, keep beside the project, or send to
+    someone;
+  * a re-export misses. The key is the decoded pixels, so the same scene saved
+    again from Figma at a different quality is a different photograph -- which is
+    exactly the "come back and improve it later" case;
+  * nothing travels to another machine.
+
+So: a small JSON file written next to the output it produced, and a load path
+that says plainly which photograph it was made for. No OS dialog is involved --
+the file lands in the folder the user already chose, Finder finds it, and the
+page takes it by drag-and-drop the same way it takes a photograph.
+
+**Geometry only.** Corners, corner radius, device. Not the grade, blend or
+grain: those belong to a *composite* and are recorded in `result.json`, which is
+the recipe for reproducing one exactly. A fit is the part that is expensive to
+make by hand and is worth carrying between runs; keeping the two apart stops one
+file quietly becoming a worse copy of the other.
+"""
+import json
+import os
+
+KIND = "screengraft-fit"
+VERSION = 1
+SUFFIX = ".fit.json"
+
+# How far the aspect ratio may drift before a scaled fit stops being trustworthy.
+# A re-export at another size keeps its aspect to within rounding; a CROP does
+# not, and a crop is where scaled corners land somewhere plausible and wrong.
+ASPECT_TOLERANCE = 0.01
+
+
+def path_for(output_path):
+    """Beside the mockup, sharing its name: photo__shot.png -> photo__shot.fit.json.
+
+    Next to the output rather than in a store of its own, because the whole
+    point is that a person can find it later without being told where to look.
+    """
+    stem = os.path.splitext(output_path)[0]
+    return stem + SUFFIX
+
+
+def build(corners, radius_frac, device, photo_path, photo_size, key):
+    return {
+        "kind": KIND,
+        "version": VERSION,
+        "corners": [[round(float(x), 2), round(float(y), 2)] for x, y in corners],
+        "radius_frac": float(radius_frac or 0.0),
+        "device": device,
+        "photo": {
+            "name": os.path.basename(photo_path or ""),
+            "size": [int(photo_size[0]), int(photo_size[1])],
+            # The pixel key, so a load can tell "this is that photograph" from
+            # "this is something else the same size". Not a path: the file is
+            # meant to be shared, and a path would be both useless elsewhere and
+            # a private detail.
+            "key": key,
+        },
+    }
+
+
+def write(output_path, doc):
+    p = path_for(output_path)
+    tmp = p + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump(doc, f, indent=1)
+    os.replace(tmp, p)
+    return p
+
+
+def parse(raw):
+    """Validate an untrusted document. Returns (doc, error).
+
+    Anything can be dropped onto a page. A fit that is not a fit has to be
+    refused with a sentence, not applied as four numbers that happen to parse.
+    """
+    if isinstance(raw, (str, bytes)):
+        try:
+            raw = json.loads(raw)
+        except ValueError as e:
+            return None, f"that file is not JSON ({e})"
+    if not isinstance(raw, dict):
+        return None, "that file does not contain a fit"
+    if raw.get("kind") != KIND:
+        return None, ("that file is not a screengraft fit — a fit is the "
+                      f"{SUFFIX} written next to a mockup you saved")
+    if int(raw.get("version", 0)) > VERSION:
+        return None, ("that fit was written by a newer version of screengraft "
+                      "than this one")
+    c = raw.get("corners")
+    if (not isinstance(c, list) or len(c) != 4
+            or not all(isinstance(p, list) and len(p) == 2 for p in c)):
+        return None, "that fit does not carry four corners"
+    try:
+        raw["corners"] = [[float(x), float(y)] for x, y in c]
+    except (TypeError, ValueError):
+        return None, "that fit's corners are not numbers"
+    return raw, None
+
+
+def apply_to(doc, photo_size, key):
+    """Fit a loaded document to the photograph currently open.
+
+    Corners are meaningless on the wrong image and *plausible but wrong* on a
+    crop of the right one, which is worse. So this never silently applies: every
+    return says which of four situations it is, and the page states it.
+    """
+    fw, fh = doc.get("photo", {}).get("size", [0, 0]) or [0, 0]
+    now_w, now_h = int(photo_size[0]), int(photo_size[1])
+    corners = doc["corners"]
+    name = doc.get("photo", {}).get("name") or "another photograph"
+
+    if key and doc.get("photo", {}).get("key") == key:
+        return corners, "exact", "This is the photograph the fit was made for."
+    if not fw or not fh:
+        return corners, "unknown", ("This fit does not say which photograph it "
+                                    "came from — check all four corners.")
+    if (fw, fh) == (now_w, now_h):
+        # The case this feature exists for: same scene, exported again, so the
+        # pixels differ and the size does not.
+        return corners, "same-size", (
+            "Different pixels, same dimensions as %s — most likely the same "
+            "photograph exported again. Corners applied unchanged." % name)
+
+    sx, sy = now_w / float(fw), now_h / float(fh)
+    scaled = [[x * sx, y * sy] for x, y in corners]
+    if abs(sx - sy) / max(sx, sy) > ASPECT_TOLERANCE:
+        return scaled, "reshaped", (
+            "%s was %dx%d and this is %dx%d — a different SHAPE, not just a "
+            "different size, so this was probably cropped. The corners are "
+            "stretched to fit and will need correcting." % (name, fw, fh, now_w, now_h))
+    return scaled, "scaled", (
+        "%s was %dx%d and this is %dx%d — corners scaled by %.3f. Worth checking "
+        "at a corner." % (name, fw, fh, now_w, now_h, sx))

package/scripts/fits.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""Remembered fits — the four corners, keyed by the photograph's own pixels.
+
+Matching the edges is the only part of the job that costs real attention, and
+it belongs to the PHOTOGRAPH, not to the screenshot: put a second screenshot
+into the same photo and the quad is identical. Until now it was thrown away at
+the end of every run, so the second screenshot meant doing the interview again.
+
+Two decisions worth stating, because both had a cheaper wrong version:
+
+**The key is the decoded pixels, not the path.** A photograph is re-exported,
+renamed, downloaded twice and dragged in from a different folder constantly, and
+a path key would miss every one of those. It would also miss the case this tool
+creates itself: /api/upload copies the bytes into the session, so the same image
+arriving by drag-drop has a path that never existed before and will not exist
+again. Hashing what the file DECODES to costs 4ms on a 12MP photo and 18ms on
+48MP (measured), which is nothing beside the read that produced the array.
+
+**A fit is remembered when it is SAVED, not while it is being dragged.** A quad
+on the canvas is a work in progress; a quad that produced an output is one the
+person looked at and kept. That also keeps the store small enough never to need
+thinking about — a few hundred bytes per entry, against the hundreds of
+megabytes of source copies the session sweep exists to remove.
+
+This file is the recipe, never the ingredients: numbers and a basename for
+display, no image data and no absolute paths.
+"""
+import hashlib
+import json
+import os
+import sys
+import threading
+import time
+
+# Enough that nobody working normally reaches it — an entry is ~200 bytes, so
+# the whole store stays under 100 KB — and bounded so it cannot grow without
+# limit on a machine that fits mockups all day.
+MAX_FITS = 500
+VERSION = 1
+
+# The server is threaded, and remembering is read-modify-write: load the store,
+# add one entry, write it back. os.replace stops the FILE from tearing and does
+# nothing about a lost update -- a render worker finishing while a save runs
+# would drop whichever entry was written first. The whole sequence is short and
+# uncontended, so one lock around it costs nothing worth measuring.
+_LOCK = threading.Lock()
+
+
+def store_path():
+    """Beside current.json, NOT inside a session directory.
+
+    A session's contents are swept when the run ends — that is the retention
+    policy — and a remembered fit has to outlive the run that made it or it has
+    remembered nothing.
+    """
+    return os.path.join(os.path.expanduser("~"), ".screengraft", "fits.json")
+
+
+def key_for(image):
+    """A stable id for a photograph's CONTENT.
+
+    The shape goes into the digest as well as the bytes: two arrays sharing a
+    buffer at different dimensions are different photographs, and hashing the
+    flat bytes alone would call them equal.
+    """
+    h = hashlib.sha256()
+    h.update(("%dx%dx%d|" % (image.shape[0], image.shape[1],
+                             image.shape[2] if image.ndim > 2 else 1)).encode())
+    h.update(memoryview(image.tobytes()))
+    return h.hexdigest()
+
+
+def _load():
+    """Tolerant, exactly like Session.read_job: a torn or hand-edited file reads
+    as no memory at all rather than taking the request down with it. Losing a
+    remembered fit costs one re-fit; refusing to serve the page costs the run.
+    """
+    try:
+        with open(store_path()) as f:
+            d = json.load(f)
+        if isinstance(d, dict) and isinstance(d.get("fits"), dict):
+            return d["fits"]
+    except (OSError, ValueError):
+        pass
+    return {}
+
+
+def _save(fits):
+    path = store_path()
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    tmp = path + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump({"version": VERSION, "fits": fits}, f, indent=1)
+    os.replace(tmp, path)
+
+
+def remember(key, corners, radius_frac, device, photo_path=None, size=None):
+    """Record the fit for this photograph, replacing any earlier one.
+
+    The last fit wins deliberately. A photograph has one right answer for where
+    its screen is; a history of near-misses would be a list to choose from,
+    which is the bookkeeping this feature exists to avoid.
+    """
+    if not key or not corners:
+        return None
+    with _LOCK:
+        return _remember_locked(key, corners, radius_frac, device, photo_path, size)
+
+
+def _remember_locked(key, corners, radius_frac, device, photo_path, size):
+    fits = _load()
+    entry = {"corners": [[float(x), float(y)] for x, y in corners],
+             "radius_frac": float(radius_frac or 0.0),
+             "device": device,
+             "saved": time.time()}
+    if photo_path:
+        # Basename only. It is there to say "the fit from birch-table.jpg" and
+        # nothing reads it back, so a full path would be a private detail kept
+        # for no purpose.
+        entry["photo"] = os.path.basename(photo_path)
+    if size:
+        entry["size"] = [int(size[0]), int(size[1])]
+    fits[key] = entry
+    if len(fits) > MAX_FITS:
+        oldest = sorted(fits.items(), key=lambda kv: kv[1].get("saved", 0))
+        for k, _ in oldest[:len(fits) - MAX_FITS]:
+            fits.pop(k, None)
+    try:
+        _save(fits)
+    except OSError as e:
+        # Remembering is a convenience wrapped around the thing the run was
+        # actually for. An unwritable home must cost the next fit, not this
+        # save -- but it is not allowed to be SILENT either, so it goes to the
+        # log the daemon already writes.
+        print(f"screengraft: could not remember this fit ({e})", file=sys.stderr)
+        return None
+    return entry
+
+
+def recall(key):
+    """The fit for this photograph, or None. Never raises."""
+    if not key:
+        return None
+    e = _load().get(key)
+    if not isinstance(e, dict) or not e.get("corners"):
+        return None
+    try:
+        e["corners"] = [[float(x), float(y)] for x, y in e["corners"]]
+    except (TypeError, ValueError):
+        return None
+    return e