wallust 3.1.0

Generate a 16 color scheme based on an image.
Documentation

wallust - Generate colors from an image

crates-io downloads license dependency-status status-badge CodeBerg MatrixChat

gif

sources: adwaita - scenic view of mountains - rms by marco novo - pixels - linus talking

If comming from v2, please check v3 breaking changes.

Usage

wallust run my_wallpaper.png

use wallust -h for an overview and wallust --help for a more detailed explanation

Docs

For ease of use you can check detailed docs with man pages (rather than cmd -hing everytime):

  • man wallust, information about terminal colors and template syntax;
  • man wallust.5, config docs;
  • man wallust-subcommand, displays a man page for subcommand.

There is also a web page for documentation! It's based on plain markdown, so you could also read it locally at docs/ directory.

Features

  • Includes man pages and completions!
  • Sets terminal colors on all (or the current, -u) active terminals:
  • Cache scheme palettes, overwritten by -w:
    • Linux: $XDG_CACHE_HOME or $HOME/.cache
    • MacOs: $HOME/Library/Caches
    • Windows: {FOLDERID_LocalAppData}
  • Read pywal/terminal-sexy colorschemes with wallust cs.
  • Built-in themes with wallust theme (compile time feature).
  • Optional Configuration file, wallust.toml:
    • wallust checks for ~/.config/wallust/wallust.toml for the config file, if not found it will use default implementations.
    • Configuration variables are avaliable as cli flags.
    • Optional templating with a subset of Jinja2 or pywal syntax if selected.
    • Configurable methods for backends, colorspaces, palettes and threshold.
    • OS dependant path:
      • Linux: $XDG_CONFIG_HOME or $HOME/.config
      • MacOs: $HOME/Library/Application Support
      • Windows: {FOLDERID_RoamingAppData}
Methods Description
Backends How to extract the colors from the image. (e.g pywal uses convert)
ColorSpace Get the most prominent color, and sort them according to the Palette, configurable by a threshold
Palette Makes a scheme palette with the gathered colors, (e.g. sets light background)

Installation

You can see if your distro has wallust in their repos by the following chart. For detail information you can check some distro installation instruction that the maintainers have left.

With cargo

cargo install wallust

This will use the lastest (non pre-release) version.

With git

Simply git clone https://codeberg.org/explosion-mental/wallust.

Recommended way is to use the Makefile, since this will install man pages and completions.

  1. Edit Makefile to meet your local setup (should be fine as is for most linux distros).
  2. Build it with make
  3. Install wallust (if necessary as root): make install

Optionally, installing only the binary can be done with the following, which moves the binary into your $CARGO_HOME/bin:

cargo install --path .

or build it and copy the binary to one folder present in your $PATH like /usr/local/bin

cargo build --release
cp -f ./target/release/wallust /usr/local/bin

Background

I've started this tool mainly for speed reasons given that I use a keybinding that runs pywal with a random wallpaper image, this resulted in a noticeable delay in between.

Of course, now I know that pywal uses image magick convert to gather the colors, which wallust can also use with the wal backend. Integrated native methods, and even much more sofisticated algorithms like kmeans or the SIMD backend fast_resize, made the need to let the user decide what fit best.

While the goal was focused on speed, the use case move on to upgrade functionality that both wallust and archived python tool shared.

I use rust given the great wide library (crates) that it offered and it's native capabilities. I also tried rewriting pywal in C after watching a tsoding video where he implmements a histogram in C for manipulating an image. That was the little push I needed start this journey.

Related