# @aitjcize/epaper-image-convert 中文文档 规范地址：https://npmcn.com/package/%40aitjcize/epaper-image-convert/ 版本：0\.1\.21 npm 元数据更新时间：2026-10-04T22:44:03.493Z 中文译文更新时间：2026-11-06T00:47:44.326Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40aitjcize/epaper-image-convert 原文对照：https://npmcn.com/package/%40aitjcize/epaper-image-convert/?lang=original 项目主页：https://github.com/aitjcize/epaper-image-convert#readme 源码仓库：https://github.com/aitjcize/epaper-image-convert ## 关键信息（来自 npm 元数据） - 包体积（解压后）：105 kB，9 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：\>=18\.0\.0 - 运行依赖：2 个 - 首次发布：2026-01-27T11:14:07.852Z - 最新版本发布：2026-10-04T22:44:03.343Z - 近 30 天下载量：7845（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：21（近 12 个月 21 个） ## 中文简介 将图像转换为电子纸张显示, 并使用高级调色图、 抖动和色调优化 ## 安装 ```sh npm install @aitjcize/epaper-image-convert ``` 也可以使用：`pnpm add @aitjcize/epaper-image-convert`、`yarn add @aitjcize/epaper-image-convert`、`bun add @aitjcize/epaper-image-convert` ## README # 电子纸-图像-转换 将图像转换为电子纸张显示,并配有高级音调映射、去色调和色调优化. ## 特征 - **高级色调映射** - S-曲线和以对比为基础的声调绘图,以优化电子纸张显示 - **扩散分配出错** - Floyd - Steinberg、斯图克、伯克和塞拉算法 - **动态范围压缩** - 自动压缩图像,以匹配显示的实际亮度范围 - **彩色调色板支持** - 内置预设和自定义调色板支持,并配有理论/感知对 - **EXIF 方向** - 自动 EXIF 定向处理 - **CLI和图书馆** - 从命令行或用作节点.js库 ## 安装 ```bash npm install epaper-image-convert ``` 或在全球安装供CLI使用: ```bash npm install -g epaper-image-convert ``` ## CLI 使用量 ### 基本用途 ```bash # Convert a single image epaper-image-convert input.jpg output.png # Convert with specific display dimensions epaper-image-convert input.jpg -d 640x384 # Convert all images in a directory epaper-image-convert ./photos ./converted ``` ### 处理预设 ```bash # List all available presets epaper-image-convert -l # Use Balanced preset - default, produces the most balanced result epaper-image-convert input.jpg -p balanced # Use Dynamic preset - enhanced contrast, vibrant colors epaper-image-convert input.jpg -p dynamic # Use Vivid preset - boosted colors for illustrations epaper-image-convert input.jpg -p vivid # Available presets: balanced, dynamic, vivid, soft, grayscale ``` ### 自定义处理参数 ```bash # Adjust exposure and saturation epaper-image-convert input.jpg --exposure 1.2 --saturation 1.4 # Use S-curve tone mapping with custom parameters epaper-image-convert input.jpg --tone-mode scurve \ --scurve-strength 0.8 \ --scurve-shadow 0.1 \ --scurve-highlight 1.5 # Use LAB color space for better grayscale matching epaper-image-convert input.jpg --color-method lab # Change dithering algorithm epaper-image-convert input.jpg --dither-algorithm stucki ``` ### 调色板选项 ```bash # Use built-in palette preset epaper-image-convert input.jpg --palette-preset spectra6 # Use custom palette (JSON format) epaper-image-convert input.jpg --palette '{ "theoretical": { "black": {"r": 0, "g": 0, "b": 0}, "white": {"r": 255, "g": 255, "b": 255}, "yellow": {"r": 255, "g": 255, "b": 0}, "red": {"r": 255, "g": 0, "b": 0}, "blue": {"r": 0, "g": 0, "b": 255}, "green": {"r": 0, "g": 255, "b": 0} }, "perceived": { "black": {"r": 5, "g": 5, "b": 5}, "white": {"r": 200, "g": 200, "b": 195}, "yellow": {"r": 210, "g": 200, "b": 10}, "red": {"r": 180, "g": 35, "b": 25}, "blue": {"r": 20, "g": 70, "b": 160}, "green": {"r": 45, "g": 120, "b": 70} } }' ``` ### ESP32 相片Frame 设备配置 一个 [ESP32 相片阵列](https://github.com/aitjcize/esp32-photoframe) 出口 其从网络用户界面设置( E)**设置 维护 配置备份 导出配置**) (中文(简体) ). 将 CLI 指向该文件以转换该框架 不重制校正: ```bash epaper-image-convert input.jpg output.epdgz --device-config living-room-config.json ``` 文件提供默认值 : - `palette` • 面板的可感知颜色 光谱 6 理论调色板,或在 GC16 面板上测量出亮度 灰度斜坡的终点来自 - `processing` + 处理参数(取代 `-p`)加上 `--scale-mode` 编号 : `--background-color` 版式 - `config.display_orientation` → `--orientation` - `system_info` • 面板大小(`-d`旧的固件没有出口, 所以通过 `-d WxH` 这些 命令线上明确给出的任何东西仍然胜利: `-d`, (中文(简体) ), `-p`, (中文(简体) ), `--exposure` 朋友们, `--scale-mode`, (中文(简体) ), `--orientation`,以及 `--gray-*` (它一次推翻文件的终点). `--palette` 或一个 明确 `--palette-preset` 完全替换文件的调色板. 相同的文件与框架的自有关系 `photoframe-process --device-config`。 。 。 . ### 生成缩略图 ```bash # Generate thumbnail alongside output epaper-image-convert input.jpg output.png -t output_thumb.jpg # Custom thumbnail dimensions epaper-image-convert input.jpg output.png -t thumb.jpg --thumbnail-dimension 200x120 ``` ### 输出格式 ```bash # Output as PNG (default) epaper-image-convert input.jpg output.png # Output as BMP epaper-image-convert input.jpg output.bmp -f bmp # Format is auto-detected when output is a directory epaper-image-convert input.jpg /tmp -f bmp # Creates /tmp/input.bmp ``` ### 所有选项 ``` Options: -V, --version output the version number -l, --list-presets List available presets and exit -d, --dimension Display dimension (e.g., 800x480) (default: "800x480") -f, --format Output format: epdgz, png, or bmp (default: "epdgz") --palette-preset Palette preset: spectra6, grayscale16, default (default: "spectra6") --palette Custom palette JSON (overrides --palette-preset) --device-config Config exported from an ESP32 PhotoFrame's web UI (Maintenance > Config Backup > Export Config): its palette, processing settings, orientation and panel size become the defaults; explicit flags (-d, -p, --exposure, --gray-*, ...) still win, and --palette or --palette-preset replaces its palette --gray-black-y GC16 grayscale: measured relative luminance (0..1) of full black --gray-white-y GC16 grayscale: measured relative luminance (0..1) of full white --gray-gamma GC16 grayscale: mid-level gamma (1 = linear in L*, >1 darkens mids) -p, --processing-preset Processing preset: balanced, dynamic, vivid, soft, grayscale (default: "balanced") --exposure Exposure multiplier (0.5-2.0) --saturation Saturation multiplier (0.5-2.0) --contrast Contrast multiplier (0.5-2.0) --tone-mode Tone mapping mode: scurve or contrast --scurve-strength S-curve overall strength (0.0-1.0) --scurve-shadow S-curve shadow boost (0.0-1.0) --scurve-highlight S-curve highlight compress (0.5-5.0) --scurve-midpoint S-curve midpoint (0.3-0.7) --color-method Color matching: rgb or lab --dither-algorithm Dithering algorithm: floyd-steinberg, stucki, burkes, or sierra --compress-dynamic-range Compress dynamic range to display range --no-compress-dynamic-range Disable dynamic range compression --orientation Display orientation: landscape or portrait (default: native) --scale-mode Scale mode: cover (crop to fill) or fit (letterbox) (default: "cover") --background-color Background palette color for fit mode (black, white, etc.) (default: "white") --skip-dithering Skip dithering step --use-perceived-output Use perceived palette for output (for preview) -t, --thumbnail Generate thumbnail and save to path --thumbnail-max-dimension Maximum thumbnail dimension (longest side) (default: "400") -v, --verbose Enable verbose output -h, --help display help for command ``` ## 图书馆的使用 ### 基本转换 ```javascript import { convertImage } from 'epaper-image-convert'; const { canvas, buffer } = await convertImage('input.jpg', { width: 800, height: 480, processingPreset: 'balanced', verbose: true, }); // buffer is a PNG Buffer ready to write or send to device fs.writeFileSync('output.png', buffer); ``` ### 高级使用 ```javascript import { processImage, applyExifOrientation, createPNG, getPreset, getPalette, SPECTRA6, } from 'epaper-image-convert'; import { createCanvas, loadImage } from 'canvas'; // Load image const image = await loadImage('input.jpg'); const sourceCanvas = createCanvas(image.width, image.height); sourceCanvas.getContext('2d').drawImage(image, 0, 0); // Process with custom options const { canvas, originalCanvas } = processImage(sourceCanvas, { displayWidth: 800, displayHeight: 480, palette: SPECTRA6, params: { ...getPreset('dynamic'), exposure: 1.1, saturation: 1.4, }, skipRotation: false, verbose: true, createCanvas, }); // Convert to PNG const pngBuffer = await createPNG(canvas); ``` ### 自定义调色板 ```javascript import { processImage, validatePalette } from 'epaper-image-convert'; const customPalette = { theoretical: { black: { r: 0, g: 0, b: 0 }, white: { r: 255, g: 255, b: 255 }, yellow: { r: 255, g: 255, b: 0 }, red: { r: 255, g: 0, b: 0 }, blue: { r: 0, g: 0, b: 255 }, green: { r: 0, g: 255, b: 0 }, }, perceived: { black: { r: 10, g: 10, b: 10 }, white: { r: 220, g: 215, b: 210 }, yellow: { r: 200, g: 190, b: 20 }, red: { r: 170, g: 40, b: 30 }, blue: { r: 30, g: 80, b: 150 }, green: { r: 50, g: 110, b: 65 }, }, }; // Validate palette format validatePalette(customPalette); // Use in processing const { canvas } = processImage(sourceCanvas, { displayWidth: 800, displayHeight: 480, palette: customPalette, }); ``` ## 调色板格式 调色板成一对 `theoretical` 财务报告和审定财务报表 `perceived`数字 : - **理论**:电子纸显示驱动程序所期望的理想RGB值. 这些是写入设备固件将解释的输出图像的值 . - **感觉**:测量或观察物理显示时显示的实际RGB颜色。 电子纸上显示有有限的彩色游戏-"白色"经常是灰色的,"红色"看起来比较哑等. ### 为什么是两个调色板? 电子纸的显示不准确复制出颜色. 例如,当将"纯红"(255,0,0)发送到Spectra 6显示器时,实际出现的颜色可能更接近(135,19,0)-更暗,饱和度更低的红色. **分色算法使用感知调色板** 做出准确的颜色匹配决定。 当决定哪种调色板颜色最能代表像素时,我们比较哪种颜色 _其实看起来像_ 在显示,不是我们告诉显示. **输出图像使用理论调色板** 因为设备固件就是这么理解的 显示驱动程序将这些理论值映射到适当的墨水颜色. 这种分离使得去色算法能够产生视觉上准确的结果,同时保持与设备预期的输入格式相容. 关于显示使用感知调色板对理论调色板的影响的可视化比较,见 [图像质量比较](https://github.com/aitjcize/esp32-photoframe?tab=readme-ov-file#image-quality-comparison) 在ESP32 PhotoFrame项目中. ```json { "theoretical": { "black": { "r": 0, "g": 0, "b": 0 }, "white": { "r": 255, "g": 255, "b": 255 }, "yellow": { "r": 255, "g": 255, "b": 0 }, "red": { "r": 255, "g": 0, "b": 0 }, "blue": { "r": 0, "g": 0, "b": 255 }, "green": { "r": 0, "g": 255, "b": 0 } }, "perceived": { "black": { "r": 2, "g": 2, "b": 2 }, "white": { "r": 190, "g": 190, "b": 190 }, "yellow": { "r": 205, "g": 202, "b": 0 }, "red": { "r": 135, "g": 19, "b": 0 }, "blue": { "r": 5, "g": 64, "b": 158 }, "green": { "r": 39, "g": 102, "b": 60 } } } ``` ## 处理预设 | 预设 | 说明 | 最佳服务 | | --- | --- | --- | | `balanced` | 压缩动态范围( 默认) | 一般用途,防止过度接触 | | `dynamic` | S- Curve 语气映射 | 动态范围好的照片 | | `vivid` | 高饱和度 | 彩色图像、插图 | | `soft` | 低对比度 | 细梯度 | | `grayscale` | LAB 颜色空间 | B&W 相片,文档 | ## 支助 如果你觉得这个项目有用,就请我喝杯咖啡吧 [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-ffdd00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/aitjcize) ## 许可证 麻省理工学院 ## 贷项 联合国 [ESP32 相片阵列](https://github.com/aitjcize/esp32-photoframe) 项目. ## 常见问题 ### @aitjcize/epaper-image-convert 是什么？ 将图像转换为电子纸张显示, 并使用高级调色图、 抖动和色调优化 ### 如何安装 @aitjcize/epaper-image-convert？ 在项目目录运行 npm install @aitjcize/epaper-image-convert，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 epaper-image-convert，可以用 npx epaper-image-convert 直接运行。 ### @aitjcize/epaper-image-convert 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/aitjcize\_\_epaper-image-convert 是否存在。 ### @aitjcize/epaper-image-convert 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @aitjcize/epaper-image-convert 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @aitjcize/epaper-image-convert 可以商用吗？ @aitjcize/epaper-image-convert 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @aitjcize/epaper-image-convert 的下载量有多少？ 根据 npm 官方下载统计，@aitjcize/epaper-image-convert 在 2026/10/05 – 2026/11/03 这 30 天内被下载 7,845 次，日均约 262 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @aitjcize/epaper-image-convert 还在维护吗？ 最新版本 0\.1\.21 发布于 2026/10/05（1 个月前）；至今共发布 21 个版本，其中过去 12 个月发布了 21 个；首次发布于 2026/01/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。