Lucida Background Removal

Use the bgr executable from egeorcun/lucida. Preserve the source image and create a separate transparent PNG.

Workflow

1. Resolve the input image and confirm it exists.

2. Use the user's output path when provided. Otherwise, write <input-stem>-transparent.png beside the input. Do not overwrite the source unless the user explicitly requests it.

3. Check whether bgr is available:

   bgr --help
   

   If the current environment is sandboxed, run all bgr commands in the user's normal terminal.

4. If bgr is missing, verify that uv is available and install the CLI:

   uv tool install --from git+https://github.com/egeorcun/lucida.git my-bg-remover
   

   The package requires Python 3.12 or newer. The installation exposes one executable: bgr.

5. Select the model:

   • Use lucida by default, especially for glass, partial transparency, smoke, glow, VFX, camouflage, text or logos with soft shadows, line art, illustrations, and print or sticker designs.
   • Use birefnet-hr for high-resolution general segmentation, especially solid physical subjects, product photos, or when Lucida keeps unwanted low-alpha background haze. Expect higher compute and memory use because it processes at 2048×2048.
   • Read references/models.md only when an alternate model, a versioned local checkpoint, or model-loading troubleshooting is needed.

6. Run the removal command with quoted paths:

   bgr remove "<input-path>" -o "<output-path>.png" --model lucida
   

   Replace lucida with birefnet-hr when that model better matches the subject.

7. Confirm that the command succeeds and the output PNG exists. Inspect the result when image viewing is available, paying particular attention to partial transparency, holes, fine edges, retained background haze, and color fringing.

8. Return the output file to the user and state which model and optional flags were used.

Optional passes

• Add --refine when the first result has visibly rough or broken edges. Treat it as a retry, not a default, because refinement adds processing and can change soft boundaries.
• Keep color decontamination enabled by default. Add --no-decontaminate only when decontamination shifts intentional glow, translucent color, or edge color.
• Change one variable per retry so the effect of the model or flag remains clear.

Examples:

bgr remove "input.jpg" -o "output.png" --model lucida --refine
bgr remove "product.jpg" -o "product-transparent.png" --model birefnet-hr
bgr remove "glow.png" -o "glow-transparent.png" --model lucida --no-decontaminate

Weight behavior

• The current lucida registry entry uses the Hugging Face model ID egeorcun/lucida. On first use, Transformers downloads the published weights to its cache; allow time and network access for this download.
• The birefnet-hr registry entry uses the Hugging Face model ID ZhengPeng7/BiRefNet_HR and downloads its published weights to the same cache on first use.
• The separate lucida-v7 registry entry expects a training checkpoint at data/checkpoints/epoch_7.pth, resolved from the command's working directory. Use that entry only when the matching training checkpoint is already available at that exact path.
• Do not rename the published model.safetensors to epoch_7.pth: the local entry expects a training-checkpoint payload containing a model state dictionary.

Guardrails

• Always use PNG for transparent output. JPEG cannot preserve an alpha channel.
• Keep the original dimensions unless the user explicitly requests resizing.
• Do not claim success from the command exit alone when visual inspection is possible.
• Do not switch to experimental or versioned checkpoints without explaining the choice.