电子纸-图像-转换

将图像转换为电子纸张显示,并配有高级音调映射、去色调和色调优化.

特征

• 高级色调映射 - S-曲线和以对比为基础的声调绘图,以优化电子纸张显示
• 扩散分配出错 - Floyd - Steinberg、斯图克、伯克和塞拉算法
• 动态范围压缩 - 自动压缩图像,以匹配显示的实际亮度范围
• 彩色调色板支持 - 内置预设和自定义调色板支持,并配有理论/感知对
• EXIF 方向 - 自动 EXIF 定向处理
• CLI和图书馆 - 从命令行或用作节点.js库

安装

npm install epaper-image-convert

或在全球安装供CLI使用:

npm install -g epaper-image-convert

CLI 使用量

基本用途

# 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

处理预设

# 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

自定义处理参数

# 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

调色板选项

# 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 相片阵列 出口 其从网络用户界面设置( E)设置 维护 配置备份 导出配置) (中文(简体) ). 将 CLI 指向该文件以转换该框架 不重制校正:

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。 。 。 .

生成缩略图

# 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

输出格式

# 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 <WxH>               Display dimension (e.g., 800x480)
                                      (default: "800x480")
  -f, --format <format>               Output format: epdgz, png, or bmp
                                      (default: "epdgz")
  --palette-preset <name>             Palette preset: spectra6, grayscale16,
                                      default (default: "spectra6")
  --palette <json>                    Custom palette JSON (overrides
                                      --palette-preset)
  --device-config <file>              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 <Y>                  GC16 grayscale: measured relative
                                      luminance (0..1) of full black
  --gray-white-y <Y>                  GC16 grayscale: measured relative
                                      luminance (0..1) of full white
  --gray-gamma <g>                    GC16 grayscale: mid-level gamma (1 =
                                      linear in L*, >1 darkens mids)
  -p, --processing-preset <name>      Processing preset: balanced, dynamic,
                                      vivid, soft, grayscale (default:
                                      "balanced")
  --exposure <value>                  Exposure multiplier (0.5-2.0)
  --saturation <value>                Saturation multiplier (0.5-2.0)
  --contrast <value>                  Contrast multiplier (0.5-2.0)
  --tone-mode <mode>                  Tone mapping mode: scurve or contrast
  --scurve-strength <value>           S-curve overall strength (0.0-1.0)
  --scurve-shadow <value>             S-curve shadow boost (0.0-1.0)
  --scurve-highlight <value>          S-curve highlight compress (0.5-5.0)
  --scurve-midpoint <value>           S-curve midpoint (0.3-0.7)
  --color-method <method>             Color matching: rgb or lab
  --dither-algorithm <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 <mode>                Display orientation: landscape or portrait
                                      (default: native)
  --scale-mode <mode>                 Scale mode: cover (crop to fill) or fit
                                      (letterbox) (default: "cover")
  --background-color <name>           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 <path>              Generate thumbnail and save to path
  --thumbnail-max-dimension <pixels>  Maximum thumbnail dimension (longest side)
                                      (default: "400")
  -v, --verbose                       Enable verbose output
  -h, --help                          display help for command

图书馆的使用

基本转换

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);

高级使用

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);

自定义调色板

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)-更暗,饱和度更低的红色.

分色算法使用感知调色板 做出准确的颜色匹配决定。 当决定哪种调色板颜色最能代表像素时,我们比较哪种颜色 其实看起来像 在显示,不是我们告诉显示.

输出图像使用理论调色板 因为设备固件就是这么理解的 显示驱动程序将这些理论值映射到适当的墨水颜色.

这种分离使得去色算法能够产生视觉上准确的结果,同时保持与设备预期的输入格式相容.

关于显示使用感知调色板对理论调色板的影响的可视化比较,见 图像质量比较 在ESP32 PhotoFrame项目中.

{
  "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 }
  }
}

处理预设

支助

如果你觉得这个项目有用,就请我喝杯咖啡吧

许可证

麻省理工学院

贷项

联合国 ESP32 相片阵列 项目.