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: load Images strip tiles as thumbnails instead of full PNGs (#12228)

oobabooga7965e20ccd80
diff --git a/studio/backend/core/inference/image_gallery.py b/studio/backend/core/inference/image_gallery.py
index 09739c036a8..a4a86f1ced4 100644
--- a/studio/backend/core/inference/image_gallery.py
+++ b/studio/backend/core/inference/image_gallery.py
@@ -171,6 +171,21 @@ def owned_image_path(image_id: str) -> Optional[Path]:
return path
+def thumbnail(path: Path, size: int) -> bytes:
+ """Return a WebP thumbnail with its longest side at most ``size`` pixels."""
+ import io
+
+ from PIL import Image
+
+ with Image.open(path) as im:
+ im.thumbnail((size, size), Image.LANCZOS)
+ if im.mode not in ("RGB", "RGBA"):
+ im = im.convert("RGBA" if "A" in im.getbands() or "transparency" in im.info else "RGB")
+ buf = io.BytesIO()
+ im.save(buf, format = "WEBP", quality = 85, method = 4)
+ return buf.getvalue()
+
+
def _mtime(path: Path) -> float:
try:
return path.stat().st_mtime
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 6ae08f6c001..2a567075a3d 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -41729,21 +41729,29 @@ async def list_gallery_images(
@studio_router.get("/images/gallery/{image_id}/file")
async def get_gallery_image_file(
- image_id: str, current_subject: str = Depends(get_current_subject)
+ image_id: str,
+ thumb: Optional[int] = None,
+ current_subject: str = Depends(get_current_subject),
):
+ """Serve the original PNG or a WebP thumbnail when ``thumb`` is set."""
from core.inference import image_gallery
# Ownership-gate the serve like delete/clear: resolve only an Unsloth-owned PNG, so a guessed stem cannot stream out a foreign file.
path = await asyncio.to_thread(image_gallery.owned_image_path, image_id)
if path is None:
raise HTTPException(status_code = 404, detail = "Image not found.")
- data = await asyncio.to_thread(path.read_bytes)
# Immutable content (id is unique per image), so let the browser cache it.
- return Response(
- content = data,
- media_type = "image/png",
- headers = {"Cache-Control": "private, max-age=31536000, immutable"},
- )
+ headers = {"Cache-Control": "private, max-age=31536000, immutable"}
+ if thumb is not None:
+ size = max(32, min(1024, thumb))
+ try:
+ data = await asyncio.to_thread(image_gallery.thumbnail, path, size)
+ except Exception as exc: # noqa: BLE001 -- fall back to the PNG
+ logger.warning("Gallery thumbnail failed for %s: %s", image_id, exc)
+ else:
+ return Response(content = data, media_type = "image/webp", headers = headers)
+ data = await asyncio.to_thread(path.read_bytes)
+ return Response(content = data, media_type = "image/png", headers = headers)
@studio_router.post("/search-images/lookup")
diff --git a/studio/backend/tests/test_diffusion_routes.py b/studio/backend/tests/test_diffusion_routes.py
index 8fba0a10082..59688f7f167 100644
--- a/studio/backend/tests/test_diffusion_routes.py
+++ b/studio/backend/tests/test_diffusion_routes.py
@@ -331,6 +331,40 @@ def test_load_generate_status_unload_roundtrip(client):
def test_gallery_serve_refuses_unowned_id(client):
# The serve route resolves through the ownership guard, so a guessed stem is a 404, not a stream of foreign bytes.
assert client.get("/api/inference/images/gallery/family-photo/file").status_code == 404
+ assert (
+ client.get("/api/inference/images/gallery/family-photo/file?thumb=256").status_code == 404
+ )
+
+
+def test_gallery_serve_thumb_is_a_webp_and_falls_back_to_the_png(client, monkeypatch):
+ _post_load(
+ client,
+ model_path = "unsloth/Z-Image-Turbo-GGUF",
+ gguf_filename = "z-image-turbo-Q4_K_S.gguf",
+ base_repo = "unsloth/Z-Image-base",
+ )
+ url = _post_generate(client, prompt = "a sloth", seed = 7).json()["images"][0]["url"]
+ sizes = []
+
+ def _thumbnail(path, size):
+ sizes.append(size)
+ return b"WEBP"
+
+ monkeypatch.setattr(gallery_module, "thumbnail", _thumbnail)
+ thumb = client.get(f"{url}?thumb=5000")
+ assert thumb.headers["content-type"] == "image/webp" and thumb.content == b"WEBP"
+ assert sizes == [1024]
+ assert client.get(f"{url}?thumb=0").headers["content-type"] == "image/webp"
+ assert sizes == [1024, 32]
+ original = client.get(url)
+ assert original.headers["content-type"] == "image/png" and original.content == b"PNG"
+
+ def _undecodable(path, size):
+ raise OSError("truncated PNG")
+
+ monkeypatch.setattr(gallery_module, "thumbnail", _undecodable)
+ fallback = client.get(f"{url}?thumb=256")
+ assert fallback.headers["content-type"] == "image/png" and fallback.content == b"PNG"
def test_generate_holds_progress_active_during_persist(client, monkeypatch):
diff --git a/studio/backend/tests/test_image_gallery.py b/studio/backend/tests/test_image_gallery.py
index c3062eaf0b3..75ef97e1032 100644
--- a/studio/backend/tests/test_image_gallery.py
+++ b/studio/backend/tests/test_image_gallery.py
@@ -532,3 +532,11 @@ def test_save_looks_up_the_folder_after_encoding(tmp_path, monkeypatch):
monkeypatch.setattr(gallery, "gallery_dir", lambda: order.append("dir") or tmp_path)
gallery.save(Image.new("RGB", (4, 4)), {"prompt": "p"})
assert order[:2] == ["encode", "dir"]
+
+
+def test_thumbnail_is_a_downscaled_webp_of_the_png():
+ record = gallery.save(Image.new("RGB", (64, 32), (200, 10, 10)), _meta())
+ data = gallery.thumbnail(gallery.image_path(record["id"]), 16)
+ with Image.open(io.BytesIO(data)) as im:
+ assert im.format == "WEBP"
+ assert im.size == (16, 8)
diff --git a/studio/frontend/src/features/images/api.ts b/studio/frontend/src/features/images/api.ts
index 0d5f96acf54..f27fe0a054a 100644
--- a/studio/frontend/src/features/images/api.ts
+++ b/studio/frontend/src/features/images/api.ts
@@ -553,6 +553,11 @@ export async function fetchGalleryObjectUrl(
return { url: URL.createObjectURL(blob), bytes: blob.size };
}
+/** Thumbnail URL for use with fetchGalleryObjectUrl. */
+export function galleryThumbnailUrl(url: string, thumb = 256): string {
+ return `${url}?thumb=${thumb}`;
+}
+
// Diffusion LoRA training. Mirrors DiffusionTrainingStartRequest on the backend; only the paths
// are required.
export interface DiffusionTrainingStartRequest {
diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsx
index 04469756919..2c2eefcfa2b 100644
--- a/studio/frontend/src/features/images/images-page.tsx
+++ b/studio/frontend/src/features/images/images-page.tsx
@@ -219,6 +219,7 @@ import {
fetchGalleryBlob,
fetchGalleryResponse,
fetchGalleryObjectUrl,
+ galleryThumbnailUrl,
generateDiffusionImage,
getDiffusionLoadProgress,
getDiffusionStatus,
@@ -428,6 +429,9 @@ const galleryCache: {
srcById: BlobUrlCache;
// Ids with a fetch in flight, so concurrent ensureSrc calls do not double-fetch and leak a duplicate object URL.
inflight: Set<string>;
+ // Keep thumbnails separate from originals used for viewing and downloads.
+ thumbById: BlobUrlCache;
+ thumbInflight: Set<string>;
// Ids deleted while their PNG was still downloading: a fetch landing afterwards must throw its blob away.
deleted: Set<string>;
} = {
@@ -437,6 +441,8 @@ const galleryCache: {
quant: null,
srcById: new BlobUrlCache(IMAGE_BLOB_BUDGET_BYTES),
inflight: new Set(),
+ thumbById: new BlobUrlCache(32 * 1024 * 1024),
+ thumbInflight: new Set(),
deleted: new Set(),
};
@@ -1495,9 +1501,12 @@ export function ImagesPage({
const [srcById, setSrcById] = useState<Record<string, string>>(() =>
galleryCache.srcById.toRecord(),
);
+ const [thumbById, setThumbById] = useState<Record<string, string>>(() =>
+ galleryCache.thumbById.toRecord(),
+ );
// Guards a "load more" so a fast scroll cannot fire several at once.
const loadingMore = useRef(false);
- // The gallery strip, used as the IntersectionObserver root so a tile PNG is fetched as it nears view.
+ // Observer root for loading thumbnails near the visible strip.
const stripRef = useRef<HTMLDivElement | null>(null);
// Ids currently intersecting the strip; the blob cache never evicts these.
const visibleIds = useRef<Set<string>>(new Set());
@@ -1804,6 +1813,7 @@ export function ImagesPage({
[images, selectedId],
);
const selectedSrc = selected ? srcById[selected.id] : undefined;
+ const selectedThumb = selected ? thumbById[selected.id] : undefined;
const [viewerId, setViewerId] = useState<string | null>(null);
const viewerImage = viewerId ? (images.find((image) => image.id === viewerId) ?? null) : null;
const viewerSrc = viewerImage ? srcById[viewerImage.id] : undefined;
@@ -1849,6 +1859,37 @@ export function ImagesPage({
}
}, []);
+ // Fetch a thumbnail unless the tile already has a cached image or pending request.
+ const ensureThumb = useCallback(async (image: GalleryImage) => {
+ if (
+ galleryCache.thumbById.has(image.id) ||
+ galleryCache.srcById.has(image.id) ||
+ galleryCache.thumbInflight.has(image.id)
+ )
+ return;
+ galleryCache.thumbInflight.add(image.id);
+ try {
+ const { url, bytes } = await fetchGalleryObjectUrl(galleryThumbnailUrl(image.url));
+ if (galleryCache.deleted.has(image.id)) {
+ URL.revokeObjectURL(url);
+ return;
+ }
+ galleryCache.thumbById.set(image.id, url, bytes);
+ const evicted = galleryCache.thumbById.prune(
+ new Set([image.id, ...visibleIds.current, galleryCache.selectedId ?? ""]),
+ );
+ setThumbById((prev) => {
+ const next = { ...prev, [image.id]: url };
+ for (const id of evicted) delete next[id];
+ return next;
+ });
+ } catch {
+ // Leave it without a src; the tile shows a placeholder.
+ } finally {
+ galleryCache.thumbInflight.delete(image.id);
+ }
+ }, []);
+
// Bumped by every LOCAL change to the strip. A resync started before one holds a snapshot the
// listing cannot reconcile with what the user just did.
const stripEpoch = useRef(0);
@@ -1877,12 +1918,12 @@ export function ImagesPage({
setHasMore(page.has_more);
// No visibility signal without IntersectionObserver (jsdom / old webview), so keep the eager fetch there.
if (typeof IntersectionObserver === "undefined") {
- page.images.forEach((image) => void ensureSrc(image));
+ page.images.forEach((image) => void ensureThumb(image));
}
} catch {
// Best-effort: a failed gallery load should not block the page.
}
- }, [ensureSrc]);
+ }, [ensureThumb]);
// Load the next older page. offset = how many are loaded so far; a new image sorts to the front on the backend too.
const loadMore = useCallback(async () => {
@@ -1909,17 +1950,16 @@ export function ImagesPage({
galleryCache.hasMore = page.has_more;
setHasMore(page.has_more);
if (typeof IntersectionObserver === "undefined") {
- page.images.forEach((image) => void ensureSrc(image));
+ page.images.forEach((image) => void ensureThumb(image));
}
} catch {
// transient; the user can scroll again to retry
} finally {
loadingMore.current = false;
}
- }, [ensureSrc]);
+ }, [ensureThumb]);
- // A gallery page holds PAGE_SIZE multi-megabyte PNGs and an object URL lives until the page
- // closes, so fetch a tile as it nears the strip edge instead. Mirrors Video.
+ // Load thumbnails as tiles approach the visible strip.
useEffect(() => {
const root = stripRef.current;
if (!root || typeof IntersectionObserver === "undefined") return;
@@ -1935,8 +1975,9 @@ export function ImagesPage({
}
visibleIds.current.add(id);
galleryCache.srcById.touch(id);
+ galleryCache.thumbById.touch(id);
const image = images.find((i) => i.id === id);
- if (image) void ensureSrc(image);
+ if (image) void ensureThumb(image);
}
},
// rootMargin applies to the ROOT box only, so the root must be the scrolling strip; the
@@ -1945,7 +1986,7 @@ export function ImagesPage({
);
for (const tile of root.querySelectorAll("[data-image-id]")) io.observe(tile);
return () => io.disconnect();
- }, [images, ensureSrc]);
+ }, [images, ensureThumb]);
// The preview is what the user looks at, so the selected image is fetched whether or not its tile is on screen.
useEffect(() => {
@@ -1960,12 +2001,18 @@ export function ImagesPage({
const dropFromStrip = useCallback((id: string, discardBlob: boolean) => {
if (discardBlob) {
galleryCache.srcById.delete(id); // revokes the URL with the entry
+ galleryCache.thumbById.delete(id);
galleryCache.deleted.add(id);
setSrcById((prev) => {
const next = { ...prev };
delete next[id];
return next;
});
+ setThumbById((prev) => {
+ const next = { ...prev };
+ delete next[id];
+ return next;
+ });
}
visibleIds.current.delete(id);
stripEpoch.current += 1;
@@ -2032,12 +2079,12 @@ export function ImagesPage({
setImages(collected);
setHasMore(more);
if (typeof IntersectionObserver === "undefined") {
- collected.forEach((image) => void ensureSrc(image));
+ collected.forEach((image) => void ensureThumb(image));
}
return;
}
},
- [ensureSrc],
+ [ensureThumb],
);
// This page stays mounted across route changes, so an archive restore would not reach the
@@ -5490,6 +5537,18 @@ export function ImagesPage({
/>
</div>
</>
+ ) : selected && selectedThumb ? (
+ // Match the original's display size while loading; actions require the original.
+ // Leave the box unpainted because object-contain can leave empty space.
+ <>
+ <img
+ src={selectedThumb}
+ alt={selected.prompt}
+ style={{ maxWidth: selected.width, maxHeight: selected.height }}
+ className="size-full object-contain"
+ />
+ <Spinner className="absolute size-8 text-muted-foreground" />
+ </>
) : selected ? (
// The selected record's blob is still loading; spin in place.
<div className="flex flex-col items-center gap-3 text-muted-foreground">
@@ -5575,9 +5634,9 @@ export function ImagesPage({
onClick={() => setSelectedId(image.id)}
className="relative size-full overflow-hidden rounded-[10px] bg-muted/40 outline-none ring-1 ring-transparent transition-shadow hover:ring-border focus-visible:ring-2 focus-visible:ring-ring"
>
- {srcById[image.id] ? (
+ {(thumbById[image.id] ?? srcById[image.id]) ? (
<img
- src={srcById[image.id]}
+ src={thumbById[image.id] ?? srcById[image.id]}
alt={image.prompt}
draggable={false}
className="size-full object-cover"
diff --git a/studio/frontend/tests/images-gallery-thumbnails.test.ts b/studio/frontend/tests/images-gallery-thumbnails.test.ts
new file mode 100644
index 00000000000..38ba2acf830
--- /dev/null
+++ b/studio/frontend/tests/images-gallery-thumbnails.test.ts
@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// Check thumbnail/original separation in source because the page has no DOM test harness.
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+function source(path: string): string {
+ return readFileSync(
+ fileURLToPath(new URL(path, import.meta.url)),
+ "utf8",
+ ).replace(/\r\n/g, "\n");
+}
+
+function between(text: string, start: string, end: string): string {
+ const from = text.indexOf(start);
+ const to = text.indexOf(end, from + start.length);
+ if (from === -1 || to <= from) {
+ throw new Error(`markers not found: ${start} / ${end}`);
+ }
+ return text.slice(from, to);
+}
+
+const page = source("../src/features/images/images-page.tsx");
+
+test("strip tiles fetch and show thumbnails, falling back to a cached original", () => {
+ const strip = between(
+ page,
+ "{(thumbById[image.id] ?? srcById[image.id]) ? (",
+ "{/* Selection marker",
+ );
+ assert.ok(strip.includes("src={thumbById[image.id] ?? srcById[image.id]}"));
+
+ const observer = between(page, "const io = new IntersectionObserver(", "return () => io.disconnect();");
+ assert.ok(observer.includes("void ensureThumb(image);"));
+ assert.ok(!observer.includes("ensureSrc("));
+ assert.ok(page.includes("fetchGalleryObjectUrl(galleryThumbnailUrl(image.url))"));
+ // The canvas shows the selected thumbnail while its original loads, even with the tile off-screen.
+ const thumbPrune = between(page, "galleryCache.thumbById.prune(", ");");
+ assert.ok(thumbPrune.includes("galleryCache.selectedId"));
+});
+
+test("the canvas, viewer and downloads read only the original", () => {
+ assert.ok(page.includes("const selectedSrc = selected ? srcById[selected.id] : undefined;"));
+ assert.ok(page.includes("const viewerSrc = viewerImage ? srcById[viewerImage.id] : undefined;"));
+ // The selected record is fetched in full whether or not its tile is on screen.
+ const preview = between(page, "// The preview is what the user looks at", "// Drop an image from the strip.");
+ assert.ok(preview.includes("await ensureSrc(selected);"));
+
+ const canvas = between(page, "{selected && selectedSrc ? (", ") : selected && selectedThumb ? (");
+ assert.ok(canvas.includes("src={selectedSrc}"));
+ for (const format of ["png", "jpeg", "webp"]) {
+ assert.ok(canvas.includes(`downloadImage(selectedSrc, selected, "${format}")`));
+ }
+ assert.ok(!canvas.includes("thumbById"));
+ assert.ok(!canvas.includes("selectedThumb"));
+
+ const quickDownload = between(page, "const handleQuickDownload = useCallback(", "const stripReorder");
+ assert.ok(quickDownload.includes("srcById[image.id]"));
+ assert.ok(quickDownload.includes("fetchGalleryBlob(image.url)"));
+ assert.ok(!quickDownload.includes("thumbById"));
+});
+
+test("the thumbnail placeholder offers no action that needs the original", () => {
+ const placeholder = between(page, ") : selected && selectedThumb ? (", ") : selected ? (");
+ assert.ok(placeholder.includes("src={selectedThumb}"));
+ for (const action of ["downloadImage", "openViewer", "GalleryItemMenu", "RecipePopover", "onClick"]) {
+ assert.ok(!placeholder.includes(action), action);
+ }
+});