obrobka

完全在浏览器中运行的图像处理——转换、调整大小、移除背景。文件永远不会离开你的设备。

obrobka.dobrovolskyi.com.ua

以乌克兰语优先，英语其次。采用 MIT 许可证。

它能做什么

所有操作都在 Web Worker 中，以 WebAssembly 形式运行。没有服务器、没有上传、没有账号。

Related MCP server: Agent Helper

它为什么值得你关注

同一个核心既能驱动浏览器应用，也能驱动 MCP 服务器。packages/core 与 DOM 和 NODE 无关——它只是基于 RGBA 缓冲区的纯函数，所有 I/O 都放在 port 边界之后。一个runJob() 同时服务于浏览器标签页和 AI 智能体。

npx obrobka-mcp

可给智能体八个工具——convert_image、resize_image、remove_background、smart_crop、upscale_image、read_metadata、strip_metadata 和 process_batch——它们操作的是文件路径，而不是 base64 数据块。

• 模型选择依据的是实测，而不是模型卡。 每个候选在入选前都会被下载并分析。数字见 M2 计划 两个的发现改变了设计：

  • MODNet 和 OBNG 只在人物上训练。用于非人物主体时返回空遮罩，因此不能作为通用默认选项。

  • BiRefNet_lite 在 1024×1024 可用内存 4.2 GB 时被 OEM killer 杀掉。浏览器标签页上限更低，因此它被剔除。

• U²-Netp 只有 4.4 MB，却证明是通用的，默认档位因此比原计划轻了十倍。

• 你手机里的照片可能处理完变成横的了，而且毫无征兆。 JPEG 和 HEIC 把方向存成标签，而不是放在像素中。<jsquash/jpeg> 会忽略这个标签；浏览器的 <img> 则会应用它。于是“处理前”的预览是正的，结果却成了横向——这是在刻意构造的 8×4 JPEG、并带有 Orientation: 6 上测量到的；无论是否读取标签，它解码后都是 8×4。现在，处理流程会先读取该标签并旋转，然后再执行所有需要依赖坐标的操作。

• 批量方案的并发有两个不同的正确答案。 没有模型时，四个 worker 处理20个文件，耗时从 3639 ms 降到 1186 ms——对于 223 MB 的数据提速 3.1。有模型时，同样的线程池反而是一个陷阱：ONNX Runtime 又在一个会话内部进行并行，所以四个 U²-Netp 会话只带来 1.8 ×，却要占 1.2 GB；而两个 isnet 会话就已经到 2.2 个还是"G" 时 reaches? "2.2 GB" 已经超过了标签页能容纳的内存。因此并发池是 at needsModel ? 1 : min(cores − 1,4).

• ZIP 压缩取决于文件格式，但结果与你的直觉不同。 对 WebP 进行 deflate，节省 0.1%，却耗十倍 CPU——符合预期。对我们的 PNG 进行 deflate 节省 15.2%，因为编码器压缩速度快，留下了冗余。PNG 使用 level 4，其他格式全部 store。

架构

packages/core             pure ops over RGBA buffers — no DOM, no Node
  ops/                    resample · crop · fit · mask · outline · smartCrop
  ports/                  Codec · Segmenter · Upscaler · Metadata
packages/codecs           jSquash, split into browser and Node adapters
packages/models           model registry and three preprocessing recipes
packages/onnx-node        onnxruntime-node + on-disk cache
packages/onnx-web         onnxruntime-web + Cache Storage, WebGPU → WASM
packages/metadata         EXIF reading (exifr) and byte-level stripping
packages/heic             libheif, isolated — LGPL, loaded on demand
packages/contract-tests   one suite, run against both adapters
apps/web                  Astro + Svelte island, PWA
apps/mcp                  stdio MCP server

契约测试是 port 分界线的关键：同一套测试同时运行于 onnxruntime-node 和 onnxRuntime-web，这样两者之间的差异会立即浮出水面，而不是到了生产环境才暴露。

模型

所有 model 都采用宽松许可——项目接受赞助，所以非商业许可证的模型反而不合适。

模型托管在 R2 上，并在首次使用后缓存在浏览器中。

开发

需要 Node ≥ 22.12 和 pnpm 11。

pnpm install
pnpm typecheck
pnpm test
pnpm --filter @obrobka/web dev

有些测试需要真实的 HEIC 文件，而它们无法在本地生成——libheif 只能读取。该文件一次从 HEIC conformance 测试集中获取，并缓存在 ~/.cache/obrobka/fixtures，和模型放一起。其他所有内容，包括带 EXIF orientation 和 GPS 的 JPEG，都是测试时逐字节构造的：仓库里有照片，就会是某人的照片、某人的坐标。

端到端测试会跑在一个应用了生产环境 _headers 的静态服务器上，因为 crossOriginIsolated 无法在其他方式下得到验证：

pnpm --filter @obrobka/web build
pnpm exec playwright test

关于测试的一点说明

分割模型的测试对象是一个程序化生成的带光影球体，而不是真实照片。这能证明管线可以跑通——预处理、推理、掩膜、合成——但无法说明头发、玻璃或毛发的处理质量。请通过实际使用网站来验证。

早期的一个测试样本，是带硬边的平面圆，后来发现它对于这些模型来说是分布外数据：同一个形状，得分是0.93 还是0.93，仅取决于它有没有被放大一点。若你为分割模型写测试，这一点值得了解。

许可证

MIT。模型权重使用各自上表所列的许可证。