# background_removal

A RocketRide image node that removes an image's background and produces an RGBA cutout plus alpha-coverage statistics. Choose it when a downstream image node needs the foreground isolated for re-compositing.

## About BiRefNet

BiRefNet is the image background-removal model family used by this node. The node can load the default BiRefNet model or its higher-resolution HR variant, using the configured model identifier and optional revision.

## What it does

The node accepts an image stream, runs background removal for each completed image, and can emit both a cutout image and JSON alpha statistics. The image output preserves the source RGB pixels and combines them with a straight, non-premultiplied alpha matte, so another node can composite it over a new background. Choose this node when you need that RGBA foreground asset rather than a caption, detections, or a depth map.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `image` | `image` | An RGBA PNG cutout using the input image's RGB data and the predicted alpha matte. |
| `image` | `text` | JSON statistics: `mean_alpha` and `alpha_coverage_pct`. |

## Profiles

Default: **BiRefNet — default, 1K (MIT)** (`birefnet-default`).

| Profile | Model | Maximum input edge |
| --- | --- | --- |
| BiRefNet — default, 1K (MIT) **(default)** | `ZhengPeng7/BiRefNet` | `1024` px |
| BiRefNet HR — 2K, finer hair / edge detail (MIT) | `ZhengPeng7/BiRefNet_HR` | `2048` px |

## Configuration

Select the BiRefNet profile that gives the edge detail you need, then tune the maximum input edge only when latency or edge quality calls for it. The node falls back to its implementation default model if no model is configured.

### Model

The default profile uses the 1K BiRefNet variant; the HR profile uses the 2K variant for finer hair and edge detail. Start with the default profile and use HR when the foreground boundary needs more detail. A configured model identifier overrides the profile's model value, and the optional revision is passed to the model loader; use an override only when you intend to load a compatible BiRefNet model.

### Max input edge (px)

This caps the source image's long edge before inference. The default is `1024`; a lower value reduces inference work and memory use at the cost of a less detailed alpha matte, while a higher value can improve edges. The resulting alpha matte is restored to the original image dimensions before the RGBA cutout is created. The runtime clamps supplied values to `256` through `4096`, so values outside that range do not take effect as entered.

## Requirements

With a model server configured, inference runs there. Otherwise it runs locally on CPU, Apple Silicon (MPS), or CUDA, and a device lock serializes local inference so concurrent frames never run through the model at once.

## Notes

### Output and failures

For each successful image, `mean_alpha` is the alpha matte's average after scaling alpha bytes to `0.0`–`1.0`; `alpha_coverage_pct` is the percentage of pixels with alpha greater than `0.5`. The PNG encoder uses compression level 1. If image decoding or inference fails, the node logs a warning, drops that frame, and emits neither output for it.

## Upstream docs

- [BiRefNet model page](https://huggingface.co/ZhengPeng7/BiRefNet)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `background_removal.maxEdge` | `number` | **Max input edge (px)**<br/>Downscale source so long edge <= this value before inference; alpha is upsampled back to the original source size for compositing. Lower = faster + less VRAM; higher = sharper edges. | `1024` |
| `background_removal.model` | `string` | **Model**<br/>HuggingFace model identifier for background removal (overrides the profile default) |  |
| `background_removal.profile` | `string` | **Model**<br/>BiRefNet variant — default is 1K, HR is 2K for finer edges. | `"birefnet-default"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/background_removal)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->