pixel-art-processing（像素艺术处理）

Pixel Art Processing / 像素美术处理

[!NOTE] This skill is based on FrameRonin (https://github.com/systemchester/FrameRonin). All core algorithms and workflows are derived from the FrameRonin project.

Overview / 概述

This skill provides a complete pixel art / sprite sheet processing pipeline:

Quick Start / 快速开始

1. Deploy Backend / 部署后端

# Docker部署（推荐 / Recommended）
cd <skill>/scripts
docker-compose up -d

# 或手动部署 / Or manual:
pip install -r requirements.txt
python run_api.py

后端地址 / Backend URL: http://localhost:8000 API文档 / API docs: http://localhost:8000/docs

2. Start Worker / 启动Worker

# 需要Redis / Redis required
rq worker pixelwork --url redis://localhost:6379/0

Core Concepts / 核心概念

Sprite Sheet Layout / Sprite Sheet布局

┌────┬────┬────┬────┐
│ 0  │ 1  │ 2  │ 3  │  row=0
├────┼────┼────┼────┤
│ 4  │ 5  │ 6  │ 7  │  row=1
├────┼────┼────┼────┤
│ 8  │ 9  │ ..│ .. │
└────┴────┴────┴────┘

Index JSON:  { i, x, y, w, h, t }
i = frame index
x, y = position on sheet
w, h = frame size
t = timestamp (seconds)

Processing Modes / 处理模式

• tight_bbox: 紧贴alpha边界裁切 / Crop tightly to alpha boundary
• safe_bbox: alpha边界+padding / Alpha boundary + padding margin
• none: 不裁切 / No crop

API Reference / API参考

详见 / See: references/api.md

Client-side Processing / 客户端处理

对于 GIF/序列帧转换等纯前端功能，使用浏览器Canvas API直接处理：

For pure client-side features like GIF/frames conversion, use browser Canvas API directly:

scripts/
├── client_gif_processor.html   # GIF拆帧/合成 - 浏览器直接运行
├── sprite_split.html           # Sprite sheet拆分 - 浏览器直接运行
└── image_processor.html         # 图像基本处理 - 浏览器直接运行

直接在浏览器打开这些HTML文件即可使用。

Open these HTML files directly in browser to use.

RPG Maker Workflow / RPG Maker 工作流

详见 / See: references/rpgmaker.md

Sprite Sheet Math / Sprite Sheet 数学

详见 / See: references/sprite_math.md

Algorithm Details / 算法细节

透明行列检测 / Transparent Row/Column Detection

用于超级拆分：按透明行/列智能切割图像。

Used for super-split: intelligently cuts image by transparent rows/columns.

// 找出完全透明的行索引
// Find fully transparent rows
function findTransparentRows(imageData) {
  const { data, width, height } = imageData
  const rows = []
  for (let y = 0; y < height; y++) {
    let allTransparent = true
    for (let x = 0; x < width; x++) {
      if (data[(y * width + x) * 4 + 3] !== 0) {
        allTransparent = false
        break
      }
    }
    if (allTransparent) rows.push(y)
  }
  return rows
}

Alpha边界框 / Alpha Bounding Box

function getAlphaBbox(img) {
  // 返回 {x1, y1, x2, y2} 或 null
  // Returns {x1, y1, x2, y2} or null
}

连通域检测 / Connected Component

用于超级橡皮等工具：按连通域+容差选区。

Used for super eraser: select by connected component + tolerance.

FFmpeg Integration / FFmpeg集成

视频帧提取依赖 ffprobe/ffmpeg：

Video frame extraction requires ffprobe/ffmpeg:

# 提取帧 / Extract frames
ffmpeg -y -ss <timestamp> -i video.mp4 -vframes 1 output.png

# 获取视频信息 / Get video info
ffprobe -v quiet -print_format json -show_format -show_streams video.mp4

Dependencies / 依赖

Backend / 后端

• FastAPI >= 0.104.0
• PIL/Pillow >= 10.0.0
• rembg >= 2.0.50 (u2net model)
• ffmpeg-python >= 0.2.0
• opencv-python-headless >= 4.8.0
• Redis + RQ (for async jobs)

Frontend / 前端

• gifuct-js (GIF拆帧)
• gifenc (GIF编码)
• jszip (批量下载)
• React + Ant Design

Feature Flags / 特性开关

Deploy to Remote / 远程部署

# 1. 构建前端 / Build frontend
cd frontend && npm install && npm run build

# 2. 配置Nginx / Nginx config
# See nginx.conf in references/

# 3. 启动后端 / Start backend
uvicorn app.main:app --host 0.0.0.0 --port 8000

# 4. Docker完整部署 / Full Docker deploy
docker-compose -f docker-compose.yml up -d

Credits / 致谢

• FrameRonin by systemchester: https://github.com/systemchester/FrameRonin
• rembg for AI matting: https://github.com/danielgatis/rembg
• gifuct-js / gifenc for GIF processing