🪄 Godot Smart Image Slicer (智能图像切割插件)

一个轻量级的 Godot 4 编辑器插件。无需编写代码，只需在 Inspector（属性）面板点击一下，即可自动按透明间隔识别并切割 Sprite Sheet（图集），或自动裁切单张图片的透明边缘。

非常适合需要快速拆分 UI 图集、角色序列帧或清理素材边缘的美术与开发人员。

✨ 核心特性 (Features)

• 🖱️ 无缝集成编辑器：通过 EditorInspectorPlugin 直接在右侧属性面板生成操作按钮。
• 🧠 **泛洪填充算法 (Flood Fill)**：精准识别不透明像素的连通域，自动计算最大外接矩形 (Bounding Box)。
• 🎨 保留抗锯齿边缘：智能 Alpha 阈值判断（默认 > 0.01），完美保留图像边缘的半透明过渡像素，不会出现生硬的白边。
• 🔄 自动刷新文件系统：切割并导出 PNG 后，自动触发 EditorFileSystem.scan()，新图片即刻可用。
• 📂 自定义导出目录：每次切割可自由选择保存路径，并自动按 原图名_slice_序号.png 规范命名。

📸 演示 (Demo)

(建议在此处插入一张 GIF 动图，展示：选中图片 -> 点击按钮 -> 选择目录 -> 文件系统刷出新图片的过程)

📥 安装指南 (Installation)

1. 下载本仓库的代码，或者手动创建以下目录结构：

   res://addons/smart_image_slicer/
     ├── plugin.cfg
     ├── plugin.gd
     ├── smart_slice_inspector.gd
     └── smart_slice_logic.gd
   

2. 在 Godot 顶部菜单栏点击 Project (项目) -> **Project Settings (项目设置)**。
3. 切换到 Plugins (插件) 选项卡。
4. 找到 Smart Image Slicer，将其状态从 Inactive 改为 **Active**。

🚀 使用方法 (Usage)

1. 在左下角的 FileSystem (文件系统) 面板中，单击选中一张包含多个元素的图集 (Texture2D / Sprite Sheet)。
2. 看向右侧的 Inspector (属性) 面板。
3. 点击最顶部出现的黄色 🔪 智能切割 (按透明区域) 按钮。
4. 在弹出的窗口中选择一个保存目录（例如 res://sliced_sprites/）。
5. 等待控制台输出 ✅ 智能切割完成！，切好的小图就会自动出现在你选择的文件夹中！

⚠️ 常见问题与排错 (Troubleshooting)

Q: 为什么点击切割后，只生成了 1 张图片？

A: 这说明算法认为整张图是一个“没有透明间隔的整体”。通常由以下 3 种原因导致：

1. 图片没有真正的透明通道：
   • 你的图片可能是 .jpg 格式（JPG 不支持透明度），或者导出 PNG 时没有勾选“Alpha/透明度”。
   • 解决：用画图软件打开原图，确保背景真的是透明的（灰白格子），然后重新导出为 PNG-24 格式。
2. 元素之间有“隐藏”的连接：
   • 哪怕两个元素之间只有 1个像素 的半透明阴影相连，或者有极其细微的杂色像素，算法就会认为它们是连在一起的。
   • 解决：打开 smart_slice_logic.gd，找到 color.a > 0.01，将其改大（例如 color.a > 0.5），以切断极淡的阴影连接。
3. 你其实只需要“裁切边缘 (Trim)”：
   • 如果你不是想把图集切成多个碎片，而只是想把一张大图四周多余的透明边缘裁掉，请修改 smart_slice_logic.gd 中的 _process_image 函数，使用 Godot 原生的 image.get_used_rect() 即可。

Q: 切割 4K/8K 超大分辨率图片时编辑器卡顿了？

A: 本插件使用 GDScript 逐像素遍历。对于常规的 UI/Sprite 图集（1024x1024 左右）是瞬间完成的。但如果图片极大，建议在游戏加载界面使用后台线程（Thread）运行核心算法，避免阻塞主线程。

🛠️ 工作原理 (How it Works)

1. 读取选中 Texture2D 的底层 Image 数据。
2. 使用一维 PackedByteArray 记录像素访问状态，极大优化内存。
3. 遍历像素，当发现 Alpha > 0.01 的未访问像素时，触发 **泛洪填充 (Flood Fill)**。
4. 在填充过程中动态更新当前色块的 Rect2i (最小外接矩形)。
5. 使用 image.get_region(rect) 裁切出子图并保存为 PNG。

🤝 贡献 (Contributing)

欢迎提交 Issue 和 Pull Request！如果你有更好的图像分割算法（如基于轮廓检测 OpenCV 的思路），欢迎一起探讨优化。

📜 许可证 (License)

本项目基于 MIT License 开源。你可以自由在商业或非商业项目中使用此插件。