Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio Images: encode gallery PNGs about 2x faster with byte-identical output (#16190)

Daniel Han9d27efcc78b9
diff --git a/studio/backend/core/inference/image_gallery.py b/studio/backend/core/inference/image_gallery.py
index 1ba69b1fddc..78f1f86e52d 100644
--- a/studio/backend/core/inference/image_gallery.py
+++ b/studio/backend/core/inference/image_gallery.py
@@ -18,7 +18,7 @@ from collections.abc import Callable, Iterable, Iterator
from pathlib import Path
from typing import Any, Optional
-from core.inference import gallery_flags
+from core.inference import gallery_flags, png_encode
from loggers import get_logger
from utils.account_context import is_owner_context
from utils.paths import ensure_account_dir, studio_root
@@ -131,6 +131,9 @@ def _png_bytes(image: Any, meta: dict[str, Any]) -> bytes:
info = PngInfo()
info.add_text(_META_KEY, json.dumps(meta))
info.add_text("parameters", _params_text(meta))
+ data = png_encode.encode(image, pnginfo = info, compress_level = png_compress_level())
+ if data is not None:
+ return data
buf = io.BytesIO()
image.save(buf, format = "PNG", pnginfo = info, compress_level = png_compress_level())
return buf.getvalue()
diff --git a/studio/backend/core/inference/png_encode.py b/studio/backend/core/inference/png_encode.py
new file mode 100644
index 00000000000..271cb97536b
--- /dev/null
+++ b/studio/backend/core/inference/png_encode.py
@@ -0,0 +1,256 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Pillow's exact PNG bytes, with ZipEncode.c's per-row filter choice done in numpy beside deflate.
+
+Used per (mode, level) only after a probe matched Pillow byte for byte in this process; UNSLOTH_IMAGE_PNG_FAST=0 off."""
+
+from __future__ import annotations
+
+import io
+import os
+import struct
+import threading
+import zlib
+from typing import Any, Iterator, Optional
+
+FAST_ENV = "UNSLOTH_IMAGE_PNG_FAST"
+# mode -> (bytes per pixel, IHDR colour type)
+_MODES = {"L": (1, 0), "LA": (2, 4), "RGB": (3, 2), "RGBA": (4, 6)}
+# Smaller bands made a batch's concurrent encodes queue on the GIL (32 rows of 512 px: 4 at once 1.6x slower).
+_BAND_BYTES = 192 * 1024
+_AHEAD = 2
+_PROBE_LOCK = threading.Lock()
+_PROBED: dict[tuple[str, int], bool] = {}
+engaged = 0
+_ENGAGED_LOCK = threading.Lock()
+
+
+def enabled() -> bool:
+ return (os.environ.get(FAST_ENV) or "").strip().lower() not in ("0", "false", "no", "off")
+
+
+def _filtered(pixels: Any, bpp: int, start: int, stop: int) -> bytes:
+ """ZipEncode.c's choice: None, Up, Sub, Paeth, each kept only on a strictly lower sum of |signed byte|."""
+ import numpy as np
+
+ x = pixels[start:stop]
+ if start:
+ prev = pixels[start - 1 : stop - 1]
+ else:
+ prev = np.empty_like(x)
+ prev[0] = 0
+ prev[1:] = x[:-1]
+ n, stride = x.shape
+
+ def cost(v: Any) -> Any:
+ return np.abs(v.view(np.int8), dtype = np.int16).sum(axis = 1, dtype = np.int64)
+
+ up = x - prev
+ sub = x.copy()
+ np.subtract(x[:, bpp:], x[:, :-bpp], out = sub[:, bpp:])
+ a = np.zeros((n, stride), np.int16)
+ a[:, bpp:] = x[:, :-bpp]
+ b = prev.astype(np.int16)
+ c = np.zeros((n, stride), np.int16)
+ c[:, bpp:] = prev[:, :-bpp]
+ pa = np.abs(b - c)
+ pb = np.abs(a - c)
+ pc = np.abs(a + b - 2 * c)
+ paeth = x - np.where((pa <= pb) & (pa <= pc), a, np.where(pb <= pc, b, c)).astype(np.uint8)
+
+ out = np.empty((n, stride + 1), np.uint8)
+ out[:, 0] = 0
+ out[:, 1:] = x
+ best = cost(x)
+ for code, rows in ((2, up), (1, sub), (4, paeth)):
+ score = cost(rows)
+ better = score < best
+ if better.any():
+ best = np.where(better, score, best)
+ out[better, 0] = code
+ out[better, 1:] = rows[better]
+ return out.tobytes()
+
+
+def _deflated(pixels: Any, bpp: int, level: int) -> Iterator[bytes]:
+ height, stride = pixels.shape
+ compressor = zlib.compressobj(level, zlib.DEFLATED, 15, 9, zlib.Z_FILTERED)
+ rows = max(1, _BAND_BYTES // (stride + 1))
+ bands = [(start, min(height, start + rows)) for start in range(0, height, rows)]
+ if len(bands) < 3:
+ for start, stop in bands:
+ yield compressor.compress(_filtered(pixels, bpp, start, stop))
+ else:
+ from collections import deque
+ from concurrent.futures import ThreadPoolExecutor
+ from itertools import islice
+
+ # Bounded lead: deflate is slower at high levels, an unbounded worker would hold the whole filtered image.
+ with ThreadPoolExecutor(max_workers = 1, thread_name_prefix = "png-filter") as pool:
+ todo = iter(bands)
+ futures = deque(
+ pool.submit(_filtered, pixels, bpp, *band) for band in islice(todo, _AHEAD)
+ )
+ try:
+ while futures:
+ data = futures.popleft().result()
+ band = next(todo, None)
+ if band is not None:
+ futures.append(pool.submit(_filtered, pixels, bpp, *band))
+ yield compressor.compress(data)
+ finally:
+ for future in futures:
+ future.cancel()
+ yield compressor.flush()
+
+
+def _chunks(data: bytes) -> Optional[list[tuple[bytes, int, int]]]:
+ if data[:8] != b"\x89PNG\r\n\x1a\n":
+ return None
+ out = []
+ pos = 8
+ while pos + 12 <= len(data):
+ (length,) = struct.unpack(">I", data[pos : pos + 4])
+ out.append((data[pos + 4 : pos + 8], pos, length))
+ pos += 12 + length
+ return out if pos == len(data) else None
+
+
+def _framing(image: Any, mode: str, save_kwargs: dict) -> Optional[tuple[bytes, bytes]]:
+ """Pillow's bytes around the IDATs: a 1x1 crop (keeps ``info``) saved with the same options, real size in IHDR."""
+ buffer = io.BytesIO()
+ image.crop((0, 0, 1, 1)).save(buffer, format = "PNG", **save_kwargs)
+ data = buffer.getvalue()
+ chunks = _chunks(data)
+ if not chunks or chunks[0][0] != b"IHDR" or chunks[0][2] != 13:
+ return None
+ idat = [index for index, chunk in enumerate(chunks) if chunk[0] == b"IDAT"]
+ if not idat or idat != list(range(idat[0], idat[-1] + 1)):
+ return None
+ ihdr = bytearray(data[16:29])
+ if bytes(ihdr[8:13]) != bytes((8, _MODES[mode][1], 0, 0, 0)):
+ return None
+ ihdr[0:8] = struct.pack(">II", image.width, image.height)
+ header = (
+ data[:8]
+ + struct.pack(">I", 13)
+ + b"IHDR"
+ + bytes(ihdr)
+ + struct.pack(">I", zlib.crc32(b"IHDR" + bytes(ihdr)))
+ )
+ first, last = chunks[idat[0]], chunks[idat[-1]]
+ return header + data[33 : first[1]], data[last[1] + 12 + last[2] :]
+
+
+def _encode(image: Any, mode: str, level: int, save_kwargs: dict) -> Optional[bytes]:
+ import numpy as np
+ from PIL import ImageFile
+
+ framing = _framing(image, mode, save_kwargs)
+ if framing is None:
+ return None
+ pixels = np.asarray(image)
+ bpp = _MODES[mode][0]
+ pixels = np.ascontiguousarray(pixels.reshape(image.height, image.width * bpp), dtype = np.uint8)
+ # ImageFile._save's buffer: one full IDAT per buffer, the last one short.
+ bufsize = max(int(ImageFile.MAXBLOCK), image.width * 4)
+ out = io.BytesIO()
+ out.write(framing[0])
+ pending = bytearray()
+
+ def idat(piece: Any) -> None:
+ out.write(struct.pack(">I", len(piece)) + b"IDAT")
+ out.write(piece)
+ out.write(struct.pack(">I", zlib.crc32(piece, zlib.crc32(b"IDAT"))))
+
+ for data in _deflated(pixels, bpp, level):
+ pending += data
+ while len(pending) >= bufsize:
+ idat(pending[:bufsize])
+ del pending[:bufsize]
+ if pending:
+ idat(pending)
+ out.write(framing[1])
+ return out.getvalue()
+
+
+def _probe_image(mode: str) -> Any:
+ """Every filter wins some rows; the stream passes zlib's 32 KiB window and one 64 KiB IDAT buffer."""
+ import numpy as np
+ from PIL import Image
+
+ rng = np.random.default_rng(20261030)
+ bands = len(mode)
+ height, width = 224, 1028 // bands + 1
+ yy, xx = np.mgrid[0:height, 0:width].astype(np.float32)
+ smooth = np.stack(
+ [128 + 100 * np.sin(xx / (11 + 7 * k) + yy / (23 + 5 * k)) for k in range(bands)], -1
+ )
+ pixels = np.clip(smooth + rng.normal(0, 4, smooth.shape), 0, 255).astype(np.uint8)
+ pixels[20:28] = 9
+ pixels[40:44] = pixels[39]
+ pixels[60:170] = rng.integers(0, 256, pixels[60:170].shape, dtype = np.uint8)
+ pixels[180:200, :, :] = (np.arange(width) % 256).astype(np.uint8)[None, :, None]
+ if bands == 1:
+ pixels = pixels[..., 0]
+ return Image.fromarray(pixels, mode)
+
+
+def _pillow(image: Any, save_kwargs: dict) -> bytes:
+ buffer = io.BytesIO()
+ image.save(buffer, format = "PNG", **save_kwargs)
+ return buffer.getvalue()
+
+
+def _proven(mode: str, level: int) -> bool:
+ key = (mode, level)
+ proven = _PROBED.get(key)
+ if proven is not None:
+ return proven
+ with _PROBE_LOCK:
+ proven = _PROBED.get(key)
+ if proven is None:
+ try:
+ from PIL.PngImagePlugin import PngInfo
+
+ info = PngInfo()
+ info.add_text("probe", "x" * 40)
+ probe = _probe_image(mode)
+ kwargs = {"pnginfo": info, "compress_level": level}
+ proven = _encode(probe, mode, level, kwargs) == _pillow(probe, kwargs)
+ except Exception: # noqa: BLE001 - unproven means Pillow encodes
+ proven = False
+ _PROBED[key] = proven
+ return proven
+
+
+def encode(
+ image: Any,
+ *,
+ pnginfo: Any = None,
+ compress_level: int,
+) -> Optional[bytes]:
+ """``image.save(fp, "PNG", pnginfo = ..., compress_level = ...)``'s bytes, or None: the caller uses Pillow."""
+ global engaged
+ mode = getattr(image, "mode", None)
+ if (
+ mode not in _MODES
+ # Level 0 stored blocks follow Pillow's output buffer size.
+ or not 1 <= int(compress_level) <= 9
+ or min(getattr(image, "size", (0, 0))) < 1
+ or not enabled()
+ or not _proven(mode, int(compress_level))
+ ):
+ return None
+ kwargs = {"compress_level": int(compress_level)}
+ if pnginfo is not None:
+ kwargs["pnginfo"] = pnginfo
+ try:
+ data = _encode(image, mode, int(compress_level), kwargs)
+ except Exception: # noqa: BLE001 - Pillow's encoder is always correct
+ return None
+ if data is not None:
+ with _ENGAGED_LOCK:
+ engaged += 1
+ return data
diff --git a/studio/backend/tests/test_png_encode.py b/studio/backend/tests/test_png_encode.py
new file mode 100644
index 00000000000..d68a14dada5
--- /dev/null
+++ b/studio/backend/tests/test_png_encode.py
@@ -0,0 +1,268 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+import io
+
+import pytest
+
+np = pytest.importorskip("numpy")
+pytest.importorskip("PIL")
+from PIL import Image # noqa: E402
+from PIL.PngImagePlugin import PngInfo # noqa: E402
+
+import core.inference.image_gallery as gallery # noqa: E402
+from core.inference import png_encode # noqa: E402
+
+
[email protected](autouse = True)
+def _fresh(monkeypatch, tmp_path):
+ monkeypatch.delenv(png_encode.FAST_ENV, raising = False)
+ monkeypatch.delenv(gallery.PNG_COMPRESS_LEVEL_ENV, raising = False)
+ monkeypatch.setattr(png_encode, "_PROBED", {})
+ monkeypatch.setattr(gallery, "studio_root", lambda: tmp_path)
+
+
+def _fast_here():
+ """False where Pillow's bundled zlib (macOS / Windows wheels) differs from Python's."""
+ saved = dict(png_encode._PROBED)
+ png_encode._PROBED.clear()
+ try:
+ return png_encode._proven("RGB", 1)
+ finally:
+ png_encode._PROBED.clear()
+ png_encode._PROBED.update(saved)
+
+
+FAST_HERE = _fast_here()
+needs_fast = pytest.mark.skipif(
+ not FAST_HERE, reason = "Pillow's zlib differs from Python's here, so Pillow encodes every image"
+)
+
+
+def _pillow(image, **kwargs):
+ buffer = io.BytesIO()
+ image.save(buffer, format = "PNG", **kwargs)
+ return buffer.getvalue()
+
+
+def _pixels(
+ height,
+ width,
+ bands,
+ seed = 0,
+):
+ rng = np.random.default_rng(seed)
+ yy, xx = np.mgrid[0:height, 0:width].astype(np.float32)
+ smooth = np.stack(
+ [128 + 90 * np.sin(xx / (13 + 5 * k) + yy / (29 + 3 * k)) for k in range(bands)], -1
+ )
+ pixels = np.clip(smooth + rng.normal(0, 3, smooth.shape), 0, 255).astype(np.uint8)
+ if height > 8:
+ pixels[height // 8 : height // 4] = 17
+ pixels[height // 4 + 1 : height // 4 + 3] = pixels[height // 4]
+ pixels[height // 2 : height // 2 + height // 4] = rng.integers(
+ 0, 256, pixels[height // 2 : height // 2 + height // 4].shape, dtype = np.uint8
+ )
+ return pixels[..., 0] if bands == 1 else pixels
+
+
+def _image(
+ mode,
+ height,
+ width,
+ seed = 0,
+):
+ return Image.fromarray(_pixels(height, width, len(mode), seed), mode)
+
+
+def _info():
+ info = PngInfo()
+ info.add_text("unsloth", '{"prompt": "a sloth", "seed": 7}')
+ info.add_text("parameters", "a sloth\nSteps: 9, Seed: 7")
+ return info
+
+
[email protected]("mode", ["RGB", "RGBA", "L", "LA"])
[email protected]("size", [(1, 1), (1, 9), (9, 1), (63, 130), (300, 257), (2, 17000)])
[email protected]("level", [1, 6, 9])
+@needs_fast
+def test_bytes_match_pillow(mode, size, level):
+ image = _image(mode, *size, seed = size[0] * 31 + size[1])
+ before = png_encode.engaged
+ data = png_encode.encode(image, pnginfo = _info(), compress_level = level)
+ assert (
+ png_encode._PROBED[(mode, level)] is True
+ ), "the probe must hold where Pillow and zlib agree"
+ assert data == _pillow(image, pnginfo = _info(), compress_level = level)
+ assert png_encode.engaged == before + 1
+
+
+@needs_fast
+def test_bytes_match_pillow_without_text_and_across_idat_buffers():
+ for size in ((1500, 400), (40, 20000)):
+ image = Image.fromarray(
+ np.random.default_rng(3).integers(0, 256, (*size, 3), dtype = np.uint8), "RGB"
+ )
+ assert png_encode.encode(image, compress_level = 1) == _pillow(image, compress_level = 1)
+
+
+@needs_fast
+def test_bytes_match_pillow_for_what_the_image_carries():
+ image = _image("RGB", 40, 50)
+ image.info["transparency"] = (1, 2, 3)
+ image.info["icc_profile"] = bytes(range(128))
+ info = PngInfo()
+ info.add_text("unsloth", "中文 prompt") # not latin-1: an iTXt chunk
+ info.add(b"prVt", b"after the pixels", after_idat = True)
+ data = png_encode.encode(image, pnginfo = info, compress_level = 1)
+ assert data is not None
+ assert data == _pillow(image, pnginfo = info, compress_level = 1)
+
+
[email protected]("mode", ["RGB", "RGBA", "L", "LA"])
+def test_the_probe_spans_more_than_one_idat_buffer(mode):
+ data = _pillow(png_encode._probe_image(mode), compress_level = 9)
+ assert sum(chunk[0] == b"IDAT" for chunk in png_encode._chunks(data)) >= 2
+
+
+@needs_fast
+def test_lazy_png_source_matches_pillow():
+ source = io.BytesIO(_pillow(_image("RGBA", 70, 90), compress_level = 6))
+ expected = _pillow(Image.open(io.BytesIO(source.getvalue())), compress_level = 1)
+ assert png_encode.encode(Image.open(source), compress_level = 1) == expected
+
+
[email protected]("mode", ["P", "1", "I;16", "CMYK"])
+def test_other_modes_are_left_to_pillow(mode):
+ assert png_encode.encode(Image.new(mode, (8, 8)), compress_level = 1) is None
+
+
+def test_level_zero_is_left_to_pillow():
+ assert png_encode.encode(_image("RGB", 64, 64), compress_level = 0) is None
+
+
+def test_kill_switch(monkeypatch):
+ monkeypatch.setenv(png_encode.FAST_ENV, "0")
+ assert png_encode.encode(_image("RGB", 64, 64), compress_level = 1) is None
+
+
+def test_a_failed_probe_keeps_pillow_for_that_mode_and_level(monkeypatch):
+ real = png_encode._deflated
+
+ def other_zlib(pixels, bpp, level):
+ return real(pixels, bpp, 2 if level == 1 else 1)
+
+ monkeypatch.setattr(png_encode, "_deflated", other_zlib)
+ image = _image("RGB", 64, 64)
+ assert png_encode.encode(image, compress_level = 1) is None
+ assert png_encode._PROBED == {("RGB", 1): False}
+ monkeypatch.setattr(png_encode, "_deflated", real)
+ assert png_encode.encode(image, compress_level = 1) is None
+
+
+@needs_fast
+def test_an_encode_error_falls_back(monkeypatch):
+ image = _image("RGB", 64, 64)
+ assert png_encode.encode(image, compress_level = 1) is not None
+
+ def broken(*args, **kwargs):
+ raise MemoryError("no room")
+
+ monkeypatch.setattr(png_encode, "_filtered", broken)
+ assert png_encode.encode(image, compress_level = 1) is None
+
+
+@needs_fast
+def test_the_filter_worker_stays_a_few_bands_ahead_of_deflate(monkeypatch):
+ import threading
+ import time
+
+ real = png_encode._filtered
+ lock = threading.Lock()
+ state = {"filtered": 0, "deflated": 0, "lead": 0}
+
+ def counted(*args):
+ out = real(*args)
+ with lock:
+ state["filtered"] += 1
+ state["lead"] = max(state["lead"], state["filtered"] - state["deflated"])
+ return out
+
+ compressobj = png_encode.zlib.compressobj
+
+ class SlowCompressor:
+ def __init__(self, *args):
+ self.inner = compressobj(*args)
+
+ def compress(self, data):
+ time.sleep(0.01)
+ with lock:
+ state["deflated"] += 1
+ return self.inner.compress(data)
+
+ def flush(self):
+ return self.inner.flush()
+
+ image = _image("RGB", 1200, 400) # 1200 rows of 1201 bytes: 8 bands
+ expected = _pillow(image, compress_level = 1)
+ assert png_encode.encode(image, compress_level = 1) == expected # probe with the real zlib
+ monkeypatch.setattr(png_encode, "_filtered", counted)
+ monkeypatch.setattr(png_encode.zlib, "compressobj", SlowCompressor)
+ assert png_encode.encode(image, compress_level = 1) == expected
+ assert state["filtered"] == state["deflated"] >= 6
+ assert state["lead"] <= png_encode._AHEAD + 1
+
+
+def _meta(index = 0):
+ return {
+ "prompt": "a sloth",
+ "width": 300,
+ "height": 257,
+ "steps": 9,
+ "guidance": 0.0,
+ "seed": 7 + index,
+ "batch_index": index,
+ "model": "m",
+ "created_at": 100.0,
+ }
+
+
[email protected]("level", ["1", "6"])
+def test_gallery_writes_pillows_bytes(monkeypatch, level):
+ monkeypatch.setenv(gallery.PNG_COMPRESS_LEVEL_ENV, level)
+ images = [_image("RGB", 257, 300, seed = i) for i in range(4)]
+ before = png_encode.engaged
+ records = list(gallery.save_many((image, _meta(i)) for i, image in enumerate(images)))
+ assert png_encode.engaged == before + (4 if FAST_HERE else 0)
+ monkeypatch.setenv(png_encode.FAST_ENV, "0")
+ for i, (image, record) in enumerate(zip(images, records)):
+ written = gallery.image_path(record["id"]).read_bytes()
+ recipe = gallery._recipe(_meta(i))
+ assert written == gallery._png_bytes(image, recipe)
+ with Image.open(io.BytesIO(written)) as im:
+ assert im.tobytes() == image.tobytes()
+
+
+def test_gallery_falls_back_to_pillow_when_the_fast_path_steps_aside(monkeypatch):
+ monkeypatch.setattr(png_encode, "encode", lambda *a, **k: None)
+ image = _image("RGB", 64, 64)
+ record = gallery.save(image, _meta())
+ written = gallery.image_path(record["id"]).read_bytes()
+ info = PngInfo()
+ recipe = gallery._recipe(_meta())
+ import json
+
+ info.add_text("unsloth", json.dumps(recipe))
+ info.add_text("parameters", gallery._params_text(recipe))
+ assert written == _pillow(image, pnginfo = info, compress_level = 1)
+
+
+def test_encode_returns_pillows_bytes_or_steps_aside_on_every_platform():
+ image = _image("RGBA", 120, 90, seed = 5)
+ data = png_encode.encode(image, pnginfo = _info(), compress_level = 1)
+ if FAST_HERE:
+ assert data == _pillow(image, pnginfo = _info(), compress_level = 1)
+ else:
+ assert data is None