{"record":{"id":"d2c469247f5e37b1","repo":"sgl-project/sglang","slug":"image-is-fully-transparent","errorCode":null,"errorMessage":"Image is fully transparent","messagePattern":"Image is fully transparent","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/utils/mesh3d_utils.py","lineNumber":920,"sourceCode":"    image_pts = repeat(image_pt, \"c h w -> b c h w\", b=1)\n    return image_pts\n\n\ndef recenter_image(image, border_ratio=0.2):\n    \"\"\"Recenter a PIL image, cropping to non-transparent content with a border.\"\"\"\n    from PIL import Image as PILImage\n\n    if image.mode == \"RGB\":\n        return image\n    elif image.mode == \"L\":\n        return image.convert(\"RGB\")\n    if image.mode != \"RGBA\":\n        image = image.convert(\"RGBA\")\n\n    alpha_channel = np.array(image)[:, :, 3]\n    non_zero_indices = np.argwhere(alpha_channel > 0)\n    if non_zero_indices.size == 0:\n        raise ValueError(\"Image is fully transparent\")\n\n    min_row, min_col = non_zero_indices.min(axis=0)\n    max_row, max_col = non_zero_indices.max(axis=0)\n\n    cropped_image = image.crop((min_col, min_row, max_col + 1, max_row + 1))\n\n    width, height = cropped_image.size\n    border_width = int(width * border_ratio)\n    border_height = int(height * border_ratio)\n\n    new_width = width + 2 * border_width\n    new_height = height + 2 * border_height\n    square_size = max(new_width, new_height)\n\n    new_image = PILImage.new(\"RGBA\", (square_size, square_size), (255, 255, 255, 0))\n\n    paste_x = (square_size - new_width) // 2 + border_width\n    paste_y = (square_size - new_height) // 2 + border_height","sourceCodeStart":902,"sourceCodeEnd":938,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/utils/mesh3d_utils.py#L902-L938","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the input image's alpha channel (np.array(img)[:,:,3].any()) before calling recenter_image","Check the upstream producer of the image (mask/matting model) — an all-transparent output usually means the source step failed, not this API","If the image is meant to be opaque, convert with a white background instead of straight convert('RGBA') (paste onto opaque canvas)","If transparency is expected, validate the file renders correctly in an image viewer; re-export it"],"exampleFix":"// before\nimg = Image.open(path)\nrecenter_image(img)\n\n// after\nimg = Image.open(path).convert(\"RGBA\")\nif not (np.array(img)[:, :, 3] > 0).any():\n    raise ValueError(f\"{path} is fully transparent; regenerate it\")\nrecenter_image(img)","handlingStrategy":"validation","validationCode":"import numpy as np\nfrom PIL import Image\n\ndef has_visible_content(img: Image.Image) -> bool:\n    rgba = img.convert(\"RGBA\")\n    return bool((np.array(rgba)[:, :, 3] > 0).any())\n\nimg = Image.open(path)\nif not has_visible_content(img):\n    raise ValueError(f\"{path} is fully transparent\")","typeGuard":null,"tryCatchPattern":"try:\n    recenter_image(img)\nexcept ValueError as e:\n    if \"fully transparent\" in str(e):\n        # regenerate the source image / re-run matting upstream\n        raise","preventionTips":["Validate alpha before any auto-crop pipeline step","Log image stats (alpha max/sum) when ingesting user-supplied images","Alert on upstream matting models that return empty masks"],"tags":["image-processing","alpha-channel","rgba","mesh3d","validation"],"backgroundTag":"empty-image-input","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}