竭力互动素描系统现场操作教程（自动流程主线版）
硬件安装教程：
一、部署前准备
在正式出图前，请先确认以下内容：
- 操作系统：Windows 10 / 11
- 硬件：Rotrics DexArm 机械臂 + 画笔模块 + USB 串口连接
- 建议部署环境：全屏触摸一体机或带触摸显示器的 Windows 设备
- 纸张已经固定，画笔已经安装完成，机械臂活动范围无遮挡
如果是开发环境运行，可先安装依赖：
pip install customtkinter opencv-python-headless pyserial scikit-image numpy scipy Pillow python-docx如果现场直接使用绿色版，通常只需要解压后双击 EXE 即可运行。
二、软件启动后的主界面
软件启动后会进入主界面：
- 左侧：图片预览区
- 右侧：任务历史 / 队列区
- 底部：开始、暂停、停止、设置按钮
- 顶部：API 状态和机械臂连接状态
图 1 软件主界面
三、首次配置：先在设置页完成基础联调
点击主界面右下角“设置”后，会打开设置抽屉。首次部署建议按以下顺序检查：
- 连接设置
- 笔控制
- 画幅设置
- 自动获取
- 高级设置
3.1 设置页上半部分
图 2-1 设置页上半部分
3.2 设置页中下半部分
图 2-2 设置页中下半部分
3.3 高级设置区域
图 2-3 高级设置区域
四、连接机械臂
- 在“连接设置”里点击“检测”
- 从串口下拉框里选择正确的 COM 口
- 点击“连接”
- 连接成功后，按钮会切换为“断连”，日志里会看到初始化完成信息
图 3 机械臂连接成功后的设置界面
如果连接失败，请优先检查：
- USB 数据线是否连接正常
- 串口是否被其他软件占用
- 设备管理器里是否能看到对应 COM 口
五、首次校准：画笔高度与画幅参数
连接成功后，先调画笔高度，再调画布尺寸和中心坐标。这个步骤决定了落笔深浅、绘画范围和落点位置。
- 落笔高度 Z：决定是否能正常画线
- 抬笔高度 Z：决定移动时是否离纸
- 画布宽 / 高：决定绘制尺寸范围
- 中心 X / Y：决定画面落点位置
建议通过“测试落笔 / 测试抬笔 / 移到中心”反复验证。
图 4 参数设置完成后的参考状态
提示：首次部署建议先用手动模式试一张测试图，确认笔压和中心位置无误后，再切到自动流程正式运行。
六、正式使用主线：自动流程
现场正式出图建议以自动流程为主。自动流程的核心是：
设置接收目录 → 开启自动模式 → 图片进入队列 → 连续绘制 → 完成图归档
6.1 自动流程的三个图片来源
- 自动获取：从本地“获取图片路径”读取图片，是最基础、最常用的现场流程
- API 接收：外部设备通过 HTTP 把图片传给软件，软件会把图片保存到“获取图片路径”，再进入同一套自动流程
- 服务器取图：软件定时从接口拉取图片，下载到“获取图片路径”后，再进入同一套自动流程
- 图片可以从不同入口进来
- 但后面的排队、开始绘画、继续下一张、归档逻辑都是同一套
6.2 自动获取设置
在“自动获取”区域设置：
- 获取图片路径：待绘图片放入这里
- 完成图片路径：绘画完成后的图片归档到这里
图 5 自动获取路径设置完成
6.3 开启自动模式
勾选“启用自动模式”后，状态应变为“监视中”。
图 6 自动模式已开启后的状态
6.4 API 接收和服务器取图如何配合自动流程
如果现场接了拍照机、上位机或后台系统，可以按需启用下面两种入口：
- API 接收：外部系统把图片直接推送给本软件
- 服务器取图：软件定时去后台接口拉图
这两种方式拿到图片后，仍然会把图片放进“获取图片路径”或同一待绘队列里，后续还是走自动流程。
- 自动获取 = 本地文件夹入口
- API 接收 = 外部推送入口
- 服务器取图 = 后台拉取入口
- 后续执行流程一致
6.5 队列与绘画执行
图片进入系统后，会先进入右侧任务队列。点击“开始”后，软件会按队列顺序开始绘画。
图 7 自动模式下队列里已有等待中任务
绘画运行时，可以观察：
- 当前预览图
- 当前进度条
- 当前队列状态
- 正在绘画 / 等待中 / 已完成 等状态
图 8 自动流程正在绘画中的界面
6.6 是否继续下一张
当前一张图绘完后，软件会弹出“是否开始绘画下一张”的提示框。
图 9 自动流程中“是否继续下一张”弹窗
- 继续下一张
- 暂停后续任务
6.7 完成图归档
绘画完成后，图片会从接收目录移到完成目录，方便归档和后续核对。
图 10 自动流程完成后的归档结果
提示：自动流程是现场正式运行的主线；如果只是调参数、试笔压、试中心位置，优先用手动模式先测一张。
七、手动模式：用于调试和快速测试
- 首次部署
- 参数联调
- 测试单张图片
- 确认笔压和中心位置是否正确
7.1 打开测试图
在设置页“操作”区域点击“打开图片”，选择一张测试图。软件会自动完成图像处理、路径生成与 G-code 输出。
图 11 手动模式下打开图片并处理完成后的界面
7.2 开始测试绘画
确认图片正常、参数无误后，点击主界面左下角“开始”。绘画过程中观察轨迹、进度条和日志，确认笔压与画面位置是否正确。
图 12 手动模式绘画进行中的界面
八、任务队列、暂停与停止
- 当前任务
- 已完成任务
- 等待中的任务
常用操作包括：
- 暂停：临时中断绘画，调整后可继续
- 停止：中止当前任务
- 重画：重新输出某一张历史任务
- 插队：调整任务优先级
- 删除：从队列中移除任务
图 13 任务历史 / 队列界面示意
停止当前任务时，软件会弹出确认框：
图 14 停止绘画时的确认弹窗
九、扩展模式
- 自动获取：监听本地文件夹，新图片进入后自动加入任务队列
- API 接收：外部设备通过 HTTP 接口把图片推送到本机
- 服务器取图：软件定时从接口拉取图片并加入队列
建议顺序：
- 先把手动模式跑通
- 再把自动模式跑通
- 最后接入 API 或服务器取图
十、现场常见问题
1）点开始后没有反应
- 是否已经连接机械臂
- 是否已有待绘图片
- 是否已经打开测试图并处理完成
2）画不出来或压得太重
- 落笔高度 Z
- 抬笔高度 Z
3）画面偏移或超出纸张
- 画布宽 / 高
- 中心 X / Y
4）自动模式不出图
- 接收目录是否正确
- 自动模式是否已启用
- 队列里是否已经有任务
5）API 接收或服务器取图不工作
- 获取图片路径是否已配置
- 监听地址和端口是否正确
- 取图地址、响应地址是否正确
- 网络是否可达
6）停止后不确定是否继续
查看右侧任务历史，必要时使用“重画”重新出图。
7）软件异常退出后参数会不会丢
软件会自动保存设置到 settings.json，并保留 .bak 备份。
十一、关键参数速查表
| 项目 | 说明 | 建议 |
|---|---|---|
| 落笔高度 Z | 决定是否能正常画线 | 根据纸张和画笔实际调试 |
| 抬笔高度 Z | 决定移动时是否离纸 | 通常高于落笔高度 |
| 画布宽 / 高 | 决定绘制尺寸范围 | 按实际纸张填写 |
| 中心 X / Y | 决定画面落点位置 | 先用测试图确认 |
| 绘画速度 | 影响绘画时长与稳定性 | 现场先保守后微调 |
| 命令缓冲 | 影响串口流式发送 | 默认 8，一般不建议随意改小 |