lutgen-rs: applying a colour scheme to an image with an interpolated lookup table

A palette becomes a lookup table, and the lookup table becomes an image

The project describes itself as a blazingly fast interpolated 3D lookup table utility for arbitrary and popular color palettes, with the tagline that you can theme any image to your desktop colorscheme. The mechanism has two halves and they are separate operations. The generator takes a small set of palette colours and produces a Hald CLUT, which is the image format designed for exactly this: a cube of every possible colour mapping, sampled on a lattice. The applier takes that LUT and runs an image through it, so every pixel in the original is mapped through the table into the new palette. The Hald CLUT convention comes from the source list in the README, with the original by Quelsolaar, editing with Hald CLUTs by Snibgo, and sparse Hald CLUTs also by Snibgo. The word interpolated in the description is the substantive part, and the sources list tells you how it is done: RBF interpolation, radial basis function interpolation, and Shepard's method, which is inverse distance weighting. Oklab is the colour space, and the source list points at the Oklab post by Ottosson. So the intermediate colours are computed in a perceptually uniform space rather than picked by eye.

The repository is a Cargo workspace with three published artefacts

The root Cargo.toml shows a Cargo workspace with members matching crates/*, and the release history confirms that several things are published from it. There is lutgen-cli at version 1.1.1, the library itself as lutgen with documentation on docs.rs, and a lutgen-studio package at 0.4.0. The dependency list is short and tells you what the tool is made of: regex and strum with derive, serde, bpaf for argument parsing with the derive, dull-color, autocomplete and docgen features enabled, dirs, the image crate at 0.25, oklab at 1.1, and rayon for parallelism. The release profile sets opt-level 3 with LTO enabled and panic set to abort, and the test profile inherits from release, which is an unusual choice that says something about how the project treats its own test runtime. The workspace also carries a rust-toolchain.toml and a rustfmt.toml, and a .cargo directory, so the toolchain version is pinned for contributors. The parallel processing through rayon is what makes applying a LUT to a large image practical, and the panic abort setting keeps the binary small and fast at the cost of not unwinding.

Installing the CLI from crates.io or from source

The CLI is published on crates.io as lutgen-cli, and the Repology badge in the README tracks packaging status across distributions, so a packaged build probably exists for most Linux desktops. To build from source, the sequence is clone, enter the directory and install the crate path:

git clone https://github.com/ozwaldorf/lutgen-rs
cd lutgen-rs
cargo install --path crates/cli

Or, if you do not want to compile, the published crate installs the same way any other Rust tool does:

cargo install lutgen-cli

The documentation, examples and more live on the Lutgen Wiki linked from the README. There is also a Nix flake that provides the lutgen package and can be run directly, which is the shortest path for someone on Nix:

nix run github:ozwaldorf/lutgen-rs

The flake also provides a development shell, and the README shows how to enter it and run the binary from source inside it, with the shell giving you the toolchain without a separate install step:

git clone https://github.com/ozwaldorf/lutgen-rs
cd lutgen-rs
nix develop

# inside dev shell
cargo run -r --bin lutgen

Build caching is provided through garnix.io, which is the service behind the CI badge in the README header, so the Nix route is fast even on a cold cache.

The desktop studio is gone, and the web app took its place

There is an interactive WebGL app at lut.sh/app, supporting every built-in palette with live previews, and the README is explicit about what happened to the desktop GUI. Lutgen Web replaces lutgen-studio, the previous desktop GUI, which is no longer built or maintained, and existing studio releases remain published on crates.io and in distro repositories. That is a significant change for anyone who had the studio installed, because the new app runs in the browser and the old one did not. The web app is built from the web/ directory in this repository, and you can run it locally with npm install followed by npm run dev. The topic list gives the clearest picture of the audience: cli, gui, hald-clut, image-converter, colorscheme, color-grading, theming, wallpaper, rice and linux-desktop. The rice tag is the giveaway. This is a tool for the Linux desktop theming community, the people who set a wallpaper and a colour scheme and want them to match, and the fast iteration between a palette choice and a rendered result is what the WebGL preview is for.

What the examples show, and why palettes are the hard part

The README's example output section is organised as two sets of images, and reading them tells you what the tool is for. The first set is Hald CLUTs for Catppuccin Mocha, Gruvbox Dark and Nord, which is the palette input rendered as the lookup table itself. The second set is colour corrections: an original example image, then the same image graded to Catppuccin Mocha, to Gruvbox Dark, and to Nord. The interesting property is visible in the comparison. A wallpaper that already has its own colours does not simply get its dominant colours replaced, it gets mapped through a continuous function, so the gradients, the shadows and the highlights all shift consistently while the image stays recognisable. That is what the interpolation buys you. The catch is the same catch that every automatic grading tool has: a LUT derived from a handful of palette anchors cannot know which colour in the source image is meant to be the background and which is meant to be the subject, so the result is a plausible regrade rather than a selective one.

Where this approach stops working

The limits are worth being explicit about. The first is that the pipeline is anchored on a small palette, and a palette is a set of a dozen or so colours, while a photograph contains thousands. Everything between those anchors is inferred, and the inference is a smooth mathematical mapping rather than a judgement about what matters, so skin tones and neutral greys can drift in ways that are hard to predict. The second is the acknowledged gap in the planned features: interpolation for more accuracy when correcting with low level LUTs, meaning under sixteen levels, is still unchecked, and hardware acceleration for applying LUTs to images is also unchecked, so the rayon-based parallel path is doing the work. The third is that the web app is now the only graphical surface, and a browser app that runs WebGL shaders cannot be scripted the way a CLI can, so a batch pipeline over a directory of wallpapers is a job for the CLI or the library, not for the app. And the fourth is the workflow cost of a lookup table at all, since a single theme change means regenerating the CLUT and reapplying it to every image you want regraded, which is a job for a script and not a job for a person clicking through a gallery.

Maintenance, licence and where the credits go

The release history is short and the cadence is visible. The Lutgen CLI is at 1.1.1, released on 2026-05-14, with 1.0.1 from 2025-08-01 before it, and the Lutgen Studio package sits at 0.4.0 from the same day in May 2026, though the studio is no longer built. The last push to the repository was on 2026-10-20, so the tree is active even though the last tagged release is five months old. The licence is MIT, and the repository carries a LICENSE file, a CHANGELOG.md and a CONTRIBUTING.md. The acknowledgements section is a good indicator of the project's shape. It credits Gingeh for the initial inspiration and the imagemagick approach, which tells you the original was a shell script wrapping ImageMagick before this Rust rewrite existed, The Catppuccin Org for continual feedback and support, Stonks3141 for maintaining the Alpine Linux package, and all the nixpkgs maintainers. A project with distribution packaging, a Nix flake, a web app and a library in one workspace is doing more than one thing, and the release split between the CLI and the studio shows how that gets managed.

Editorial conclusion

lutgen-rs suits a Linux desktop user who wants their wallpaper to match a colour scheme rather than merely sit next to it, and the interpolated CLUT approach gives a smoother result than a hand-made palette swap because the intermediate colours are computed rather than picked. It is the wrong tool if you need colour management with an ICC profile workflow, since the pipeline is built around palette input and Hald CLUTs rather than profiled output, and it is the wrong tool for batch work on large photo libraries, since the README's planned features list still has hardware acceleration for applying LUTs to images as an open item. Verify first which colour space your palette is expressed in, because the project works in Oklab and that choice changes the result, and note that the desktop GUI has been replaced by the web app, with lutgen-studio no longer built or maintained even though its releases remain published.

Frequently asked questions

Official sources

1. License: MIT
2. ozwaldorf/lutgen-rs on GitHub
3. Project website
4. README
5. Releases