lutgen-rs CLI命令完全手册:6大子命令一次讲清楚
lutgen-rs CLI命令完全手册:6大子命令一次讲清楚
lutgen-rs 是一款用 Rust 编写的极速 Hald CLUT(LUT)生成与应用工具,能把你喜欢的配色方案"涂"到任意图片上。它的命令行 lutgen 提供 6 个子命令:generate、extract、apply、patch、palette names 和 palette all,覆盖从生成 LUT、提取配色、应用到图片,到批量替换文本颜色的完整工作流。读完本文,你就能熟练驾驭 lutgen-rs 的 CLI 命令。
⚡ 先看懂:LUT 在这里是什么意思
简单说,Hald CLUT 就是一张"颜色转换查找表":把 sRGB 色彩空间压缩成一张立方体图片,lutgen 会把调色板里的颜色按距离映射进去。之后任何像素查表,就能被"翻译"成配色方案里最接近的颜色。lutgen-rs 内置了多种插值算法(高斯模糊、RBF、Shepard 法等),让颜色过渡平滑自然,而不是生硬的"最近色"。
📋 6 大子命令速览
| 子命令 | 快捷键 | 一句话作用 | 典型场景 |
|---|---|---|---|
generate |
g |
从配色板生成 Hald CLUT 图片 | 导出 LUT 给其他软件用 |
extract |
e |
从图片提取配色再生成 LUT | 胶片模拟、复刻照片风格 |
apply |
a |
把 LUT 应用到图片上 | 换壁纸/照片配色(最常用) |
patch |
p |
替换文本文件里的颜色值 | 给 CSS、配置文件换主题 |
palette names |
P |
列出全部配色板名称 | 脚本检索、配合 grep/fzf |
palette all |
P |
打印所有配色板及其颜色 | 浏览、挑选配色 |
1️⃣ generate:从配色板生成 Hald CLUT
# 用内置配色板 gruvbox-dark 生成 LUT(默认输出 gruvbox-dark.png)
lutgen generate -p gruvbox-dark
# 指定输出路径,并把自定义颜色追加到配色板
lutgen generate -o custom.png -- "#ABCDEF" ffffff 000000
-p / --palette PALETTE:内置或自定义配色板(名字不区分大小写)-- #HEX ...:追加自定义颜色,与配色板合并使用-o / --output PATH:输出路径,默认按配色板命名
生成好的 Hald CLUT 是标准图片格式,可以直接导入 Photoshop、Krita 等支持查找表的软件。命令定义见 main.rs,内置配色板数据在 palettes.toml 里,上百种流行配色开箱即用。
2️⃣ extract:从现有图片提取配色,复刻风格
这是"偷师"别人照片配色的神器:先提取图中主要颜色,再生成对应 LUT,之后就能把同样的色调"套"到别的图片上。
# 从一张图片提取 128 个颜色(默认值)生成 LUT
lutgen extract -o my-look.png photo.png
# 用多张参考图提取,颜色集更稳定
lutgen extract --color-count 64 -o film-669.png polaroid-samples/*.png
--color-count:提取的颜色数量,默认 128- 支持一次传入多张图片,结果取并集
3️⃣ apply:把 LUT 应用到图片(核心命令)
这是使用频率最高的子命令,支持批量处理和动画 GIF:
# 最常用:直接用配色板改一张图(输出 xxx_配色名.扩展名)
lutgen apply -p catppuccin-mocha wallpaper.png
# 使用外部 LUT 文件
lutgen apply --hald-clut polaroid-669.png another-image.png
# 批量处理:多张输入时 -o 自动视为输出目录
lutgen apply -p gruvbox-dark -o out/ photos/*.jpg
关键参数:
-o / --output PATH:输出文件(单张)或目录(多张)-d / --dir:单张输入也强制保存到目录-c / --cache:缓存生成的 LUT,多次运行免重复计算--hald-clut FILE:直接使用现成的 Hald CLUT,跳过生成
4️⃣ patch:批量替换文本文件中的颜色
给前端项目换主题色?patch 会自动找出文本里的十六进制、rgb()、rgba() 颜色值并替换:
# 生成 diff 补丁文件(不修改原文件)
lutgen patch -p catppuccin-mocha ./**/*.css > theme.patch
# 直接写回文件,不输出补丁
lutgen patch -wn -p gruvbox-dark theme.css
-w / --write:直接把改动写回文件-n / --no-patch:禁用 diff 输出,常与--write搭配
5️⃣ palette:浏览与检索配色板
palette 是脚本友好的"配色板浏览器",含 names 和 all 两个内置子命令:
# 只列出全部配色板名称(适合检索)
lutgen palette names | grep gruvbox
# 打印某个/多个配色板的具体颜色
lutgen palette catppuccin-mocha nord
# 打印所有配色板及颜色
lutgen palette all
# 配合 fzf 交互式挑选配色
lutgen palette names | fzf --preview 'lutgen palette --ansi {}'
--ansi:在管道输出中强制渲染 ANSI 彩色预览
🛠 通用参数速查(generate / extract / apply / patch 通用)
| 参数 | 说明 | 默认值 |
|---|---|---|
-l / --level |
Hald CLUT 层级(2–16,越高越精细、文件越大) | 10 |
-P / --preserve |
保留原图亮度,颜色更真实 | 关 |
-L / --lum |
亮度权重因子,常与 --preserve 搭配 |
1.0 |
-r / --radius |
高斯模糊半径(sigma),越大越柔和 | 8.0 |
-n / --nearest |
RBF 插值时考虑的最邻近颜色数 | 16 |
插值算法通过开关切换:默认高斯模糊;-R 启用 Gaussian RBF(-s 调形状参数);-S 启用 Shepard 方法(-p 调幂参数);-G 高斯采样(质量高但慢);-N 关闭插值直接取最近色。算法实现位于 crates/lib/src/interpolation/ 目录。
💡 实用技巧
- 自定义配色板:在
~/.config/lutgen/(Linux)下放一个纯文本文件,内容用空格分隔的十六进制颜色,文件名即为配色板名,例如:echo "fff 555 000" > ~/.config/lutgen/my-palette,之后-p my-palette即可。也可用LUTGEN_DIR环境变量指定目录。 - Shell 补全:支持 bash / zsh / fish,如
lutgen --bpaf-complete-style-zsh > _lutgen。 - 完整参数参考:机器生成的权威文档见 docs/pages/cli.md 和手册页 docs/man/lutgen.1。
- 更多用法示例:参考 docs/pages/examples.md。
- 快速上手:
cargo install lutgen-cli即可安装;想从源码构建可先git clone https://gitcode.com/gh_mirrors/lu/lutgen-rs再执行cargo install --path crates/cli。
✅ 小结
lutgen-rs 的 6 个 CLI 子命令分工清晰:palette 查配色 → generate 造 LUT → extract 复刻风格 → apply 套到图片 → patch 批量改文本颜色。配合 --preserve、--lum 等通用参数和 4 种插值算法,基本能覆盖所有换色需求。





