Background Removal Transparency Threshold

bg-remove-transparency-threshold

The bg-remove-transparency-threshold parameter controls whether background removal processing should be applied based on the amount of transparency already present in the source image.

When an image’s transparency level is above the specified threshold, background removal will be skipped. If it is equal to or below the transparency threshold, background removal will be applied.

This parameter accepts a float value between 0.0 and 1.0, representing the transparency threshold. Examples:

0.0: Only an image with no transparency will have its background removed. A single pixel of transparency will cause background removal to be skipped
0.2 (default): Skips background removal if 20% or more of the image is transparent
1.0: Never skips background removal, regardless of the image’s transparency

Only applied on the first render

This parameter is only applied on the first render of an image. Subsequent requests for the same image will not re-evaluate the transparency threshold.

To re-evaluate the transparency threshold, you can purge the image from the cache using the Purging Tools

See this example image with approximately 61% transparency:

sandbox-demo — Transparency > 60%: Skips BGR

Troubleshooting

The transparency of an image can be seen using the the fm=json parameter, which displays the TransparentPercentage property:

GET https://assets.imgix.net/docs/digital-art-03-transparency.png?fm=json
{
  ...
  "TransparentPercentage": 0.609987,
  ...
}

If background removal is skipped based on the transparency threshold, we will return a header indicating so in the response:

curl -I https://assets.imgix.net/docs/digital-art-03-60.png?bg-remove=true&bg-remove-transparency-threshold=.6

HTTP/2 200
x-imgix-bg-remove-failure-reason: Transparency threshold exceeded

Usage

This parameter is used to avoid unnecessary processing on images that already have their backgrounds removed, as additional background removal may cause undesirable results.

Background Removal Semi-Transparency Background Replacement