@xprite/pixelate 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rhinoc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,12 @@
+# Third-party notices
+
+| Part | Source | License | Text |
+| --- | --- | --- | --- |
+| `wasm/` and `wasm-src/`: AC+RL grid-count consensus (`acf`, `autocorr`, `runlengths`, `gray`, `sigproc`), made sequential and compiled to WebAssembly | [Retro-Diffusion/pixel-art-fixer](https://github.com/Retro-Diffusion/pixel-art-fixer), Copyright (c) 2026 Astropulse, LLC | MIT | [licenses/pixel-art-fixer-MIT.txt](licenses/pixel-art-fixer-MIT.txt) |
+| `src/line-guided/pixeloe-legacy.ts`, `cv-ops.ts`, `cv-lab.ts`: port of PixelOE's legacy `pixelize()` | [KohakuBlueleaf/PixelOE](https://github.com/KohakuBlueleaf/PixelOE) | Apache-2.0 | [licenses/PixelOE-Apache-2.0.txt](licenses/PixelOE-Apache-2.0.txt) |
+| `src/pixeloe-prepass.ts`: port of PixelOE's outline expansion and colour match (`torch/outline.py`, `torch/color.py`); `src/cell-color-picker.ts`: its contrast-based downscale | [KohakuBlueleaf/PixelOE](https://github.com/KohakuBlueleaf/PixelOE) | Apache-2.0 | [licenses/PixelOE-Apache-2.0.txt](licenses/PixelOE-Apache-2.0.txt) |
+| `src/grid-detect.ts`: the edge-mesh idea (anchor cuts on projected edges, fill gaps at an even pitch); `src/cell-color-picker.ts`: per-cell colour choice and output colour merging | [KennethJAllen/proper-pixel-art](https://github.com/KennethJAllen/proper-pixel-art), Copyright (c) 2024 Kenneth Allen | MIT | [licenses/proper-pixel-art-MIT.txt](licenses/proper-pixel-art-MIT.txt) |
+| `src/palette-snap.ts`: Bayer 8x8 matrix and ordered dithering to a palette (`matrices.rs`, `ordered.rs`) | [tensorhead/dithering](https://github.com/tensorhead/dithering) | MIT | [licenses/tensorhead-dithering-MIT.txt](licenses/tensorhead-dithering-MIT.txt) |
+
+The PixelOE ports are modified versions: they were rewritten from Python, OpenCV and NumPy into
+TypeScript, and the legacy port's expansion weight can be replaced by a line guide.

package/README.md

@@ -1,3 +1,271 @@
-# Temporary Holding Version
+# @xprite/pixelate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@xprite/pixelate)](https://www.npmjs.com/package/@xprite/pixelate)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+English | [简体中文](https://github.com/rhinoc/xprite-pixelate/blob/main/README.zh-CN.md)
+
+Recover the real pixel grid of AI-generated pixel art and get back one clean pixel per cell. It
+also turns ordinary images into pixel art. It runs in browsers and Node, has no runtime
+dependencies, and is the importer of the [Xprite](https://xprite.cc) pixel editor.
+
+## Compared with other tools
+
+A real generated image (887×887, cells 15 to 21 px wide), recovered by each tool with its default
+settings. Xprite puts each cut on a colour edge, so it does not cut through the eye, the boots or
+the sword.
+
+| Recovered grid | Xprite, 48×49 | [pixel-art-fixer](https://github.com/Retro-Diffusion/pixel-art-fixer), 47×48 | [perfectPixel](https://github.com/theamusing/perfectPixel), 50×50 | [proper-pixel-art](https://github.com/KennethJAllen/proper-pixel-art), 53×54 |
+| :---: | :---: | :---: | :---: | :---: |
+| ![Grid](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/griffith-mesh.png) | ![Xprite](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/griffith-xprite.png) | ![pixel-art-fixer](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/griffith-fixer.png) | ![perfectPixel](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/griffith-perfectpixel.png) | ![proper-pixel-art](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/griffith-proper.png) |
+
+On the AI suite of [our benchmark](#benchmark) (1746 cases), Xprite gets the exact size most
+often:
+
+| Method | Exact size | Within 1 cell | Pixel match | Half-transparent fringe | Median time |
+| --- | --- | --- | --- | --- | --- |
+| Xprite Auto | **83.6%** | **90.0%** | **99.8%** | 0.1% | 1.55 s |
+| pixel-art-fixer | 49.7% | 80.9% | 98.3% | 0.0% | 0.18 s |
+| perfectPixel | 53.3% | 68.0% | 96.7% | - | 0.03 s |
+| proper-pixel-art | 72.2% | 80.4% | 99.7% | 0.0% | 0.49 s |
+
+## Contents
+
+- [Examples](#examples)
+- [Install](#install)
+- [Usage](#usage)
+- [How it works](#how-it-works)
+- [Benchmark](#benchmark)
+- [License](#license)
+
+## Examples
+
+Each example is one case from a category of the benchmark's AI suite: CC0 pixel art rendered the
+way generators fake it, with a known native size. The sizes are the visible art in cells; ✓ marks
+the exact native size. Every tool runs with its default settings.
+
+### Two sprites on one canvas
+
+- [Goblins by LuizMelo](https://luizmelo.itch.io/monsters-creatures-fantasy), CC0. Category `gen_pair`. Native art: 78×36.
+
+| Input, 1800×845 | Xprite, 78×36 ✓ | pixel-art-fixer, 78×35 ✗ | perfectPixel, 80×36 ✗ | proper-pixel-art, 79×36 ✗ |
+| :---: | :---: | :---: | :---: | :---: |
+| ![Input, 1800×845](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/pair-input.png) | ![Xprite](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/pair-xprite.png) | ![pixel-art-fixer](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/pair-fixer.png) | ![perfectPixel](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/pair-perfectpixel.png) | ![proper-pixel-art](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/pair-proper.png) |
+
+### Cells that drift and jitter
+
+- [Boss dragon by ansimuz](https://opengameart.org/content/sideview-fantasy-patreon-collection), CC0. Category `gen_wobble`. Native art: 71×39.
+
+| Input, 1226×664 | Xprite, 71×39 ✓ | pixel-art-fixer, 69×38 ✗ | perfectPixel, 74×39 ✗ | proper-pixel-art, 69×38 ✗ |
+| :---: | :---: | :---: | :---: | :---: |
+| ![Input, 1226×664](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/wobble-input.png) | ![Xprite](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/wobble-xprite.png) | ![pixel-art-fixer](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/wobble-fixer.png) | ![perfectPixel](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/wobble-perfectpixel.png) | ![proper-pixel-art](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/wobble-proper.png) |
+
+### Small cells and WebP damage
+
+- [Monster by Denzi](https://opengameart.org/content/denzis-public-domain-art), CC0. Category `gen_small_pitch`. Native art: 32×48.
+
+| Input, 218×339 | Xprite, 32×48 ✓ | pixel-art-fixer, 32×47 ✗ | perfectPixel, 32×49 ✗ | proper-pixel-art, 34×49 ✗ |
+| :---: | :---: | :---: | :---: | :---: |
+| ![Input, 218×339](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/small-input.png) | ![Xprite](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/small-xprite.png) | ![pixel-art-fixer](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/small-fixer.png) | ![perfectPixel](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/small-perfectpixel.png) | ![proper-pixel-art](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/small-proper.png) |
+
+### A small sprite on a large clear canvas
+
+- [Nekomimi girl by cawfeecrow](https://opengameart.org/content/nekomimi-girl-portrait), CC0. Category `gen_sparse`. Native art: 123×136.
+
+| Input, 1797×1800 | Xprite, 123×136 ✓ | pixel-art-fixer, 122×136 ✗ | perfectPixel, 124×136 ✗ | proper-pixel-art, 127×142 ✗ |
+| :---: | :---: | :---: | :---: | :---: |
+| ![Input, 1797×1800](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/sparse-input.png) | ![Xprite](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/sparse-xprite.png) | ![pixel-art-fixer](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/sparse-fixer.png) | ![perfectPixel](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/sparse-perfectpixel.png) | ![proper-pixel-art](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/sparse-proper.png) |
+
+### An off-white background
+
+- [Dragon by ansimuz](https://opengameart.org/content/sideview-fantasy-patreon-collection), CC0. Category `gen_white`. Native art: 162×106.
+
+| Input, 1800×1210 | Xprite, 162×106 ✓ | pixel-art-fixer, 325×208 ✗ | perfectPixel, 161×105 ✗ | proper-pixel-art, 168×106 ✗ |
+| :---: | :---: | :---: | :---: | :---: |
+| ![Input, 1800×1210](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/white-input.png) | ![Xprite](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/white-xprite.png) | ![pixel-art-fixer](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/white-fixer.png) | ![perfectPixel](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/white-perfectpixel.png) | ![proper-pixel-art](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/white-proper.png) |
+
+### Painterly shading inside cells
+
+- [Naga mage, Dungeon Crawl Stone Soup](https://github.com/crawl/tiles), CC0. Category `gen_painterly`. Native art: 31×32.
+
+| Input, 411×425 | Xprite, 31×32 ✓ | pixel-art-fixer, 30×33 ✗ | perfectPixel, 31×32 ✓ | proper-pixel-art, 31×34 ✗ |
+| :---: | :---: | :---: | :---: | :---: |
+| ![Input, 411×425](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/painterly-input.png) | ![Xprite](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/painterly-xprite.png) | ![pixel-art-fixer](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/painterly-fixer.png) | ![perfectPixel](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/painterly-perfectpixel.png) | ![proper-pixel-art](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/painterly-proper.png) |
+
+## Install
+
+```bash
+npm install @xprite/pixelate
+```
+
+## Usage
+
+An image is `{ width, height, data }`, where `data` holds RGBA bytes, row by row, with straight
+alpha. `ImageData` from a canvas has this shape.
+
+### Recover a grid
+
+```ts
+import {
+  CellColorPicker,
+  PixelationAlgorithm,
+  PixelationMode,
+  detectWithAlgorithm,
+  pixelateImage,
+  preloadWasm,
+} from "@xprite/pixelate";
+
+await preloadWasm(); // optional: loads the grid-count detector once, before the first image
+
+const image = { width, height, data: new Uint8ClampedArray(rgba) };
+
+const grid = detectWithAlgorithm(image, PixelationAlgorithm.Auto);
+if (grid.reliable) {
+  const art = pixelateImage(image, {
+    mode: PixelationMode.RecoverGrid,
+    grid,
+    colorPicker: CellColorPicker.TwoStage,
+    paletteSnap: { adaptive: true }, // merge the near-shades a generator leaves behind
+  });
+  // art.width × art.height is the native size: one pixel per recovered cell.
+}
+```
+
+`grid.reliable` is false when the image has no consistent grid (a photo, a drawing, or real 1×
+pixel art). `RecoverGrid` mode throws an error for such a grid. Use `Convert` mode for those
+images.
+
+### Convert an image
+
+```ts
+const art = pixelateImage(photo, {
+  mode: PixelationMode.Convert,
+  targetSize: { width: 64, height: 64 },
+  paletteSnap: { colors: 16 },
+});
+```
+
+### Remove a flat background
+
+```ts
+import { removeBackground } from "@xprite/pixelate";
+
+const clear = removeBackground(image); // keys the most common border colour
+```
+
+Call it before detection when a generator painted a white or checkerboard background.
+
+### Options
+
+`pixelateImage(image, options)`:
+
+| Option | Description |
+| --- | --- |
+| `mode` | `RecoverGrid` uses a detected grid. `Convert` makes pixel art at a size you give. |
+| `grid` | A grid from `detectWithAlgorithm`. If you omit it, the grid is detected with `algorithm`. |
+| `algorithm` | Grid detector. `Auto` runs all of them and picks one grid. |
+| `colorPicker` | Colour rule per cell: `TwoStage`, `MostCommon` (default), `Median`, `Average`, `KMeans`, `Contrast` and others. |
+| `targetSize`, `targetWidth`, `targetHeight`, `blockSize` | Output size in `Convert` mode. |
+| `paletteSnap` | Limit colours: `{ adaptive: true }`, `{ colors: 16 }` or `{ palette: [...] }`, with optional `dither`. |
+| `prepass` | Outline pre-pass from PixelOE (`Pixeloe`, `PixeloeLines`). |
+| `removeNoise` | Light smoothing of similar neighbour colours. |
+| `preserveDimensions` | Scale the result back up to the source size, nearest neighbour. |
+
+[`src/types.ts`](src/types.ts) documents every option.
+
+### Workers
+
+`detectWithAlgorithm` and `pixelateImage` are synchronous and can take a few seconds on large
+images, so run them in a Web Worker. In a browser, Auto can also run its grid-count detector in a
+nested worker, in parallel with the other detectors:
+
+```ts
+import { setAcRlBrowserWorkerFactory, detectWithAlgorithmAsync } from "@xprite/pixelate";
+
+setAcRlBrowserWorkerFactory(
+  () =>
+    new Worker(
+      new URL("@xprite/pixelate/wasm/ac-rl-detect-browser-worker.js", import.meta.url),
+      { type: "module" },
+    ),
+);
+const grid = await detectWithAlgorithmAsync(image);
+```
+
+In Node, the detector starts a `worker_threads` worker from `wasm/ac-rl-detect-worker.mjs` by
+itself. Set `XPRITE_AC_RL_WORKER=0` to keep it on the calling thread.
+
+## How it works
+
+1. **Straighten.** Auto estimates the tilt. When the tilt is clear, it detects on a straightened
+   copy.
+2. **Propose.** Seven detectors propose grids: uniform grid, edge grid, frame lattice, pitch
+   lattice, colour period, border runs and edge spacing. A WebAssembly port of pixel-art-fixer's
+   autocorrelation and run-length vote gives an independent cell count.
+3. **Follow the edges.** At each pitch the detectors keep, a dynamic program walks each axis and
+   puts every cut on a colour edge. Each cell stays within 0.75 to 1.25 of the pitch, and a change
+   of width costs extra. This step handles cells of uneven width.
+4. **Filter.** A candidate is dropped when its cuts miss the colour edges that a coarser grid
+   follows.
+5. **Choose.** The grid that describes the image in the fewest bits wins (minimum description
+   length). A grid that is not locked to the content's phase pays a penalty. Drift and sheared
+   rows are read as strip shifts or as a phase field.
+6. **Sample.** Each cell gets one colour (`TwoStage` packs the cell's colours in two steps).
+   Adaptive palette snapping then merges near-duplicate shades.
+7. **Settle alpha.** Cells that the art covers become fully opaque, and cells outside the art
+   become clear.
+
+Each source file in [`src/`](src) describes its step.
+
+## Benchmark
+
+[`bench/`](bench) compares this package with three other tools on CC0 native pixel art. The
+benchmark damages the art in known ways and scores each result against the original. Every tool
+runs with its default settings.
+
+AI suite (1746 cases in 12 categories, rendered the way generators fake pixel art):
+
+| Method | Exact size | Within 1 cell | Pixel match | ΔE | Half-transparent fringe | Median time |
+| --- | --- | --- | --- | --- | --- | --- |
+| Xprite Auto | **83.6%** | **90.0%** | **99.8%** | 0.82 | 0.1% | 1.55 s |
+| pixel-art-fixer | 49.7% | 80.9% | 98.3% | 1.74 | 0.0% | 0.18 s |
+| perfectPixel | 53.3% | 68.0% | 96.7% | 2.42 | - | 0.03 s |
+| proper-pixel-art | 72.2% | 80.4% | 99.7% | **0.64** | 0.0% | 0.49 s |
+
+Exact size per category:
+
+| Category | Xprite | pixel-art-fixer | perfectPixel | proper-pixel-art |
+| --- | --- | --- | --- | --- |
+| Clean (`gen_clean`) | **93.6%** | 71.7% | 58.4% | 74.6% |
+| Sparse canvas (`gen_sparse`) | **99.0%** | 63.5% | 71.9% | 88.5% |
+| Off-white background (`gen_white`) | 77.7% | 65.2% | 66.1% | **82.1%** |
+| Soft outline (`gen_soft_edge`) | **95.8%** | 61.9% | 67.8% | 82.2% |
+| Drift and WebP (`gen_webp`) | **80.9%** | 40.5% | 57.8% | 71.1% |
+| Halos and JPEG (`gen_halo_jpeg`) | **82.7%** | 52.6% | 60.1% | 72.8% |
+| Painterly shading (`gen_painterly`) | **84.5%** | 39.1% | 67.8% | 79.3% |
+| Small cells (4-8 px) (`gen_small_pitch`) | **72.2%** | 47.9% | 40.2% | 43.8% |
+| Large cells (24-48 px) (`gen_large_pitch`) | 68.2% | 22.0% | 68.2% | **78.0%** |
+| Strong drift (`gen_wobble`) | **73.3%** | 30.8% | 30.8% | 54.1% |
+| Two sprites (`gen_pair`) | **97.1%** | 62.7% | 45.1% | 72.5% |
+| Drop shadow (`gen_shadow`) | **97.3%** | 64.0% | 0.0% | 84.7% |
+
+[pixel-bench](https://github.com/Retro-Diffusion/pixel-bench) suite v1 (7651 cases of upscales and
+lossy pipelines):
+
+| Method | Exact size | Within 1 cell | Pixel match | ΔE | Median time |
+| --- | --- | --- | --- | --- | --- |
+| Xprite Auto | **87.1%** | **90.1%** | 94.3% | **2.79** | 0.24 s |
+| pixel-art-fixer | 77.8% | 83.5% | **94.4%** | 2.83 | 0.04 s |
+| perfectPixel | 24.2% | 32.9% | 89.7% | 4.31 | 0.002 s |
+| proper-pixel-art | 16.5% | 28.6% | 93.0% | 3.85 | 0.05 s |
+
+Pixel match and ΔE are measured only on the cases with the exact size. Xprite is the slowest of
+the four tools. The damage is synthetic, so the scores show how the tools rank on these features,
+not how often they succeed on real images. [bench/README.md](bench/README.md) gives the method,
+the categories and the steps to run it.
+
+## License
+
+MIT. Parts are adapted from pixel-art-fixer, PixelOE, proper-pixel-art and tensorhead/dithering
+(see [NOTICE.md](NOTICE.md)). The example art is CC0 (see
+[bench/corpus/CREDITS.md](bench/corpus/CREDITS.md)).

package/README.zh-CN.md

@@ -0,0 +1,240 @@
+# @xprite/pixelate
+
+[![npm](https://img.shields.io/npm/v/@xprite/pixelate)](https://www.npmjs.com/package/@xprite/pixelate)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+[English](https://github.com/rhinoc/xprite-pixelate/blob/main/README.md) | 简体中文
+
+找出 AI 生成像素画中真正的像素网格，每一格还原成一个干净的像素。它也能把普通图片转成像素画。它可以在浏览器和 Node 中运行，没有运行时依赖，是像素编辑器 [Xprite](https://xprite.cc) 的导入器。
+
+## 与其他工具对比
+
+一张真实的 AI 生成图（887×887，格宽 15 到 21 像素不等），各工具用默认设置还原的结果。Xprite 把每一刀都切在颜色边缘上，所以不会切开眼睛、靴子和剑。
+
+| 找到的网格 | Xprite，48×49 | [pixel-art-fixer](https://github.com/Retro-Diffusion/pixel-art-fixer)，47×48 | [perfectPixel](https://github.com/theamusing/perfectPixel)，50×50 | [proper-pixel-art](https://github.com/KennethJAllen/proper-pixel-art)，53×54 |
+| :---: | :---: | :---: | :---: | :---: |
+| ![网格](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/griffith-mesh.png) | ![Xprite](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/griffith-xprite.png) | ![pixel-art-fixer](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/griffith-fixer.png) | ![perfectPixel](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/griffith-perfectpixel.png) | ![proper-pixel-art](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/griffith-proper.png) |
+
+在[我们的基准测试](#基准测试)的 AI 套件（1746 个用例）上，Xprite 得到正确尺寸的次数最多：
+
+| 方法 | 尺寸完全正确 | 差 1 格以内 | 像素一致率 | 半透明毛边 | 中位耗时 |
+| --- | --- | --- | --- | --- | --- |
+| Xprite Auto | **83.6%** | **90.0%** | **99.8%** | 0.1% | 1.55 s |
+| pixel-art-fixer | 49.7% | 80.9% | 98.3% | 0.0% | 0.18 s |
+| perfectPixel | 53.3% | 68.0% | 96.7% | - | 0.03 s |
+| proper-pixel-art | 72.2% | 80.4% | 99.7% | 0.0% | 0.49 s |
+
+## 目录
+
+- [示例](#示例)
+- [安装](#安装)
+- [用法](#用法)
+- [原理](#原理)
+- [基准测试](#基准测试)
+- [许可证](#许可证)
+
+## 示例
+
+每个示例取自基准测试 AI 套件的一个类别：把 CC0 像素画按生成模型的方式渲染，原画尺寸已知。尺寸是可见画面的格数，✓ 表示与原画尺寸完全一致。每个工具都使用默认设置。
+
+### 一张画布上的两个角色
+
+- [哥布林，作者 LuizMelo](https://luizmelo.itch.io/monsters-creatures-fantasy)，CC0。类别 `gen_pair`。原画：78×36。
+
+| 输入，1800×845 | Xprite，78×36 ✓ | pixel-art-fixer，78×35 ✗ | perfectPixel，80×36 ✗ | proper-pixel-art，79×36 ✗ |
+| :---: | :---: | :---: | :---: | :---: |
+| ![输入，1800×845](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/pair-input.png) | ![Xprite](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/pair-xprite.png) | ![pixel-art-fixer](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/pair-fixer.png) | ![perfectPixel](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/pair-perfectpixel.png) | ![proper-pixel-art](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/pair-proper.png) |
+
+### 格子漂移和抖动
+
+- [巨龙，作者 ansimuz](https://opengameart.org/content/sideview-fantasy-patreon-collection)，CC0。类别 `gen_wobble`。原画：71×39。
+
+| 输入，1226×664 | Xprite，71×39 ✓ | pixel-art-fixer，69×38 ✗ | perfectPixel，74×39 ✗ | proper-pixel-art，69×38 ✗ |
+| :---: | :---: | :---: | :---: | :---: |
+| ![输入，1226×664](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/wobble-input.png) | ![Xprite](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/wobble-xprite.png) | ![pixel-art-fixer](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/wobble-fixer.png) | ![perfectPixel](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/wobble-perfectpixel.png) | ![proper-pixel-art](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/wobble-proper.png) |
+
+### 小格子和 WebP 压缩损伤
+
+- [怪物，作者 Denzi](https://opengameart.org/content/denzis-public-domain-art)，CC0。类别 `gen_small_pitch`。原画：32×48。
+
+| 输入，218×339 | Xprite，32×48 ✓ | pixel-art-fixer，32×47 ✗ | perfectPixel，32×49 ✗ | proper-pixel-art，34×49 ✗ |
+| :---: | :---: | :---: | :---: | :---: |
+| ![输入，218×339](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/small-input.png) | ![Xprite](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/small-xprite.png) | ![pixel-art-fixer](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/small-fixer.png) | ![perfectPixel](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/small-perfectpixel.png) | ![proper-pixel-art](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/small-proper.png) |
+
+### 大块透明画布上的小角色
+
+- [猫耳少女，作者 cawfeecrow](https://opengameart.org/content/nekomimi-girl-portrait)，CC0。类别 `gen_sparse`。原画：123×136。
+
+| 输入，1797×1800 | Xprite，123×136 ✓ | pixel-art-fixer，122×136 ✗ | perfectPixel，124×136 ✗ | proper-pixel-art，127×142 ✗ |
+| :---: | :---: | :---: | :---: | :---: |
+| ![输入，1797×1800](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/sparse-input.png) | ![Xprite](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/sparse-xprite.png) | ![pixel-art-fixer](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/sparse-fixer.png) | ![perfectPixel](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/sparse-perfectpixel.png) | ![proper-pixel-art](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/sparse-proper.png) |
+
+### 近白色背景
+
+- [飞龙，作者 ansimuz](https://opengameart.org/content/sideview-fantasy-patreon-collection)，CC0。类别 `gen_white`。原画：162×106。
+
+| 输入，1800×1210 | Xprite，162×106 ✓ | pixel-art-fixer，325×208 ✗ | perfectPixel，161×105 ✗ | proper-pixel-art，168×106 ✗ |
+| :---: | :---: | :---: | :---: | :---: |
+| ![输入，1800×1210](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/white-input.png) | ![Xprite](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/white-xprite.png) | ![pixel-art-fixer](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/white-fixer.png) | ![perfectPixel](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/white-perfectpixel.png) | ![proper-pixel-art](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/white-proper.png) |
+
+### 格内有绘画式明暗
+
+- [娜迦法师，Dungeon Crawl Stone Soup](https://github.com/crawl/tiles)，CC0。类别 `gen_painterly`。原画：31×32。
+
+| 输入，411×425 | Xprite，31×32 ✓ | pixel-art-fixer，30×33 ✗ | perfectPixel，31×32 ✓ | proper-pixel-art，31×34 ✗ |
+| :---: | :---: | :---: | :---: | :---: |
+| ![输入，411×425](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/painterly-input.png) | ![Xprite](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/painterly-xprite.png) | ![pixel-art-fixer](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/painterly-fixer.png) | ![perfectPixel](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/painterly-perfectpixel.png) | ![proper-pixel-art](https://raw.githubusercontent.com/rhinoc/xprite-pixelate/main/docs/images/painterly-proper.png) |
+
+## 安装
+
+```bash
+npm install @xprite/pixelate
+```
+
+## 用法
+
+图像是 `{ width, height, data }`，`data` 是逐行排列的 RGBA 字节，alpha 未预乘。canvas 的 `ImageData` 就是这个结构。
+
+### 还原网格
+
+```ts
+import {
+  CellColorPicker,
+  PixelationAlgorithm,
+  PixelationMode,
+  detectWithAlgorithm,
+  pixelateImage,
+  preloadWasm,
+} from "@xprite/pixelate";
+
+await preloadWasm(); // 可选：在处理第一张图之前加载格数检测器
+
+const image = { width, height, data: new Uint8ClampedArray(rgba) };
+
+const grid = detectWithAlgorithm(image, PixelationAlgorithm.Auto);
+if (grid.reliable) {
+  const art = pixelateImage(image, {
+    mode: PixelationMode.RecoverGrid,
+    grid,
+    colorPicker: CellColorPicker.TwoStage,
+    paletteSnap: { adaptive: true }, // 合并生成模型留下的相近色
+  });
+  // art.width × art.height 是原生尺寸：每个格子一个像素。
+}
+```
+
+图里没有一致的网格时（照片、手绘，或本来就是 1× 的像素画），`grid.reliable` 为 false，`RecoverGrid` 模式会对这种网格抛出错误。这类图片请用 `Convert` 模式。
+
+### 转换图片
+
+```ts
+const art = pixelateImage(photo, {
+  mode: PixelationMode.Convert,
+  targetSize: { width: 64, height: 64 },
+  paletteSnap: { colors: 16 },
+});
+```
+
+### 去除纯色背景
+
+```ts
+import { removeBackground } from "@xprite/pixelate";
+
+const clear = removeBackground(image); // 以边框上最常见的颜色为键
+```
+
+生成模型画了白色或棋盘格背景时，先调用它，再检测网格。
+
+### 选项
+
+`pixelateImage(image, options)`：
+
+| 选项 | 说明 |
+| --- | --- |
+| `mode` | `RecoverGrid` 使用检测到的网格；`Convert` 按给定尺寸生成像素画。 |
+| `grid` | `detectWithAlgorithm` 返回的网格。省略时用 `algorithm` 检测。 |
+| `algorithm` | 网格检测器。`Auto` 运行全部检测器并选出一个网格。 |
+| `colorPicker` | 每格的取色规则：`TwoStage`、`MostCommon`（默认）、`Median`、`Average`、`KMeans`、`Contrast` 等。 |
+| `targetSize`、`targetWidth`、`targetHeight`、`blockSize` | `Convert` 模式的输出尺寸。 |
+| `paletteSnap` | 限制颜色：`{ adaptive: true }`、`{ colors: 16 }` 或 `{ palette: [...] }`，可选 `dither`。 |
+| `prepass` | 来自 PixelOE 的轮廓预处理（`Pixeloe`、`PixeloeLines`）。 |
+| `removeNoise` | 对相近的相邻颜色做轻度平滑。 |
+| `preserveDimensions` | 用最近邻把结果放大回原图尺寸。 |
+
+所有选项见 [`src/types.ts`](src/types.ts)。
+
+### Worker
+
+`detectWithAlgorithm` 和 `pixelateImage` 是同步函数，大图可能要几秒，请在 Web Worker 中运行。在浏览器中，Auto 还可以把格数检测器放进嵌套 Worker，和其他检测器并行：
+
+```ts
+import { setAcRlBrowserWorkerFactory, detectWithAlgorithmAsync } from "@xprite/pixelate";
+
+setAcRlBrowserWorkerFactory(
+  () =>
+    new Worker(
+      new URL("@xprite/pixelate/wasm/ac-rl-detect-browser-worker.js", import.meta.url),
+      { type: "module" },
+    ),
+);
+const grid = await detectWithAlgorithmAsync(image);
+```
+
+在 Node 中，检测器会自己从 `wasm/ac-rl-detect-worker.mjs` 启动一个 `worker_threads` Worker。设置 `XPRITE_AC_RL_WORKER=0` 可以让它留在调用线程。
+
+## 原理
+
+1. **扶正。** Auto 先估计倾斜角。倾斜明确时，在扶正后的副本上检测。
+2. **提议。** 七个检测器提议网格：均匀网格、边缘网格、边框晶格、格距晶格、颜色周期、边界游程和边缘间距。pixel-art-fixer 的自相关与游程投票移植成 WebAssembly，给出一个独立的格数。
+3. **沿边缘切。** 在检测器保留的每个格宽上，动态规划沿每条轴走一遍，把每一刀切在颜色边缘上。每格宽度保持在格宽的 0.75 到 1.25 倍之间，宽度变化另有代价。这一步处理宽度不均的格子。
+4. **过滤。** 候选网格的切线若没有落在更粗网格所跟随的颜色边缘上，就被剔除。
+5. **选择。** 描述图像所需比特数最少的网格胜出（最小描述长度）。没有锁定到内容相位的网格要付出额外代价。漂移和错位的行读作条带位移或相位场。
+6. **取色。** 每格取一个颜色（`TwoStage` 分两步归并格内颜色），自适应调色板再合并近似色。
+7. **整理透明度。** 被画覆盖的格子变为完全不透明，画外的格子变为透明。
+
+`src/` 中每个源文件都说明了自己负责的步骤，见 [`src/`](src)。
+
+## 基准测试
+
+[`bench/`](bench) 在 CC0 原生像素画上比较本包和另外三个工具。基准测试以已知方式损伤原画，再把每个结果和原画对比打分。每个工具都使用默认设置。
+
+AI 套件（12 个类别共 1746 个用例，按生成模型伪造像素画的方式渲染）：
+
+| 方法 | 尺寸完全正确 | 差 1 格以内 | 像素一致率 | ΔE | 半透明毛边 | 中位耗时 |
+| --- | --- | --- | --- | --- | --- | --- |
+| Xprite Auto | **83.6%** | **90.0%** | **99.8%** | 0.82 | 0.1% | 1.55 s |
+| pixel-art-fixer | 49.7% | 80.9% | 98.3% | 1.74 | 0.0% | 0.18 s |
+| perfectPixel | 53.3% | 68.0% | 96.7% | 2.42 | - | 0.03 s |
+| proper-pixel-art | 72.2% | 80.4% | 99.7% | **0.64** | 0.0% | 0.49 s |
+
+各类别的尺寸完全正确率：
+
+| 类别 | Xprite | pixel-art-fixer | perfectPixel | proper-pixel-art |
+| --- | --- | --- | --- | --- |
+| 干净 (`gen_clean`) | **93.6%** | 71.7% | 58.4% | 74.6% |
+| 稀疏画布 (`gen_sparse`) | **99.0%** | 63.5% | 71.9% | 88.5% |
+| 近白色背景 (`gen_white`) | 77.7% | 65.2% | 66.1% | **82.1%** |
+| 柔和轮廓 (`gen_soft_edge`) | **95.8%** | 61.9% | 67.8% | 82.2% |
+| 漂移和 WebP (`gen_webp`) | **80.9%** | 40.5% | 57.8% | 71.1% |
+| 光晕和 JPEG (`gen_halo_jpeg`) | **82.7%** | 52.6% | 60.1% | 72.8% |
+| 绘画式明暗 (`gen_painterly`) | **84.5%** | 39.1% | 67.8% | 79.3% |
+| 小格子（4-8 px） (`gen_small_pitch`) | **72.2%** | 47.9% | 40.2% | 43.8% |
+| 大格子（24-48 px） (`gen_large_pitch`) | 68.2% | 22.0% | 68.2% | **78.0%** |
+| 强漂移 (`gen_wobble`) | **73.3%** | 30.8% | 30.8% | 54.1% |
+| 两个角色 (`gen_pair`) | **97.1%** | 62.7% | 45.1% | 72.5% |
+| 投影 (`gen_shadow`) | **97.3%** | 64.0% | 0.0% | 84.7% |
+
+[pixel-bench](https://github.com/Retro-Diffusion/pixel-bench) v1 套件（7651 个放大和有损处理用例）：
+
+| 方法 | 尺寸完全正确 | 差 1 格以内 | 像素一致率 | ΔE | 中位耗时 |
+| --- | --- | --- | --- | --- | --- |
+| Xprite Auto | **87.1%** | **90.1%** | 94.3% | **2.79** | 0.24 s |
+| pixel-art-fixer | 77.8% | 83.5% | **94.4%** | 2.83 | 0.04 s |
+| perfectPixel | 24.2% | 32.9% | 89.7% | 4.31 | 0.002 s |
+| proper-pixel-art | 16.5% | 28.6% | 93.0% | 3.85 | 0.05 s |
+
+像素一致率和 ΔE 只在尺寸完全正确的用例上统计。四个工具中 Xprite 最慢。损伤是合成的，所以得分反映各工具在这些特征上的排名，不代表在真实图片上的成功率。方法、类别和运行步骤见 [bench/README.md](bench/README.md)。
+
+## 许可证
+
+MIT。部分代码改编自 pixel-art-fixer、PixelOE、proper-pixel-art 和 tensorhead/dithering（见 [NOTICE.md](NOTICE.md)）。示例图均为 CC0（见 [bench/corpus/CREDITS.md](bench/corpus/CREDITS.md)）。

package/dist/analyze.d.ts

@@ -0,0 +1,8 @@
+import type { PixelBuffer } from "./base.ts";
+import type { PixelArtAnalysis, PixelArtAnalysisOptions } from "./types.ts";
+export declare function analyzePixelArt(image: PixelBuffer, options?: PixelArtAnalysisOptions): PixelArtAnalysis;
+/**
+ * Async analyze for product import-worker. Same metrics/classification as analyzePixelArt;
+ * Auto grid uses detectWithAlgorithmAsync (WASM||proposers Promise overlap).
+ */
+export declare function analyzePixelArtAsync(image: PixelBuffer, options?: PixelArtAnalysisOptions): Promise<PixelArtAnalysis>;