pixel-math-wasm

37 个图像处理与数学算法，编译为 Rust + WebAssembly。 JS 侧零依赖（自带一个 .wasm），gzip 后约 80 KB。

安装

npm install pixel-math-wasm

快速上手

import init, { invert } from 'pixel-math-wasm'

await init()                       // 加载 .wasm（只需一次）

const canvas = document.querySelector('canvas')
const { data, width, height } = canvas.getContext('2d').getImageData(0, 0, w, h)

const out = invert(data, width, height)   // RGBA 进，RGBA 出
ctx.putImageData(new ImageData(new Uint8ClampedArray(out), width, height), 0, 0)

就这么简单。所有函数接收 Uint8Array 的 RGBA 像素（部分 ML 例程是 Float64Array）+ width / height，返回一个新的 RGBA 缓冲。

功能（37 个算法）

单像素滤镜

invert · grayscale_with · brightness_contrast · threshold · color_filter · color_matrix · color_calibrate

卷积与邻域

mean_blur · median_blur · denoise_row_mean · mosaic · vignette · emboss · sobel · rgb_shift

几何变换

flip · rotate90 · rotate · scale_shear · fisheye

分形

mandelbrot · mandelbrot_f32 · julia · julia_f32

线性变换

pca_compress · pca_first_component · pca_variance_ratios · covariance_handwritten · covariance_library · covariance_max_diff · regression · ycbcr_channel · ycbcr_luma_only · ycbcr_chroma_only · chroma_subsample · chroma_key · ycbcr_adjust_luma

概率图像

add_noise · salt_pepper_noise · random_walk · markov_synthesize · inpaint · adaptive_threshold · histogram_equalize

频率域

fft2d · frequency_filter · filter_spectrum · jpeg_compress · jpeg_quant_table_image · jpeg_stats

机器学习

kmeans → KmeansResult  ·  image_histogram · knn_search · histogram_similarity  ·  ocr_train → OcrModel  ·  ocr_recognize → OcrResult  ·  ocr_components_image  ·  mlp_train → MlpModel  ·  mlp_predict → MlpPrediction  ·  mlp_weights_image

物理与特效

new ParticleWorld(w, h) · step(dt) · render(fade)  ·  new SphWorld(w, h) · step(dt) · render(fade, r)  ·  new VfxScene(w, h) · set_preset('fire' \| 'smoke' \| 'explosion') · step(dt) · render(fade)

API 约定

• 所有图像函数接收 Uint8Array 的 RGBA 像素（长度 = width * height * 4）。
• 浮点例程（mlp_*、ocr_*、image_histogram）使用 Float64Array。
• 返回的数组是新分配的缓冲——原数组永远不会被修改。
• 物理世界是有状态的类；每帧调用 step(dt) 然后 render(fade)。

示例

K-Means 颜色量化（卡通化一张照片）：

import init, { kmeans } from 'pixel-math-wasm'
await init()

const { pixels, centers } = kmeans(rgba, w, h, 5 /* K */, 20, 12345)
// `pixels` 是卡通化后的 RGBA；`centers` 是 K 个 RGB 三元组

K-NN 以图搜图（按颜色直方图找相似）：

import init, { image_histogram, knn_search } from 'pixel-math-wasm'
await init()

const query = image_histogram(rgbaA, w, h)
// libraryHistograms 是扁平 Float64Array：[hist0..., hist1..., hist2...]
const result = knn_search(query, libraryHistograms, libCount, 5 /* top-K */)
// result = [idx0, dist0, idx1, dist1, ...]

实时粒子物理：

import init, { ParticleWorld } from 'pixel-math-wasm'
await init()

const world = new ParticleWorld(600, 400)
world.add_random_particles(100, 42)
world.set_gravity(400)
world.set_particle_collisions(true)

function loop() {
  world.step(1/60)
  const rgba = world.render(8)        // 8 = 每帧轨迹衰减
  ctx.putImageData(new ImageData(new Uint8ClampedArray(rgba), 600, 400), 0, 0)
  requestAnimationFrame(loop)
}
loop()

背景

本包是 pixel-math-wasm 主项目的 WASM 核心 —— 一个 37 篇的实战教程系列，从零开始用 Rust 搭建完整的"图像处理 + 机器学习 + 物理模拟"工具集。

每个算法都是手写实现（Cooley-Tukey FFT、Müller SPH、反向传播、K-Means++…）。除了 nalgebra 之外没有外部数学库（wasm-pack 在编译时会把它从最终 .wasm 中剔除）。

Vue.js 演示站放在同一仓库里，用到了这里的每一个函数。

License

MIT

English

37 image-processing and math algorithms compiled to Rust + WebAssembly. Zero JS-side dependencies (one bundled .wasm). ~100 KB gzipped.

Install

npm install pixel-math-wasm

Quick start

import init, { invert } from 'pixel-math-wasm'

await init()                       // load the .wasm (one-time)

const canvas = document.querySelector('canvas')
const { data, width, height } = canvas.getContext('2d').getImageData(0, 0, w, h)

const out = invert(data, width, height)   // RGBA in, RGBA out
ctx.putImageData(new ImageData(new Uint8ClampedArray(out), width, height), 0, 0)

That's it. Every function takes Uint8Array of RGBA pixels (or Float64Array for some ML routines) plus width / height, and returns a new RGBA buffer.

Features (37 algorithms)

Single-pixel filters

invert · grayscale_with · brightness_contrast · threshold · color_filter · color_matrix · color_calibrate

Convolution & neighborhood

mean_blur · median_blur · denoise_row_mean · mosaic · vignette · emboss · sobel · rgb_shift

Geometry

flip · rotate90 · rotate · scale_shear · fisheye

Fractals

mandelbrot · mandelbrot_f32 · julia · julia_f32

Linear algebra

pca_compress · pca_first_component · pca_variance_ratios · covariance_handwritten · covariance_library · covariance_max_diff · regression · ycbcr_channel · ycbcr_luma_only · ycbcr_chroma_only · chroma_subsample · chroma_key · ycbcr_adjust_luma

Probability

add_noise · salt_pepper_noise · random_walk · markov_synthesize · inpaint · adaptive_threshold · histogram_equalize

Frequency domain

fft2d · frequency_filter · filter_spectrum · jpeg_compress · jpeg_quant_table_image · jpeg_stats

Machine learning

kmeans → KmeansResult  ·  image_histogram · knn_search · histogram_similarity  ·  ocr_train → OcrModel  ·  ocr_recognize → OcrResult  ·  ocr_components_image  ·  mlp_train → MlpModel  ·  mlp_predict → MlpPrediction  ·  mlp_weights_image

Physics & VFX

new ParticleWorld(w, h) · step(dt) · render(fade)  ·  new SphWorld(w, h) · step(dt) · render(fade, r)  ·  new VfxScene(w, h) · set_preset('fire' \| 'smoke' \| 'explosion') · step(dt) · render(fade)

API conventions

• All image functions take Uint8Array of RGBA pixels (length = width * height * 4).
• Float routines (mlp_*, ocr_*, image_histogram) use Float64Array.
• Returned arrays are fresh buffers — originals are never mutated.
• Physics worlds are stateful classes; call step(dt) then render(fade) each frame.

Examples

K-Means color quantization (cartoonize a photo):

import init, { kmeans } from 'pixel-math-wasm'
await init()

const { pixels, centers } = kmeans(rgba, w, h, 5 /* K */, 20, 12345)
// `pixels` is the cartoonized RGBA; `centers` is the K RGB triples

K-NN image search (find similar images by color histogram):

import init, { image_histogram, knn_search } from 'pixel-math-wasm'
await init()

const query = image_histogram(rgbaA, w, h)
// libraryHistograms is a flat Float64Array: [hist0..., hist1..., hist2...]
const result = knn_search(query, libraryHistograms, libCount, 5 /* top-K */)
// result = [idx0, dist0, idx1, dist1, ...]

Real-time particle physics:

import init, { ParticleWorld } from 'pixel-math-wasm'
await init()

const world = new ParticleWorld(600, 400)
world.add_random_particles(100, 42)
world.set_gravity(400)
world.set_particle_collisions(true)

function loop() {
  world.step(1/60)
  const rgba = world.render(8)        // 8 = trail fade per frame
  ctx.putImageData(new ImageData(new Uint8ClampedArray(rgba), 600, 400), 0, 0)
  requestAnimationFrame(loop)
}
loop()

Background

This package is the compiled WASM core of pixel-math-wasm, a 37-article tutorial series that builds an entire image-processing + ML + physics toolkit from scratch in Rust.

Each algorithm is implemented by hand (Cooley-Tukey FFT, Müller SPH, backprop, K-Means++…). No external math libraries besides nalgebra (which wasm-pack strips from the final .wasm).

The Vue.js demo site lives in the same repo and uses every one of these functions.

License

MIT