# PixelCraft Studio
**Repository Path**: vampirewal/pixel-craft-studio
## Basic Information
- **Project Name**: PixelCraft Studio
- **Description**: PixelCraft Studio 是一款面向像素艺术家、独立游戏开发者以及 AI 创作者的现代像素画编辑工具。它弥补了市面上现有工具的空白——将硬件加速渲染、专业级图层系统与AI 协议集成融于一身，在 Windows 平台上提供流畅、精准且富有创造力的像素画创作体验。--AI说的
- **Primary Language**: C#
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-29
## Categories & Tags
**Categories**: Uncategorized
**Tags**: WPF, MCP, SkiaSharp
## README
# PixelCraft Studio 🎨
**高性能像素画编辑器 — 基于 WPF + SkiaSharp + .NET 8**
[](https://dotnet.microsoft.com/)
[](https://github.com/dotnet/wpf)
[](https://github.com/mono/SkiaSharp)
[](https://github.com/HandyOrg/HandyControl)
[](LICENSE)
**像素艺术从未如此强大** — 硬件加速渲染 · 专业图层系统 · AI 智能集成 · 流畅创作体验
---
## 📖 目录
- [项目简介](#-项目简介)
- [核心特性](#-核心特性)
- [技术栈](#-技术栈)
- [项目架构](#-项目架构)
- [功能详解](#-功能详解)
- [画布与图层系统](#-画布与图层系统)
- [工具系统](#-工具系统)
- [渲染引擎](#-渲染引擎)
- [命令系统与撤销重做](#-命令系统与撤销重做)
- [时间轴与动画系统](#-时间轴与动画系统)
- [颜色管理](#-颜色管理)
- [文件格式](#-文件格式)
- [MCP 服务集成](#-mcp-服务集成)
- [界面概览](#-界面概览)
- [快捷键一览](#-快捷键一览)
- [快速开始](#-快速开始)
- [项目结构](#-项目结构)
- [开发指南](#-开发指南)
- [许可证](#-许可证)
---
## 🚀 项目简介
**PixelCraft Studio** 是一款面向像素艺术家、独立游戏开发者以及 AI 创作者的**现代像素画编辑工具**。它弥补了市面上现有工具的空白——将**硬件加速渲染**、**专业级图层系统**与**AI 协议集成**融于一身，在 Windows 平台上提供流畅、精准且富有创造力的像素画创作体验。
无论是绘制精致的像素角色、设计复古风格的游戏素材，还是通过 AI 助手自动生成像素艺术，PixelCraft Studio 都能胜任。
---
## ✨ 核心特性
| 特性 | 说明 |
|------|------|
| 🖌️ **14 种绘图工具** | 铅笔、画笔、橡皮擦、油漆桶、取色器、选区、魔棒、移动、直线、矩形、椭圆、文字、替换同色、提亮/压暗 |
| 📐 **对称绘制** | 支持无对称、水平对称、垂直对称、四象限对称 |
| 🎯 **像素完美模式** | 自动消除 L 形拐角冗余像素，线条更干净锐利 |
| 📂 **图层系统** | 多图层管理、混合模式（Normal / Multiply / Screen / Overlay / SoftLight）、不透明度、锁定类型（Alpha / 像素 / 位置） |
| ✍️ **文字图层** | 独立文字图层，支持字体、样式、对齐、间距、12 种变形效果 |
| ⏱️ **时间轴动画** | 多帧管理、洋葱皮辅助、循环/一次/乒乓播放模式、GIF 导出、帧序列导出、跨帧共享图层模式 |
| ↩️ **撤销 / 重做** | 基于命令模式，最多 50 步历史，像素级差异存储，15 种命令类型 |
| ⚡ **硬件加速渲染** | SkiaSharp 驱动，脏矩形优化，图层版本号缓存，仅重绘变化区域 |
| 🎨 **颜色管理** | 前景/背景色、颜色历史（32 色）、调色板系统（DB16 / PICO-8 / AAP-64 / 灰度）、高级颜色编辑器 |
| 🔲 **选区系统** | 矩形选区、魔棒选区、追加/减除/相交模式、蚂蚁线动画、轮廓描边 |
| 🖼️ **参考图** | 导入外部图片作为半透明参考层，可缩放/偏移/锁定 |
| 💾 **文件格式** | 自定义 `.pxart` 工程文件（Deflate 压缩 + SHA256 校验，支持文字图层与动画）、`.pxpal` 调色板文件 |
| 📤 **多格式导出** | PNG / JPEG / BMP / ICO / GIF / 精灵表 / 帧序列，支持多级放大导出 |
| 🤖 **MCP 协议集成** | 内置 MCP 服务，允许 AI 客户端直接操控画布（33 个远程工具） |
| 📐 **画布视图控制** | 缩放（0.5x - 32x）、平移、适配窗口、实际像素、迷你地图导航 |
| 🎛️ **现代化 UI** | HandyControl 主题、可停靠面板布局、暗色/亮色主题 |
| 📝 **多文档支持** | 标签页管理多画布、独立编辑、自动保存（5 分钟间隔）、崩溃恢复 |
| 📋 **剪贴板操作** | 复制 / 剪切 / 粘贴选区内容 |
| ⌨️ **自定义快捷键** | 快捷键自定义设置、持久化到 JSON、冲突检测、一键重置默认 |
| 🔲 **可变网格** | 支持 1×1 ~ 16×16 多种网格规格，大网格低缩放可见 |
---
## 🛠️ 技术栈
| 技术 | 用途 |
|------|------|
| **.NET 8.0** | 开发平台与运行时 |
| **WPF** | 桌面 UI 框架 |
| **CommunityToolkit.Mvvm 8.4** | MVVM 架构（源生成器驱动） |
| **SkiaSharp 2.88** | 硬件加速 2D 渲染引擎 |
| **HandyControl 3.5** | 第三方 WPF 控件库与主题 |
| **StreamJsonRpc 2.24** | JSON-RPC 2.0 协议实现 |
| **Serilog 4.3** | 结构化日志系统 |
| **System.IO.Compression** | Deflate 数据压缩（工程文件） |
| **System.Security.Cryptography** | SHA256 文件完整性校验 |
---
## 🏗️ 项目架构
项目采用**清晰的分层架构**，遵循 **MVVM 设计模式**，由 7 个源代码项目和 5 个测试项目组成：
```
┌──────────────────────────────────────────────────────────────────────────┐
│ PixelCraft.UI (WPF 主界面) │
│ ViewModels · Controls · Converters · Dialogs · Windows · Services │
│ MainWindow · DocumentManager · SkiaCanvasControl · TimelineControl │
├───────────────────┬──────────────────────────────────────────────────────┤
│ PixelCraft.Mcp │ PixelCraft.Rendering │
│ (MCP 服务协议) │ (渲染引擎) │
│ McpServer · │ CanvasRenderer · LayerCompositor · LayerCacheManager│
│ McpHttpTransport │ ImageExporter · GifExporter · SpriteSheetExporter │
│ 33 个远程工具 │ Checkerboard · Grid · MarchingAnts · SymmetryAxis │
│ │ OnionSkin · ReferenceImage · Text · DirtyRectManager│
├───────────────────┼──────────────────────────────────────────────────────┤
│ PixelCraft.Tools │ PixelCraft.FileFormat │
│ (工具系统) │ (文件格式) │
│ ITool / ToolBase │ .pxart 工程文件 · .pxpal 调色板文件 │
│ 14 种工具实现 │ SpriteSheetMetadata · GIMP / Paint.NET 导入 │
├───────────────────┴──────────────────────────────────────────────────────┤
│ PixelCraft.Core (核心类库) │
│ Models: Canvas · Layer · TextLayer · Selection · Palette · Timeline · │
│ Frame · Text · ReferenceImage · ViewTransform · PresetPalettes │
│ Commands: 15 种命令 · CommandHistory (50步撤销/重做) · PixelDiffCollector│
│ Enums: 18 种 · Extensions · Helpers (SymmetryHelper · BresenhamLine) │
├──────────────────────────────────────────────────────────────────────────┤
│ PixelCraft.McpServer (独立 MCP 控制台) │
│ pixelcraft-mcp.exe (stdio JSON-RPC 服务) │
└──────────────────────────────────────────────────────────────────────────┘
```
### 模块依赖关系
```
PixelCraft.UI ──→ Core ──→ Tools ──→ Rendering ──→ FileFormat ──→ Mcp
↑ ↑ ↑ ↑ ↑
└─────────┴───────────┴──────────────┴───────────┘
PixelCraft.McpServer → Core + Rendering + FileFormat + Mcp
```
---
## 🔍 功能详解
### 🖼️ 画布与图层系统
- **画布**：支持 1×1 ~ 1024×1024 像素，可选择透明或纯色背景
- **图层**：最多 256 层，每层独立存储 RGBA 像素数据
- **图层属性**：名称、可见性、不透明度（0.0~1.0）、混合模式、锁定类型（无 / 透明 / 像素 / 位置）
- **图层操作**：添加、删除、重排、合并、属性修改
- **混合模式**：Normal（正常）、Multiply（正片叠底）、Screen（滤色）、Overlay（叠加）、SoftLight（柔光）
### 🖊️ 工具系统
| 工具 | 快捷键 | 功能 |
|------|--------|------|
| 铅笔 (Pencil) | `P` | 单像素精确绘制，1px 固定大小 |
| 画笔 (Brush) | `B` | 可调笔刷大小（1~20px）的方形笔刷绘制 |
| 橡皮擦 (Eraser) | `E` | 擦除像素，可调大小 |
| 油漆桶 (Flood Fill) | `G` | 扫描线洪水填充，支持容差和连通方式（4/8 方向） |
| 取色器 (Eyedropper) | `I` | 拾取画布颜色，支持 1×1 / 3×3 / 5×5 平均取样 |
| 选区 (Selection) | `M` | 矩形选区，支持新建 / 追加 / 减除 / 相交模式，选区内拖拽可移动像素 |
| 魔棒 (Magic Wand) | `W` | 根据颜色相似度自动选择连通区域 |
| 移动 (Move) | `V` | 移动选区内容或整个图层，方向键微调 |
| 直线 (Line) | `U` | 直线绘制，可调粗细，Shift 约束角度，实时预览 |
| 矩形 (Rectangle) | `O` | 矩形绘制，支持边框 / 填充 / 边框+填充 三种模式，Shift 约束正方形 |
| 椭圆 (Ellipse) | `Shift+O` | 椭圆绘制，中点椭圆算法，支持边框 / 填充 / 边框+填充，Shift 约束正圆 |
| 文字 (Text) | `T` | 点击画布创建文字图层，支持字体、样式、颜色、对齐、变形效果 |
| 替换同色 (Replace Color) | `X` | 将图层中与目标颜色相同的像素替换为前景色，支持容差 |
| 提亮/压暗 (Brighten) | `O` | 对图层像素调整亮度，正值提亮，负值压暗，可调步进值 |
所有工具通过 `ITool` 接口统一管理，支持鼠标事件、Shift 约束、坐标裁剪和对称绘制。提供**像素完美模式**（`PixelPerfectMode`），在绘制后自动消除路径 L 形拐角的冗余像素，使线条更干净锐利。
### ⚙️ 渲染引擎
基于 **SkiaSharp** 的高性能渲染管线，采用**脏矩形更新**与**图层版本号缓存**双重优化策略：
1. **棋盘格背景** — 透明区域以经典棋盘格图案显示
2. **参考图渲染** — 半透明参考图层叠加，可配置显示位置（图层上方/下方）
3. **洋葱皮渲染** — 前后帧半透明叠加（前帧蓝色调、后帧红色调），辅助动画制作
4. **图层合成** — 从底部向上逐层混合（处理不透明度和混合模式），利用版本号缓存避免重复创建位图
5. **像素网格** — 支持 1×1 ~ 16×16 多种网格规格，缩放 ≥ 400% 时显示辅助虚线网格（大网格可在更低缩放下显示）
6. **蚂蚁线动画** — 选区边界的经典黑白动态虚线效果，80ms 间隔驱动
7. **对称轴指示** — 对称模式下显示青色辅助虚线
8. **笔刷光标** — 根据笔刷大小和缩放级别动态生成自定义光标
缩放范围 **0.5x ~ 32x**，支持平移和快捷键适配窗口/实际像素。提供**迷你地图**（MiniMap）快速导航画布全局视图。
### ↩️ 命令系统与撤销重做
采用**命令模式**（Command Pattern），所有操作封装为命令对象，统一管理：
- **CommandHistory**：撤销/重做堆栈管理，上限 50 步
- **PixelDiffCollector**：像素级差异存储，拖拽期间增量收集，最终合并为单个命令，只记录变化像素的原始值，节省内存
- **15 种命令类型**：像素绘制（PixelDrawCommand）、图层管理（添加/删除/合并/重排序）、图层属性变更、画布调整大小、变换操作（翻转/旋转）、像素移动、选区删除、轮廓描边、文字属性变更等
### ⏱️ 时间轴与动画系统
- **帧管理**：添加/删除/复制/移动帧，每帧独立存储图层快照，支持双击重命名帧
- **播放控制**：播放/暂停/停止，支持三种播放模式——**Loop**（循环）、**Once**（一次）、**PingPong**（乒乓）
- **帧属性**：可设置帧延迟（毫秒）、帧标签（关键帧标记）
- **洋葱皮**（Onion Skin）：显示前后帧半透明叠加，前帧蓝色调/后帧红色调，可调帧数和透明度
- **缩略图**：时间轴面板实时显示每帧缩略图预览
- **共享图层模式**：所有帧共享同一组图层，每帧只存储差异像素，切换模式时自动转换数据
- **帧序列导出**：逐帧导出为图片文件，可选帧范围、格式和缩放
### 🎨 颜色管理
- **前景色 / 背景色**：独立编辑，`X` 键快速交换，`D` 键重置为黑/白
- **颜色历史**：最近使用 32 种颜色自动记录，左键选为前景色、右键选为背景色
- **预设调色板**：内置 **DB16**（DawnBringer 16 色）、**PICO-8**（PICO-8 16 色）、**AAP-64**（AAP-64 64 色）、**灰度**（16 级灰度）四种经典像素调色板
- **自定义调色板**：新建/导入/导出/删除自定义调色板，支持从图片自动提取颜色
- **颜色编辑器**：高级颜色编辑对话框（HandyControl ColorPicker），支持 ARGB 十六进制直接输入
- **取色**：通过取色器工具从画布任意位置拾取颜色，支持单像素/3×3/5×5 平均取样
### 💾 文件格式
| 格式 | 扩展名 | 说明 |
|------|--------|------|
| **PixelCraft 工程文件** | `.pxart` | JSON 元数据头 + Deflate 压缩的每层 RGBA 像素数据 + SHA256 完整性校验，支持文字图层、时间轴动画、共享图层模式（文件格式版本 v3） |
| **PixelCraft 调色板文件** | `.pxpal` | JSON 格式存储颜色列表 |
| **GIMP 调色板** | `.gpl` | 支持导入 GIMP 格式的调色板 |
| **Paint.NET 调色板** | `.txt` | 支持导入 Paint.NET 格式的调色板 |
**导出格式**：
| 格式 | 说明 |
|------|------|
| **PNG** | 支持透明背景，多级放大导出 |
| **JPEG** | 可指定背景填充色 |
| **BMP** | 标准位图格式 |
| **ICO** | 多尺寸图标文件（16/32/48/64/128），手动写入 ICO 文件头 |
| **GIF** | 完整 GIF89a 编码实现，含颜色量化与 LZW 压缩，支持透明度 |
| **精灵表** | 将帧/图层排列为精灵表 PNG，可选生成 JSON 元数据（含每帧位置和尺寸） |
| **帧序列** | 逐帧导出为独立图片文件，可选帧范围、格式（PNG/JPEG/BMP）和缩放 |
### 🤖 MCP 服务集成
**MCP（Model Context Protocol）** 是 AI 客户端与编辑器之间的标准化通信协议。PixelCraft Studio 内置完整的 MCP 服务支持：
- **传输方式**：支持 Streamable HTTP 和 SSE（Server-Sent Events）两种模式
- **监听地址**：`127.0.0.1:9800`
- **33 个远程工具**，涵盖：
- 画布管理（创建项目、查询信息、调整大小、保存/加载工程）
- 绘制操作（画像素、画线、画矩形、画椭圆、填充、擦除、轮廓描边、批量绘制、场景生成、替换同色、提亮/压暗）
- 图层操作（添加/删除/移动/复制/合并/重命名/清空图层、设置属性、翻转/旋转）
- 选区操作（全选、取消选区、矩形选区、反选、删除选区）
- 时间轴与动画（帧管理、播放控制、洋葱皮设置）
- 编辑操作（撤销、重做）
- 多页签管理（切换/关闭/重命名页签）
- 文件操作（保存/加载项目、导出图片/GIF/精灵表/帧序列）
- 像素读取（单像素、区域、画布快照）
- 设置操作（设置颜色、对称模式、网格规格）
- 快捷键查询（获取当前快捷键映射）
- **独立 MCP Server**：`pixelcraft-mcp.exe` 支持通过 stdin/stdout 通信，可集成到 Claude Desktop 等 AI 客户端
---
## 🖥️ 界面概览
```
┌─────────────────────────────────────────────────────────────────┐
│ 菜单栏: 文件 · 编辑 · 视图 · 帮助 │
├────┬────────────────────────────────────────┬───────────────────┤
│ │ │ │
│ 工 │ 画布编辑区域 │ 颜色面板 │
│ 具 │ (SkiaSharp Canvas) │ ────────── │
│ 条 │ │ 调色板 │
│ │ │ ────────── │
│ │ │ 颜色历史 │
│ │ │ ────────── │
│ │ │ 图层面板 │
│ │ │ ────────── │
│ │ │ 参考图面板 │
│ │ │ ────────── │
│ │ │ 迷你地图 │
├────┴────────────────────────────────────────┴───────────────────┤
│ 工具属性栏: 笔刷大小 · 容差 · 取样大小 · 绘制模式 · 对称模式 │
├─────────────────────────────────────────────────────────────────┤
│ 时间轴面板: 帧缩略图 · 播放控制 · 洋葱皮设置 │
├─────────────────────────────────────────────────────────────────┤
│ 文档标签栏: 多页签切换 │
├─────────────────────────────────────────────────────────────────┤
│ 状态栏: 工具名称 · 画布尺寸 · 帧信息 · 图层名称 · 坐标 · 颜色 · MCP · 缩放 │
└─────────────────────────────────────────────────────────────────┘
```
- **左侧**：48px 宽工具条，包含 14 个工具按钮 + MCP 开关 + 像素完美模式开关
- **中间**：SkiaSharp 硬件加速画布，支持缩放和平移
- **右侧**：可停靠面板，整合颜色、图层、调色板、参考图管理、迷你地图等
- **顶部**：文档标签栏（多标签页管理）和工具属性栏（根据当前工具动态显示参数）
- **底部**：时间轴面板（帧管理与动画播放控制）和状态栏
---
## ⌨️ 快捷键一览
| 快捷键 | 功能 |
|--------|------|
| `Ctrl + N` | 新建画布 |
| `Ctrl + O` | 打开工程文件 |
| `Ctrl + S` | 保存工程文件 |
| `Ctrl + Shift + S` | 另存为 |
| `Ctrl + E` | 导出图片 |
| `Ctrl + Z` | 撤销 |
| `Ctrl + Y` | 重做 |
| `Ctrl + A` | 全选 |
| `Ctrl + D` | 取消选区 |
| `Ctrl + Shift + I` | 反选 |
| `Ctrl + X` | 剪切 |
| `Ctrl + C` | 复制 |
| `Ctrl + V` | 粘贴 |
| `Delete` | 删除选区内容 |
| `Ctrl + 0` | 适配窗口 |
| `Ctrl + 1` | 实际像素 |
| `Ctrl + Shift + G` | 显示/隐藏网格 |
| `Ctrl + Shift + T` | 平铺预览 |
| `Ctrl + Shift + H` | 水平翻转 |
| `Ctrl + Shift + V` | 垂直翻转 |
| `Ctrl + Shift + R` | 顺时针旋转 90° |
| `Ctrl + Shift + M` | 合并可见图层 |
| `Ctrl + F` | 加载参考图 |
| `Enter` | 播放/暂停动画 |
| `←` / `→` | 前一帧 / 后一帧 |
| `P / B / E / G / I / M / W / V / U / O / T / X` | 切换工具（可在快捷键设置中自定义） |
| `Shift+O` | 切换到椭圆工具 |
| `X` | 交换前景色/背景色 / 替换同色工具 |
| `D` | 重置为默认前景色/背景色（黑/白） |
完整快捷键请参考需求文档中的附录。
---
## 🚀 快速开始
### 前置条件
- Windows 10 / 11（64 位）
- [.NET 8.0 Desktop Runtime](https://dotnet.microsoft.com/download/dotnet/8.0)
### 构建与运行
```bash
# 克隆仓库
git clone https://github.com/your-org/PixelCraft-Studio.git
cd PixelCraft-Studio
# 还原依赖
dotnet restore
# 运行主程序
dotnet run --project src/PixelCraft.UI
# 或者以 Release 配置编译
dotnet build -c Release
./src/PixelCraft.UI/bin/Release/net8.0-windows/PixelCraft.UI.exe
```
### 启动 MCP 服务（可选）
```bash
# 启动独立 MCP Server
dotnet run --project src/PixelCraft.McpServer
```
---
## 📁 项目结构
```
PixelCraft Studio/
├── src/ # 源代码
│ ├── PixelCraft.Core/ # 核心类库
│ │ ├── Models/ # 数据模型（Canvas、Layer、TextLayer、Selection、Palette、Timeline、Frame、Text、ReferenceImage 等）
│ │ ├── Commands/ # 命令模式实现（15 种命令 + CommandHistory + PixelDiffCollector）
│ │ ├── Enums/ # 枚举定义（18 种：ToolType、BlendMode、SymmetryMode、TransformType、DrawMode 等）
│ │ ├── Extensions/ # 扩展方法（ColorExtensions）
│ │ ├── Helpers/ # 算法辅助类（SymmetryHelper）
│ │ └── Services/ # 服务（RecentFileService、ShortcutService）
│ ├── PixelCraft.Tools/ # 工具系统
│ │ └── Tools/ # 14 种工具 + 基类 + 管理器 + 算法（BresenhamLine、PixelPerfectLine）
│ ├── PixelCraft.Rendering/ # 渲染引擎
│ │ └── Renderers/ # 子渲染器（Checkerboard、Grid、MarchingAnts、SymmetryAxis、OnionSkin、ReferenceImage、Text）
│ │ └── 导出器（ImageExporter、GifExporter、SpriteSheetExporter）
│ ├── PixelCraft.FileFormat/ # 文件格式（.pxart、.pxpal、SpriteSheetMetadata）
│ ├── PixelCraft.Mcp/ # MCP 协议服务
│ │ ├── Protocol/ # JSON-RPC 协议类型
│ │ └── Tools/ # 33 个 MCP 远程工具
│ ├── PixelCraft.McpServer/ # 独立 MCP 主机（stdio JSON-RPC 服务）
│ └── PixelCraft.UI/ # WPF 主界面
│ ├── ViewModels/ # MVVM 视图模型（MainViewModel、TimelineViewModel）
│ ├── Controls/ # 自定义控件（画布、图层面板、调色板、时间轴、迷你地图等 11 个）
│ ├── Converters/ # 值转换器（3 个）
│ ├── Dialogs/ # 对话框（新建画布、调整大小、颜色编辑器、文字编辑器、精灵表 等 7 个）
│ ├── Windows/ # 辅助窗口（MCP 配置、操作指南、平铺预览）
│ ├── Services/ # UI 服务（MCP、自动保存、颜色、主题）
│ ├── Helpers/ # UI 辅助（BrushCursorGenerator）
│ └── Rendering/ # UI 层渲染辅助（ThumbnailGenerator）
├── tests/ # 测试项目（5 个）
└── PixelCraft.slnx # 解决方案文件
```
---
## 🧑💻 开发指南
### 编码规范
- 遵循 **MVVM 架构**，使用 `[ObservableProperty]` 和 `[RelayCommand]` 源生成器
- 枚举统一添加 `[DescriptionAttribute]` 中文描述
- 项目中已配置 `.editorconfig` 和代码分析规则
- 核心逻辑均编写单元测试（位于 `tests/` 目录）
### 运行测试
```bash
dotnet test
```
### 构建发布
```bash
dotnet publish src/PixelCraft.UI -c Release -o publish
```
---
## 📄 许可证
本项目基于 **MIT 许可证** 开源。
---
**PixelCraft Studio** — 让像素艺术更简单、更强大、更智能
⭐ 如果这个项目对你有帮助，欢迎 Star 支持！