Skip to content

Commit 8469a16

Browse files
Imran Kocabiyikcursoragent
Imran Kocabiyik
and
cursoragent
committed
docs: rewrite README for clarity and conviction
Lead with visual results and the three-line API, install via uv, and briefly route readers to Docker, Mac, GIMP, and Hugging Face. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent c99988f commit 8469a16

1 file changed

Lines changed: 102 additions & 79 deletions

File tree

‎README.md‎

Lines changed: 102 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -2,25 +2,25 @@
22

33
![AlphaMate reveal — background removal in action](docs/revealed.webp)
44

5-
**One clean alpha. Zero hassle. Drop the background in three lines of Python.**
5+
**Remove backgrounds in Python. Free locally. One line to switch to the Cloud API.**
66

77
[![PyPI](https://img.shields.io/pypi/v/withoutbg.svg)](https://pypi.org/project/withoutbg/)
88
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
99
[![CI](https://github.com/withoutbg/withoutbg/actions/workflows/ci.yml/badge.svg)](https://github.com/withoutbg/withoutbg/actions/workflows/ci.yml)
1010

11-
**Remove backgrounds in Python. Free locally, or use the cloud API.**
11+
Same API for both paths: run open weights on your machine (private, offline, unlimited) or call the Cloud API (sharper edges on hair and fur, no local GPU). Built for scripts, notebooks, backends, and batch jobs.
1212

13-
Two modes that share the same API — run the open-weights model locally (free, private, offline) or call the cloud API (better quality, no GPU, pay per image). Switch with one line of code.
13+
**[Full documentation →](https://withoutbg.com/docs/open-model/python?utm_source=github&utm_medium=withoutbg-readme&utm_campaign=main-readme)**
1414

15-
**[View Documentation →](https://withoutbg.com/docs/open-model/python?utm_source=github&utm_medium=withoutbg-readme&utm_campaign=main-readme)**
15+
## See the results
1616

17-
## Try it
17+
![Example 1](sample-results/open-weights/example1.png)
18+
![Example 2](sample-results/open-weights/example2.png)
19+
![Example 3](sample-results/open-weights/example3.png)
1820

19-
![Python Package Intro](images/python-package-intro.png)
21+
**[Open Weights results →](https://withoutbg.com/open-model/results?utm_source=github&utm_medium=withoutbg-readme&utm_campaign=main-readme)** · **[Cloud API results →](https://withoutbg.com/pro-model/results?utm_source=github&utm_medium=withoutbg-readme&utm_campaign=main-readme)** · **[Compare →](https://withoutbg.com/compare/withoutbg-open-model-vs-pro-model?utm_source=github&utm_medium=withoutbg-readme&utm_campaign=main-readme)**
2022

21-
```bash
22-
pip install withoutbg
23-
```
23+
## Three lines of Python
2424

2525
```python
2626
from withoutbg import WithoutBG
@@ -29,39 +29,31 @@ model = WithoutBG.open_weights()
2929
model.remove_background("photo.jpg").save("result.png")
3030
```
3131

32-
## Choose your mode
32+
Returns a PIL `Image` in RGBA. Prefer PNG or WebP — JPEG drops transparency silently.
3333

34-
| | Local (`open_weights()`) | Cloud (`api()`) |
35-
|---|---|---|
36-
| Cost | Free forever | Pay per image |
37-
| Quality | Good | Better (esp. hair, fur) |
38-
| Privacy | Stays on your machine | Image sent to API |
39-
| GPU required | No (CPU ONNX) | No |
40-
| First-run setup | ~455MB download, once | API key only |
41-
| Best for | Offline, private, batch jobs | Products, occasional use |
42-
43-
**[Compare results →](https://withoutbg.com/compare/withoutbg-open-model-vs-pro-model?utm_source=github&utm_medium=withoutbg-readme&utm_campaign=main-readme)**
34+
## Install
4435

36+
```bash
37+
uv add withoutbg
4538
```
46-
Need offline or private processing? → Local
47-
Processing a large batch? → Local (pay the setup cost once, amortize across all images)
48-
Building a product? → Cloud (better quality, zero infra overhead)
49-
Occasional use, no setup tolerance? → Cloud
50-
```
39+
40+
Don't have [uv](https://astral.sh/uv) yet? It's a fast Python package manager from Astral. Install it once, then the command above.
5141

5242
## Quick start
5343

54-
**Local (withoutBG Open Weights Model):**
44+
**Local (Open Weights — free, private, offline):**
5545

5646
```python
5747
from withoutbg import WithoutBG
5848

5949
model = WithoutBG.open_weights()
60-
result = model.remove_background("input.jpg") # returns PIL Image (RGBA)
50+
result = model.remove_background("input.jpg")
6151
result.save("output.png")
6252
```
6353

64-
**Cloud (withoutBG API):**
54+
First local run downloads ~455 MB of weights from Hugging Face (once). After that, everything stays on your machine.
55+
56+
**Cloud (withoutBG API — best quality):**
6557

6658
```python
6759
from withoutbg import WithoutBG
@@ -72,17 +64,19 @@ result = model.remove_background("input.jpg")
7264
result.save("output.png")
7365
```
7466

75-
**Batch processing:**
67+
**Batch (load once, process many):**
7668

7769
```python
7870
from withoutbg import WithoutBG
7971

80-
model = WithoutBG.open_weights() # load once
72+
model = WithoutBG.open_weights() # keep this object alive
8173

8274
images = ["photo1.jpg", "photo2.jpg", "photo3.jpg"]
8375
results = model.remove_background_batch(images, output_dir="results/")
8476
```
8577

78+
Recreating the model for every image reloads the weights each time — don't do that in a loop.
79+
8680
**Progress callback:**
8781

8882
```python
@@ -92,110 +86,149 @@ def on_progress(value: float) -> None:
9286
result = model.remove_background("photo.jpg", progress_callback=on_progress)
9387
```
9488

95-
See [`examples/`](examples/) for runnable scripts.
89+
Runnable scripts live in [`examples/`](examples/).
90+
91+
## Choose your mode
92+
93+
| | Local (`open_weights()`) | Cloud (`api()`) |
94+
|---|---|---|
95+
| Cost | Free forever | Pay per image |
96+
| Quality | Good | Better (esp. hair, fur) |
97+
| Privacy | Stays on your machine | Image sent to API |
98+
| GPU required | No (CPU ONNX) | No |
99+
| First-run setup | ~455 MB download, once | API key only |
100+
| Best for | Offline, private, batch jobs | Products, occasional use |
101+
102+
```
103+
Need offline or private processing? → Local
104+
Processing a large batch? → Local (pay setup once, amortize across images)
105+
Building a product? → Cloud (better quality, zero infra)
106+
Occasional use, no setup tolerance? → Cloud
107+
```
96108

97109
## CLI
98110

99111
```bash
100112
# Single image (local model)
101113
withoutbg photo.jpg
114+
withoutbg photo.jpg --output result.png
102115

103-
# Batch
116+
# Batch a directory
104117
withoutbg ~/Photos/vacation/ --batch --output-dir ~/Photos/no-bg/
105118

106119
# Cloud API
107120
export WITHOUTBG_API_KEY=sk_your_key
108121
withoutbg photo.jpg --use-api
109122

110-
# JPEG output with white background fill
123+
# JPEG with white background fill
111124
withoutbg portrait.jpg --format jpg --quality 95
112125

113126
withoutbg --help
114127
```
115128

116-
## Example outputs
129+
## What you get
117130

118-
**[See Local model results →](https://withoutbg.com/open-model/results?utm_source=github&utm_medium=withoutbg-readme&utm_campaign=main-readme)**
119-
**[See Cloud API results →](https://withoutbg.com/pro-model/results?utm_source=github&utm_medium=withoutbg-readme&utm_campaign=main-readme)**
131+
All methods return a PIL `Image` in RGBA mode:
120132

121-
![Example 1](sample-results/open-weights/example1.png)
122-
![Example 2](sample-results/open-weights/example2.png)
123-
![Example 3](sample-results/open-weights/example3.png)
133+
```python
134+
result = model.remove_background("photo.jpg")
124135

125-
## What gets returned
136+
result.save("output.png") # keeps transparency
137+
result.save("output.webp") # keeps transparency
138+
result.save("output.jpg") # transparency dropped silently
139+
```
126140

127-
All methods return a PIL `Image` in RGBA mode:
141+
Compositing example:
128142

129143
```python
130-
result = model.remove_background("photo.jpg") # PIL Image, RGBA
144+
from PIL import Image
145+
from withoutbg import WithoutBG
131146

132-
result.save("output.png") # PNG — preserves transparency
133-
result.save("output.webp") # WebP — also supports transparency
134-
result.save("output.jpg") # JPEG — transparency is dropped silently
147+
model = WithoutBG.open_weights()
148+
fg = model.remove_background("subject.jpg")
149+
bg = Image.open("background.jpg")
150+
bg.paste(fg, (0, 0), fg) # alpha used as mask
151+
bg.save("composite.png")
135152
```
136153

137154
## Configuration
138155

139156
| Environment variable | Effect |
140157
|---|---|
141-
| `WITHOUTBG_API_KEY` | API key for Cloud mode (alternative to passing `api_key=`) |
158+
| `WITHOUTBG_API_KEY` | API key for Cloud mode (alternative to `api_key=`) |
142159
| `WITHOUTBG_MODEL_PATH` | Path to a local `.onnx` file (skips Hugging Face download) |
143160

144-
When using `WITHOUTBG_MODEL_PATH`, the sidecar metadata file (`withoutbg-open-weights.onnx.json`) must be in the same directory.
161+
When using `WITHOUTBG_MODEL_PATH`, keep the sidecar metadata file (`withoutbg-open-weights.onnx.json`) next to the ONNX file.
145162

146163
## Performance
147164

148165
| | Local | Cloud |
149166
|---|---|---|
150-
| First run | 5–10s (~455MB download) | 1–3s |
167+
| First run | 5–10s (~455 MB download) | 1–3s |
151168
| Per image | 2–5s | 1–3s |
152-
| RAM | ~2GB | None |
153-
| Disk | 455MB (one-time cache) | None |
169+
| RAM | ~2 GB | None (client) |
170+
| Disk | 455 MB (one-time cache) | None |
154171

155-
Keep the model object alive across all images in a batch. Recreating it for every image reloads the weights each time.
172+
## Error handling
173+
174+
```python
175+
from withoutbg import WithoutBG, APIError, WithoutBGError
176+
177+
try:
178+
model = WithoutBG.api()
179+
result = model.remove_background("photo.jpg")
180+
result.save("output.png")
181+
except APIError as e:
182+
print(f"API error: {e}")
183+
except WithoutBGError as e:
184+
print(f"Processing error: {e}")
185+
```
156186

157187
## Troubleshooting
158188

159-
**Model download fails:** The weights are pulled from [Hugging Face](https://huggingface.co/withoutbg/withoutbg-openweights-onnx) on first run (~455MB). Check your connection, or set `WITHOUTBG_MODEL_PATH` to a local copy.
189+
**Model download fails:** Weights come from [Hugging Face](https://huggingface.co/withoutbg/withoutbg-openweights-onnx) on first local run (~455 MB). Check your connection, or set `WITHOUTBG_MODEL_PATH` to a local copy.
160190

161-
**Out of memory:** The local model uses ~2GB of RAM. Reduce batch size or switch to Cloud mode.
191+
**Out of memory:** Local mode uses ~2 GB of RAM. Process fewer images at once, or switch to Cloud.
162192

163193
**Import error:**
164194

165195
```bash
166196
which python
167-
pip list | grep withoutbg
168-
pip install withoutbg
197+
uv pip list | grep withoutbg
198+
uv add withoutbg
169199
```
170200

171201
**API key rejected:** Get a key at [withoutbg.com](https://withoutbg.com). Set `export WITHOUTBG_API_KEY=sk_your_key`.
172202

173-
**Migrating from older API names** (`WithoutBG.opensource()`, `ProAPI`): see [docs/MIGRATION.md](docs/MIGRATION.md).
203+
**Migrating from older names** (`WithoutBG.opensource()`, `ProAPI`): see [docs/MIGRATION.md](docs/MIGRATION.md).
174204

175-
## Error handling
205+
## More than Python
176206

177-
```python
178-
from withoutbg import WithoutBG, APIError, WithoutBGError
207+
This package is the **in-process** path — embed withoutBG in your Python code or CLI. Same open-weights technology powers the rest of the ecosystem; pick the surface that matches your workflow:
179208

180-
try:
181-
model = WithoutBG.api()
182-
result = model.remove_background("photo.jpg")
183-
result.save("output.png")
184-
except APIError as e:
185-
print(f"API error: {e}")
186-
except WithoutBGError as e:
187-
print(f"Processing error: {e}")
209+
| Surface | Choose when |
210+
|---|---|
211+
| **[Docker / self-host](https://github.com/withoutbg/withoutbg-inference)** | You want an HTTP API or browser UI on your own server (CPU or NVIDIA GPU) |
212+
| **[Mac app](https://withoutbg.com/mac)** | You want a native desktop cutout tool, with an optional Local API for plugins and scripts |
213+
| **[GIMP plugin](https://github.com/withoutbg/withoutbg-gimp)** | You edit in GIMP 3 and want a private, mask-first workflow via Mac Local API or Docker |
214+
| **[Hugging Face](https://huggingface.co/withoutbg/withoutbg-openweights-onnx)** · **[Space](https://huggingface.co/spaces/withoutbg/withoutbg)** | You want to try a demo or download the ONNX weights directly |
215+
| **[Cloud API](https://withoutbg.com/pro-model)** | You need maximum quality without running inference yourself |
216+
217+
```bash
218+
# Self-host the open-weights web app (CPU)
219+
docker run --rm -p 8080:8080 withoutbg/withoutbg-openweights-v3-app-cpu
188220
```
189221

190222
## Model
191223

192-
The withoutBG Open Weights Model is a unified ONNX model hosted at [withoutbg/withoutbg-openweights-onnx](https://huggingface.co/withoutbg/withoutbg-openweights-onnx). Licensed under the [withoutBG Open Model License](https://withoutbg.com/open-model/license) (Apache 2.0 for withoutBG portions; Meta DINOv3 License for DINOv3 backbone weights). Built with DINOv3.
224+
The withoutBG Open Weights Model is a unified ONNX graph hosted at [withoutbg/withoutbg-openweights-onnx](https://huggingface.co/withoutbg/withoutbg-openweights-onnx). Depth, segmentation, matting, and refinement run in one pass. Built with DINOv3.
225+
226+
Licensed under the [withoutBG Open Model License](https://withoutbg.com/open-model/license) (Apache 2.0 for withoutBG portions; Meta DINOv3 License for DINOv3 backbone weights).
193227

194228
## Development
195229

196230
```bash
197231
uv sync --extra dev
198-
# or: pip install -e ".[dev]"
199232

200233
make test-fast # fast unit tests
201234
make quality # lint + format + type check
@@ -204,16 +237,6 @@ make test # full suite (downloads model on first run)
204237

205238
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
206239

207-
## Related projects
208-
209-
Need a browser UI or HTTP API instead of Python?
210-
211-
[**withoutbg-inference**](https://github.com/withoutbg/withoutbg-inference) — Docker images (CPU + GPU), FastAPI inference service, and optional web UI built on the same open-weights model.
212-
213-
```bash
214-
docker run --rm -p 8080:8080 withoutbg/withoutbg-openweights-v3-app-cpu
215-
```
216-
217240
## License
218241

219242
This Python SDK is licensed under Apache License 2.0. See [LICENSE](LICENSE).

0 commit comments

Comments
 (0)