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: train transparent PNG and WebP images on white instead of black (#12908)
Nilay3d810136c308
diff --git a/studio/backend/core/inference/mcp_images.py b/studio/backend/core/inference/mcp_images.pyindex 013a3e2851a..09b630e5a4f 100644--- a/studio/backend/core/inference/mcp_images.py+++ b/studio/backend/core/inference/mcp_images.py@@ -323,7 +323,7 @@ def png_payloads_per_result(return []-def flattened_rgb(image):+def flattened_rgb(image, background = None):"""RGB with any transparency composited onto white (black for light ink), not dropped.``convert("RGB")`` keeps whatever colour sits UNDER the alpha, and a tool that@@ -351,10 +351,12 @@ def flattened_rgb(image):# Browser canvas exports are RGBA even when opaque; skip the composite (same pixels).if alpha.getextrema()[0] == 255:return rgba.convert("RGB")- # Alpha-weighted: light ink (dark-mode logos, white text) goes onto black, not white.- ink = ImageStat.Stat(ImageChops.multiply(rgba.convert("L"), alpha)).sum[0]- light = 255 * ink > 128 * ImageStat.Stat(alpha).sum[0] > 0- canvas = Image.new("RGB", rgba.size, (0, 0, 0) if light else (255, 255, 255))+ if background is None:+ # Alpha-weighted: light ink (dark-mode logos, white text) goes onto black, not white.+ ink = ImageStat.Stat(ImageChops.multiply(rgba.convert("L"), alpha)).sum[0]+ light = 255 * ink > 128 * ImageStat.Stat(alpha).sum[0] > 0+ background = (0, 0, 0) if light else (255, 255, 255)+ canvas = Image.new("RGB", rgba.size, background)canvas.paste(rgba, mask = alpha)return canvasdiff --git a/studio/backend/core/training/diffusion_dit_trainer.py b/studio/backend/core/training/diffusion_dit_trainer.pyindex d0cf1376020..765f8033ea0 100644--- a/studio/backend/core/training/diffusion_dit_trainer.py+++ b/studio/backend/core/training/diffusion_dit_trainer.py@@ -1514,7 +1514,9 @@ def _open_resized(path, resolution):Returns the resized PIL image and its (rw, rh)."""from PIL import Image, ImageOps- img = ImageOps.exif_transpose(Image.open(path)).convert("RGB")+ from core.inference.mcp_images import flattened_rgb++ img = flattened_rgb(ImageOps.exif_transpose(Image.open(path)), background = (255, 255, 255))w0, h0 = img.sizescale = resolution / min(w0, h0)rw, rh = max(resolution, round(w0 * scale)), max(resolution, round(h0 * scale))diff --git a/studio/backend/core/training/diffusion_lora_trainer.py b/studio/backend/core/training/diffusion_lora_trainer.pyindex 885aba8901e..bea2ba363f8 100644--- a/studio/backend/core/training/diffusion_lora_trainer.py+++ b/studio/backend/core/training/diffusion_lora_trainer.py@@ -89,19 +89,15 @@ def compute_sdxl_add_time_ids(resolution: int) -> tuple[int, int, int, int, int,def _load_image_tensor(path: str, resolution: int, center_crop: bool, random_flip: bool, rng: random.Random) -> tuple[Any, tuple[int, int, int, int, int, int]]:- """Load an image to a normalised CxHxW tensor in [-1, 1] (resize shorter side to- ``resolution``, crop to a square, optional horizontal flip). No torchvision.-- Returns ``(tensor, add_time_ids)`` where add_time_ids is the SDXL micro-conditioning- (original_h, original_w, crop_top, crop_left, target_h, target_w) for THIS sample, so- the U-Net is told the real original size and crop offset (not a fixed uncropped- square). EXIF orientation is applied first so rotated phone photos train upright."""+ """CxHxW pixels in [-1, 1] with SDXL time ids for the EXIF-oriented crop."""import numpy as npimport torchfrom PIL import Image, ImageOps- # Honour EXIF orientation before any geometry, or rotated photos train sideways.- img = ImageOps.exif_transpose(Image.open(path)).convert("RGB")+ from core.inference.mcp_images import flattened_rgb++ # apply EXIF orientation before geometry so rotated photos train upright.+ img = flattened_rgb(ImageOps.exif_transpose(Image.open(path)), background = (255, 255, 255))original_w, original_h = img.sizescale = resolution / min(original_w, original_h)resized_w = max(resolution, round(original_w * scale))@@ -116,7 +112,7 @@ def _load_image_tensor(crop_left = leftif random_flip and rng.random() < 0.5:img = img.transpose(Image.FLIP_LEFT_RIGHT)- # A flip mirrors the crop's left origin, so report the mirrored offset (as diffusers does).+ # mirror the crop origin after a flip to match diffusers.crop_left = max(0, resized_w - resolution - left)arr = np.asarray(img, dtype = np.float32) / 255.0tensor = torch.from_numpy(arr).permute(2, 0, 1) * 2.0 - 1.0@@ -127,17 +123,14 @@ def _load_image_tensor(def _load_image_tensor_planned(path: str, resolution: int, center_crop: bool, u_left: float, u_top: float, flip: bool) -> tuple[Any, tuple[int, int, int, int, int, int]]:- """Deterministic variant of ``_load_image_tensor`` for the latent cache: the crop comes- as unit fractions (mapped uniformly over the same inclusive integer range ``randint``- draws from) and the flip as a bool. Geometry (EXIF transpose, LANCZOS short-side resize,- the SDXL ``add_time_ids`` from the original size + actual crop offset) matches- ``_load_image_tensor`` exactly; ``center_crop`` reproduces the legacy floor-div center- bit-for-bit. The flip does not change time_ids (only the mirrored crop_left does)."""+ """cache loader preserving ``_load_image_tensor`` crop, flip, and legacy center semantics."""import numpy as npimport torchfrom PIL import Image, ImageOps- img = ImageOps.exif_transpose(Image.open(path)).convert("RGB")+ from core.inference.mcp_images import flattened_rgb++ img = flattened_rgb(ImageOps.exif_transpose(Image.open(path)), background = (255, 255, 255))original_w, original_h = img.sizescale = resolution / min(original_w, original_h)resized_w = max(resolution, round(original_w * scale))diff --git a/studio/backend/core/training/diffusion_train_extras.py b/studio/backend/core/training/diffusion_train_extras.pyindex a6a18592f43..727cf570c28 100644--- a/studio/backend/core/training/diffusion_train_extras.py+++ b/studio/backend/core/training/diffusion_train_extras.py@@ -202,11 +202,12 @@ def save_ema_adapter(ema: "LoRAEMA", transformer: Any, spec_save: Any, out_dir:_CACHE_VERSION = "1"+# v2 composites transparent images onto white before encoding.+_LATENT_CACHE_VERSION = "2"def _file_content_hash(path: str) -> str:- """sha256 of the file bytes (truncated hex): renames/moves keep their cache- entries, edits invalidate them."""+ """return a truncated sha256; renames preserve cache entries while edits invalidate them."""h = hashlib.sha256()with open(path, "rb") as f:for chunk in iter(lambda: f.read(1 << 20), b""):@@ -337,7 +338,8 @@ class PersistentConditioningCache:geom = f"{shape[0]}x{shape[1]}" if shape else str(self.resolution)var = f"{u_left:.6f}_{u_top:.6f}_{int(bool(flip))}"return (- f"lat_v{_CACHE_VERSION}_{self.family}_{geom}_" f"{_file_content_hash(image_path)}_{var}"+ f"lat_v{_LATENT_CACHE_VERSION}_{self.family}_{geom}_"+ f"{_file_content_hash(image_path)}_{var}")def text_key(self, caption: str) -> str:@@ -350,8 +352,7 @@ class PersistentConditioningCache:return self.path_for(key).is_file()def put(self, key: str, tensors: Iterable[Any]) -> None:- """Store an ordered tuple of tensors (None entries allowed: their slot- indices are recorded in the metadata so ``get`` restores them)."""+ """store an ordered tensor tuple with None slots recorded for exact reconstruction."""from safetensors.torch import save_filenamed: dict[str, Any] = {}diff --git a/studio/backend/routes/training.py b/studio/backend/routes/training.pyindex 4bdecc9716f..bf85643ad3a 100644--- a/studio/backend/routes/training.py+++ b/studio/backend/routes/training.py@@ -4370,16 +4370,17 @@ async def get_diffusion_dataset_image(def make_thumb() -> Path:from PIL import Image+ from core.inference.mcp_images import flattened_rgb+thumbs_dir = folder / _THUMBS_DIRNAMEthumbs_dir.mkdir(exist_ok = True)- # Key on the full filename, not the stem: two images sharing a stem would collide on one cache file and the- # mtime-newer entry would be served for both.- thumb_path = thumbs_dir / f"{image_path.name}_{size}.jpg"+ # use the full filename because same-stem images would otherwise share a cache entry+ thumb_path = thumbs_dir / f"{image_path.name}_{size}_w.jpg"src_mtime = image_path.stat().st_mtimeif thumb_path.is_file() and thumb_path.stat().st_mtime >= src_mtime:return thumb_pathwith Image.open(image_path) as im:- im = im.convert("RGB")+ im = flattened_rgb(im, background = (255, 255, 255))im.thumbnail((size, size), Image.LANCZOS)im.save(thumb_path, format = "JPEG", quality = 85)return thumb_pathdiff --git a/studio/backend/tests/test_diffusion_dataset_api.py b/studio/backend/tests/test_diffusion_dataset_api.pyindex 2d12f5ba923..eef1880fe24 100644--- a/studio/backend/tests/test_diffusion_dataset_api.py+++ b/studio/backend/tests/test_diffusion_dataset_api.py@@ -258,7 +258,35 @@ def test_thumb_cache_key_distinguishes_same_stem_extensions(client, ds_root):client.get("/api/train/diffusion/dataset/d/image/sample.png?thumb=32")client.get("/api/train/diffusion/dataset/d/image/sample.jpg?thumb=32")thumbs = sorted(p.name for p in (folder / ".thumbs").glob("*.jpg"))- assert thumbs == ["sample.jpg_32.jpg", "sample.png_32.jpg"]+ assert thumbs == ["sample.jpg_32_w.jpg", "sample.png_32_w.jpg"]+++def test_thumbnail_of_transparent_image_shows_white_background(client, ds_root):+ folder = ds_root / "d"+ folder.mkdir()+ sticker = Image.new("RGBA", (64, 64), (0, 0, 0, 0))+ sticker.paste((255, 220, 0, 255), (16, 16, 48, 48))+ sticker.save(folder / "sticker.png", format = "PNG")++ r = client.get("/api/train/diffusion/dataset/d/image/sticker.png?thumb=64")++ assert r.status_code == 200+ thumb = Image.open(io.BytesIO(r.content)).convert("RGB")+ assert min(thumb.getpixel((2, 2))) > 245+++def test_thumbnail_cached_before_white_flattening_is_not_served(client, ds_root):+ folder = ds_root / "d"+ (folder / ".thumbs").mkdir(parents = True)+ Image.new("RGBA", (64, 64), (0, 0, 0, 0)).save(folder / "sticker.png", format = "PNG")+ Image.new("RGB", (64, 64), (0, 0, 0)).save(+ folder / ".thumbs" / "sticker.png_64.jpg", format = "JPEG"+ )++ r = client.get("/api/train/diffusion/dataset/d/image/sticker.png?thumb=64")++ assert r.status_code == 200+ assert min(Image.open(io.BytesIO(r.content)).convert("RGB").getpixel((2, 2))) > 245# ── traversal / validation ───────────────────────────────────────────────────diff --git a/studio/backend/tests/test_diffusion_train_extras.py b/studio/backend/tests/test_diffusion_train_extras.pyindex 34237204061..c96619f2c77 100644--- a/studio/backend/tests/test_diffusion_train_extras.py+++ b/studio/backend/tests/test_diffusion_train_extras.py@@ -151,10 +151,10 @@ def test_cache_key_tracks_content_family_and_resolution(tmp_path):c3 = PersistentConditioningCache(tmp_path / "cc", "qwen-image", 512)v = (0.5, 0.5, False)k1 = c1.latent_key(img, v)- assert c2.latent_key(img, v) != k1 # resolution in the key- assert c3.latent_key(img, v) != k1 # family in the key- assert c1.latent_key(img, (0.5, 0.5, True)) != k1 # variant in the key- # Editing the file content invalidates the key; a pure rename does not.+ assert c2.latent_key(img, v) != k1+ assert c3.latent_key(img, v) != k1+ assert c1.latent_key(img, (0.5, 0.5, True)) != k1+ # content edits invalidate keys; renames do not.img2 = _make_image(tmp_path, "y.png", color = (0, 255, 0))assert c1.latent_key(img2, v) != k1import shutil@@ -164,6 +164,15 @@ def test_cache_key_tracks_content_family_and_resolution(tmp_path):assert c1.latent_key(str(renamed), v) == k1+def test_latent_cache_misses_entries_encoded_before_white_flattening(tmp_path):+ cache = PersistentConditioningCache(tmp_path / "cc", "qwen-image", 512)+ img = _make_image(tmp_path)+ stale = cache.latent_key(img, (0.5, 0.5, False)).replace("lat_v2_", "lat_v1_", 1)+ cache.put(stale, (torch.zeros(1), torch.zeros(1)))+ assert stale != cache.latent_key(img, (0.5, 0.5, False))+ assert not cache.has(cache.latent_key(img, (0.5, 0.5, False)))++def test_cache_corrupt_entry_returns_none(tmp_path):cache = PersistentConditioningCache(tmp_path / "cc", "flux.1", 512)cache.path_for("bad_key").write_bytes(b"not a safetensors file")diff --git a/studio/backend/tests/test_diffusion_train_transparency.py b/studio/backend/tests/test_diffusion_train_transparency.pynew file mode 100644index 00000000000..d4c49f4ad30--- /dev/null+++ b/studio/backend/tests/test_diffusion_train_transparency.py@@ -0,0 +1,76 @@+# 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 random++import pytest++torch = pytest.importorskip("torch")+from PIL import Image, ImageDraw++from core.training.diffusion_dit_trainer import _load_pixel_tensor, _load_pixel_tensor_planned+from core.training.diffusion_lora_trainer import _load_image_tensor, _load_image_tensor_planned++SIZE = 64+YELLOW = (255, 220, 0)+++def _draw_sticker(draw, outline, fill):+ draw.ellipse((8, 8, SIZE - 9, SIZE - 9), fill = outline)+ draw.ellipse((14, 14, SIZE - 15, SIZE - 15), fill = fill)+++def _write_sticker(path, mode):+ # exporters commonly store fully transparent pixels as (0, 0, 0, 0).+ if mode == "P":+ img = Image.new("P", (SIZE, SIZE), 0)+ img.putpalette([0, 0, 0, *YELLOW, 0, 0, 0])+ _draw_sticker(ImageDraw.Draw(img), 2, 1)+ img.save(path, transparency = 0)+ return+ if mode == "LA":+ img = Image.new("LA", (SIZE, SIZE), (0, 0))+ _draw_sticker(ImageDraw.Draw(img), (0, 255), (200, 255))+ else:+ img = Image.new("RGBA", (SIZE, SIZE), (0, 0, 0, 0))+ _draw_sticker(ImageDraw.Draw(img), (0, 0, 0, 255), (*YELLOW, 255))+ img.save(path, lossless = True)+++def _loaders():+ rng = random.Random(0)+ return {+ "sdxl": lambda p: _load_image_tensor(str(p), SIZE, True, False, rng)[0],+ "sdxl_cached": lambda p: _load_image_tensor_planned(str(p), SIZE, True, 0.0, 0.0, False)[0],+ "dit": lambda p: _load_pixel_tensor(str(p), SIZE, True, False, rng),+ "dit_cached": lambda p: _load_pixel_tensor_planned(str(p), SIZE, True, 0.0, 0.0, False),+ }++[email protected]("loader", ["sdxl", "sdxl_cached", "dit", "dit_cached"])+ "name, mode",+ [("rgba.png", "RGBA"), ("rgba.webp", "RGBA"), ("la.png", "LA"), ("palette.png", "P")],+)+def test_transparent_training_image_trains_on_white_with_its_outline(tmp_path, loader, name, mode):+ path = tmp_path / name+ _write_sticker(path, mode)++ tensor = _loaders()[loader](path)+ pixel = lambda x, y: [round(v) for v in ((tensor[:, y, x] + 1.0) * 127.5).tolist()]++ assert pixel(2, 2) == [255, 255, 255]+ assert pixel(SIZE // 2, 10) == [0, 0, 0]+ assert pixel(SIZE // 2, SIZE // 2) != [255, 255, 255]++[email protected]("loader", ["sdxl", "dit"])+def test_opaque_training_image_is_unchanged(tmp_path, loader):+ path = tmp_path / "opaque.png"+ Image.new("RGB", (SIZE, SIZE), (10, 20, 30)).save(path)++ tensor = _loaders()[loader](path)++ assert [round(v) for v in ((tensor[:, 5, 5] + 1.0) * 127.5).tolist()] == [10, 20, 30]