background-removal

Platformneta/background-removal
Use it in Cohub

Paste this into your agent's chat — it fetches the skill and follows it.

Use the skill: background-removal. Run `npx -y @neta-art/neta-search-cli@latest skills use neta/background-removal --via site` and follow what it prints. Read its complete output, redirecting it to a temporary file first if necessary, and resolve relative paths from the skill directory it prints.
Install from a terminal
npx -y @neta-art/neta-search-cli@latest skills use neta/background-removal
Summary

Turn any image into a transparent cutout without changing its size, so sheets and game art still line up.

  • Removes plain, white or photo backgrounds from an existing image and gives you a transparent PNG.
  • Keeps the original image size, so sprite sheets, UI sheets and 4×4 grids stay in the same layout.
  • Handles a whole folder of images in one go, with a record of how each one was processed.
  • Checks each result for transparency and correct size, and tries a backup method if the first one fails.
  • Works best on clean, near-solid backgrounds; busy backgrounds may need a different mode or cell-by-cell cleanup.
SKILL.md
# Background Removal

Use this skill to remove image backgrounds while preserving production safety for game assets.

The preferred route is Cohub `birefnet-general` (BiRefNet) **via https URL input**. Local `rembg` remains the fallback route for offline or Cohub-failed runs.

## Critical Provider Constraint (read first)

`birefnet-general` only accepts image input as `url` or `base64` (schema `sources: ["url", "base64"]`). **A local file path passed to `cohub generate --image /abs/path.png` always fails upstream** with:

```text
HTTP 500 — nieta-app image input must be an http or https URL (code: convert_request_failed)
```

Also verified:

- `--image data:image/png;base64,...` does NOT work either — the CLI treats it as a file path (ENOENT). The base64 route is unusable via the CLI.
- Therefore the only working BiRefNet route is: **local file → upload to Cohub temp asset storage → https URL → `cohub generate --image <https-url>`**.
- BiRefNet output is WebP bytes even when saved as `.png`, and it **crops the result to the foreground bbox and upscales it**. Output must be converted to real PNG and, for no-crop work, re-composited back onto the original canvas.

The bundled wrapper (`scripts/rembg_cutout.py`) does all of this automatically: temp-storage upload, URL call, WebP→PNG conversion, no-crop re-composition. **Always prefer the wrapper over hand-written `cohub generate` calls for cutout work.**

The temp asset upload uses the sandbox env vars `COHUB_EXECUTION_TOKEN`, `COHUB_SPACE_ID`, `COHUB_SESSION_ID` (present inside Cohub sessions). Uploaded temp files live under an unguessable UUID URL on the platform asset store; do not upload assets the user has marked as secret without confirming.

## When To Use

Use this skill when the task is primarily:

- removing a white/solid/photo background from an existing image;
- making transparent PNG or WebP assets;
- processing many files in a folder;
- preserving the original canvas for sheets, spritesheets, UI strips, or grid-based assets;
- checking whether Cohub BiRefNet or local `rembg` is available and giving the user an exact run path.

Do not use this skill for generating new art. Use the relevant image/game asset skill first, then use this skill for local or platform cutout cleanup.

## Provider Order

Default provider mode is `auto`:

1. Upload the local input to Cohub temp asset storage and call `birefnet-general` with the resulting https URL (the wrapper does this automatically).
2. Normalize the provider output (WebP → PNG; re-composite onto the original canvas in no-crop mode).
3. Validate the output exists, has alpha, and preserves canvas size in no-crop mode.
4. If upload fails, Cohub is unavailable, command execution fails, or QA fails, retry once with local `rembg`.
5. Report `blocked` only if both Cohub and local `rembg` are unavailable or fail QA.

A successful preferred-route run must show `used_provider: "cohub"` and `preferred_hit: true` in the log. If logs show every run falling back to `rembg`, treat it as a bug — do not assume BiRefNet is working just because the overall run succeeded.

Use provider overrides only when necessary:

```bash
--provider auto   # default: Cohub BiRefNet, then rembg fallback
--provider cohub  # Cohub BiRefNet only
--provider rembg  # local rembg only
```

## Dependency Check

Before processing files, check Cohub first:

```bash
command -v cohub || true
cohub models show birefnet-general --json
```

In the model JSON, note `content.input[].sources` for the image input: it lists `url` and `base64` only — this is why local paths must be uploaded first.

Also confirm the upload env vars exist (required for the local→URL step):

```bash
env | grep -E 'COHUB_(EXECUTION_TOKEN|SPACE_ID|SESSION_ID)' | sed 's/=.*/=present/'
```

Then check the local fallback:

```bash
command -v rembg || true
python3 - <<'PY'
import importlib.util
spec = importlib.util.find_spec('rembg')
print(spec.origin if spec else '')
PY
```

If Cohub is missing or unauthorized, continue with local `rembg` when available. If local `rembg` is missing and fallback is required, first attempt a safe install in the current environment, then rerun the check and continue.

Preferred CPU fallback install:

```bash
python3 -m pip install --user --break-system-packages "rembg[cpu,cli]"
```

If the environment does not need `--break-system-packages`, omit it. If CLI extras are unavailable but the Python API installs, use an API wrapper only when available.

## Output Policy

Default output format is transparent PNG. Use WebP only if the user asks for WebP or the consuming project already expects WebP.

Always preserve the raw source file. Write outputs into a sibling or dedicated directory such as:

```text
<asset-dir>/cutout/<name>.png
<asset-dir>/logs/background-removal.json
```

For grid/sheet assets, default to no-crop mode: output dimensions must match input dimensions. Cropping or trimming is a separate explicit step after cutout.

Cutouts are files or ingredients for another work, so they do not go on the Board (see **board-ops**).

## Recommended Script

Use the bundled wrapper because it uploads local files to temp storage for the BiRefNet URL route, normalizes WebP output back to PNG on the original canvas, automatically falls back to `rembg`, verifies dimensions, verifies alpha, and writes metadata:

```bash
python3 /mods/neta/.agents/skills/background-removal/scripts/rembg_cutout.py \
  --input path/to/input.png \
  --output path/to/cutout.png \
  --mode no-crop \
  --log path/to/background-removal.json
```

Batch a directory:

```bash
python3 /mods/neta/.agents/skills/background-removal/scripts/rembg_cutout.py \
  --input-dir path/to/raw \
  --output-dir path/to/cutout \
  --mode no-crop \
  --log path/to/background-removal-batch.json
```

Force Cohub only:

```bash
python3 /mods/neta/.agents/skills/background-removal/scripts/rembg_cutout.py \
  --input path/to/input.png \
  --output path/to/cutout.png \
  --provider cohub
```

Force local fallback only:

```bash
python3 /mods/neta/.agents/skills/background-removal/scripts/rembg_cutout.py \
  --input path/to/input.png \
  --output path/to/cutout.png \
  --provider rembg
```

## Direct CLI Fallbacks

Direct Cohub call — **URL input only**. Never pass a local path or a data URL:

```bash
# WRONG — always fails with "image input must be an http or https URL":
#   cohub generate "remove background" -m birefnet-general --image input.png -o out.png

# RIGHT — https URL input:
cohub generate "remove background" \
  -m birefnet-general \
  --image https://example.com/path/to/input.png \
  -o output.png
```

For a local file without the wrapper, upload it first (temp asset storage), then pass the returned https URL. The wrapper automates exactly this; prefer it.

Remember the direct call gives you raw provider output: WebP bytes (even with a `.png` name), cropped to the foreground and upscaled. Convert and re-composite yourself, or use the wrapper.

Local `rembg` fallback (local paths are fine here):

```bash
rembg i input.png output.png
```

After any direct CLI use, verify that the output exists, is non-empty, has alpha, and for no-crop work has the same dimensions as the input.

## QA Checklist

After every run, verify:

- output file exists and is not empty;
- output is a real PNG with an alpha channel (`RGBA` or equivalent) — not WebP bytes with a `.png` name;
- no-crop outputs keep the exact original width and height;
- foreground is not accidentally empty or nearly full-canvas opaque;
- important white/light details were not removed;
- for sheets, grid order and canvas geometry remain unchanged;
- the log records `used_provider`, `preferred_hit`, `input_mode`, and which fallback attempts failed — verify `preferred_hit: true` when BiRefNet was expected to run.

For important assets, create or inspect a quick preview/contact sheet instead of trusting file existence alone.

## Failure Handling

If Cohub BiRefNet fails:

1. Record stdout/stderr in the log; check `preferred_error` to distinguish upload failures from provider failures.
2. If the error is `image input must be an http or https URL`, the call passed a local path — use the wrapper or upload to get an https URL first; this is a caller bug, not a provider outage.
3. In no-crop mode the wrapper must re-composite BiRefNet's cropped output; this requires a near-solid background. For busy backgrounds, use `--mode allow-resize` or accept the rembg fallback.
4. Retry with local `rembg` unless the user forced `--provider cohub`.
5. If local `rembg` is missing and installation is safe, install it and rerun once.
6. If both providers fail, report the exact blocker and preserve the raw source.

If the foreground is damaged, do not patch with color-key deletion by default; ask whether to try another model/provider or process per-cell/per-object.

For grid sheets, never continue with a resized/autocropped cutout unless the user explicitly wants crop mode.

## Notes For Game Assets

- For 4x4 sheets and spritesheets, no-crop cutout should happen before coordinate-based slicing.
- If full-sheet cutout damages individual objects, slice first and run this skill per cell, then normalize each asset back onto a stable canvas.
- Avoid global white-key cleanup because it can erase eyes, highlights, clothing, labels, pale props, smoke, or UI shine.
Related skills
create-roleplayPlatformTurn your world into a story space you can step into, play as a character, and explore through mysteries and relationships.generatePlatformTurn your characters and ideas into new images, videos and 3D models, right on your canvas.world-opsPlatformMake quick, precise changes to a world you've already built: add, edit, move or delete one thing, or fix its cover.create-worldPlatformTurn a rough idea, a favorite story, or a pasted text into a whole world, with its opening cards laid out for you.create-web-workPlatformTurn an idea into a working web page or browser game, published with a link you can open and share.speechPlatformGive a character a voice, change it, add languages, or have them speak your lines out loud.