pixel-art-scaler

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pixel Art Scaler

像素画放大器

Deterministic algorithms for upscaling pixel art that preserve aesthetics by adding valid sub-pixels through edge detection and pattern matching.

用于像素画放大的确定性算法，通过边缘检测和模式匹配添加有效的子像素，从而保留像素画的美学风格。

When to Use

适用场景

✅ Use for:

Upscaling retro game sprites, icons, and pixel art
2x, 3x, 4x scaling with edge-aware interpolation
Preserving sharp pixel art aesthetic at higher resolutions
Converting 8x8, 16x16, 32x32, 48x48 pixel art for retina displays
Comparing deterministic vs AI/ML approaches

❌ NOT for:

Photographs or realistic images (use AI super-resolution)
Simple geometric scaling (use nearest-neighbor)
Vector art (use SVG)
Text rendering (use font hinting)
Arbitrary non-integer scaling (algorithms work best at 2x, 3x, 4x)

✅ 适用场景：

放大复古游戏精灵、图标和像素画
2倍、3倍、4倍边缘感知插值放大
在高分辨率下保留清晰的像素画美学风格
将8x8、16x16、32x32、48x48的像素画转换为适配视网膜显示屏的版本
对比确定性算法与AI/ML放大方案

❌ 不适用场景：

照片或写实图像（建议使用AI超分辨率）
简单几何放大（建议使用最近邻算法）
矢量图（建议使用SVG）
文本渲染（建议使用字体微调）
任意非整数倍放大（算法在2x、3x、4倍放大时效果最佳）

Core Algorithms

核心算法

1. EPX/Scale2x (Fastest, Good Quality)

1. EPX/Scale2x（速度最快，质量良好）

Best for: Quick iteration, 2x/3x scaling, transparent sprites

How it works:

Examines each pixel and its 4 cardinal neighbors (N, S, E, W)
Expands 1 pixel → 4 pixels (2x) or 9 pixels (3x) using edge detection
Only uses colors from original palette (no new colors)
Handles transparency correctly

When to use:

Need fast processing (100+ icons)
Want crisp edges with no anti-aliasing
Source has clean pixel boundaries
Transparency preservation is critical

Timeline: Invented by Eric Johnston at LucasArts (~1992), rediscovered by Andrea Mazzoleni (2001)

最佳适用场景：快速迭代、2倍/3倍放大、带透明通道的精灵图

工作原理：

检查每个像素及其4个相邻像素（上、下、左、右）
通过边缘检测将1个像素扩展为4个像素（2x）或9个像素（3x）
仅使用原始调色板中的颜色（不生成新颜色）
正确处理透明通道

何时使用：

需要快速处理（100+个图标）
希望获得无抗锯齿的清晰边缘
源素材具有干净的像素边界
透明通道的保留至关重要

发展历程：由LucasArts的Eric Johnston发明（约1992年），2001年由Andrea Mazzoleni重新发掘

2. hq2x/hq3x/hq4x (High Quality, Slower)

2. hq2x/hq3x/hq4x（质量高，速度较慢）

Best for: Final renders, complex sprites, smooth gradients

How it works:

Pattern matching on 3x3 neighborhoods (256 possible patterns)
YUV color space thresholds for edge detection
Sophisticated interpolation rules per pattern
Produces smooth, anti-aliased edges

When to use:

Final production assets
Source has gradients or dithering
Want smooth, anti-aliased results
Processing time is acceptable (~5-10x slower than EPX)

Timeline: Developed by Maxim Stepin for emulators (2003)

最佳适用场景：最终渲染、复杂精灵图、平滑渐变

工作原理：

对3x3像素邻域进行模式匹配（共256种可能模式）
使用YUV色彩空间阈值进行边缘检测
针对每种模式采用复杂的插值规则
生成平滑的抗锯齿边缘

何时使用：

最终生产资源
源素材包含渐变或抖动效果
希望获得平滑的抗锯齿结果
可接受处理时间（速度约为EPX的1/5-1/10）

发展历程：由Maxim Stepin为模拟器开发（2003年）

3. xBR/Super-xBR (Highest Quality, Slowest)

3. xBR/Super-xBR（质量最高，速度最慢）

Best for: Hero assets, promotional materials, detailed sprites

How it works:

Advanced edge detection with weighted blending
Multiple passes for smoother results (Super-xBR)
Preserves fine details while smoothing edges
Best anti-aliasing of the three algorithms

When to use:

Maximum quality needed
Complex sprites with fine details
Marketing/promotional use
Time is not a constraint (~20x slower than EPX)

Timeline: xBR by Hyllian (2011), Super-xBR (2015)

最佳适用场景：核心视觉资产、宣传素材、细节丰富的精灵图

工作原理：

带加权混合的高级边缘检测
多遍处理以获得更平滑的结果（Super-xBR）
在平滑边缘的同时保留精细细节
三种算法中抗锯齿效果最佳

何时使用：

需要最高质量
细节丰富的复杂精灵图
营销/宣传素材制作
不限制处理时间（速度约为EPX的1/20）

发展历程：xBR由Hyllian开发（2011年），Super-xBR于2015年推出

Anti-Patterns

常见误区

Anti-Pattern: Nearest-Neighbor for Display

误区：使用最近邻算法进行显示放大

Novice thinking: "Just use nearest-neighbor 4x, it preserves pixels"

Reality: Nearest-neighbor creates blocky repetition without adding detail. Each pixel becomes NxN identical blocks, which looks crude on high-DPI displays.

What deterministic algorithms do: Add valid sub-pixels through pattern recognition - a diagonal edge gets anti-aliased pixels, straight edges stay crisp.

Timeline:

Pre-2000s: Nearest-neighbor was only option
2001+: EPX/Scale2x enabled smart 2x scaling
2003+: hq2x added sophisticated pattern matching
2011+: xBR became state-of-the-art

When nearest-neighbor IS correct: Viewing pixel art at exact integer multiples in pixel-perfect contexts (e.g., 1:1 reference images).

新手误区：「直接用4倍最近邻放大就行，它能保留像素」

实际情况：最近邻算法只会生成块状重复的像素，不会添加任何细节。每个像素会变成N×N的相同块，在高DPI显示屏上看起来很粗糙。

确定性算法的优势：通过模式识别添加有效的子像素——对角线边缘会生成抗锯齿像素，直线边缘则保持清晰。

发展历程：

2000年前：仅能使用最近邻算法
2001年起：EPX/Scale2x实现了智能2倍放大
2003年起：hq2x引入了复杂的模式匹配
2011年起：xBR成为行业标杆

最近邻算法的正确用法：在像素完美的场景中以精确整数倍查看像素画（例如1:1参考图）。

Anti-Pattern: Using AI/ML for Pixel Art

误区：使用AI/ML放大像素画

Novice thinking: "Real-ESRGAN / Waifu2x will give better results"

Reality: AI models trained on photos/anime add inappropriate detail to pixel art. They invent textures and smooth edges that shouldn't exist, destroying the intentional pixel-level decisions.

LLM mistake: Training data includes "upscaling = use AI models" advice from photo editing contexts.

Correct approach:

Source Type	Algorithm
Pixel art (sprites, icons)	EPX/hq2x/xBR (this skill)
Pixel art photos (screenshots)	Hybrid: xBR first, then light AI
Photos/realistic art	AI super-resolution
Mixed content	Test both, compare results

新手误区：「Real-ESRGAN / Waifu2x会给出更好的结果」

实际情况：基于照片/动漫训练的AI模型会给像素画添加不合适的细节。它们会凭空生成纹理并平滑原本不应被平滑的边缘，破坏像素画在像素层面的设计意图。

大语言模型常见错误：训练数据中包含「放大=使用AI模型」的建议，但这些建议来自照片编辑场景，并不适用于像素画。

正确做法：

素材类型	推荐算法
像素画（精灵、图标）	EPX/hq2x/xBR（本工具）
像素画截图	混合方案：先使用xBR，再轻度AI处理
照片/写实艺术	AI超分辨率
混合内容	测试两种方案，对比结果

Anti-Pattern: Wrong Algorithm for Context

误区：不分场景使用错误算法

Novice thinking: "Always use the highest quality algorithm"

Reality: Different algorithms serve different purposes:

Context	Algorithm	Why
Iteration/prototyping	EPX	10x faster, good enough
Production assets (web)	hq2x	Balance of quality/size
Hero images (marketing)	xBR	Maximum quality
Transparent sprites	EPX	Best transparency handling
Complex gradients	hq4x	Best gradient interpolation

Validation: Always compare outputs visually - sometimes EPX 2x looks better than hq4x!

新手误区：「总是使用质量最高的算法」

实际情况：不同算法适用于不同场景：

场景	推荐算法	原因
迭代/原型开发	EPX	速度快10倍，质量足够
网页生产资源	hq2x	平衡质量与文件大小
营销核心图片	xBR	最高质量
带透明通道的精灵图	EPX	透明通道处理效果最佳
复杂渐变	hq4x	渐变插值效果最佳

验证建议：始终通过视觉对比输出结果——有时候EPX 2倍放大的效果比hq4x更好！

Usage

使用方法

Quick Start

快速开始

bash

undefined

bash

undefined

Install dependencies

cd ~/.claude/skills/pixel-art-scaler/scripts pip install Pillow numpy

Scale a single icon with EPX 2x (fastest)

python3 scale_epx.py input.png output.png --scale 2

Scale with hq2x (high quality)

python3 scale_hqx.py input.png output.png --scale 2

Scale with xBR (maximum quality)

python3 scale_xbr.py input.png output.png --scale 2

Batch process directory

python3 batch_scale.py input_dir/ output_dir/ --algorithm epx --scale 2

Compare all algorithms side-by-side

python3 compare_algorithms.py input.png output_comparison.html

undefined

python3 compare_algorithms.py input.png output_comparison.html

undefined

Algorithm Selection Guide

算法选择指南

Decision tree:

Need to scale pixel art?
├── Transparency important? → EPX
├── Fast iteration needed? → EPX
├── Complex gradients/dithering? → hq2x or hq4x
├── Maximum quality for hero asset? → xBR
└── Not sure? → Run compare_algorithms.py

决策树:

Need to scale pixel art?
├── Transparency important? → EPX
├── Fast iteration needed? → EPX
├── Complex gradients/dithering? → hq2x or hq4x
├── Maximum quality for hero asset? → xBR
└── Not sure? → Run compare_algorithms.py

Typical Workflow

典型工作流程

Prototype with EPX 2x: Process all assets quickly
Review results: Identify which need higher quality
Re-process heroes with hq4x or xBR: Apply to key assets only
Compare outputs: Use
```
compare_algorithms.py
```
for side-by-side
Optimize: Sometimes 2x looks better than 4x (test both)

使用EPX 2倍放大快速原型制作：快速处理所有资源
审核结果：确定哪些资源需要更高质量
使用hq4x或xBR重新处理核心资产：仅应用于关键资源
对比输出结果：使用
```
compare_algorithms.py
```
进行并排对比
优化调整：有时候2倍放大的效果比4倍更好（建议都测试）

Scripts Reference

脚本参考

All scripts in

scripts/

directory:

Script	Purpose	Speed	Quality
`scale_epx.py`	EPX/Scale2x implementation	Fast	Good
`scale_hqx.py`	hq2x/hq3x/hq4x implementation	Medium	Great
`scale_xbr.py`	xBR/Super-xBR implementation	Slow	Best
`batch_scale.py`	Process directories	Varies	Varies
`compare_algorithms.py`	Generate comparison HTML	N/A	N/A

Each script includes:

CLI interface with
```
--help
```
Transparency preservation
Error handling for corrupted inputs
Progress indicators for batch operations

所有脚本位于

scripts/

Script	Purpose	Speed	Quality
`scale_epx.py`	EPX/Scale2x实现	快	良好
`scale_hqx.py`	hq2x/hq3x/hq4x实现	中	优秀
`scale_xbr.py`	xBR/Super-xBR实现	慢	最佳
`batch_scale.py`	批量处理目录	可变	可变
`compare_algorithms.py`	生成对比HTML	N/A	N/A

每个脚本包含：

带
```
--help
```
的CLI界面
透明通道保留
损坏输入的错误处理
批量操作的进度指示

Technical Details

技术细节

Color Space Considerations

色彩空间考量

EPX: Works in RGB, binary edge detection hq2x/hq4x: Uses YUV color space with thresholds (Y=48, Cb=7, Cr=6) xBR: Advanced edge weighting in RGB with luminance consideration

EPX：在RGB色彩空间工作，使用二进制边缘检测 hq2x/hq4x：使用YUV色彩空间和阈值（Y=48, Cb=7, Cr=6） xBR：在RGB色彩空间中使用带亮度考量的高级边缘加权

Transparency Handling

透明通道处理

All algorithms preserve alpha channel:

Transparent pixels don't influence edge detection
Semi-transparent pixels are handled correctly
Output maintains RGBA format if input has alpha

所有算法均保留Alpha通道：

透明像素不影响边缘检测
半透明像素处理正确
如果输入包含Alpha通道，输出将保持RGBA格式

Performance Benchmarks (M4 Max, 48x48 input)

性能基准测试（M4 Max，48x48输入）

Algorithm	Time (1 image)	Batch (100 images)
EPX 2x	0.01s	1s
EPX 3x	0.02s	2s
hq2x	0.10s	10s
hq4x	0.30s	30s
xBR 2x	0.15s	15s
xBR 4x	0.50s	50s

Rule of thumb: EPX is ~10x faster than hq2x, ~20x faster than xBR

Algorithm	Time (1 image)	Batch (100 images)
EPX 2x	0.01s	1s
EPX 3x	0.02s	2s
hq2x	0.10s	10s
hq4x	0.30s	30s
xBR 2x	0.15s	15s
xBR 4x	0.50s	50s

经验法则：EPX的速度约为hq2x的10倍，xBR的20倍

Output Validation

输出验证

After scaling, verify results:

bash

undefined

放大完成后，验证结果：

bash

undefined

Check output dimensions

identify output.png # Should be exactly 2x, 3x, or 4x input

Visual inspection

open output.png # Look for artifacts, incorrect edges

Compare algorithms

python3 compare_algorithms.py input.png comparison.html open comparison.html # Side-by-side comparison


**Common issues**:
- Jagged diagonals → Try hq2x or xBR instead of EPX
- Blurry edges → Check if input was already scaled (apply to original)
- Wrong colors → Verify input is RGB/RGBA (not indexed/paletted PNG)

python3 compare_algorithms.py input.png comparison.html open comparison.html # Side-by-side comparison


**常见问题**:
- 对角线边缘锯齿明显 → 尝试用hq2x或xBR替代EPX
- 边缘模糊 → 检查输入是否已被放大过（建议使用原始素材）
- 颜色错误 → 验证输入为RGB/RGBA格式（而非索引/调色板PNG）

pixel-art-scaler

Original

Translation

Pixel Art Scaler

像素画放大器

When to Use

适用场景

Core Algorithms

核心算法

1. EPX/Scale2x (Fastest, Good Quality)

1. EPX/Scale2x（速度最快，质量良好）

2. hq2x/hq3x/hq4x (High Quality, Slower)

2. hq2x/hq3x/hq4x（质量高，速度较慢）

3. xBR/Super-xBR (Highest Quality, Slowest)

3. xBR/Super-xBR（质量最高，速度最慢）

Anti-Patterns

常见误区

Anti-Pattern: Nearest-Neighbor for Display

误区：使用最近邻算法进行显示放大

Anti-Pattern: Using AI/ML for Pixel Art

误区：使用AI/ML放大像素画

Anti-Pattern: Wrong Algorithm for Context

误区：不分场景使用错误算法

Usage

使用方法

Quick Start

快速开始

Install dependencies

Install dependencies

Scale a single icon with EPX 2x (fastest)

Scale a single icon with EPX 2x (fastest)

Scale with hq2x (high quality)

Scale with hq2x (high quality)

Scale with xBR (maximum quality)

Scale with xBR (maximum quality)

Batch process directory

Batch process directory

Compare all algorithms side-by-side

Compare all algorithms side-by-side

Algorithm Selection Guide

算法选择指南

Typical Workflow

典型工作流程

Scripts Reference

脚本参考

Technical Details

技术细节

Color Space Considerations

色彩空间考量

Transparency Handling

透明通道处理

Performance Benchmarks (M4 Max, 48x48 input)

性能基准测试（M4 Max，48x48输入）

Output Validation

输出验证

Check output dimensions

Check output dimensions

Visual inspection

Visual inspection

Compare algorithms

Compare algorithms

References

参考资料

Deep Dives

深度解析

Research Papers & Sources

研究论文与来源

Example Assets

示例资源

Changelog

更新日志