Sprite-Editor

Sprite Editor 是一个用于从 sprite sheet 中提取角色帧并生成透明蒙版的可视化工具， 用于编辑提取序列图片

工具集

Sprite Editor (模块化)

Sprite Editor 是一个用于从 sprite sheet 中提取角色帧并生成透明蒙版的可视化工具，现已重构为模块化结构，位于 sprite_editor/ 目录下。

主要功能

• 自动分析 sprite sheet，提取角色帧
• 自动生成透明蒙版
• 支持手动调整蒙版（画笔/橡皮工具）
• 高级蒙版编辑功能：
  • GrabCut 交互式分割
  • Watershed 标记式分割
  • Canny 边缘检测蒙版生成
  • 自适应阈值蒙版生成
  • 形态学自动修复
• 缩放与平移编辑区域
• 批量导出角色帧
• 帧排序、筛选与自定义命名
• 帧标签与备注管理
• 动画预览功能
• 参数预设保存与加载
• 现代化UI/UX：
  • 选项卡式参数区
  • 可滚动的缩略图区域
  • 进度反馈与状态提示
  • 右键上下文菜单
  • 统一的现代化样式
  • 设置持久化
  • 键盘快捷键支持

安装

1. 确保你安装了 Python 3.8 或更高版本。
2. (可选但推荐) 创建并激活一个虚拟环境：

   python -m venv .venv
   # Windows
   ./.venv/Scripts/activate
   # macOS/Linux
   source .venv/bin/activate

3. 安装所需的依赖项：

   pip install -r requirements.txt

快速开始

1. 运行 python -m tools.sprite_editor.main 启动工具
2. 点击"加载图片"按钮加载 sprite sheet
3. 调整参数获得最佳结果
4. 在缩略图区域浏览提取的帧
5. 可选：编辑帧的蒙版（右键菜单）、设置标签/备注
6. 点击"导出全部"或使用批量导出功能

模块结构 (sprite_editor/)

• main.py: 应用程序入口点
• main_window.py: 主窗口界面和主要逻辑
• dialogs.py: 各种对话框（蒙版编辑、参数设置、动画预览等）
• widgets.py: 自定义控件（缩略图列表、蒙版编辑区域等）
• mask_processor.py: 核心图像处理和蒙版生成逻辑
• roi.py: 定义 FrameROI 类
• constants.py: 应用程序常量
• presets.py: 参数预设管理
• resources.qrc, resources.py, icons/: UI 资源文件

界面与交互详解

主窗口 (Main Window)

主窗口是工具的核心交互界面，分为几个主要区域：

1. 菜单栏 (Menu Bar):

   • 文件: 加载图片、加载/保存预设、导出全部帧、退出。
   • 编辑: 触发参数重置。
   • 工具: 打开动画预览窗口。
   • 帮助: 显示关于信息。

2. 参数设置区 (Parameter Area):

   • 使用选项卡分类展示不同的处理参数：
     • 基础阈值: 控制初始蒙版生成的阈值。
     • 形态学: 噪声去除 (Open) 和孔洞填充 (Close) 的核大小及迭代次数。
     • 轮廓筛选: 最小/最大面积、最大提取数量等，用于过滤不需要的 ROI。
     • ROI 设置: 帧宽度、高度、内边距 (Padding)。
   • 悬停在参数名称上会显示详细说明。
   • 修改参数后，如果影响蒙版或 ROI 提取，会自动刷新预览和缩略图。

3. 缩略图列表 (Thumbnail List):

   • 横向滚动显示所有提取出的帧 (ROI) 的缩略图。
   • 选择:
     • 单击: 选择单个帧，并在预览区显示。该帧成为"当前帧"。
     • Ctrl + 单击: 添加或移除选中帧，不改变"当前帧"。
     • Shift + 单击: 选择从"当前帧"到被点击帧之间的所有帧，并将被点击帧设为"当前帧"。
   • 右键菜单 (Context Menu):
     • 对单个选中帧: "编辑 Mask" 打开蒙版编辑器。
     • 对一个或多个选中帧: "导出选中帧"、"批量设置标签"、"批量设置备注"。

4. 预览区 (Preview Area):

   • 显示当前选中的单个帧及其生成的蒙版叠加效果。

5. 状态栏 (Status Bar):

   • 显示当前加载的文件名、提取和显示的 ROI 数量、鼠标悬停控件的提示信息等。

蒙版编辑对话框 (Mask Edit Dialog)

通过在缩略图列表右键菜单选择 "编辑 Mask" 打开。

1. 工具栏 (Toolbar):

   • 绘制 [B]: 使用画笔添加白色区域到蒙版（前景）。
   • 擦除 [E]: 使用橡皮擦除蒙版区域（变为黑色，背景）。
   • GrabCut 前景标记 (仅 GrabCut 模式): 标记确定为前景的区域。
   • GrabCut 背景标记 (仅 GrabCut 模式): 标记确定为背景的区域。
   • GrabCut 完成分割 (仅 GrabCut 模式): 应用 GrabCut 结果并退出 GrabCut 模式。
   • Watershed 前景标记 [蓝] (仅 Watershed 模式): 标记确定为前景的区域。
   • Watershed 背景标记 [红] (仅 Watershed 模式): 标记确定为背景的区域。
   • Watershed 执行分割 (仅 Watershed 模式): 基于标记执行分割并退出 Watershed 模式。
   • 撤销 [Ctrl+Z]: 撤销上一步编辑操作。
   • 重做 [Ctrl+Y]: 重做上一步撤销的操作。
   • 重置 [R]: 将蒙版恢复到最初加载时的状态。
   • 自动修复 [A]: 使用形态学开/闭运算平滑蒙版，去除噪点和填充孔洞（参数可调）。
   • 自动蒙版 [D]: 下拉菜单提供多种自动生成蒙版的算法：
     • Canny 边缘检测: 基于边缘查找生成蒙版（参数可调）。
     • 自适应阈值: 基于局部亮度变化生成蒙版（参数可调）。
     • GrabCut 分割: 启动 GrabCut 流程（先框选，后标记修正）。
     • 分水岭 分割: 启动 Watershed 流程（标记前景/背景）。
   • 重置视图 [Home]: 将缩放和平移恢复到默认状态。
   • 笔刷大小 [ [ / ] ]: 调整绘制/擦除/标记的笔刷大小。
   • 快捷键 [?]: 显示快捷键帮助信息。

2. 编辑区域 (Editing Area):

   • 显示当前帧图像和蒙版的叠加效果。背景区域会变暗。
   • 鼠标左键拖动: 根据当前模式进行绘制、擦除或标记。
   • Shift + 鼠标左键拖动: 平移视图。
   • 鼠标滚轮: 缩放视图。
   • GrabCut 模式:
     • 框选模式: 拖动绘制红色虚线框包围前景。
     • 细化模式: 使用前景/背景画笔进行标记。可能的前景/背景区域会以蓝色/红色半透明叠加显示。
   • Watershed 模式:
     • 使用前景(蓝色)/背景(红色)画笔进行标记。标记会以半透明颜色叠加显示。

3. 快捷键 (Keyboard Shortcuts):

   • B: 切换到绘制模式
   • E: 切换到擦除模式
   • [: 减小笔刷大小
   • ]: 增大笔刷大小
   • Ctrl+Z: 撤销
   • Ctrl+Y: 重做
   • R: 重置蒙版
   • A: 自动修复蒙版（使用默认或上次参数）
   • D: 触发默认自动蒙版算法（Canny）或打开菜单
   • Home: 重置视图（缩放和平移）
   • Ctrl+S: 保存当前蒙版并关闭对话框
   • Esc: 取消编辑并关闭对话框

动画预览对话框 (Animation Preview Dialog)

通过主窗口 "工具" -> "动画预览" 打开。

• 显示所有当前筛选后的帧的动画序列。
• 提供 "播放/暂停" 按钮。
• 可以调整 "帧率 (FPS)" 来控制播放速度。
• 显示当前播放的帧号和总帧数。

资源文件生成

如果需要更新或添加图标，请按以下步骤操作：

1. 将所需图标放入 icons/ 目录
2. 运行 build_resources.py 生成 resources.py 文件