@xprite/pixelate 0.0.0-stage → 0.1.0

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,239 @@
-# 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)
+
+| AI-generated, 887×887 | Recovered grid | Real pixel art, 48×49 |
+| :---: | :---: | :---: |
+| ![Input](docs/images/griffith-input.png) | ![Grid](docs/images/griffith-mesh.png) | ![Result](docs/images/griffith-result.png) |
+
+## Summary
+
+Image generators draw "pixel art" with soft edges, noise, half-transparent outlines and cells of
+uneven width. This package finds the real pixel grid in such an image and gives back one clean
+pixel per cell. It also turns ordinary images into pixel art.
+
+It runs in browsers and Node and has no runtime dependencies. One WebAssembly module ships inside
+the package. It is the importer of the [Xprite](https://xprite.cc) pixel editor.
+
+## Contents
+
+- [Examples](#examples)
+- [Compared with other tools](#compared-with-other-tools)
+- [Install](#install)
+- [Usage](#usage)
+- [How it works](#how-it-works)
+- [Benchmark](#benchmark)
+- [License](#license)
+
+## Examples
+
+These inputs come from the benchmark's AI suite: CC0 pixel art rendered the way generators fake
+it. Each result has exactly the size of the original art.
+
+### Two sprites on one canvas
+
+- Goblins by LuizMelo ([Monsters Creatures Fantasy](https://luizmelo.itch.io/monsters-creatures-fantasy), CC0)
+
+| Input, 1800×845 | Recovered grid | Result, 103×49 |
+| :---: | :---: | :---: |
+| ![Input](docs/images/goblins-input.png) | ![Grid](docs/images/goblins-mesh.png) | ![Result](docs/images/goblins-result.png) |
+
+### Painterly shading inside cells
+
+- Naga mage from [Dungeon Crawl Stone Soup tiles](https://github.com/crawl/tiles) (CC0)
+
+| Input, 411×425 | Recovered grid | Result, 50×50 |
+| :---: | :---: | :---: |
+| ![Input](docs/images/naga-input.png) | ![Grid](docs/images/naga-mesh.png) | ![Result](docs/images/naga-result.png) |
+
+### Cells that drift and jitter
+
+- Monster by Denzi ([Denzi's public domain art](https://opengameart.org/content/denzis-public-domain-art), CC0)
+
+| Input, 606×924 | Recovered grid | Result, 45×67 |
+| :---: | :---: | :---: |
+| ![Input](docs/images/wobble-input.png) | ![Grid](docs/images/wobble-mesh.png) | ![Result](docs/images/wobble-result.png) |
+
+### Small cells and WebP damage
+
+- Old man by ansimuz ([Gothicvania Town](https://opengameart.org/content/gothicvania-town), CC0)
+
+| Input, 250×380 | Recovered grid | Result, 39×57 |
+| :---: | :---: | :---: |
+| ![Input](docs/images/oldman-input.png) | ![Grid](docs/images/oldman-mesh.png) | ![Result](docs/images/oldman-result.png) |
+
+## Compared with other tools
+
+The image at the top, recovered by each tool with its default settings:
+
+| Xprite Auto, 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 |
+| :---: | :---: | :---: | :---: |
+| ![Xprite](docs/images/griffith-result.png) | ![pixel-art-fixer](docs/images/griffith-fixer.png) | ![perfectPixel](docs/images/griffith-perfectpixel.png) | ![proper-pixel-art](docs/images/griffith-proper.png) |
+
+The cells of this image are 15 to 21 px wide, so a grid of even cells cuts through drawn pixels
+somewhere. Xprite puts each cut on a colour edge. The [Benchmark](#benchmark) section has scores
+on 1746 cases.
+
+## 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 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 |
+
+[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,209 @@
+# @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 生成，887×887 | 找到的网格 | 真正的像素画，48×49 |
+| :---: | :---: | :---: |
+| ![输入](docs/images/griffith-input.png) | ![网格](docs/images/griffith-mesh.png) | ![结果](docs/images/griffith-result.png) |
+
+## 简介
+
+图像生成模型画出的“像素画”边缘发虚，有噪点，轮廓半透明，每一格的宽度也不一样。这个包找出图里真正的像素网格，每一格还原成一个干净的像素。它也能把普通图片转成像素画。
+
+它可以在浏览器和 Node 中运行，没有运行时依赖，包内自带一个 WebAssembly 模块。它是像素编辑器 [Xprite](https://xprite.cc) 的导入器。
+
+## 目录
+
+- [示例](#示例)
+- [与其他工具对比](#与其他工具对比)
+- [安装](#安装)
+- [用法](#用法)
+- [原理](#原理)
+- [基准测试](#基准测试)
+- [许可证](#许可证)
+
+## 示例
+
+下面的输入来自基准测试的 AI 套件：把 CC0 像素画按生成模型的方式渲染成假像素画。每个结果的尺寸都和原画完全一致。
+
+### 一张画布上的两个角色
+
+- 哥布林，作者 LuizMelo（[Monsters Creatures Fantasy](https://luizmelo.itch.io/monsters-creatures-fantasy)，CC0）
+
+| 输入，1800×845 | 找到的网格 | 结果，103×49 |
+| :---: | :---: | :---: |
+| ![输入](docs/images/goblins-input.png) | ![网格](docs/images/goblins-mesh.png) | ![结果](docs/images/goblins-result.png) |
+
+### 格内有绘画式明暗
+
+- 娜迦法师，来自 [Dungeon Crawl Stone Soup tiles](https://github.com/crawl/tiles)（CC0）
+
+| 输入，411×425 | 找到的网格 | 结果，50×50 |
+| :---: | :---: | :---: |
+| ![输入](docs/images/naga-input.png) | ![网格](docs/images/naga-mesh.png) | ![结果](docs/images/naga-result.png) |
+
+### 格子漂移和抖动
+
+- 怪物，作者 Denzi（[Denzi's public domain art](https://opengameart.org/content/denzis-public-domain-art)，CC0）
+
+| 输入，606×924 | 找到的网格 | 结果，45×67 |
+| :---: | :---: | :---: |
+| ![输入](docs/images/wobble-input.png) | ![网格](docs/images/wobble-mesh.png) | ![结果](docs/images/wobble-result.png) |
+
+### 小格子和 WebP 压缩损伤
+
+- 老人，作者 ansimuz（[Gothicvania Town](https://opengameart.org/content/gothicvania-town)，CC0）
+
+| 输入，250×380 | 找到的网格 | 结果，39×57 |
+| :---: | :---: | :---: |
+| ![输入](docs/images/oldman-input.png) | ![网格](docs/images/oldman-mesh.png) | ![结果](docs/images/oldman-result.png) |
+
+## 与其他工具对比
+
+顶部那张图，各工具用默认设置还原的结果：
+
+| Xprite Auto，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 |
+| :---: | :---: | :---: | :---: |
+| ![Xprite](docs/images/griffith-result.png) | ![pixel-art-fixer](docs/images/griffith-fixer.png) | ![perfectPixel](docs/images/griffith-perfectpixel.png) | ![proper-pixel-art](docs/images/griffith-proper.png) |
+
+这张图的格宽在 15 到 21 像素之间，所以等宽网格总会在某处切进画好的像素。Xprite 把每一刀都切在颜色边缘上。1746 个用例的得分见[基准测试](#基准测试)。
+
+## 安装
+
+```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 套件（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 |
+
+[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>;