如何使用 3D2HOLO Desktop 中的 Raster 功能

Raster 功能到底做什么

在 3d2holo-desktop 里，当你把输出格式切换为 `FORMAT = ras` 时，应用会进入 raster 输出路径。它不再只是保存一个普通 PNG 或 TIFF，而是准备一个更适合交给 CUPS 队列处理的 raster 数据流。

当前桌面端代码里，raster 模式会暴露专门的打印字段，包括分辨率、raster 方向、打印机、纸张尺寸以及 X/Y 偏移量。真正提交打印时，原生 addon 会把文件交给 CUPS，并显式传入 `Resolution`、`PageSize`、`media` 和 `StpPrintingDirection=Unidirectional` 等选项。

目前 raster 模式暂时只直接支持 Epson L1800、Epson L1300 和 Epson P608 三款打印机。其他 Epson 打印机如果有 Gutenprint 驱动支持，也可以先在 3d2holo-desktop 里选择 Epson L1800 作为临时方案进行测试。

• 当你的流程最后一步是进入 CUPS 管理的真实打印过程，而不只是导出图片文件时，优先用 raster 模式。
• 当你希望在提交任务前，就把页面尺寸和物理摆放位置与打印机设置对齐时，适合用 raster 模式。
• 当你的 Epson 打印链路依赖 Gutenprint 驱动暴露出来的参数时，raster 模式最有价值。

1. 先安装 Gutenprint 和 CUPS

在 Debian/Ubuntu 系系统上，最直接的方式就是安装 CUPS 本体，再安装 Gutenprint 的 CUPS 驱动包。下面这些包名与当前 Debian/Ubuntu 风格系统中的包搜索结果一致。

1. 安装 `cups`、`cups-client`、`cups-daemon`，确保打印服务和队列管理工具可用。
2. 安装 `printer-driver-gutenprint`，让 Epson 打印机在 CUPS 中可选择 Gutenprint 驱动。
3. 启动或启用 CUPS 服务，然后打开 `http://localhost:631` 进入 CUPS Web 管理界面。

sudo apt update
sudo apt install cups cups-client cups-daemon printer-driver-gutenprint
sudo systemctl enable --now cups

安装完成后，先确认 CUPS 能看到打印队列，再确认 Gutenprint 驱动相关选项已经暴露出来。第二条命令尤其重要，因为它能直接列出当前队列真正支持的参数名。

lpstat -p -d
lpoptions -p YOUR_PRINTER_NAME -l | rg 'Resolution|PageSize|media|Stp'

2. 在 CUPS 中配置打印机参数

CUPS 决定了打印队列、默认纸张行为以及驱动层参数。一个比较稳妥的顺序是：先把打印机加进 CUPS，先打普通测试页确认队列正常，再回到 3d2holo-desktop 做 raster 输出。

1. 打开 `http://localhost:631`，进入 `Administration`，点击 `Add Printer`。
2. 选择你的 Epson 打印机，按提示认证，然后选择对应机型的 Gutenprint 驱动条目。
3. 队列创建完成后，打开该打印机页面，进入 `Set Default Options`。

具体参数请直接按照下面这些截图来设置。

3. 在 3d2holo-desktop 中使用 Raster 功能

当打印队列准备好后，应用内的使用路径就比较直接了。只有当输出格式切换为 `ras` 时，raster 相关控件才会显示；而只有导出的结果路径是 `.ras` 文件时，界面里的 `Print` 按钮才会出现。

1. 打开 2D、3D、Sketchfab 或 pitch-test 工作区，进入你想打印的结果所在流程。
2. 在 Output 区域把 `FORMAT` 切换为 `ras`。
3. 将 `RESOLUTION` 预设选择为 `5760*2880`。
4. 设置 `DIRECTION`。如果你当前测试的是常见的横向柱状透镜排布，可以先从 `horizontal` 开始，再通过小样打印确认方向。
5. 选择 `PRINTER` 和 `SIZE`，确保任务发往正确的 CUPS 队列，并且纸张格式一致。
6. 调整 `X OFFSET (IN)` 和 `Y OFFSET (IN)`，控制内容在纸面上的物理摆放位置。桌面端的布局预览就是为了让你在导出前先把 raster 矩形居中或微调。
7. 执行导出。如果结果被保存为 `.ras` 文件，桌面端界面就会显示 `Print` 按钮，可直接通过 CUPS 提交打印任务。
8. 提交后可以同时观察 CUPS 的活动队列和应用内的打印状态，确认任务是否真的进入了打印机队列。

最常见的排查点

• 如果应用提示没有可用打印机，先确认 CUPS 已设置默认打印机，或者你在 raster 的 `PRINTER` 字段中选中了正确的队列名。
• 如果打印位置不对，先检查 CUPS 里的 `PageSize` 和应用里的 `SIZE` 是否真的引用的是同一种纸张定义。
• 如果输出比例不对，检查应用里选择的 raster 分辨率预设，是否和 Gutenprint 队列中真正使用的分辨率一致。
• 如果介质行为异常，不要假设应用能覆盖所有 Gutenprint 参数，优先回到 CUPS 队列默认选项里确认 `media` 和相关纸张设置。