Add server-configurable refresh interval + face-aware cropping
Build and push server image / build-and-push (push) Failing after 10s

Two features, both toggleable/settable from the web config UI:

Refresh interval: new GET /frame/config returns
{"refresh_interval_s": ...} as plain JSON. Reuses the endpoint the frame
already needs to hit for a reachability check each wake cycle (previously
/health) rather than adding a third round trip, and always returns 200
with current settings regardless of Immich-configured state so it stays
valid as a pure reachability signal. Clamped to [60, 86400] seconds in
POST /api/config.

Face-aware cropping: GET /api/faces?id={assetId} on Immich already
returns real per-photo face bounding boxes from its own People-feature
ML -- confirmed against a live instance, boxes scaled to the asset's
native resolution. No face detection built or bundled here at all, just
an API call plus rectangle math. image_pipeline.render_frame() gains an
optional `faces` param: when present, computes the largest crop window
matching the panel's aspect ratio that fits in the source image, centered
on the union of all face boxes' centroid (scaled into the downloaded
preview's actual resolution) instead of the image's geometric center,
clamped to stay within bounds. No faces (or the smart_crop_faces config
toggle off) falls straight back to the existing ImageOps.fit() center-crop
-- zero behavior change in that case. A faces-lookup failure logs and
degrades to center-crop rather than failing the whole request.

Verified: unit tests for the crop-box math (horizontal shift toward an
off-center face, edge clamping), a full mock-Immich end-to-end pass
(extended to serve /faces) confirming the toggle changes output and the
response is still exactly 192,000 bytes, and a live comparison against a
real 4-face photo on the user's Immich instance (crop top shifted from
528px to 246px toward the detected faces).
This commit is contained in:
2026-07-18 15:32:29 -04:00
parent 34a3293a07
commit 6e353c2271
5 changed files with 112 additions and 3 deletions
+53 -2
View File
@@ -34,13 +34,64 @@ def _build_palette_image() -> Image.Image:
_PALETTE_IMAGE = _build_palette_image()
def render_frame(source: Image.Image) -> bytes:
def _face_aware_crop_box(
img_width: int, img_height: int, target_width: int, target_height: int, faces: list[dict]
) -> tuple[int, int, int, int]:
"""Largest crop window matching target_width:target_height that fits
inside the source image, centered on the union of all face bounding
boxes instead of the image's geometric center. Doesn't guarantee every
face survives if they're spread wider than the crop window allows --
just biases toward keeping them on screen, best-effort.
Each face's box is given relative to its own imageWidth/imageHeight
(the resolution Immich ran detection on), which may differ from the
downloaded preview's resolution passed in here, so each box is scaled
into img_width/img_height space before use.
"""
min_x = min_y = float("inf")
max_x = max_y = float("-inf")
for face in faces:
face_w = face.get("imageWidth") or img_width
face_h = face.get("imageHeight") or img_height
scale_x = img_width / face_w
scale_y = img_height / face_h
min_x = min(min_x, face["boundingBoxX1"] * scale_x)
max_x = max(max_x, face["boundingBoxX2"] * scale_x)
min_y = min(min_y, face["boundingBoxY1"] * scale_y)
max_y = max(max_y, face["boundingBoxY2"] * scale_y)
faces_cx = (min_x + max_x) / 2
faces_cy = (min_y + max_y) / 2
target_ratio = target_width / target_height
if img_width / img_height > target_ratio:
crop_h = img_height
crop_w = int(crop_h * target_ratio)
else:
crop_w = img_width
crop_h = int(crop_w / target_ratio)
left = max(0, min(faces_cx - crop_w / 2, img_width - crop_w))
top = max(0, min(faces_cy - crop_h / 2, img_height - crop_h))
return (int(left), int(top), int(left) + crop_w, int(top) + crop_h)
def render_frame(source: Image.Image, faces: list[dict] | None = None) -> bytes:
"""Fits `source` to the panel's resolution, quantizes it to the 6-color
palette with Floyd-Steinberg dithering, and packs 2 pixels/byte the way
epd7in3e.c expects. Always returns exactly EPD_WIDTH*EPD_HEIGHT/2 bytes.
If `faces` (from ImmichClient.get_asset_faces) is non-empty, crops
toward keeping them on screen instead of a plain center-crop.
"""
fitted = ImageOps.exif_transpose(source.convert("RGB"))
fitted = ImageOps.fit(fitted, (EPD_WIDTH, EPD_HEIGHT), method=Image.LANCZOS)
if faces:
box = _face_aware_crop_box(fitted.width, fitted.height, EPD_WIDTH, EPD_HEIGHT, faces)
fitted = fitted.crop(box).resize((EPD_WIDTH, EPD_HEIGHT), Image.LANCZOS)
else:
fitted = ImageOps.fit(fitted, (EPD_WIDTH, EPD_HEIGHT), method=Image.LANCZOS)
quantized = fitted.quantize(palette=_PALETTE_IMAGE, dither=Image.Dither.FLOYDSTEINBERG)
pixels = quantized.load()