🎨 MyPixel

像素风格图像生成与编辑工具
A pixel art generation & editing toolkit

---

📖 项目简介 / Introduction

MyPixel 是一个像素风格图像生成与编辑工具，采用 Web 编辑器 + CLI 混合架构。

• Web 编辑器：浏览器中可视化绘制像素艺术，支持多工具、调色板、撤销重做、导入导出
• CLI 工具：命令行生成/验证 PNG，适合 CI/CD 流水线和 Coding Agent 集成
• JSON 驱动：结构化数据格式，便于程序化操作和版本管理

---

MyPixel is a pixel art generation and editing tool with a Web Editor + CLI hybrid architecture.

• Web Editor: Visual pixel art drawing in the browser with multi-tool support, palettes, undo/redo, and import/export
• CLI Tool: Generate/validate PNG from command line, perfect for CI/CD pipelines and Coding Agent integration
• JSON-driven: Structured data format for programmatic manipulation and version control

---

✨ 特性 / Features

Feature	Description
🖌️ Web 可视化编辑器	铅笔、橡皮、油漆桶、取色器、矩形、圆形、直线工具
🎨 内置 6 种调色板	DB16, DB32, PICO-8, Game Boy, Endesga 32, NES
📐 缩放与平移	滚轮缩放（1x-32x），空格拖拽平移
↩️ 撤销 / 重做	最多 50 步历史记录
📁 导入 / 导出	JSON 工程文件、PNG 图片（可选缩放倍数）
🖥️ CLI 工具	generate / validate / palettes 命令
🤖 Agent-First	JSON 格式便于 AI Agent 程序化生成像素艺术

---

🚀 快速开始 / Quick Start

环境要求 / Prerequisites

• Node.js >= 18
• pnpm >= 8

安装 / Install

git clone https://github.com/2eeYuan/myPixel.git
cd myPixel
pnpm install

启动 Web 编辑器 / Start Web Editor

pnpm --filter @mypixel/web-editor dev

打开浏览器访问 http://localhost:5173，即可开始绘制。

Open your browser and start drawing.

使用 CLI / Use CLI

# 构建 CLI
pnpm --filter @mypixel/cli build

# 验证 JSON 文件
node packages/cli/dist/index.js validate -i docs/examples/hero.json

# 生成 PNG（4 倍缩放）
node packages/cli/dist/index.js generate -i docs/examples/hero.json -o hero.png -s 4

# 查看内置调色板
node packages/cli/dist/index.js palettes

---

🖌️ Web 编辑器使用 / Web Editor Usage

工具栏 (左侧) / Toolbar (Left)

快捷键	工具	说明
B	✏️ 铅笔	绘制单个像素
E	🧹 橡皮擦	擦除像素（变为透明）
G	🪣 油漆桶	填充连续同色区域
I	💉 取色器	从画布拾取颜色
R	⬜ 矩形	拖拽绘制矩形边框
O	⭕ 圆形	拖拽绘制椭圆边框
L	📏 直线	拖拽绘制直线

快捷键 / Shortcuts

快捷键	功能
Ctrl+Z	撤销
Ctrl+Shift+Z	重做
Ctrl+S	保存项目 (JSON)
Ctrl+O	打开项目
Ctrl+Shift+E	导出 PNG
Ctrl+G	切换网格线
0	重置缩放
鼠标滚轮	缩放画布
空格 + 拖拽	平移画布

菜单栏 / Menu Bar

菜单	功能
File → Open Project	打开 .json 工程文件继续编辑
File → Save Project	保存为 .mypixel.json 工程文件
File → Export PNG	导出成品 PNG（可选缩放倍数，透明背景）
File → Export JSON	导出原始 JSON 数据
Edit → Undo / Redo	撤销 / 重做
Edit → Canvas Size	修改画布尺寸 (最大 1024×1024)
View → Toggle Grid	显示 / 隐藏网格线

---

🖥️ CLI 命令参考 / CLI Reference

命令 / Command	说明 / Description
mypixel generate	从 JSON 生成 PNG 图像
mypixel validate	验证 JSON 格式是否合法
mypixel palettes	查看内置调色板列表

generate 命令

mypixel generate -i input.json -o output.png -s 4 --bg "#ffffff"

参数	说明	默认值
-i, --input	输入 JSON 文件路径	stdin
-o, --output	输出 PNG 文件路径	stdout
-s, --scale	缩放倍数 (1-32)	1
--bg	背景颜色 (透明则不填)	透明

validate 命令

mypixel validate -i input.json
# ✓ Valid

palettes 命令

# 表格格式
mypixel palettes

# JSON 格式
mypixel palettes --format json

---

📄 JSON 数据格式 / JSON Format

{
  "version": "1.0",
  "name": "heart",
  "width": 8,
  "height": 8,
  "palette": ["#000000", "#ff004d"],
  "pixels": [
    [0, 0, 1, 1, 1, 1, 0, 0],
    [0, 1, 1, 1, 1, 1, 1, 0],
    [1, 1, 1, 1, 1, 1, 1, 1],
    [1, 1, 1, 1, 1, 1, 1, 1],
    [1, 1, 1, 1, 1, 1, 1, 1],
    [0, 1, 1, 1, 1, 1, 1, 0],
    [0, 0, 1, 1, 1, 1, 0, 0],
    [0, 0, 0, 1, 1, 0, 0, 0]
  ]
}

字段 / Field	类型 / Type	说明 / Description
version	string	固定 "1.0"
width	integer	画布宽度 (1-1024)
height	integer	画布高度 (1-1024)
palette	string[]	颜色数组 #RRGGBB
pixels	number[][]	像素网格，值为调色板索引，-1 表示透明

---

📁 项目结构 / Project Structure

myPixel/
├── packages/
│   ├── core/          # 核心库：类型定义、调色板、工具函数
│   └── cli/           # CLI 工具：generate / validate / palettes
├── apps/
│   └── web-editor/    # Web 编辑器：Vite + Canvas 2D
├── docs/
│   ├── examples/      # 示例 JSON 文件
│   ├── cli-reference.md
│   └── json-schema.md
└── PRD-mypixel.md     # 产品需求文档

---

🎨 内置调色板 / Built-in Palettes

调色板	色数	说明
DB16	16	DawnBringer 16 色经典调色板
DB32	32	DawnBringer 32 色扩展调色板
PICO-8	16	PICO-8 幻想主机 16 色调色板
Game Boy	4	经典 Game Boy 4 色调色板
Endesga 32	32	现代像素艺术常用 32 色调色板
NES	64	NES/Famicom 2C02 PPU 系统调色板

---

🛠️ 技术栈 / Tech Stack

• TypeScript — 类型安全
• pnpm workspaces — Monorepo 管理
• Vite — Web 编辑器构建
• HTML Canvas 2D API — 画布渲染
• Commander.js — CLI 框架
• pngjs — PNG 生成（纯 JavaScript）
• Vitest — 测试框架

---

📜 许可证 / License

MIT