# PixelCraft Studio

**Repository Path**: vampirewal/pixel-craft-studio

## Basic Information

- **Project Name**: PixelCraft Studio
- **Description**: No description available
- **Primary Language**: Unknown
- **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-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# PixelCraft Studio 🎨

**高性能像素画编辑器 — 基于 WPF + SkiaSharp + .NET 8**

[![.NET](https://img.shields.io/badge/.NET-8.0-512BD4?logo=dotnet&logoColor=white)](https://dotnet.microsoft.com/)
[![WPF](https://img.shields.io/badge/WPF-Windows-0078D6?logo=windows&logoColor=white)](https://github.com/dotnet/wpf)
[![SkiaSharp](https://img.shields.io/badge/SkiaSharp-2.88-29BEB0?logo=skia&logoColor=white)](https://github.com/mono/SkiaSharp)
[![HandyControl](https://img.shields.io/badge/HandyControl-3.5-FF6A00)](https://github.com/HandyOrg/HandyControl)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

**像素艺术从未如此强大** — 硬件加速渲染 · 专业图层系统 · AI 智能集成 · 流畅创作体验

</div>

---

## 📖 目录

- [项目简介](#-项目简介)
- [核心特性](#-核心特性)
- [技术栈](#-技术栈)
- [项目架构](#-项目架构)
- [功能详解](#-功能详解)
  - [画布与图层系统](#-画布与图层系统)
  - [工具系统](#-工具系统)
  - [渲染引擎](#-渲染引擎)
  - [命令系统与撤销重做](#-命令系统与撤销重做)
  - [颜色管理](#-颜色管理)
  - [文件格式](#-文件格式)
  - [MCP 服务集成](#-mcp-服务集成)
- [界面概览](#-界面概览)
- [快捷键一览](#-快捷键一览)
- [快速开始](#-快速开始)
- [项目结构](#-项目结构)
- [开发指南](#-开发指南)
- [许可证](#-许可证)

---

## 🚀 项目简介

**PixelCraft Studio** 是一款面向像素艺术家、独立游戏开发者以及 AI 创作者的**现代像素画编辑工具**。它弥补了市面上现有工具的空白——将**硬件加速渲染**、**专业级图层系统**与**AI 协议集成**融于一身，在 Windows 平台上提供流畅、精准且富有创造力的像素画创作体验。

无论是绘制精致的像素角色、设计复古风格的游戏素材，还是通过 AI 助手自动生成像素艺术，PixelCraft Studio 都能胜任。

---

## ✨ 核心特性

| 特性 | 说明 |
|------|------|
| 🖌️ **11 种绘图工具** | 铅笔、画笔、橡皮擦、油漆桶、取色器、选区、魔棒、移动、直线、矩形、椭圆 |
| 📐 **对称绘制** | 支持无对称、水平对称、垂直对称、四象限对称 |
| 📂 **图层系统** | 多图层管理、混合模式（Normal / Multiply / Screen / Overlay / SoftLight）、不透明度、锁定类型 |
| ↩️ **撤销 / 重做** | 基于命令模式，最多 50 步历史，像素级差异存储 |
| ⚡ **硬件加速渲染** | SkiaSharp 驱动，脏矩形优化，仅重绘变化区域 |
| 🎨 **颜色管理** | 前景/背景色、颜色历史、调色板系统、高级颜色编辑器 |
| 🔲 **选区系统** | 矩形选区、魔棒选区、追加/减除/相交模式、蚂蚁线动画 |
| 💾 **文件格式** | 自定义 `.pxart` 工程文件（Deflate 压缩 + SHA256 校验）、`.pxpal` 调色板文件 |
| 📤 **多格式导出** | PNG / JPEG / BMP / ICO，支持 2x / 4x / 8x 放大导出 |
| 🤖 **MCP 协议集成** | 内置 MCP 服务，允许 AI 客户端直接操控画布（26+ 个远程工具） |
| 📐 **画布视图控制** | 缩放（0.5x - 32x）、平移、适配窗口、实际像素 |
| 🎛️ **现代化 UI** | HandyControl 主题、三栏可停靠布局、暗色/亮色主题 |
| 📝 **多文档支持** | 标签页管理多画布、独立编辑、自动保存 |
| 📋 **剪贴板操作** | 复制 / 剪切 / 粘贴选区内容 |

---

## 🛠️ 技术栈

| 技术 | 用途 |
|------|------|
| **.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          │
│  MainWindow · DocumentManager · SkiaCanvasControl                │
├───────────────────┬──────────────────────────────────────────────┤
│  PixelCraft.Mcp   │  PixelCraft.Rendering                        │
│  (MCP 服务协议)    │  (渲染引擎)                                 │
│  McpServer ·       │  CanvasRenderer · LayerCompositor            │
│  McpHttpTransport  │  ImageExporter · DirtyRectManager           │
│  26+ 远程工具      │  Checkerboard · MarchingAnts · Grid · 等   │
├───────────────────┼──────────────────────────────────────────────┤
│  PixelCraft.Tools │  PixelCraft.FileFormat                       │
│  (工具系统)        │  (文件格式)                                  │
│  ITool / ToolBase │  .pxart 工程文件 · .pxpal 调色板文件         │
│  11 种工具实现     │  ImageImportService · GIMP/ Paint.NET 导入   │
├───────────────────┴──────────────────────────────────────────────┤
│                   PixelCraft.Core (核心类库)                      │
│  Models: Canvas · Layer · Palette · Selection · ViewTransform    │
│  Commands: 13 种命令 · CommandHistory (50步撤销/重做)           │
│  Enums: 15 种 · Extensions · Helpers (Bresenham · Symmetry)     │
├──────────────────────────────────────────────────────────────────┤
│              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` | 矩形绘制，支持纯边框 / 纯填充 / 边框+填充 |
| 椭圆 (Ellipse) | `Ctrl+O` | 椭圆绘制，支持纯边框 / 纯填充 / 边框+填充 |

所有工具通过 `ITool` 接口统一管理，支持鼠标事件、Shift 约束、坐标裁剪和对称绘制。

### ⚙️ 渲染引擎

基于 **SkiaSharp** 的高性能渲染管线，采用**脏矩形更新**策略优化性能：

1. **棋盘格背景** — 透明区域以棋盘格显示
2. **图层合成** — 从底部向上逐层混合（处理不透明度和混合模式）
3. **像素网格** — 缩放 ≥ 400% 时显示辅助网格线
4. **蚂蚁线动画** — 选区边界的动态虚线效果
5. **对称轴指示** — 对称模式下显示辅助虚线
6. **光标预览** — 笔刷大小和位置预览提示

缩放范围 **0.5x ~ 32x**，支持平移和快捷键适配窗口/实际像素。

### ↩️ 命令系统与撤销重做

采用**命令模式**（Command Pattern），所有操作封装为命令对象，统一管理：

- **CommandHistory**：撤销/重做堆栈管理，上限 50 步
- **PixelDiffCollector**：像素级差异存储，只记录变化像素的原始值，节省内存
- **13 种命令类型**：绘制、图层管理、画布调整、选区操作、变换操作等

### 🎨 颜色管理

- **前景色 / 背景色**：快速切换和编辑
- **颜色历史**：记录最近使用的颜色
- **调色板**：内置预设调色板，支持自定义颜色
- **颜色编辑器**：高级颜色编辑对话框，精确调整颜色值
- **取色**：通过取色器工具从画布任意位置拾取颜色

### 💾 文件格式

| 格式 | 扩展名 | 说明 |
|------|--------|------|
| **PixelCraft 工程文件** | `.pxart` | JSON 元数据头 + Deflate 压缩的每层 RGBA 像素数据 + SHA256 完整性校验 |
| **PixelCraft 调色板文件** | `.pxpal` | JSON 格式存储颜色列表 |
| **GIMP 调色板** | `.gpl` | 支持导入 GIMP 格式的调色板 |
| **Paint.NET 调色板** | `.txt` | 支持导入 Paint.NET 格式的调色板 |

### 🤖 MCP 服务集成

**MCP（Model Context Protocol）** 是 AI 客户端与编辑器之间的标准化通信协议。PixelCraft Studio 内置完整的 MCP 服务支持：

- **传输方式**：支持 Streamable HTTP 和 SSE（Server-Sent Events）两种模式
- **监听地址**：`127.0.0.1:9800`
- **26+ 个远程工具**，涵盖：
  - 画布管理（创建项目、查询信息、调整大小）
  - 绘制操作（画像素、画线、画矩形、填充、擦除）
  - 图层操作（添加/删除图层、设置属性、翻转/旋转）
  - 选区操作（全选、取消选区、矩形选区、删除选区）
  - 编辑操作（撤销、重做）
  - 文件操作（保存/加载项目、导出图片）
  - 设置操作（设置颜色、对称模式）
- **独立 MCP Server**：`pixelcraft-mcp.exe` 支持通过 stdin/stdout 通信，可集成到 Claude Desktop 等 AI 客户端

---

## 🖥️ 界面概览

```
┌─────────────────────────────────────────────────────────────────┐
│  菜单栏: 文件 · 编辑 · 视图 · 帮助                              │
├────┬────────────────────────────────────┬───────────────────────┤
│    │                                    │                       │
│ 工 │         画布编辑区域                │  颜色面板              │
│ 具 │     (SkiaSharp Canvas)             │  ──────────           │
│ 条 │                                    │  调色板               │
│    │                                    │  ──────────           │
│    │                                    │  颜色历史             │
│    │                                    │  ──────────           │
│    │                                    │  图层面板             │
│    │                                    │  ──────────           │
│    │                                    │  迷你地图             │
├────┴────────────────────────────────────┴───────────────────────┤
│  状态栏: 坐标 · 缩放比例 · MCP 状态 · 操作提示                  │
└─────────────────────────────────────────────────────────────────┘
```

- **左侧**：48px 宽工具条，包含 11 个工具按钮 + 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` | 合并可见图层 |
| `P / B / E / G / I / M / W / V / U / O` | 切换工具 |

完整快捷键请参考需求文档中的附录。

---

## 🚀 快速开始

### 前置条件

- 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/                   # 数据模型
│   │   ├── Commands/                 # 命令模式实现
│   │   ├── Enums/                    # 枚举定义
│   │   ├── Extensions/               # 扩展方法
│   │   ├── Helpers/                  # 算法辅助类
│   │   └── Services/                 # 服务
│   ├── PixelCraft.Tools/             # 工具系统
│   │   └── Tools/                    # 11 种工具实现
│   ├── PixelCraft.Rendering/         # 渲染引擎
│   │   └── Renderers/                # 子渲染器
│   ├── PixelCraft.FileFormat/        # 文件格式
│   ├── PixelCraft.Mcp/               # MCP 协议服务
│   │   ├── Protocol/                 # JSON-RPC 协议类型
│   │   └── Tools/                    # MCP 远程工具
│   ├── PixelCraft.McpServer/         # 独立 MCP 主机
│   └── PixelCraft.UI/                # WPF 主界面
│       ├── ViewModels/               # MVVM 视图模型
│       ├── Controls/                 # 自定义控件
│       ├── Converters/               # 值转换器
│       ├── Dialogs/                  # 对话框
│       ├── Windows/                  # 辅助窗口
│       └── Rendering/                # UI 层渲染辅助
├── tests/                            # 测试项目
└── PixelCraft.slnx                   # 解决方案文件
```

---

## 🧑‍💻 开发指南

### 编码规范

- 遵循 **MVVM 架构**，使用 `[ObservableProperty]` 和 `[RelayCommand]` 源生成器
- 枚举统一添加 `[DescriptionAttribute]` 中文描述
- 项目中已配置 `.editorconfig` 和代码分析规则
- 核心逻辑均编写单元测试（位于 `tests/` 目录）

### 运行测试

```bash
dotnet test
```

### 构建发布

```bash
dotnet publish src/PixelCraft.UI -c Release -o publish
```

---

## 📄 许可证

本项目基于 **MIT 许可证** 开源。

---

<div align="center">

**PixelCraft Studio** — 让像素艺术更简单、更强大、更智能

⭐ 如果这个项目对你有帮助，欢迎 Star 支持！

</div>