pinecoresystems commited on
Commit
518d72c
Β·
verified Β·
1 Parent(s): fcbd8aa

Upload UPSTREAM-README.md with huggingface_hub

Browse files
Files changed (1) hide show
  1. UPSTREAM-README.md +106 -0
UPSTREAM-README.md ADDED
@@ -0,0 +1,106 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ license: mit
3
+ pipeline_tag: image-segmentation
4
+ base_model: ZhengPeng7/BiRefNet_HR
5
+ datasets:
6
+ - joelseytre/toonout
7
+ tags:
8
+ - background-removal
9
+ - image-matting
10
+ - BiRefNet
11
+ - transparency
12
+ - camouflage
13
+ - text-preservation
14
+ - illustration
15
+ - rgba
16
+ library_name: transformers
17
+ ---
18
+
19
+ # Lucida β€” general-purpose background removal with soft-alpha mastery
20
+
21
+ Lucida is a BiRefNet-based background-removal / image-matting model fine-tuned to
22
+ excel where most open models fail: **camouflaged objects, transparent materials
23
+ (glass), text & logos, VFX glows, and illustrations** β€” while staying competitive
24
+ everywhere else.
25
+
26
+ On our 203-image, 9-category benchmark (MAE, lower is better) Lucida leads every
27
+ model we tested β€” including a commercial reference β€” in **camouflage (0.0270)** and
28
+ **illustration (0.0092)**, beats the commercial reference in **text/logo
29
+ preservation (0.0091 vs 0.0123)** and in **print-design/sticker art (0.0235 β€” 2x better
30
+ than every model measured)**, and sets our best-ever **transparency-in-mixed-objects** handling and
31
+ **overall (0.0257)** score β€” ahead of every model we measured, specialist or commercial, on the 203-image average. Full benchmark, gallery and training recipe:
32
+ **https://github.com/egeorcun/lucida** β€” or try the [live demo](https://huggingface.co/spaces/egeorcun/lucida-demo).
33
+
34
+ > **Changelog note (2026-07-24):** an experimental v13 build was published for a day and then
35
+ > reverted β€” community testing showed it regressed on real-world layered artwork
36
+ > (poster/collage-style illustrations) that our synthetic design test set does not cover.
37
+ > The current weights are the proven v7. The v13 improvements (reduced background haze on
38
+ > real photos, a transparency milestone) will return in v14 together with the fix.
39
+
40
+ ## Files
41
+
42
+ | File | What it is | Load with |
43
+ |---|---|---|
44
+ | `model.safetensors` | **lucida-v7** β€” the published general-purpose release; the snippet above and the benchmark table refer to this. | `transformers` (with `Normalize`) |
45
+ | `lucida-m35-comfy.safetensors` | **lucida-m35 (experimental)** β€” the `design-expert` branch working model: a checkpoint blend of the v8–v13 background-purity soup with the v18 limb/atmosphere campaign (0.65/0.35), exported **folded** for ComfyUI: the `Normalize` preprocessing is baked into the first conv. | ComfyUI `RemoveBackground` node β€” **not** the `transformers` snippet (no `Normalize` at inference) |
46
+
47
+ ### lucida-m35 + the design pipeline (ComfyUI)
48
+
49
+ Try it in the browser: **[lucida-design space](https://huggingface.co/spaces/egeorcun/lucida-design)** β€” the full pipeline (m35 + SAM3 referee + poster policy) on ZeroGPU.
50
+
51
+ m35 is tuned for **print/POD design artwork** (posters, tee graphics, stickers) and is
52
+ meant to run inside a pipeline, not bare: poster policy (training-free decision layer)
53
+ + SAM3 semantic referee (protective subject evidence) + finish package (color
54
+ decontamination, edge defringe). The whole chain ships as ComfyUI custom nodes with a
55
+ ready workflow β€” install steps:
56
+ [github.com/egeorcun/lucida/tree/design-expert/comfyui](https://github.com/egeorcun/lucida/tree/design-expert/comfyui).
57
+
58
+ Place the file in `ComfyUI/models/background_removal/`. The referee additionally uses
59
+ [facebook/sam3](https://huggingface.co/facebook/sam3) (gated β€” accept the license with
60
+ your own HF account) and CLIP ViT-B/32, both auto-downloaded on first run.
61
+
62
+ Verified against the 203-image benchmark for zero category regression vs the published
63
+ v7 before adoption; the pipeline itself is judged by eye against a commercial
64
+ reference on real design artwork (duel catalog in the branch docs). Outside the design
65
+ domain the poster policy is not recommended β€” use `model.safetensors` bare instead.
66
+
67
+ ## Usage
68
+
69
+ ```python
70
+ import torch
71
+ from PIL import Image
72
+ from torchvision import transforms
73
+ from transformers import AutoModelForImageSegmentation
74
+
75
+ model = AutoModelForImageSegmentation.from_pretrained(
76
+ "egeorcun/lucida", trust_remote_code=True, dtype=torch.float32)
77
+ model.eval()
78
+
79
+ t = transforms.Compose([
80
+ transforms.Resize((1024, 1024)),
81
+ transforms.ToTensor(),
82
+ transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]),
83
+ ])
84
+ img = Image.open("input.jpg").convert("RGB")
85
+ with torch.no_grad():
86
+ preds = model(t(img).unsqueeze(0))[-1].sigmoid()
87
+ alpha = transforms.functional.resize(preds[0], img.size[::-1]).squeeze(0)
88
+ rgba = img.copy()
89
+ rgba.putalpha(Image.fromarray((alpha.numpy() * 255).astype("uint8")))
90
+ rgba.save("output.png")
91
+ ```
92
+
93
+ For color decontamination (removing background color fringing) and the full
94
+ pipeline (CLI, FastAPI service, Docker web UI), see the GitHub repository.
95
+
96
+ ## Base model & attribution
97
+
98
+ - Architecture and initial weights: [ZhengPeng7/BiRefNet_HR](https://huggingface.co/ZhengPeng7/BiRefNet_HR) (MIT). Lucida is a fine-tune; the original copyright notice is preserved.
99
+ - Illustration data includes [ToonOut](https://huggingface.co/datasets/joelseytre/toonout) (CC-BY 4.0).
100
+ - Some training datasets (e.g. P3M-10k, COD10K, DIS5K) are distributed for research
101
+ purposes; see the GitHub README for the full dataset/license table and evaluate
102
+ suitability for your use case.
103
+
104
+ ## License
105
+
106
+ MIT (weights and code).