sgl-project/sglang · error · ValueError

Image is fully transparent

Error message

Image is fully transparent

What it means

Raised by recenter_image in mesh3d_utils.py when, after converting an image to RGBA and inspecting its alpha channel, every pixel has alpha == 0 — i.e. the image contains no visible content. The function crops to the alpha bounding box, so an empty mask leaves it nothing to operate on.

Solutions

  1. Inspect the input image's alpha channel (np.array(img)[:,:,3].any()) before calling recenter_image
  2. Check the upstream producer of the image (mask/matting model) — an all-transparent output usually means the source step failed, not this API
  3. If the image is meant to be opaque, convert with a white background instead of straight convert('RGBA') (paste onto opaque canvas)
  4. If transparency is expected, validate the file renders correctly in an image viewer; re-export it

Example fix

// before
img = Image.open(path)
recenter_image(img)

// after
img = Image.open(path).convert("RGBA")
if not (np.array(img)[:, :, 3] > 0).any():
    raise ValueError(f"{path} is fully transparent; regenerate it")
recenter_image(img)
Defensive patterns

Strategy: validation

Validate before calling

import numpy as np
from PIL import Image

def has_visible_content(img: Image.Image) -> bool:
    rgba = img.convert("RGBA")
    return bool((np.array(rgba)[:, :, 3] > 0).any())

img = Image.open(path)
if not has_visible_content(img):
    raise ValueError(f"{path} is fully transparent")

Try / catch

try:
    recenter_image(img)
except ValueError as e:
    if "fully transparent" in str(e):
        # regenerate the source image / re-run matting upstream
        raise

Prevention

When it happens

Trigger: Calling _load_input_image / recenter_image on an RGBA (or transparent-converted) image whose alpha channel is entirely zero; e.g. an SVG/PNG render that came out fully transparent, or a mask generation step upstream produced an all-empty mask.

Common situations: Broken transparent PNG exports from design tools; upstream alpha/matte generation failing (e.g. rembg returning an empty result); images whose content lives in RGB but alpha got zeroed by a prior compositing step; corrupted image downloads.

Related errors


AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/d2c469247f5e37b1. Report an issue: GitHub.

Appendix: source

Thrown at python/sglang/multimodal_gen/runtime/utils/mesh3d_utils.py:920

    image_pts = repeat(image_pt, "c h w -> b c h w", b=1)
    return image_pts


def recenter_image(image, border_ratio=0.2):
    """Recenter a PIL image, cropping to non-transparent content with a border."""
    from PIL import Image as PILImage

    if image.mode == "RGB":
        return image
    elif image.mode == "L":
        return image.convert("RGB")
    if image.mode != "RGBA":
        image = image.convert("RGBA")

    alpha_channel = np.array(image)[:, :, 3]
    non_zero_indices = np.argwhere(alpha_channel > 0)
    if non_zero_indices.size == 0:
        raise ValueError("Image is fully transparent")

    min_row, min_col = non_zero_indices.min(axis=0)
    max_row, max_col = non_zero_indices.max(axis=0)

    cropped_image = image.crop((min_col, min_row, max_col + 1, max_row + 1))

    width, height = cropped_image.size
    border_width = int(width * border_ratio)
    border_height = int(height * border_ratio)

    new_width = width + 2 * border_width
    new_height = height + 2 * border_height
    square_size = max(new_width, new_height)

    new_image = PILImage.new("RGBA", (square_size, square_size), (255, 255, 255, 0))

    paste_x = (square_size - new_width) // 2 + border_width
    paste_y = (square_size - new_height) // 2 + border_height

View on GitHub (pinned to 0132848349)