How handsupmin/fast-pixelizer works
1. Repository purpose
- fast-pixelizer is a small TypeScript image-processing library, published as a zero-dependency package for both browser and Node.js.
- The architecture is centered on two exported operations: pixelate() for creating pixel art, and snap() for repairing noisy or misaligned pixel-art grids.
2. Public API boundary
- src/index.ts is the package entrypoint and likely re-exports the public surface.
- Consumers import from the package root only; the internal algorithm files are not meant to be used directly.
3. Core processing subsystems
- src/algorithms.ts contains the shared low-level image math: grid sampling, resampling, color aggregation, and likely the performance-oriented bucket/count logic described in the README.
- src/snap.ts contains the higher-level grid-recovery pipeline for existing pixel art, including color quantization, boundary detection, and resolution inference.
4. Data model boundary
- The library operates on plain image buffers rather than DOM objects or file formats.
- Input is a generic { data: Uint8ClampedArray, width, height } shape compatible with browser ImageData, node-canvas, and raw buffers.
- Output is the same raw RGBA buffer shape plus derived metadata for snap().
5. pixelate() flow
- The pixelate path is a deterministic transform from arbitrary source image data to a coarser pixel-grid representation.
- It supports two modes, clean and detail, which imply different cell-aggregation strategies: dominant color versus average color.
- It also supports two output modes: preserving original dimensions or emitting a resized resolution × resolution grid.
6. snap() flow
- The snap path is an analysis-plus-reconstruction pipeline, not just a resize.
- It first simplifies colors, then detects likely row/column cuts, infers grid periodicity, and reconstructs a uniform lattice.
- Its result includes diagnostic metadata (detectedResolution, colCuts, rowCuts) used for overlays and verification.
7. Performance architecture
- The implementation is intentionally allocation-light and optimized for CPU-bound image loops.
- The README calls out preallocated typed-array buckets and row-major iteration, which indicates the main performance boundary is in tight in-memory processing rather than I/O or async orchestration.
8. Runtime and platform support
- The package is designed to run identically in browser and Node.js environments.
- Browser usage is synchronous and canvas-based; Node.js usage is typically paired with sharp to read/write PNGs and convert to/from raw RGBA buffers.
- There are no runtime dependencies in the library itself.
9. Build and packaging
- tsup.config.ts suggests the package is bundled from TypeScript into distributable JavaScript artifacts.
- tsconfig.json, eslint.config.js, and .prettierrc indicate a conventional TypeScript library toolchain rather than an app framework.
10. Validation and regression protection
- tests/snap.test.mjs focuses specifically on snap() behavior, which is consistent with the README’s emphasis on regression fixes for grid drift.
- scripts/evaluate-snap-regressions.mjs appears to benchmark or compare snap behavior across known problematic samples.
- docs/2026-03-29-snap-autoresearch-report.md suggests the snap algorithm has been iteratively researched and documented, likely to justify detection heuristics and stability fixes.
11. Examples and reproducibility
- The examples/ and docs/ assets are part of the repo’s verification story: they provide before/after outputs and sample images to demonstrate the algorithms.
- scripts/generate-examples.mjs likely regenerates these example artifacts from the current implementation, making visual regressions easy to spot.
12. Main architectural boundary to diagram
- The key diagram should show a thin public API layer (index.ts) feeding into two internal pipelines:
- direct pixel-grid generation via algorithms.ts
- adaptive grid recovery via snap.ts
- Both pipelines consume the same raw image buffer contract and emit raw RGBA outputs, with snap() additionally emitting grid metadata for overlays and diagnostics.
Main entry points: snap.ts Snap Pipeline · index.ts Entrypoint · algorithms.ts Algorithms · generate-examples.mjs Examples
Components 19
Public API
Package entrypoint and exported surface
- Entrypoint · Package root that re-exports the public API
src/index.ts - Pixelate · Deterministic transform that turns source images into a coarser pixel grid
- Snap · Analysis-plus-reconstruction API for repairing noisy or misaligned pixel art
- RGBA Buffer · Shared raw image shape: { data, width, height } compatible with browser and Node runtimes
Core Processing
Shared pixel math and grid-recovery pipelines
- Algorithms · Shared low-level sampling, resampling, and aggregation logic
src/algorithms.ts - Sampling · Row-major grid sampling over source pixels and cells
- Resampling · Reconstructs a coarser or resized output grid from source data
- Buckets · Preallocated typed-array bucket/count logic for dominant-color and average-color aggregation
- Snap Pipeline · Higher-level grid recovery flow for existing pixel art
src/snap.ts - Simplify · Reduces color noise before boundary and lattice detection
- Cut Detect · Finds likely row and column boundaries in pixel-art grids
- Infer Grid · Estimates the underlying periodic resolution from detected cuts
- Rebuild Grid · Reconstructs a uniform lattice from the inferred cuts and resolution
- Diagnostics · Detected resolution and cut arrays used for overlays and verification
Verification
Tests, regression evaluation, and visual examples
- Snap Test · Focused regression coverage for snap behavior
tests/snap.test.mjs - Regressions · Compares snap behavior across known problematic samples
scripts/evaluate-snap-regressions.mjs - Examples · Regenerates before/after example artifacts from the current implementation
scripts/generate-examples.mjs - Research Report · Documents the snap heuristic research and stability work
docs/2026-03-29-snap-autoresearch-report.md
Tooling
Build and repository automation
- Build Setup · TypeScript bundling and library packaging configuration
tsup.config.ts
Connections 20
- Entrypoint → Pixelate: exports · Public package entrypoint exposes pixelate()
- Entrypoint → Snap: exports · Public package entrypoint exposes snap()
- Entrypoint → RGBA Buffer: defines · Entrypoint publishes the shared raw image buffer contract
- Pixelate → Algorithms: uses · Pixelate delegates to shared image math
- Pixelate → Sampling: samples · Computes source cells from the input image
- Pixelate → Resampling: writes · Produces the coarser output grid or resized image
- Pixelate → Buckets: aggregates · Uses bucketed dominant-color or average-color accumulation
- Snap → Snap Pipeline: delegates · Snap API enters the adaptive recovery pipeline
- Snap Pipeline → Simplify: prep · Simplifies colors before structural analysis
- Snap Pipeline → Cut Detect: detects · Finds likely row and column cuts
- Snap Pipeline → Infer Grid: infers · Estimates the underlying grid periodicity
- Snap Pipeline → Rebuild Grid: reconstructs · Rebuilds a uniform lattice from the inferred grid
- Snap Pipeline → Diagnostics: returns · Emits detectedResolution, colCuts, and rowCuts metadata
- Snap Pipeline → Algorithms: shares math · Reuses low-level pixel processing utilities where appropriate
- Snap Test → Snap Pipeline: validates · Regression coverage targets the snap pipeline
- Regressions → Snap Pipeline: measures · Compares pipeline behavior on known difficult samples
- Examples → Algorithms: renders · Uses current algorithms to regenerate example outputs
- Examples → Snap Pipeline: renders · Uses current snap behavior to regenerate before/after examples
- Research Report → Snap Pipeline: documents · Explains the heuristic and stability rationale behind snap
- Build Setup → Entrypoint: bundles · Build configuration packages the TypeScript library entrypoint