Package {rembg}

Type: Package
Title: Remove Image Backgrounds with Pre-Trained Segmentation Models
Version: 0.1.1
Date: 2026-07-13
Description: Remove the background from an image using pre-trained deep learning segmentation models ('U-2-Net', 'ISNet', 'BiRefNet' and others) run through the 'ONNX' Runtime via the 'onnxr' package. Given an image, a model predicts a foreground alpha matte which is composited into a cutout with a transparent (or solid-colour) background; optional closed-form alpha matting (ported from 'pymatting') refines soft edges. An R port of the Python 'rembg' package (https://github.com/danielgatis/rembg). Models are downloaded on first use and cached in a per-user cache directory.
License: MIT + file LICENSE
URL: https://github.com/cornball-ai/rembg
BugReports: https://github.com/cornball-ai/rembg/issues
Imports: onnxr, jpeg, png, Matrix, tools, utils
Suggests: tinytest, openssl
Encoding: UTF-8
RoxygenNote: 7.3.2
NeedsCompilation: no
Packaged: 2026-07-14 01:39:13 UTC; troy
Author: Troy Hernandez ORCID iD [aut, cre], cornball.ai [cph], Daniel Gatis [cph] (Author of the Python 'rembg' package this is ported from)
Maintainer: Troy Hernandez <troy@cornball.ai>
Repository: CRAN
Date/Publication: 2026-07-22 07:30:07 UTC

rembg: Remove Image Backgrounds

Description

An R port of the Python rembg package. Removes the background from an image using pre-trained ONNX segmentation models run through the ONNX Runtime (via onnxr). The main entry point is [rembg()]; models are managed with [new_session()] and listed with [rembg_models()].

Details

On first use the ONNX Runtime shared library must be present. If onnxr cannot find it, run onnxr::onnx_install() once.

Directory where downloaded models are cached

Description

Models are cached in tools::R_user_dir("rembg", "cache"), the standard per-package cache location. Set the U2NET_HOME environment variable to override it, for example to ~/.u2net to share the cache with the Python rembg package.

Usage

model_home()

Value

A file path (character scalar). The directory is not created.

Examples

model_home()

Create a background-removal session

Description

Loads a segmentation model (downloading it on first use) and returns a session object that [rembg()] can reuse across many images. Building the session once and passing it to [rembg()] avoids re-loading the model each call.

Usage

new_session(model = "u2net", backend = c("cpu", "cuda", "coreml"),
            model_path = NULL, size = NULL, mean = NULL, std = NULL, ...)

Arguments

model

Model name; see [rembg_models()]. Defaults to "u2net". The "u2net_custom", "dis_custom" and "ben_custom" presets run your own local .onnx (via model_path) through a fixed preprocessing profile.

backend

ONNX Runtime execution backend passed to [onnxr::onnx_model()]: "cpu" (default), "cuda" (NVIDIA GPU, needs a CUDA runtime build), or "coreml" (macOS).

model_path

Optional path to a local .onnx file to run instead of a downloaded model (bring-your-own-model). Required for the *_custom presets; when set, model selects the preprocessing profile.

size

Input size (pixels) for a custom model_path; defaults to the profile of model (320 for a bare model_path).

mean

Length-3 per-channel normalisation mean for a custom model_path; defaults to the profile of model.

std

Length-3 per-channel normalisation standard deviation for a custom model_path; defaults to the profile of model.

...

Reserved for future use.

Value

An object of class "rembg_session".

See Also

[rembg()], [rembg_models()]

Examples


# interactive() guard: new_session() downloads the model on first use
if (interactive() && onnxr::onnx_is_installed()) {
  sess <- new_session("u2netp")
  sess
  # bring your own model:
  # new_session("u2net_custom", model_path = "~/.u2net/my_model.onnx")
}

Remove the background from an image

Description

Runs a segmentation model to predict a foreground alpha matte and composites the result into a cutout with a transparent (or solid-colour) background.

Usage

rembg(input, model = "u2net", session = NULL, only_mask = FALSE,
      post_process_mask = FALSE, alpha_matting = FALSE,
      alpha_matting_foreground_threshold = 240,
      alpha_matting_background_threshold = 10, alpha_matting_erode_size = 10,
      cloth_category = NULL, points = NULL, labels = NULL, bgcolor = NULL,
      out = NULL, output = c("array", "raw"), ...)

Arguments

input

The image to process: a file path (PNG or JPEG), a raw vector of encoded PNG/JPEG bytes, or a numeric [h,w] / [h,w,c] array in [0,1] (or 0-255).

model

Model name to use when session is not supplied; see [rembg_models()]. Defaults to "u2net".

session

An [rembg_session] from [new_session()]. If NULL, one is created for model. Pass a session to reuse a loaded model across calls.

only_mask

If TRUE, return the predicted mask instead of a cutout.

post_process_mask

If TRUE, clean the mask with a morphological opening + gaussian blur + threshold before compositing.

alpha_matting

If TRUE, refine the cutout edges with closed-form alpha matting (soft hair/fur edges). Slower, and requires the Matrix package. Falls back to the plain cutout if matting fails.

alpha_matting_foreground_threshold

Mask values (0-255 domain) above this are treated as definite foreground in the matting trimap. Default 240.

alpha_matting_background_threshold

Mask values (0-255 domain) below this are treated as definite background in the matting trimap. Default 10.

alpha_matting_erode_size

Pixels by which the trimap foreground and background regions are eroded, leaving an unknown band for matting to solve. Default 10.

cloth_category

For the "u2net_cloth_seg" model only: which garment(s) to segment, one or more of "upper", "lower", "full". NULL (default) returns all three, stacked vertically.

points

For the "sam" model only: point prompt(s) as a length-2 c(x, y) vector or an N x 2 matrix of (x, y) pixel coordinates in the input image. Defaults to the image centre.

labels

For the "sam" model only: one label per point, 1 for foreground or 0 for background. Defaults to all foreground.

bgcolor

Optional background colour to composite the cutout onto, as a length-3 (RGB) or length-4 (RGBA) numeric vector in [0,1] or 0-255.

out

Optional output file path. If given, the result is written there as a PNG (in addition to being returned).

output

In-memory return type: "array" (default) for a numeric array in [0,1], or "raw" for PNG-encoded bytes.

...

Passed to [new_session()] when session is NULL.

Value

Depending on output: an [h,w,4] RGBA array (or [h,w] mask if only_mask) in [0,1], or a raw vector of PNG bytes. If out is set, the PNG is also written to that path.

See Also

[new_session()], [rembg_models()]

Examples


# interactive() guard: rembg() downloads the model on first use
if (interactive() && onnxr::onnx_is_installed()) {
  cutout <- rembg(system.file("extdata", "example.jpg", package = "rembg"))
  dim(cutout)
}

Available background-removal models

Description

Returns the names of the segmentation models that [new_session()] and [rembg()] can use. Models are downloaded on first use.

Usage

rembg_models()

Value

A character vector of model names.

Examples

rembg_models()