hdae/karume-lucida

Lucida (BiRefNet) — Karume

This is an unofficial conversion of egeorcun/lucida for Karume. It is not affiliated with or endorsed by egeorcun.

What is this

A background-removal distribution, converted into the WebGPU inference runtime Karume's container format (a .krm part sequence whose first part carries the graph and model descriptors). Runs as-is in the browser and in Deno.

The weights are a BiRefNet fine-tune aimed at camouflage, transparency, text/logos and illustration.

• One graph, one call: pixels in, an 8-bit alpha matte out, at the same size as the image you handed over.
• One model per input resolution. The resolution is baked into the graph (window masks and padding constants are per-resolution), so it is picked with model, not at call time. Each model declares its own resize target below; the bigger one holds more detail at the edges and costs more GPU memory and time.
• Pre- and post-processing are included. The pipeline resizes to 1024 × 1024 for the default model 1024, normalizes with the constants below, then takes the sigmoid of the logits, scales the matte back to the original resolution and rounds it to 8 bits — in the order and with the interpolation upstream uses for this checkpoint (listed per model below). Decoding PNG / JPEG is not part of this — use createImageBitmap in the browser, or any decoder in Deno.
• Compositing is yours. The pipeline returns the matte, not a cut-out: whether alpha goes into an RGBA buffer, gets composited over a flat colour, or is fed to a colour decontamination pass is a decision this repository should not make for you.
• Not readable by transformers (it's a different container with an embedded graph); the reader is a pipeline that implements birefnet/2.
• Exporter used for the conversion: karume/0.14.0. The distribution manifest is karume.json (karume/5).

Base weights and attribution

• Weights: egeorcun/lucida, licensed mit (as of retrieval) — a verbatim copy of the license, carrying the copyright notices that apply to this repository, is in LICENSE.md.
• Fine-tune of: ZhengPeng7/BiRefNet_HR (mit) — architecture and initial weights; the upstream copyright notice is preserved.
• Illustration training data includes ToonOut (CC-BY-4.0); other sets it draws on (P3M-10k, COD10K, DIS5K) are distributed for research purposes — check them against your own use case.
• Not included: lucida-m35-comfy.safetensors. That experimental variant has the Normalize step folded into its first convolution (it expects raw [0, 1] pixels), so the preprocessing this pipeline applies would be counted twice, and upstream ships it to run inside a larger ComfyUI pipeline rather than bare.
• Architecture: BiRefNet (arxiv.org/abs/2401.03407).
• Changes made here (also listed in NOTICE.md): conversion into the Karume container format. No retraining and no fine-tuning; the stored values per quant seat are listed below. The graph is the upstream forward with layout-only rewrites (windowing, the shifted-window roll, spatial padding and the patch merges were folded into equivalent operations — bit-exact), plus three rewrites that are equivalent up to floating-point rounding: inference-time BatchNorm2d became a per-channel affine, the ASPP image-level pooling became a two-stage sum, and the decoder tail's 1×1 convolution was swapped with the bilinear upsample it used to follow (both are linear, so they commute — this removes two full-resolution intermediates).
• Quantization: the source checkpoint is stored in f32; per quant seat:
  • f32: the checkpoint's own f32 values, unchanged.
  • f16: quantized — every weight was rounded to the nearest f16 value before export; the linear, convolution and embedding (relative-position) weights are stored as f16, the deformable convolutions' sampling weights (regular_conv), the biases and the remaining normalization parameters keep f32 storage, inference-time BatchNorm is a derived per-channel affine in f32, and all computation stays in f32.

Models

Model	Pipeline	Quants	Default quant
1024 (default)	birefnet/2	f32 / f16	f32
2048	birefnet/2	f32 / f16	f32

model selects one of these; omitted, it is 1024. quant defaults to that model's own default quant.

Usage

import { Pipeline } from "jsr:@karume/models/birefnet";

await using pipeline = await Pipeline.fromPretrained({
  repo: "hdae/karume-lucida",
  // Pin a commit for reproducible builds — without it you track `main`, and a future
  // repo update (renamed files, new manifest format) may break your app.
  // Copy the full hash from this repo's "Files and versions" tab:
  // revision: "<full commit sha>",
}, {
  // model: "1024", // default — available: 1024 / 2048
  // quant: "f32", // default — available: f16 / f32
});

// RGB8, row-major, 3 bytes per pixel. Decoding is the caller's job.
const image = { data: pixels, width, height };
const matte = await pipeline.segment(image);

// matte.data is one alpha byte per pixel, same width/height as the input.
// Straight alpha into an RGBA buffer (canvas, ImageData, an RGBA encoder):
const rgba = new Uint8Array(matte.width * matte.height * 4);
for (let i = 0; i < matte.data.length; i += 1) {
  for (let c = 0; c < 3; c += 1) rgba[i * 4 + c] = image.data[i * 3 + c];
  rgba[i * 4 + 3] = matte.data[i];
}

segment() keeps one GPU session alive for the lifetime of the pipeline, so processing many images uploads the weights once; concurrent calls are queued rather than run side by side. Weights are fetched once and cached (verified against karume.json's size / sha256).

Model: 1024

Quants

Quant	What it is	Download	Weights	Compute
f32 (default)	Full precision (f32) — Every weight in f32 storage — the largest download and the most resident GPU memory.	843 MiB (842 MiB shared)	matte = f32	—
f16	Half-size weights (f16) — The linear, convolution and embedding (relative-position) weights stored as f16 and computed in f32 — a smaller download and less resident GPU memory.	432 MiB (431 MiB shared)	matte = f16	—

If no quant is given, it runs as f32 (this model's recommended default). Per-file size and sha256 live in karume.json — verify against that at the fetch layer. Dtype labels use the runtime's storage dtype vocabulary (f16 / bf16 / i8 / i4 / i2), not the fp16 spelling common elsewhere in the ecosystem. Weights ship as Karume container files (.krm), split into numbered parts; a part is fetched and verified on its own. A path under shared/ is one this model shares byte for byte with another model in this repository (it is fetched and cached once).

Input and output

The resize target is the exported graph's own input shape; the normalization constants are the upstream preprocessor's (ImageNet statistics).

• input: RGB8 pixels, resized to 1024 × 1024 (bilinear, antialiased). The aspect ratio is not preserved — there is no crop and no padding, matching the upstream processor.
• normalization: (pixel / 255 - mean) / std, mean 0.485 / 0.456 / 0.406, std 0.229 / 0.224 / 0.225
• output: one alpha byte per pixel at the size of the image you passed in (the graph itself emits pre-sigmoid logits; the sigmoid and the resize back happen on the host).
• post-processing (float-bilinear, the order upstream uses for this checkpoint): the sigmoid of the logits is resized back to the image's size in floating point with antialiased bilinear interpolation, then rounded to 8 bits. Rounding is half-up (the upstream code truncates).
• required GPU memory: about 1.5 GiB allocated in total with the f32 quant — its weights listed above, resident, plus 689 MiB for the intermediate tensors — and the largest single storage buffer is 320 MiB (memory from the runtime's estimate, 2026-10-26; run time measured 2026-10-16 on an RTX 3080 Ti); one image takes about 1.4 s. WebGPU's default maxStorageBufferBindingSize is 128 MiB, so this is in practice a desktop-class GPU requirement. karume.json does not declare it: the declared limits cover the resident weights and state, not the intermediate tensors a run allocates.

Model: 2048

Quants

Quant	What it is	Download	Weights	Compute
f32 (default)	Full precision (f32) — Every weight in f32 storage — the largest download and the most resident GPU memory.	843 MiB (842 MiB shared)	matte = f32	—
f16	Half-size weights (f16) — The linear, convolution and embedding (relative-position) weights stored as f16 and computed in f32 — a smaller download and less resident GPU memory.	432 MiB (431 MiB shared)	matte = f16	—

If no quant is given, it runs as f32 (this model's recommended default). Per-file size and sha256 live in karume.json — verify against that at the fetch layer. Dtype labels use the runtime's storage dtype vocabulary (f16 / bf16 / i8 / i4 / i2), not the fp16 spelling common elsewhere in the ecosystem. Weights ship as Karume container files (.krm), split into numbered parts; a part is fetched and verified on its own. A path under shared/ is one this model shares byte for byte with another model in this repository (it is fetched and cached once).

Input and output

The resize target is the exported graph's own input shape; the normalization constants are the upstream preprocessor's (ImageNet statistics).

• input: RGB8 pixels, resized to 2048 × 2048 (bilinear, antialiased). The aspect ratio is not preserved — there is no crop and no padding, matching the upstream processor.
• normalization: (pixel / 255 - mean) / std, mean 0.485 / 0.456 / 0.406, std 0.229 / 0.224 / 0.225
• output: one alpha byte per pixel at the size of the image you passed in (the graph itself emits pre-sigmoid logits; the sigmoid and the resize back happen on the host).
• post-processing (float-bilinear, the order upstream uses for this checkpoint): the sigmoid of the logits is resized back to the image's size in floating point with antialiased bilinear interpolation, then rounded to 8 bits. Rounding is half-up (the upstream code truncates).
• required GPU memory: about 3.5 GiB allocated in total with the f32 quant — its weights listed above, resident, plus 2,725 MiB for the intermediate tensors — and the largest single storage buffer is 1,280 MiB (memory from the runtime's estimate, 2026-10-26; run time measured 2026-10-16 on an RTX 3080 Ti); one image takes 6.7 – 6.9 s. WebGPU's default maxStorageBufferBindingSize is 128 MiB, so this is in practice a desktop-class GPU requirement. karume.json does not declare it: the declared limits cover the resident weights and state, not the intermediate tensors a run allocates.