简介：这是基于Java实现的电子墨水屏相册项目源码包，面向对Java桌面开发与电子墨水屏应用感兴趣的开发者和在校学生；项目针对传统纸质相册不易保存、携带不便等痛点，结合电子墨水屏低功耗、类纸质显示的特点，利用Java跨平台与丰富类库，演示了相册浏览、触摸翻页等功能的完整实现思路，可作为课程设计或二次开发的参考工程。压缩包共23个文件，约13.21MB，包含7个Java源文件、9张示例图片，以及配置文件、构建脚本、启动脚本、说明文档、开源许可证等辅助文件，覆盖了项目运行所需的代码、资源和文档要素，便于直接阅读和运行调试；目前已有41人学习，适合初到中级Java开发者参考。通过学习这套源码，可掌握Java图形界面开发、多线程刷新、图片与文件处理、基于JSON的配置管理等方法，同时借鉴清晰的项目结构，快速搭建自己的电子墨水屏应用原型；源码附带启动脚本和说明文档，降低了上手门槛，兼顾学习与实用价值。
1. 电子墨水屏相册为什么选 Java 而不是 C
见过STM32上用C调墨水屏驱动的朋友都知道，改一版波形要重新烧录，调一次灰度要盯逻辑分析仪半天。等到要做一个真正能天天换照片的电子墨水屏相册时，我反而把语言换成了Java，跑在树莓派上。相册的复杂度不在底层刷新那几十毫秒，而在文件扫描、缩略图缓存、按键状态、突然断电后恢复显示这些琐碎逻辑，Java标准库处理这些东西比指针管理快一个数量级。
电子墨水屏平时不耗电、只在刷新瞬间才有明显电流，所以树莓派跑Java进程并不会造成续航危机。屏幕对外只是SPI设备，Java用Pi4J就能驱动，剩下的活基本是普通的多线程编程和IO操作。无论你是已经配好类路径的Java后端，还是刚看完Java基础、正被Java环境变量配置折腾到深夜的新手，用这套思路搭一台相册都可行。
这篇文章按我能复现的路线写：先解释墨水屏为什么不能像LCD那样一帧一帧刷新，再给一个可落地的Java GPIO驱动，接着处理JPEG到墨水屏灰度的转换算法，最后把相册的状态机和验证手段收在可测量、可排查的细节上。
2. 电子墨水屏相册的Java最小驱动：SPI引脚初始化与波形选择
2.1 电子墨水屏为什么不能直接刷一帧图片
墨水屏内部是胶囊状带电粒子，刷新过程需要施加一系列正负电压脉冲，让粒子完成“上浮-下沉”或“翻转到中间灰度态”。这套脉冲序列不是随意给的，每一帧都需要查波形查找表，对应到常见驱动芯片上就是一组LUT（Look-Up Table）寄存器。Java通过SPI总线把图片像素和LUT命令一起写进屏幕控制器的RAM。
全刷会先把整块屏打成黑或白，再写目标画面，残影最少，但一次需要1到3秒；局刷只改变指定区域的像素，通常几百毫秒就能完成，但如果频繁局刷，未刷新区域的电压残留会累积成永久性残影。相册的“翻页”仍建议全刷，只有时间、电量文字这类小面积区域才考虑局刷。
三类常见控制器的对比先放在这里，选屏或看驱动源码时便于对照：
| 控制器 | 常见分辨率 | 灰度级 | 刷新特点 | Java驱动要额外处理的坑 |
|---|---|---|---|---|
| SSD1681 | 200x200 | 4级 | 小屏，局刷效果好 | 行列映射是反的 |
| UC8253 | 800x480 | 4级 | 大屏，全刷波形多 | 需要外部LUT加载 |
| IT8951 | 任意面板 | 16级 | 内置加速引擎 | 用内存映射写图像，不走普通SPI命令 |
实现时，Java程序先要判断屏幕用的是哪类控制器。很多板子宣称“兼容七合一”，但Java驱动层不能只认型号，读ID命令返回的数值才是真正决定波形表的关键。
2.2 用Pi4J写一个能点亮的Java类
树莓派上做Java硬件驱动，我一般用Pi4J原生的SPI和GPIO通道，不引额外的native库。屏幕通常需要四根控制线：DC（数据/命令选择）、CS（片选）、RST（复位）、BUSY（忙状态），数据走SPI的MOSI。自定义片选的工作方式是：DC为低时SPI字节被解释成命令，DC为高时被解释成显示数据。
下面是初始化SPI、做复位脉冲的最小类，直接继承基础GPIO事件模型也可以，但先跑通亮屏更重要：
import com.pi4j.io.gpio.*; import com.pi4j.io.spi.SpiChannel; import com.pi4j.io.spi.SpiDevice; import com.pi4j.io.spi.SpiFactory; import com.pi4j.io.spi.SpiMode; import java.util.concurrent.TimeUnit; public class EinkSpi { // 杜邦线超过10cm时建议降到1MHz private static final int SPI_SPEED = 2_000_000; private final GpioPinDigitalOutput dc; private final GpioPinDigitalOutput rst; private GpioPinDigitalInput busy; private SpiDevice spi; public EinkSpi(GpioController gpio) { // 注意：RaspiPin.GPIO_17对应BCM17，不是物理引脚顺序 dc = gpio.provisionDigitalOutputPin(RaspiPin.GPIO_25, "DC"); rst = gpio.provisionDigitalOutputPin(RaspiPin.GPIO_17, "RST"); busy = gpio.provisionDigitalInputPin(RaspiPin.GPIO_24, "BUSY"); } public void open() throws Exception { spi = SpiFactory.getInstance(SpiChannel.CS0, SPI_SPEED, SpiMode.MODE_0); rst.high(); sleep(10); rst.low(); sleep(10); rst.high(); sleep(20); waitWhileBusy(1000); } private void sendCommand(byte cmd) throws Exception { dc.low(); spi.write(cmd); dc.high(); } private void sendData(byte[] data) throws Exception { dc.high(); spi.write(data); } private void waitWhileBusy(int timeoutMs) throws Exception { long start = System.currentTimeMillis(); // 多数屏忙时为低，但务必看模块原理图 while (!busy.isLow()) { if (System.currentTimeMillis() - start > timeoutMs) { throw new IllegalStateException("BUSY引脚超时，先查电平方向"); } sleep(1); } } private void sleep(int ms) throws InterruptedException { TimeUnit.MILLISECONDS.sleep(ms); } }这段代码里最容易被忽略的就是waitWhileBusy里的电平判断。同一家店的三种模块，BUSY脚可能一个高表示忙、一个低表示忙，写错屏幕会提前发下一帧命令，产生一整屏的杂块。RaspiPin.GPIO_25对应的是BCM 25，物理引脚的排列顺序完全无关，接线前用pinout命令核对。
2.3 波形表与全刷/局刷的Java参数
方波时序由驱动芯片决定，但Java层能控制的是“刷新模式和等待时间”。全刷前先写DRF（Display Refresh）命令，发送缓冲区的每个字节对应2或4个像素；局刷则要先把需要保留的区域锁存，否则会出现大面积“烧屏”效果。
这里给一个实用参数表格，适合写进application.properties或常量类：
| 场景 | 刷新模式 | BUSY等待 | 建议间隔 |
|---|---|---|---|
| 相册翻页 | FULL | 等待到低电平 | 3秒以上 |
| 电量/时钟 | PARTIAL | 可放宽超时 | 30秒一次 |
| 开机自检 | FULL两次，中间间隔200ms | 每次都要等待 | 仅上电 |
Java代码中不要把waitWhileBusy放进异步线程就撒手不管，一定要加超时。一旦SPI线上有毛刺，BUSY永远降不下来，相册就卡在重启循环里。超时后做一次重新上电复位，比打印堆栈更有价值。
3. 相册图片的灰度映射：从JPEG到墨水屏四位图的Java算法
3.1 灰度量化不是简单除4，先做色彩空间转换
电子墨水屏大多数只能显示4级或16级灰度，相册图片拿到后先要转成灰度。直接用BufferedImage.TYPE_BYTE_GRAY虽然快，但它按Gamma 0.5做线性变换，墨水屏实际上有偏白的底色，直接用标准灰度在屏上会显得非常脏。
推荐Java侧手动做加权灰度转换：
public static int[] toGray(BufferedImage src, int width, int height) { BufferedImage scaled = new BufferedImage(width, height, BufferedImage.TYPE_INT_RGB); var g2d = scaled.createGraphics(); // 用双三次插值比双线性更不容易产生水波纹 g2d.setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BICUBIC); g2d.drawImage(src, 0, 0, width, height, null); g2d.dispose(); int[] gray = new int[width * height]; int idx = 0; for (int y = 0; y < height; y++) { for (int x = 0; x < width; x++) { int rgb = scaled.getRGB(x, y); int r = (rgb >> 16) & 0xFF; int g = (rgb >> 8) & 0xFF; int b = rgb & 0xFF; // ITU-R BT.601加权：人眼对绿色更敏感 gray[idx++] = (int) (0.299 * r + 0.587 * g + 0.114 * b); } } return gray; }toGray里先缩放再灰度，是因为先灰度再缩放会让高频信息被插值抹掉，照片边缘会出现断点。800x480的屏，对4:3照片建议缩放到800x600再居中裁切，或者在缩放时保持宽高比，避免人物脸被拉宽。
3.2 用Floyd-Steinberg误差扩散替换固定阈值
灰度数组拿到后，如果简单分四档，照片天空会形成明显色块。正确做法是用误差扩散算法，把每个像素的量化误差传播到右侧和下方的邻域。Java实现时要注意像素值可能溢出，尤其在误差传播后需要clamp。
public static void floydSteinberg(int[] gray, int width, int height) { int levels = 4; int maxGray = 255; int step = maxGray / (levels - 1); // 85 int[] out = new int[width * height]; for (int y = 0; y < height; y++) { for (int x = 0; x < width; x++) { int oldVal = gray[y * width + x]; if (oldVal < 0) oldVal = 0; if (oldVal > 255) oldVal = 255; int newVal = Math.round(oldVal / (float) step) * step; out[y * width + x] = newVal; int err = oldVal - newVal; if (x + 1 < width) { gray[y * width + x + 1] += err * 7 / 16; } if (y + 1 < height) { int yNext = (y + 1) * width; if (x > 0) gray[yNext + x - 1] += err * 3 / 16; gray[yNext + x] += err * 5 / 16; if (x + 1 < width) gray[yNext + x + 1] += err * 1 / 16; } } } System.arraycopy(out, 0, gray, 0, gray.length); }这段算法的关键参数是step = 85，它把0-255分成0、85、170、255四档。newVal必须要和out数组的值一致，不能直接改原数组，否则后面的误差传播已经被二次量化污染。误差系数7/16、5/16、3/16、1/16是Floyd-Steinberg的标准权重，适合照片；如果处理的是黑白漫画书扫描件，Bayer矩阵反而更能保留线条。
实际渲染前，还要做一步“黑白映射”，也就是把深色像素往0偏移、浅色像素往255偏移。墨水屏底色偏蓝灰，用newVal = (int)(newVal * 0.95)反而让白色区域更接近纸张效果。
3.3 缩放参数与摩尔纹的取舍
图像原始分辨率高于屏幕时，直接抽点会产生摩尔纹。除了代码里的KEY_INTERPOLATION_BICUBIC，还要控制缩放的目标尺寸：800x480的屏，目标输出宽度最好是800，高度480；但相机照片比例通常是3:2，硬压成8:3会损失构图信息。
常见做法是先按宽高比缩放到短边匹配屏幕，再在屏幕左右各留一列黑边或直接用灰度值128填充。Java侧用BufferedImage的drawImage一次完成，但要注意setRenderingHint对灰度图无效，必须在RGB模式下缩放，否则锯齿会全部保留下来。
算法对比表格值得存一份：
| 算法 | 照片观感 | 耗时（800x480） | 适合场景 |
|---|---|---|---|
| 固定阈值 | 色块严重 | 10ms | 文本扫描件 |
| Bayer抖动 | 有颗粒感 | 20ms | 图表、天气图标 |
| Floyd-Steinberg | 接近报纸印刷 | 120ms | 人物照片 |
耗时是在树莓派Zero 2W上测的，如果跑在树莓派4上可以再用一个线程池缓存结果，不用每次翻页都重新算。
4. 相册核心逻辑：本地文件索引、线程池与刷屏状态机
4.1 用Java文件扫描做启动预览
相册机最重要的是“开机后隔几秒就能看到照片”。在Java里用Files.list扫描一个相册目录，过滤图片后缀，排序后把路径加载进内存。普通外接U盘有上千张照片时，直接在UI层面遍历会卡死。
public List<Path> loadPhotoPaths(Path dir) throws IOException { try (var stream = Files.list(dir)) { return stream .filter(Files::isRegularFile) .filter(p -> { String name = p.getFileName().toString().toLowerCase(); return name.endsWith(".jpg") || name.endsWith(".png") || name.endsWith(".webp"); }) .sorted(Comparator.comparing(p -> p.getFileName().toString())) .collect(Collectors.toList()); } }注意sorted这里用的是字典序，中文文件名会出现“10.jpg”排在“2.jpg”前面的问题。相册目录我一般建议重命名成“IMG_0001.jpg”这类前缀模式，或者在Java里用Collator.getInstance(Locale.CHINESE)做自然排序。
扫描结果可以直接作为幻灯片顺序，但不要每次都重新扫描。用ConcurrentHashMap存一份Path -> List<Path>，在启动线程里预热，翻页时只读缓存。
4.2 线程池把图片转换和屏幕刷新分开
Java的BufferedImage加载和抖动计算都吃CPU，直接在翻页回调里做会让系统按键响应变成“哑巴”。至少拆两个线程：IO线程负责磁盘读取，渲染线程负责灰度转换和刷新。下面这段代码用固定线程池保护刷新操作：
public class EinkPlayer { private final ExecutorService renderExecutor = Executors.newSingleThreadExecutor(r -> { Thread t = new Thread(r, "epd-render"); t.setDaemon(true); return t; }); private final Semaphore screenLock = new Semaphore(1); public void showNext(Path photo) { renderExecutor.execute(() -> { try { BufferedImage epdImage = convert(photo); screenLock.acquire(); try { eink.display(epdImage, RefreshMode.FULL); } finally { screenLock.release(); } } catch (Exception ex) { // 打印错误后保留上一帧，不要在屏上显示异常信息 System.err.printf("render fail: %s%n", ex.toString()); } }); } }Semaphore的作用是保证两次刷新不会并发执行。墨水屏不像LCD，并发写SPI总线会让画面出现随机条纹，而且大部分驱动芯片不支持重入。渲染线程必须是“单线程+信号量”的组合，如果只提交到CachedThreadPool，一旦翻页速度大于刷新速度，SPI缓冲区就会混入两帧数据。
4.3 状态机能避免一半的残影问题
相册翻页看起来简单，实际有两种操作：下一张和上一张；屏幕状态又分为空闲、等待图片读取、刷新中。没有状态机时，连续快速按两下按键，第一帧还没刷完就被第二帧打断，结果就是屏幕上并排显示两张照片的区域。
我通常用一个EnumSet记录当前状态，而不是直接用AtomicBoolean：
| 当前状态 | 事件 | 下一状态 | 屏幕动作 |
|---|---|---|---|
| IDLE | 按键下一张 | WAIT_LOADING | 禁用按键，加载图片 |
| WAIT_LOADING | 图片加载完成 | REFRESHING | 发送全刷命令 |
| REFRESHING | BUSY低电平 | IDLE | 允许下一次按键 |
| REFRESHING | 超时 | IDLE | 恢复相册，不重启进程 |
在代码里做状态流转时，按键消抖要放在IDLE状态之前：
enum State { IDLE, WAIT_LOADING, REFRESHING } State state = State.IDLE; // 防抖：100ms内的第二次按键直接忽略，避免一次抖动触发两帧这个100ms很有讲究。机械按键抖动通常小于20ms，但人手快速连击可以到70ms，取值100ms能用物理手感挡住连续误触，又不会让熟练用户觉得按键迟钝。
4.4 图片渲染前后的清理
已经交给eink.display的BufferedImage在刷新完成后要及时释放，否则一张12MB的照片在堆里累积，老年代GC一触发，翻页就会卡上1秒。做法是在刷新成功后调用image.flush()并清掉缩略图缓存；如果相册机内存只有1GB，可把缓存大小限制在30张以下。
这里常被Java八股文里的集合知识误导：HashMap和ArrayList放照片路径没问题，但放BufferedImage时要考虑堆外内存，因为TYPE_INT_RGB的像素缓冲可能直接分配在DirectBuffer里，普通回收拿不到。用ByteBuffer.allocateDirect配合一个固定大小LRU缓存更稳。
5. 相册上线前的三个验证手段：功耗、残影与异常刷新排查
5.1 用运行时日志测刷新时长
加一行日志统计刷新耗时，是判断波形参数合不合适的直接方法。代码里在eink.display前后记录System.nanoTime()，并对全刷和局刷分别输出平均值：
java -jar eink-photo.jar | grep REFRESH日志里如果全刷耗时从1800ms缓慢涨到2100ms，说明屏幕老化了；如果局刷耗时波动超过50%，优先查肖特基二极管和电容，而不是改代码。真正投产时，把日志级别调到INFO，收集最近100次刷新的分位数，残影不是一次刷新能测出来的。
5.2 残影检测用灰度梯度图而不是纯色图
用纯黑纯白测试残影太乐观。我会生成一张灰度梯度图，从左到右依次是0、85、170、255四个灰度带，先全刷一次，再局刷一个小的移动进度条，最后全刷梯度图。如果原来进度条位置的灰度明显偏淡，且要刷两三次才能消除，那就要把局刷的BUSY等待时间加长30%。
检测过程可以写成一个独立的Java命令：java -jar test-gradient.jar，它不会修改相册配置，只输出“PASS/FAIL”结论。
5.3 断电恢复时从缓存路径重建当前页
相册被拔电是常态。验证时不要只按电源键重启，要直接拔USB线。启动恢复阶段如果发现本地缓存里记录着“最后显示的照片索引”，先显示一张白色清洗页再显示该照片。这里有个小技巧：显示白页时不要用全刷灰度255，用0xF0F0的块填充，因为整屏纯白会暴露残影，杂色块反而看不出脏污。
最后别忘了把波形参数表从代码里移到src/main/resources/waveforms.json，这样调参数不需要重编译，直接改JSON文件就能让Java程序在启动时加载。相册交付给朋友维护时，这个文件就是他唯一需要动的部分。
本文还有配套的精品资源，点击获取
