# imgcmd

**Repository Path**: aleckstygit/imgcmd

## Basic Information

- **Project Name**: imgcmd
- **Description**: imgcmd 是一个命令行工具,用于处理图像文件并将其转换为C语言格式. 它支持多种选项来定制转换过程,包括输入输出路径、图像尺寸、格式、字节顺序、压缩等. 它可以将图像转换为C语言数组,适用于嵌入式系统和其他需要图像数据的应用. 它支持多种图像格式,包括BMP、PNG、JPEG等,并可以输出为C语言数组或其他文本格式.
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 图片文件命令行转换工具

## 简介
`imgcmd` 是一个命令行工具,用于处理图像文件并将其转换为文本格式.
它支持多种选项来定制转换过程,包括输入输出路径、图像尺寸、格式、字节顺序、压缩等.
它可以将图像转换为C语言数组,适用于嵌入式系统和其他需要图像数据的应用.
它支持多种图像格式,包括BMP、PNG、JPEG等,并可以输出为C语言数组或其他文本格式.

## 特性
- 支持多种图像格式: BMP, PNG, JPEG, TIFF等.
- 支持等比例缩放,自适应缩放,拉升缩放等.
- 支持三种压缩模式: RLE、行间差值、稀疏编码.
- 支持设置颜色步长.
- 支持设置输出文本数组的名称.
- 支持设置图像的宽度和高度.
- 支持设置每像素位数(BPP).
- 支持设置颜色顺序.
- 支持动画序列处理（仅存储帧间差异）
- 支持 GIF 文件直接导入
- 支持关键帧间隔,降低帧率减少数据量

## 安装
本程序是一个独立的可执行文件,无需安装.

## 使用方法
### 1. 命令行参数
`imgcmd` 工具通过命令行参数来控制其行为,以下是可用的参数:

- `-i/--input <input>` : 指定输入图像文件的路径.
- `-o/--output <output>` : 指定输出文本文件的路径.
- `-w/--width <width>` : 设置目标图像的宽度.
- `-h/--height <height>` : 设置目标图像的高度.
- `-a/--auto/--autosize` : 自动调整图像大小.
- `-n/--name <name>` : 设置输出文本数组的名称.
- `-b/--bpp <1/2/4/8/16/24/32>` : 设置目标图像的每像素位数(BPP).
- `-e/--line/--linewidth <line width>` : 设置每行的字节宽度,有些格式需要`8/16/24/32`字节对齐.
- `-c/--color <rgb/rbg/grb/gbr/bgr/brg>` : 设置颜色顺序,部分显示屏需要交换颜色通道.
- `-r/--rotate <90/180/270>` : 设置旋转角度`(90,180,270)`.    
- `-m/--msb` : 设置字节顺序为最高字节在前.
- `-l/--lsb` : 设置字节顺序为最低字节在前.
- `-z0/--zip` : RLE 压缩图像数据（通用）.
- `-z1/-Z/--zip-delta` : 行间差值+RLE 压缩（单帧渐变/UI图片）.
- `-z2/--zip-sparse` : 稀疏编码压缩（动画帧间差值）.
- `-z3/--zip-smart` : 自适应 RLE/稀疏（自动兼顾首帧与差值，推荐动画用）.
- `-s/--step <2/4/8/16/32/64/128>` : 设置颜色步长.
- `-d/--debug` : 输出调试信息.
- `-v/--version` : 显示版本信息.
- `-x/--scale <scale>` : 设置缩放比例.
- `-t/--palette <1/2/3/4>` : 设置调色板颜色字节数.
- `-p/--prefix <prefix>` : 设置输出文件前缀.
- `--outdir/-od <dir>` : 输出目录（GIF/动画模式时指定输出目录，默认当前目录）。
- `--include <include>` : 设置 include 文件名.

### 动画相关
- `-a/--ani-dir <dir>` : 设置动画目录,处理目录下所有图片.
- `-k/--keyframe <N>` : 设置关键帧间隔（默认1=取全部, -k 3 则每3帧取1帧）.
- `-g/--gif <file.gif>` : 导入 GIF 动画文件.
- `--fps/--frames <N>` : 设置 GIF 目标帧率（每秒取 N 帧, 默认0=取全部）.
- `--outdir/-od <dir>` : 设置输出目录（GIF/动画模式时输出文件存放目录, 默认当前目录）.

### 2. 示例:
以下是一些使用示例:

```bash
# 单帧 RLE 压缩
imgcmd -i i.bmp -o o.c -w 128 -h 64 -n array -b 16 -c rbg -m -z0 -s 32

# 单帧 行间差值压缩（适合渐变/UI图片）
imgcmd -i ui_bg.png -o ui_bg.c -b 16 -z1

# 动画目录 RLE 压缩
imgcmd -a ./ani -b 16 -z0

# 动画目录 稀疏压缩 + 每3帧取1帧
imgcmd -a ./ani -b 16 -z2 -k 3

# GIF 导入 + 每秒10帧 + 稀疏压缩 + 每2帧取1帧
imgcmd -g anim.gif --fps 10 -b 16 -z2 -k 2

# GIF 导入 + 智能压缩（推荐）
imgcmd -g anim.gif --fps 10 -b 4 -z3 -k 2 -p out/

# GIF 导入 + 智能压缩 + 最大压缩比
imgcmd -g anim.gif -b 4 -z3 -p out/

# GIF 导入 + 指定输出目录
imgcmd -g anim.gif -b 16 -z2 --outdir ./output

# GIF 导入 + 通过 -o 路径自动提取输出目录（等效于上一条）
imgcmd -g anim.gif -b 16 -z2 -o ./output/frame.c

# 动画目录 + 指定输出目录
imgcmd -a ./ani -b 16 -z2 -od ./output
```

### 3. 压缩模式对比:

| 参数 | 模式 | 适用场景 | 原理 |
|---|---|---|---|---|
| `-z0` | RLE | 通用 | 两遍扫描,短运行合并到 DIFF,长运行编码为 REP |
| `-z1` | Row-Delta | 单帧渐变/UI | 每行 XOR 前一行,相似行变长零序列 |
| `-z2` | Sparse | 动画帧间差值 | varint 编码零运行+非零块,全零行仅1字节 |
| `-z3` | Smart | 通用最佳 | 每行自动选择 RLE 或 Sparse,密行→RLE,疏行→Sparse |

### 4. 注意事项:
- 确保输入文件存在且路径正确.
- 输出文件路径必须是有效的.
- 如果未指定宽度和高度,则默认使用输入图像的原始尺寸.
- 如果只指定了宽度或高度,则另一个参数将根据图像的原始尺寸进行缩放.
- 如果使用了 `--auto` 选项,宽度和高度将缩放到指定高度宽度,保持图像的原始比例.
- 如果使用了 `--rotate` 选项,图像将被旋转指定角度.
- 如果使用了 `--scale` 选项,图像将被缩放指定比例.
- 动画模式存储帧间差值, 第一帧为完整数据.
- 动画模式结束后会输出总帧数、总大小、压缩率和节省字节数.
- `-z1` 不适合动画模式, 会导致数据膨胀.
- 工具使用 SixLabors.ImageSharp, 跨平台支持 Windows/Linux/macOS.