img2lcd 中文说明

img2lcd 是一个独立的命令行工具，用来把图片转换成适合 LCD / OLED / 单色屏 / 嵌入式项目使用的字节数组，也支持把字节数组反解回图片。

它基于 image2cpp 的功能模型做了 CLI 化包装，源码采用标准 src/img2lcd 布局，支持单次命令、REPL 交互模式、JSON 输出和会话配置持久化。

安装说明

环境要求

Python 3.8+
pip

AI Skill 兼容性

当前仓库已经同时包含三套可直接识别的 skill / plugin 入口：

Codex: skills/img2lcd
Claude Code 项目技能: .claude/skills/img2lcd
Claude Code 插件: .claude-plugin/plugin.json + skills/img2lcd
Cursor 项目技能: .cursor/skills/img2lcd
Cursor 项目规则: .cursor/rules/img2lcd-skill.mdc

安装命令

在项目根目录执行：

cd /home/leo/work/open-git/pix_cli/img2lcd
python3 -m pip install -e .

安装完成后可用命令：

cli-anything-img2lcd --version
cli-anything-img2lcd --help

安装为 Codex Skill

仓库内已经包含标准 skill 目录：

skills/img2lcd

发布到 GitHub 后，可直接按仓库路径安装：

python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo <owner>/<repo> \
  --path skills/img2lcd

安装完成后重启 Codex。

skill 安装后既可以直接使用内置 runner，也可以先执行：

python3 "${CODEX_HOME:-$HOME/.codex}/skills/img2lcd/scripts/bootstrap_cli.py"

这样会把 cli-anything-img2lcd 命令安装到当前 Python 环境，后续在 skill 外也能直接调用。

安装为 Claude Code Skill / Plugin

这个仓库现在同时支持两种 Claude Code 用法：

直接作为项目内 skill 使用：Claude Code 会识别 .claude/skills/img2lcd
作为插件安装：仓库根目录包含 .claude-plugin/plugin.json，并复用 skills/img2lcd

如果作为插件安装，仓库里的可执行入口也已经准备好：

bin/cli-anything-img2lcd

插件启用后可直接在 Claude Code 的 Bash 工具里调用：

cli-anything-img2lcd --json inspect

如果只想使用 skill 自带 runner，也可以直接运行：

python3 skills/img2lcd/scripts/run_img2lcd.py --json inspect

安装为 Cursor Skill

仓库内已经包含 Cursor 可识别的项目级目录：

.cursor/skills/img2lcd
.cursor/rules/img2lcd-skill.mdc

打开这个项目时，Cursor 可以直接使用项目内 skill。

如果你想把它装成全局 skill，可以把 skills/img2lcd 或 .cursor/skills/img2lcd 复制到：

~/.cursor/skills/img2lcd

如果你修改了项目主源码，并且希望同步更新 skill 内置包，请执行：

cd /home/leo/work/open-git/pix_cli/img2lcd
python3 tools/sync_skill_bundle.py

这个同步脚本会同时更新：

skills/img2lcd/assets/package
.claude/skills/img2lcd
.cursor/skills/img2lcd

依赖说明

安装时会自动安装或复用这些依赖：

click
Pillow

会话文件

默认会话文件路径：

~/.cli-anything-img2lcd/session.json

你也可以用全局参数 --session-file 指定自定义会话文件。

使用说明

1. 查看工具能力

cli-anything-img2lcd --json inspect

2. 图片转字节数组

输出为普通十六进制文本：

cli-anything-img2lcd convert ./test.png \
  --draw-mode horizontal1bit \
  --output-format plain

输出为 Arduino 头文件：

cli-anything-img2lcd convert ./test.png \
  --draw-mode horizontal1bit \
  --output-format arduino \
  --output ./test.h

同时生成文本和二进制：

cli-anything-img2lcd convert ./test.png \
  --draw-mode horizontal1bit \
  --output-format plain \
  --output ./test.txt \
  --binary-output ./test.bin

3. 字节数组反解成图片

从命令行字符串反解：

cli-anything-img2lcd decode \
  --bytes "0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff" \
  --width 8 \
  --height 8 \
  --draw-mode horizontal1bit \
  --output ./decoded.png

从文件反解：

cli-anything-img2lcd decode \
  --bytes-file ./test.txt \
  --width 100 \
  --height 180 \
  --draw-mode vertical1bit \
  --output ./decoded.png

4. 使用 REPL

不带子命令直接启动 REPL：

cli-anything-img2lcd

示例：

config show
config set --width 128 --height 64 --draw-mode vertical1bit
convert ./logo.png --output-format plain
history
undo
redo
exit

命令总览

inspect
config show
config set
convert
decode
history
undo
redo

全局参数

这些参数适用于顶层命令：

参数	类型	默认值	说明
`--json`	开关	关闭	输出机器可读 JSON，而不是普通文本
`--session-file PATH`	路径	`~/.cli-anything-img2lcd/session.json`	指定会话文件路径
`--version`	开关	无	显示版本号
`--help`	开关	无	显示帮助

共享配置参数

以下参数同时适用于：

cli-anything-img2lcd convert
cli-anything-img2lcd config set

说明：

config set 用于显式保存默认配置到 session
convert 中传入的这些参数也会写回当前 session，后续命令可复用

参数	类型 / 可选值	默认值	说明
`--width`	整数	源图片宽度	输出画布宽度
`--height`	整数	源图片高度	输出画布高度
`--scale-mode`	`original` `fit` `stretch` `stretch_x` `stretch_y`	`original`	缩放模式
`--center-horizontal / --no-center-horizontal`	开关	`--no-center-horizontal`	是否水平居中
`--center-vertical / --no-center-vertical`	开关	`--no-center-vertical`	是否垂直居中
`--flip-horizontal / --no-flip-horizontal`	开关	`--no-flip-horizontal`	是否水平翻转
`--flip-vertical / --no-flip-vertical`	开关	`--no-flip-vertical`	是否垂直翻转
`--background`	`white` `black` `transparent`	`white`	背景颜色
`--draw-mode`	`horizontal1bit` `vertical1bit` `horizontal565` `horizontalAlpha` `horizontal888`	`horizontal1bit`	字节打包模式
`--threshold`	`0-255`	`128`	单色或 alpha 阈值
`--dithering-mode`	`0` `1` `2` `3`	`0`	抖动模式
`--output-format`	`plain` `arduino` `arduino_single` `adafruit_gfx`	`plain`	文本输出格式
`--invert / --no-invert`	开关	`--no-invert`	是否反相
`--rotation`	`0` `90` `180` `270`	`0`	旋转角度
`--bitswap / --no-bitswap`	开关	`--no-bitswap`	是否对每个字节做 bit reverse
`--remove-zeroes-commas / --keep-zeroes-commas`	开关	`--keep-zeroes-commas`	仅 `plain` 格式下是否移除 `0x` 和逗号
`--identifier`	文本	`img2lcd_bitmap_`	导出变量名前缀
`--first-ascii-char`	整数	`48`	`adafruit_gfx` 模式下默认起始字符
`--x-advance`	整数	`0`	`adafruit_gfx` 模式下字形步进值

参数取值说明

`draw-mode` 说明

值	说明
`horizontal1bit`	横向打包，1 bit / 像素，最常用的黑白屏模式
`vertical1bit`	纵向分页打包，1 bit / 像素，适合很多 OLED 控制器
`horizontal565`	横向 RGB565，2 字节 / 像素
`horizontalAlpha`	横向 alpha mask，1 bit / 像素
`horizontal888`	横向 RGB888，3 字节 / 像素

`output-format` 说明

值	说明
`plain`	输出纯十六进制数组文本
`arduino`	每张图生成一个数组，并额外生成汇总数组
`arduino_single`	多张图合并到一个数组
`adafruit_gfx`	输出 `GFXbitmapFont` 结构，仅适合 1-bit 模式

`scale-mode` 说明

值	说明
`original`	保持原图大小
`fit`	按比例缩放到画布内
`stretch`	拉伸到画布宽高
`stretch_x`	只拉伸宽度
`stretch_y`	只拉伸高度

`dithering-mode` 说明

值	名称	说明
`0`	`binary`	不做高级抖动，直接按阈值二值化
`1`	`bayer`	Bayer 有序抖动
`2`	`floydsteinberg`	Floyd-Steinberg 抖动
`3`	`atkinson`	Atkinson 抖动

命令与参数说明

`inspect`

用途：

查看当前支持的 draw-mode
查看当前支持的 output-format
查看当前 session 的配置

参数：

无命令专属参数

示例：

cli-anything-img2lcd inspect
cli-anything-img2lcd --json inspect

`config show`

用途：

显示当前 session 配置

参数：

无命令专属参数

示例：

cli-anything-img2lcd config show

`config set`

用途：

更新并持久化默认配置

参数：

支持“共享配置参数”一节中的全部参数

示例：

cli-anything-img2lcd config set \
  --width 128 \
  --height 64 \
  --draw-mode vertical1bit \
  --output-format plain

`convert`

用途：

把一张或多张图片转换成字节数组

位置参数：

参数	类型	必填	说明
`IMAGES...`	一个或多个图片路径	是	输入图片，可以传多张

命令专属参数：

参数	类型	默认值	说明
`--glyph TEXT`	可重复参数	图片文件名去掉扩展名	给每张图指定字形名，按图片顺序一一对应
`--output PATH`	路径	不写文件	将格式化文本写入文件；不传时输出到终端
`--binary-output PATH`	路径	不生成	将原始字节流写入二进制文件

附加参数：

支持“共享配置参数”一节中的全部参数

示例：

cli-anything-img2lcd convert ./a.png ./b.png \
  --glyph A \
  --glyph B \
  --draw-mode horizontal1bit \
  --output-format arduino \
  --output ./bitmaps.h

`decode`

用途：

把字节数组文本还原成图片

参数：

参数	类型	默认值	说明
`--bytes TEXT`	文本	无	直接传入字节数组字符串
`--bytes-file FILE`	路径	无	从文件读取字节数组
`--width INTEGER`	整数	无	输出图片宽度，必填
`--height INTEGER`	整数	无	输出图片高度，必填
`--draw-mode`	`horizontal1bit` `vertical1bit` `horizontal565` `horizontalAlpha` `horizontal888`	无	反解所用模式，必填
`--output PATH`	路径	无	输出图片路径，必填
`--bitswap / --no-bitswap`	开关	`--no-bitswap`	解码时是否先做 bit reverse

约束：

--bytes 和 --bytes-file 二选一
两者不能同时传

示例：

cli-anything-img2lcd decode \
  --bytes-file ./test.txt \
  --width 100 \
  --height 180 \
  --draw-mode vertical1bit \
  --output ./decoded.png

`history`

用途：

查看最近的 session 操作记录

参数：

参数	类型	默认值	说明
`--limit INTEGER`	整数	`10`	最多显示多少条历史记录

示例：

cli-anything-img2lcd history
cli-anything-img2lcd history --limit 20

`undo`

用途：

回退到上一个 session 配置状态

参数：

无

示例：

cli-anything-img2lcd undo

`redo`

用途：

恢复最近一次被 undo 回退的配置

参数：

无

示例：

cli-anything-img2lcd redo

输出行为说明

普通文本模式

convert 不带 --output 时，结果直接打印到标准输出
convert 带 --output 时，结果写入文件，并在终端显示写入提示

JSON 模式

顶层带 --json 时，命令输出 JSON
convert 的 JSON 会包含 output、images、binary_bytes、当前 settings
decode 的 JSON 会包含输出路径、宽高、draw_mode、消耗的 token 数量

二进制输出

仅 convert 支持 --binary-output
二进制文件内容是连续原始字节流，不带文本注释

常见用法

生成适合 OLED 的纵向 1-bit 数据

cli-anything-img2lcd convert ./logo.png \
  --draw-mode vertical1bit \
  --output-format plain \
  --output ./logo-vertical.txt

生成 Arduino 多数组头文件

cli-anything-img2lcd convert ./a.png ./b.png \
  --glyph A \
  --glyph B \
  --draw-mode horizontal1bit \
  --output-format arduino \
  --identifier glyph_ \
  --output ./glyphs.h

生成单个合并数组

cli-anything-img2lcd convert ./test.png \
  --draw-mode horizontal1bit \
  --output-format arduino_single \
  --output ./single.h

生成文本和 `.bin`

cli-anything-img2lcd convert ./test.png \
  --draw-mode horizontal1bit \
  --output-format plain \
  --output ./test.txt \
  --binary-output ./test.bin

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.claude-plugin		.claude-plugin
.claude/skills/img2lcd		.claude/skills/img2lcd
.cursor		.cursor
bin		bin
skills/img2lcd		skills/img2lcd
src/img2lcd		src/img2lcd
tests		tests
tools		tools
.gitignore		.gitignore
README.md		README.md
pyproject.toml		pyproject.toml
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation

img2lcd 中文说明

安装说明

环境要求

AI Skill 兼容性

安装命令

安装为 Codex Skill

安装为 Claude Code Skill / Plugin

安装为 Cursor Skill

依赖说明

会话文件

使用说明

1. 查看工具能力

2. 图片转字节数组

3. 字节数组反解成图片

4. 使用 REPL

命令总览

全局参数

共享配置参数

参数取值说明

draw-mode 说明

output-format 说明

scale-mode 说明

dithering-mode 说明

命令与参数说明

inspect

config show

config set

convert

decode

history

undo

redo

输出行为说明

普通文本模式

JSON 模式

二进制输出

常见用法

生成适合 OLED 的纵向 1-bit 数据

生成 Arduino 多数组头文件

生成单个合并数组

生成文本和 .bin

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`draw-mode` 说明

`output-format` 说明

`scale-mode` 说明

`dithering-mode` 说明

`inspect`

`config show`

`config set`

`convert`

`decode`

`history`

`undo`

`redo`

生成文本和 `.bin`

Packages