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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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, Iteratorfrom pathlib import Pathfrom typing import Any, Optional-from core.inference import gallery_flags+from core.inference import gallery_flags, png_encodefrom loggers import get_loggerfrom utils.account_context import is_owner_contextfrom 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 databuf = 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.pynew file mode 100644index 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 datadiff --git a/studio/backend/tests/test_png_encode.py b/studio/backend/tests/test_png_encode.pynew file mode 100644index 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