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: 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.py
index 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 canvas
diff --git a/studio/backend/core/training/diffusion_dit_trainer.py b/studio/backend/core/training/diffusion_dit_trainer.py
index 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.size
scale = 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.py
index 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 np
import torch
from 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.size
scale = resolution / min(original_w, original_h)
resized_w = max(resolution, round(original_w * scale))
@@ -116,7 +112,7 @@ def _load_image_tensor(
crop_left = left
if 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.0
tensor = 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 np
import torch
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))
original_w, original_h = img.size
scale = 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.py
index 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_file
named: dict[str, Any] = {}
diff --git a/studio/backend/routes/training.py b/studio/backend/routes/training.py
index 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_DIRNAME
thumbs_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_mtime
if thumb_path.is_file() and thumb_path.stat().st_mtime >= src_mtime:
return thumb_path
with 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_path
diff --git a/studio/backend/tests/test_diffusion_dataset_api.py b/studio/backend/tests/test_diffusion_dataset_api.py
index 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.py
index 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) != k1
import 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.py
new file mode 100644
index 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]