tfaour/espresso_frame
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 13 Wiki Activity

Color/contrast/dithering sliders + before/after render preview

Browse Source 
Advanced configuration gains three sliders (PIL ImageEnhance factors
for color/contrast, 0-2, 1=unchanged; a 0-1 dithering strength) applied
to every photo this frame renders. Confirmed the parameter conventions
against a similar project (jwchen119/EPF: ImageEnhance.Color/Contrast,
1.0 baseline) before implementing; dithering strength isn't natively
exposed by PIL's quantize(), so it's implemented by blending the source
toward its own flat/undithered quantization before running Floyd-
Steinberg on the blend -- at 0 there's no quantization error left to
diffuse (exactly the flat result), at 1 it's the original unmodified
behavior, with a smooth continuum between rather than dithering being
an on/off toggle.

image_pipeline.py split into composition (_compose), enhancement
(_enhance), quantization (_quantize), and transpose+pack stages so
render_frame (device bytes) and the new render_preview_png (a normal
viewable PNG, upright logical orientation) share the same pipeline
instead of duplicating it. Named-face overlay label math (face_labels.py)
was already routed through the shared _placement_transform, so it
needed no changes for the new params.

Also added the requested before/after comparison: the Configuration
tab's new Preview card shows the current photo's untouched Immich
preview next to that same photo run through the frame's actual saved
rendering pipeline (two new GET endpoints, /preview/original and
/preview/rendered) -- immediate visual feedback for tuning the palette
and these new sliders. "Refresh preview" re-fetches after saving.

Schema migration v6 adds color_boost/contrast_boost/dither_strength,
defaulting to 1.0/1.0/1.0 -- reproduces the exact previous rendering
until a frame's Configuration tab changes one.

Verified against the live-shaped test database: the migration, sliders
persisting and clamping out-of-range input, both preview endpoints
(real JPEG passthrough / real PNG at correct logical size+orientation),
confirmed dither_strength=0 actually changes the rendered bytes vs.
default, and the standing legacy-device curl suite.
This commit is contained in:
tfaour
2026-07-22 08:46:22 -04:00
parent 83c59af1dd
commit e48ac50ea1
9 changed files with 303 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
server/app/image_pipeline.py
+93 -38
View File
@@ -2,7 +2,9 @@
from __future__ import annotations
from PIL import Image, ImageOps
import io
from PIL import Image, ImageEnhance, ImageOps
EPD_WIDTH = 800
EPD_HEIGHT = 480
@@ -208,55 +210,59 @@ def _placement_transform(
return scale_x, scale_y, -left * scale_x, -top * scale_y
def render_frame(source: Image.Image, faces: list[dict] | None = None,
orientation: str = "landscape", palette_rgb: list | None = None,
display_mode: str = DEFAULT_DISPLAY_MODE) -> 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.
`display_mode` (see DISPLAY_MODES) picks how the photo's aspect ratio
is reconciled with the panel's: crop_fill (center-crop to fill,
excess trimmed), crop_faces (as crop_fill, but shifts the crop to
keep `faces` on screen -- falls back to crop_fill if none), stretch_fill
(fills exactly, aspect ratio not preserved), letterbox (whole photo
visible, letterboxed with LETTERBOX_BG where it doesn't fill).
`orientation` (see ORIENTATION_TRANSPOSE) composes the photo for how
the frame physically hangs, then rotates into native panel space --
the output byte layout is identical either way.
`palette_rgb` overrides DEFAULT_PALETTE_RGB (a frame's tuned colors,
see Frame.palette_rgb) -- None uses the default.
"""
def _compose(source: Image.Image, faces: list[dict] | None, orientation: str, display_mode: str) -> Image.Image:
"""Crop/resize/letterbox `source` per display_mode -- returns an RGB
image at logical_render_size(orientation), before enhancement or
quantization. See render_frame for what each display_mode does."""
logical_w, logical_h = logical_render_size(orientation)
fitted = ImageOps.exif_transpose(source.convert("RGB"))
if display_mode == "stretch_fill":
fitted = fitted.resize((logical_w, logical_h), Image.LANCZOS)
elif display_mode == "letterbox":
return fitted.resize((logical_w, logical_h), Image.LANCZOS)
if display_mode == "letterbox":
scale = min(logical_w / fitted.width, logical_h / fitted.height)
new_w, new_h = max(1, round(fitted.width * scale)), max(1, round(fitted.height * scale))
resized = fitted.resize((new_w, new_h), Image.LANCZOS)
canvas = Image.new("RGB", (logical_w, logical_h), LETTERBOX_BG)
canvas.paste(resized, ((logical_w - new_w) // 2, (logical_h - new_h) // 2))
fitted = canvas
elif display_mode == "crop_faces" and faces:
return canvas
if display_mode == "crop_faces" and faces:
box = _face_aware_crop_box(fitted.width, fitted.height, logical_w, logical_h, faces)
fitted = fitted.crop(box).resize((logical_w, logical_h), Image.LANCZOS)
else: # crop_fill, or crop_faces with no faces detected
fitted = ImageOps.fit(fitted, (logical_w, logical_h), method=Image.LANCZOS)
return _quantize_and_pack(fitted, orientation, palette_rgb)
return fitted.crop(box).resize((logical_w, logical_h), Image.LANCZOS)
return ImageOps.fit(fitted, (logical_w, logical_h), method=Image.LANCZOS) # crop_fill, or crop_faces w/ no faces
def _quantize_and_pack(logical_img: Image.Image, orientation: str, palette_rgb: list | None = None) -> bytes:
"""The shared back half of rendering: 6-color Floyd-Steinberg
quantization, rotation into native panel space, and 2-pixels/byte
packing. Takes an RGB image already composed at logical_render_size()
for the orientation."""
def _enhance(img: Image.Image, color_boost: float, contrast_boost: float) -> Image.Image:
if color_boost != 1.0:
img = ImageEnhance.Color(img).enhance(color_boost)
if contrast_boost != 1.0:
img = ImageEnhance.Contrast(img).enhance(contrast_boost)
return img
def _quantize(img: Image.Image, palette_rgb: list | None, dither_strength: float) -> Image.Image:
"""RGB -> palette-quantized P-mode image, same size/orientation as
`img` (no rotation here). dither_strength blends `img` toward its own
flat (undithered) quantization before running Floyd-Steinberg on the
blend: at 0 there's zero quantization error left to diffuse (so the
result IS the flat quantization, no dithering texture at all); at 1
it's `img` unchanged (full-strength dithering, this project's
original always-on behavior); values between give a smooth continuum
of dithering intensity rather than an on/off toggle."""
palette_image = _build_palette_image(palette_rgb or DEFAULT_PALETTE_RGB)
quantized = logical_img.quantize(palette=palette_image, dither=Image.Dither.FLOYDSTEINBERG)
if dither_strength >= 1.0:
return img.quantize(palette=palette_image, dither=Image.Dither.FLOYDSTEINBERG)
if dither_strength <= 0.0:
return img.quantize(palette=palette_image, dither=Image.Dither.NONE)
flat = img.quantize(palette=palette_image, dither=Image.Dither.NONE).convert("RGB")
blended = Image.blend(flat, img, dither_strength)
return blended.quantize(palette=palette_image, dither=Image.Dither.FLOYDSTEINBERG)
def _transpose_and_pack(quantized: Image.Image, orientation: str) -> bytes:
"""Rotates a logical-space quantized image into native panel space
and packs it 2 pixels/byte the way epd7in3e.c expects. Always
returns exactly EPD_WIDTH*EPD_HEIGHT/2 bytes."""
transpose = ORIENTATION_TRANSPOSE.get(orientation)
if transpose is not None:
quantized = quantized.transpose(transpose)
@@ -274,6 +280,54 @@ def _quantize_and_pack(logical_img: Image.Image, orientation: str, palette_rgb:
return bytes(out)
def render_frame(source: Image.Image, faces: list[dict] | None = None,
orientation: str = "landscape", palette_rgb: list | None = None,
display_mode: str = DEFAULT_DISPLAY_MODE, color_boost: float = 1.0,
contrast_boost: float = 1.0, dither_strength: float = 1.0) -> bytes:
"""Fits `source` to the panel's resolution, applies color/contrast
enhancement, quantizes it to the 6-color palette, and packs 2
pixels/byte the way epd7in3e.c expects. Always returns exactly
EPD_WIDTH*EPD_HEIGHT/2 bytes.
`display_mode` (see DISPLAY_MODES) picks how the photo's aspect ratio
is reconciled with the panel's: crop_fill (center-crop to fill,
excess trimmed), crop_faces (as crop_fill, but shifts the crop to
keep `faces` on screen -- falls back to crop_fill if none), stretch_fill
(fills exactly, aspect ratio not preserved), letterbox (whole photo
visible, letterboxed with LETTERBOX_BG where it doesn't fill).
`color_boost`/`contrast_boost` are PIL ImageEnhance factors (1.0 =
unchanged, matching PIL's own convention); `dither_strength` is
0.0-1.0 (see _quantize).
`orientation` (see ORIENTATION_TRANSPOSE) composes the photo for how
the frame physically hangs, then rotates into native panel space --
the output byte layout is identical either way.
`palette_rgb` overrides DEFAULT_PALETTE_RGB (a frame's tuned colors,
see Frame.palette_rgb) -- None uses the default.
"""
fitted = _enhance(_compose(source, faces, orientation, display_mode), color_boost, contrast_boost)
quantized = _quantize(fitted, palette_rgb, dither_strength)
return _transpose_and_pack(quantized, orientation)
def render_preview_png(source: Image.Image, faces: list[dict] | None = None,
orientation: str = "landscape", palette_rgb: list | None = None,
display_mode: str = DEFAULT_DISPLAY_MODE, color_boost: float = 1.0,
contrast_boost: float = 1.0, dither_strength: float = 1.0) -> bytes:
"""Identical composition/enhancement/quantization pipeline as
render_frame, but returned as a normal browser-viewable PNG in
logical (upright, as-the-frame-actually-hangs) orientation rather
than packed native-panel bytes and rotation -- what the web UI's
"how it will look on the frame" preview shows."""
fitted = _enhance(_compose(source, faces, orientation, display_mode), color_boost, contrast_boost)
quantized = _quantize(fitted, palette_rgb, dither_strength)
buf = io.BytesIO()
quantized.convert("RGB").save(buf, format="PNG")
return buf.getvalue()
def render_placeholder(lines: list[str], qr_url: str | None = None,
orientation: str = "landscape", palette_rgb: list | None = None) -> bytes:
"""A readable full-panel message (plus an optional QR code) in the
@@ -320,4 +374,5 @@ def render_placeholder(lines: list[str], qr_url: str | None = None,
if qr_img:
img.paste(qr_img, ((logical_w - qr_img.width) // 2, y + 14))
return _quantize_and_pack(img, orientation, palette_rgb)
quantized = _quantize(img, palette_rgb, dither_strength=1.0)
return _transpose_and_pack(quantized, orientation)