Package 'rembg'

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()

---