# bgcut

bgcut removes image backgrounds locally through the hosted browser app, packaged local app, CLI, or Node.js API. Source images are not sent to a bgcut inference backend.

This reference describes bgcut 0.6.1.

## Start here

- [Background remover](https://bgcut.dev/)
- [Documentation](https://bgcut.dev/docs)
- [Guides](https://bgcut.dev/guides)
- [Comparisons](https://bgcut.dev/compare)
- [Free image tools](https://bgcut.dev/tools)
- [Transparency checker](https://bgcut.dev/tools/transparency-checker)
- [Changelog](https://bgcut.dev/changelog)
- [npm package](https://www.npmjs.com/package/bgcut)
- [GitHub repository](https://github.com/jhomra21/bgcut)
- [Agent skill](https://github.com/jhomra21/bgcut/blob/main/skills/bgcut/SKILL.md)
- [Node API types](https://github.com/jhomra21/bgcut/blob/main/src/node/index.d.ts)

## Choose an interface

- Browser UI: interactive local removal and before/after inspection.
- Local app: run `npx bgcut` or `bgcut` after a global install.
- CLI: file-in/file-out automation.
- Node API: application code through a reusable bgcut instance.

The hosted browser and local app run inference in the browser. The CLI and Node API use the native runtime. Reuse one Node API instance for repeated work and close it when finished.

## CLI quick reference

Run one removal:

```sh
npx bgcut photo.jpg
```

After a global install:

```sh
bgcut photo.jpg
bgcut photo.jpg -o portrait.png
bgcut first.jpg second.png
bgcut photos/
bgcut photos/ -o ./cutouts
bgcut photo.jpg --webp
bgcut photo.jpg --gpu
bgcut photo.jpg --cpu
```

Directories are scanned recursively. Batch inference is sequential and reuses one warm runtime. In batch mode, `--output` names an output directory. Without it, each result is written next to its source image.

Supported input formats: JPEG, PNG, WebP, AVIF.

Output formats:
- PNG: default, transparent.
- WebP: lossless, transparent.
- JPG/JPEG: white background because JPEG has no alpha channel.

Automatic native engine selection tries WebGPU first and uses CPU if the WebGPU runtime cannot start. Explicit `--gpu` does not silently fall back to CPU.

## Local app

```sh
npx bgcut
bgcut serve
bgcut serve --port 8787
bgcut serve --no-open
bgcut serve --json
```

The server binds to `127.0.0.1`. `serve --json` prints one JSON object with `url`, `host`, `port`, and `pid` and does not open a browser.

## Node API

Install:

```sh
npm install bgcut
```

Open bgcut:

```ts
import { bgcut } from "bgcut";

const remover = await bgcut();
```

Single image:

```ts
const result = await remover.removeBackground("photo.jpg");
```

Multiple images:

```ts
for await (const item of remover.removeMany([
  "first.jpg",
  "second.png",
])) {
  if (!item.ok) {
    console.error(item.source.input, item.error);
    continue;
  }

  console.log(item.result);
}
```

Directory:

```ts
for await (const item of remover.removeMany("photos")) {
  // Recursive by default.
}
```

Call `await remover.close()` when finished.

`removeMany()` processes inputs sequentially and yields one result at a time. It accepts files, directories, iterables, and async iterables. Per-image failures are yielded with `ok: false` and do not stop later inputs.

Single-image inputs can be file paths, `Uint8Array`, or `ArrayBuffer`. Output formats are `png`, `webp`, and `jpg`.

Engine values for `bgcut({ engine })`:
- `auto`: try native WebGPU, then CPU if runtime creation fails.
- `gpu`: require native WebGPU.
- `cpu`: require CPU.

Public Node errors are `BgcutError`. Codes are `model`, `engine`, `input`, `inference`, `output`, and `closed`.

## Migrating from 0.5.x to 0.6.1

bgcut 0.6.1 does not export the old top-level `removeBackground()` or `createBgcut()` functions.

Before, one image in 0.5.x:

```ts
import { removeBackground } from "bgcut";

const result = await removeBackground("photo.jpg", {
  engine: "cpu",
  format: "webp",
});
```

In 0.6.1:

```ts
import { bgcut } from "bgcut";

const remover = await bgcut({ engine: "cpu" });
try {
  const result = await remover.removeBackground("photo.jpg", { format: "webp" });
} finally {
  await remover.close();
}
```

Reusable `createBgcut().remove()` calls become `bgcut().removeBackground()`. For several inputs, prefer `removeMany()` instead of a manual sequential loop.

## Browser runtime

The public model input is 512 x 512. bgcut restores the matte to the original source dimensions before export.

- Safari WebGPU uses the validated internal-FP16 artifact only when the adapter exposes `shader-f16`.
- Safari without `shader-f16`, Chromium-family WebGPU, browser WebAssembly, native CLI, and Node API use FP32.
- The npm tarball does not include the model artifacts.
- Cached models are verified by byte size and SHA-256 before reuse.

## Privacy

Source images, decoded pixels, masks, and generated outputs stay on the user's machine. The hosted site serves application, model, and ONNX Runtime files but does not receive the user's source image for inference.

## Agent guidance

For tool execution rules, provider constraints, supported formats, model caching, output handling, and failure behavior, use the packaged skill at `skills/bgcut/SKILL.md`. After installation it is available at `node_modules/bgcut/skills/bgcut/SKILL.md`.

Do not infer support beyond the documented JPEG, PNG, WebP, and AVIF inputs. Preserve explicit GPU or CPU constraints instead of silently changing providers.

## Search-focused resources

- [Remove a background without uploading](https://bgcut.dev/guides/remove-background-without-uploading)
- [Node.js background removal](https://bgcut.dev/guides/node-js-background-removal)
- [Batch background removal from the CLI](https://bgcut.dev/guides/batch-background-removal-cli)
- [How local background removal works](https://bgcut.dev/guides/how-local-background-removal-works)
- [How bgcut uses Effect](https://bgcut.dev/guides/how-bgcut-uses-effect)
- [PNG vs WebP vs JPEG transparency](https://bgcut.dev/guides/png-webp-jpeg-transparency)
- [Local remove.bg alternative](https://bgcut.dev/remove-bg-alternative)
- [Local remove.bg API alternative](https://bgcut.dev/remove-bg-api-alternative)