# 极光 · 拼豆盒工作室 1.3.0

把 PNG / SVG 图案转换为可打印的拼豆轨道盒与配套盖子。

## 使用流程

1. 登录极光，进入拼豆盒工作室；生成与下载使用网站现有会员及排队流程。
2. 上传 PNG / SVG。透明背景与清晰边缘更适合提取外形。
3. 编辑色块：点击选中，吸管取色，然后点击“填充选中色块”。删除与填充是两个独立操作。误操作可撤销。
4. 设置成品宽度，长度按原图比例缩放；检查轨道净宽、筋宽、壁厚、盒高和装配间隙。
5. 选择独立立豆孔或竖向连体孔；在布局中删除不需要的立豆点。
6. 开启进豆开口后沿外轮廓调整位置，盒盖与盒体开口保持同中心。盖口默认 16 mm，盒口两侧各加宽 2 mm。
   进豆口底部与盖板齐平。开启“两个取盖缺口”后，拖动蓝色 1、2 圆点分别沿外圈移动；两个缺口只开在盖子上，盒体不切。默认宽 12 mm、台阶高 3 mm，可调整或关闭。请与橙色进豆口错开；重叠处按进豆口齐平处理。
7. 可添加单面或双面盖面彩色图案、线稿刻线和内壁文字。
8. 点击生成，观察阶段提示与进度。复杂碎片和文字会增加计算时间；进度百分比不代表剩余时间严格成比例。
9. 下载 3MF，在切片软件中检查尺寸、颜色、朝向和薄壁。先小样试装，打印误差会影响松紧。

## 参数说明

- 成品宽度：整个模型的横向尺寸，长度等比例变化。
- 装饰留边：彩色图案与盖子外边缘的距离，最小 1 mm；原图自身的边框也会影响观感。
- 盒高、盖裙与顶板：以生成结果中的实际尺寸为准；盖子顶板厚度另外计入盖体总高。
- 立豆孔：默认直径 3.45 mm，连体纵向重叠 0.57 mm，横向间隔 0.7 mm。

## 常见问题

- 生成较慢：先减少微小碎片、文字和过高轮廓精度，再生成。程序仍有超时保护。
- 缺少中文字体：Windows 使用系统微软雅黑/宋体；其他系统需自行配置字体后使用内壁文字功能。
- 不显示模型：检查结果区错误提示与本地数据目录中的“运行日志.txt”。
- 源图锯齿：轮廓平滑能改善像素边缘，但无法恢复源图不存在的细节。
- 开源版无需机器码或激活码；不附带原授权后台与签发私钥。

## 本地数据

Windows 默认保存在 %LOCALAPPDATA%/PearlBoxWorkshopOpenSource。
设置环境变量 PEARL_BOX_DATA 可改变数据目录。使用启动器时，模型与日志写入该目录。
结束使用可运行 python launcher.py --stop，或安装版的停止快捷方式。

## 许可

项目原创代码采用 MIT。第三方组件保留各自许可，详见 THIRD_PARTY_NOTICES.md。
上传图案的版权属于其权利人，软件开源不改变图案版权。

## 线稿区域与凹槽填色（1.2.0）

在线稿最终预览中打开“点击填色”，选择颜色后点击封闭区域或凹槽。
“所有凹槽填此色”可一次给全部刻线与实心刻线细节上色。
可以撤销或清除填色。重新上传图片、更换模式或重新解析轮廓会清除填色。
相连凹槽共同填色；没有闭合的面板区域会连成同一选区。
面板色块与面板齐平，凹槽颜色位于槽底，保留设置的凹槽深度。
导出的 3MF 包含独立颜色实体，切片时请给各颜色实体分配实际耗材。
这不要求自动识别黑白图原本的配色；颜色由使用者选择。

## 外圈倒角与导出优化（1.2.1）

“现有外圈倒角”只控制原有盒体、盖子外圈底边倒角，范围 0–0.6 mm，默认 0.6 mm。
设为 0 关闭，不影响内部轨道。请根据耗材、打印参数与试装结果选择。
3MF 改为分批写入颜色与网格，导出期间显示当前顶点、三角面写入进度；复杂模型仍需计算时间。

## 原图与成品方向（1.2.2）

修正图像 Y 向下、打印坐标 Y 向上，以及盖子朝下打印后翻面装配的坐标转换。
标准：盖好后从外侧正面看，图案方向与上传原图一致；盒体与盖子同时转换，保持装配匹配。
盖子装饰面仍朝打印板，不能仅凭切片软件从上看盖子背面判断正面方向。
旧版本生成的不对称盒体和新版盖子可能不能匹配，请重新生成并打印整套盒体和盖子，不要只替换一件。

## 带高光眼睛的线稿识别（1.2.3）

修复实心眼睛带白色高光缺口、连着小睫毛时被误识别成细线的问题。
增加区域密度与局部厚度判断，保留眼睛实心部分，同时保留白色高光。
更新后需要重新导入原始线稿并生成，旧生成文件不会自动改变。


## 盖内立豆（1.3.0）

- 开启“在盖子内面增加立豆孔”，孔深单独可调 0.5–6 mm，默认 3 mm；孔径、独立/竖向连体、重叠与间隔均可独立设置。
- 保留原盖板，在内面增加与孔深等厚的立豆层，孔底止于原盖板；正面的凹槽或彩色图案保留。
- 实际盒高＝原盒高－盖内孔深；实际裙边＝原裙边－盖内孔深；总盖板厚＝原盖板厚＋孔深。因此装配总高度不变。例如原盒高 15、原盖板 2、孔深 3，实际盒高与裙边 12、总盖板厚 5、装配总高仍为 17 mm。
- 选择“整个盖内”自动排孔。需要部分区域时，点“框选添加区域”，在右侧“盖内立豆”视图拖出矩形；可框选多个区域。只有完整落在区域内的孔会生成，灰圈是未选中的候选孔。
- 点“点击删除／恢复孔位”后，点击孔位删除，再点击红叉恢复。支持撤销编辑、清空区域和删除记录；框选模式清空后不生成孔，可重新框选或切回“整个盖内”。
- 框选后切换到删除按钮即可编辑单孔。在盖内立豆视图操作不会修改盒体原有的豆位。
- 更换轮廓会清除盖内框选和删除记录；调整出豆方向不改变盖内孔位方向。孔层沿源图竖向连接，横向保留设置的净间隔。
- 盒体缩浅后，豆道上方需至少留 0.5 mm，裙边需高于取盖台阶；空间不足时减小孔深或增大原盒高。若开启内壁文字，文字也必须能放进缩浅后的盒壁。
- 盖内立豆占用内面，与内面彩色图案不能同时开启；关闭“双面图案”即可保留正面图案。
- 新功能需要重新生成盒体和盖子，两件一起使用；尺寸验证不能代替实物试装。

## 1.3.0 更新

增加可选盖内立豆与联动高度、区域框选和孔位删除。实心眼睛/鼻子边界增加有位移限制的曲线拟合，保留白色缺口；3D 预览区分凹槽硬边与曲面光照，减少边缘断续的显示现象。已有模型文件不会随软件修改而自动更新，需要重新生成。


### 立豆预览缩放与取消框选

鼠标停在右侧平面预览框内，滚轮可围绕鼠标位置缩放（50%–800%），也可点加减按钮。按住鼠标右键或中键拖动可平移，点“适合窗口”恢复居中与 100%。缩放只影响显示，成品尺寸、孔位和模型保持原设置。

“取消框选”或 Esc 会退出框选模式，丢弃正在拖动但未完成的矩形，保留已完成的选区。要移除已经选中的区域，点“清空选区”；可以用“撤销盖内编辑”恢复。退出后要编辑单孔，请点“点击删除／恢复孔位”。


### 右栏跟随滚动

右栏顶部的“预览跟随滚动”默认开启：左侧下滚调参数时，右栏停留在屏幕内，右栏自身可以独立向下滚动查看 3D 模型和下载结果。在平面图内滚轮仍用于缩放；要滚动右栏，可把鼠标移到图外的标题或空白区域。关闭开关后恢复随整页滚动；选择会在本机浏览器中记住。窄屏上下排列时自动停用跟随。


### 内壁文字字体与导入

字体下拉列表读取服务器字体与当前账号已导入字体，常用中文字体放在前面。列表只显示服务器实际可读取的字体；不同服务器的数量可能不同。安装新字体后点“刷新字体列表”。输入文字后，下方图片使用与实际刻字相同的字体预览；无文字时显示 Abc 123。

点“导入字体…”选择 TTF、OTF 或 TTC 文件（不超过 32 MB），导入成功后会自动选中，可在“已导入字体”分组里再次选择。TTC 字体集合使用第一个字面。导入字体保存在当前账号的私有目录，其他账号不能读取；重启后保留。每账号最多 32 款、合计 128 MB。相同字体重复导入会复用文件。

部分英文字体不包含汉字。预览与生成前会检查文字，缺字时显示缺少哪些字符；请换字体或修改文字。预览只展示笔画样式，内壁位置、深度、字高仍按建模参数控制。


### 内壁文字朝向修正

内壁文字已补偿盒体最终打印朝向的反射，从盒子内部看为正常阅读方向。此前生成的镜像刻字模型需重新生成，旧 3MF 文件不会自动改变。