How to Handle Images with Transparent Backgrounds in MCP 3D Relief

To handle images with transparent backgrounds in MCP 3D Relief, composite the RGBA image onto a solid background before converting to grayscale, or use the alpha channel as a mask to exclude transparent regions from the depth map.

The mcp_3d_relief repository converts 2D images into 3D relief STL files through depth map generation. When you handle images with transparent backgrounds, the default pipeline in relief.py discards the alpha channel during grayscale conversion, causing transparent pixels to become black. This creates unwanted geometry in the final 3D model because the depth generator interprets these dark areas as extreme depth values.

Why Transparent Backgrounds Cause Problems in 3D Relief Generation

The current conversion logic in relief.py (lines 17‑19 and 30‑32) uses Image.convert("L") to transform input images to grayscale. This operation strips any alpha channel present in PNG or WebP files, forcing transparent backgrounds to pure black. In depth map generation, black pixels typically represent maximum depth (or minimum, depending on inversion settings), causing the transparent background to appear as a raised plateau or deep cavity in the STL output rather than remaining flat.

Solution: Composite Transparent Images Before Depth Map Generation

To properly handle images with transparent backgrounds, intercept the image before the grayscale conversion and composite it onto a solid background color. This preserves the visual content while eliminating the alpha channel in a controlled manner.

The Alpha Mask Helper Function

Add the following helper function to relief.py near the existing imports. This function checks for RGBA mode, composites the image onto a configurable background (defaulting to white), then converts to grayscale:

from PIL import ImageOps

def _apply_alpha_mask(img, background=(255, 255, 255)):
    """
    Preserve transparency by compositing an RGBA image onto a solid background
    and returning a grayscale image that respects the original alpha mask.
    
    • If the image has no alpha channel, it is returned unchanged as grayscale.
    • Transparent pixels are replaced with the background color before conversion.
    • Returns a Pillow Image in mode "L" ready for the depth-map pipeline.
    """
    if img.mode == "RGBA":
        # Create a solid-color background canvas

        bg = Image.new("RGB", img.size, background)
        # Composite the RGBA image over the background (alpha is honored)

        composited = Image.alpha_composite(bg.convert("RGBA"), img)
        # Convert to grayscale – transparent areas now match the background color

        return composited.convert("L")
    # No alpha channel → standard grayscale conversion

    return img.convert("L")

Integrating the Fix into relief.py

Replace the two locations in relief.py where input_image.convert("L") currently appears. This ensures both the "skip_depth" branch and the depth-map generation branch handle transparency correctly:

# In the skip_depth branch (around lines 16-20)

# Replace: img = np.array(input_image.convert("L"))

gray_img = _apply_alpha_mask(input_image)
img = np.array(gray_img)

# In the generate_depth_map section (around lines 30-32)

# Replace manual RGB conversion or direct convert("L")

gray = np.array(_apply_alpha_mask(input_image))

Using the API with Transparent PNGs

Once the _apply_alpha_mask helper is integrated, the FastAPI endpoint defined in server.py (/convert) automatically supports transparent images without additional changes. Submit your PNG with an alpha channel as usual:

curl -X POST "http://localhost:8000/convert" \
  -F "image_path=https://example.com/logo_transparent.png" \
  -F "model_width=80" \
  -F "model_thickness=6" \
  -F "skip_depth=false"

The resulting STL will contain a flat base where the logo was transparent, and the logo itself will be raised according to the generated depth map.

Alternative Approach: Using Alpha as a Depth Mask

Instead of compositing onto a background, you can use the alpha channel directly as a binary mask. In this approach, you extract the alpha band and set depth values to zero (flat) wherever transparency is full, while preserving computed depth for opaque regions. This requires modifying the depth-map array after generation but before STL creation, and is useful when you want the background to be completely absent (void) rather than flat.

Summary

• Transparent backgrounds become black when Image.convert("L") strips the alpha channel, causing unwanted geometry in the STL output.
• Composite RGBA images onto a solid background using _apply_alpha_mask() before grayscale conversion to control how transparent areas appear in the depth map.
• Modify relief.py at lines 17‑19 and 30‑32 to replace direct convert("L") calls with the alpha-aware helper.
• The FastAPI endpoint in server.py requires no changes; it automatically supports transparent PNGs once the core library is updated.

Frequently Asked Questions

What happens if I don't handle transparent backgrounds in MCP 3D Relief?

If you pass an image with an alpha channel directly to the current pipeline, PIL.Image.convert("L") discards the transparency and renders those pixels as black. The depth-map generator interprets black as an extreme depth value, causing the background to appear as either a deep cavity or a raised plateau in the final STL model instead of remaining flat.

Can I use any background color when compositing transparent images?

Yes. The _apply_alpha_mask() helper accepts a background parameter as an RGB tuple. While white (255, 255, 255) is the default and recommended choice because it produces a flat base in the depth map, you can specify any color. Keep in mind that darker backgrounds will create varying depth levels where the image was transparent.

Does this solution work with the FastAPI endpoint?

Yes. The /convert endpoint in server.py passes the image object directly to the relief() function. Once you integrate the _apply_alpha_mask() helper into relief.py, the endpoint automatically handles transparent PNGs without requiring any changes to server.py or the API contract.

Which file contains the main conversion logic that needs modification?

The core conversion logic resides in relief.py, specifically around lines 17‑19 (the skip_depth branch) and lines 30‑32 (the depth-map generation branch). These are the locations where input_image.convert("L") is called and must be replaced with the _apply_alpha_mask() helper to properly support transparent backgrounds.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}