wallust - Generate colors from an image

gif

sources: rms by marco novo - linus talking - pixels - adwaita

It is recommended to clean the cache in a new major and minor release but is not required

If you don't have a config file, wallust will generate the default config file for you.

Usage

wallust my_wallpaper.png

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

Features

Sets terminal colors sequences on all active terminals
Respects directory structure by platform:
- Cache:
  - Linux: $XDG_CACHE_HOME or $HOME/.cache
  - MacOs: $HOME/Library/Caches
  - Windows: {FOLDERID_LocalAppData}
- Config:
  - Linux: $XDG_CONFIG_HOME or $HOME/.config
  - MacOs: $HOME/Library/Application Support
  - Windows: {FOLDERID_RoamingAppData}
Configuration file, documented at wallust.toml of this repo:
- optional templating integrated in a config file
- backends, colorspaces and filters
- configurable threshold
Cache scheme palettes
Can read pywal colorschemes with cs subcommand
Built-in pywal themes with the theme subcommand (can be disabled with compile-time features)

Backends

This let's you choose a way to read the image, as in read a file and return it's rgb8 bytes. This can be done the usual way using imagemagick convert tool, just like how pywal does it, which wallust can also do (this requires the actual CLI program convert installed), or other methods dependency free.

ColorSpace

This takes the bytes read from the backend and returns the most prominent one and sorts them acording to the filter.

This is a picky configurable section, since there isn't much difference in between the generated palettes with diverging colorspaces. However I think it's interesting to use other color spaces like OkLab (a more precise hardcoded algo) or HSL (which pywal originally uses).

Threshold

This is used inside the colorspace itself, the usual good number is 11.

Number	Description
<= 1	Not perceptible by human eyes.
1 - 2	Perceptible through close observation.
2 - 10	Perceptible at a glance.
11 - 49	Colors are more similar than opposite
100	Colors are exact opposite

Filter

This uses the colors returned by the colorspace and orders them in a way that makes sense, as in making sure that the contrast matches or the background is a certain type. All of these depend on the filter being used, each of them are described in the default config.

Terminal color sequences

By default, wallust will send these sequences to all open terminals (/dev/pts/). You can skip this with the -s or --skip-sequences flag.

When opening new terminals you will notice that the color sequences are not applied. To solve this you can send the sequences yourself when your shell opens. wallust will store the sequences in the cache directory as a file called sequences, the usual way is to cat ~/.cache/wallust/sequences in your .zshrc, .bashrc, etc.

Templating [OPTIONAL]

You can use wallust generated colors in a program by templating the colors in it's config file, like the following example:

# zathurarc config file

#keybindings
...

# colors
set default-bg     "{color2}"
set default-fg     "{foreground}"
set statusbar-bg   "{color4}"
set statusbar-fg   "{color6}"
set inputbar-bg    "{color1}"

Then add this file to ~/.config/wallust/ e.g. ~/.config/wallust/zathurarc (config directory defined by the platform) and add a new entry to wallust.toml

[[entry]]
template = "zathurarc"
target = "~/.config/zathura/zathurarc"

You can find examples at pywal templates or wpgtk templates

NOTE: The template name doesn't have to match the target name: e.g. the file could be named sample.conf, and thus the entry would have template = "sample.conf", but the target can remain the same, e.g. target = "~/.config/zathurarc".

Variables and Methods

{wallpaper}: The full path to the current wallpaper.
{alpha}: displays 100, this is here to be compatible with pywal templates.
{var}: Output the color in hex.
{var.rgb}: Output the color in rgb.
{var.rgba}: Output the color in rgba.
{var.xrgba}: Output the color in xrgb.
{var.strip}: Output the color in hex (without a #).
{var.red}: Output the red value.
{var.green}: Output the green value.
{var.blue}: Output the blue value.

Where var can be color0 - color15, background, foreground and cursor.

Installation

Keep in mind that the git repo is constantly updated, if you wanna use git, checkout to a stable version.

Binary

Go to the releases and download the tar.gz file, which contains a binary for musl, so it should work for most *nix platforms.

tar -xf wallust-TARGET.tar.gz

Build from source

From this repo

Go to the releases page and download the .zip or .tar.gz repository. After extracting the contents, go to the directory (cd MAYOR.MINOR.PATCH).

Then you can do 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

From crates.io

cargo install wallust

This will use the lastest version

NetBSD

If you are using NetBSD, a native package is available from the official repositories. To install it, simply run:

pkgin install wallust

Nix

If you are using Nix, a native package is available for the unstable channel.

Install it for your profile:

nix-env -iA nixos.wallust # change `nixos` for `nixpkgs`, if on a non-NixOS system

Try it with nix-shell

nix-shell -p wallust

Contribute!

Show some of your taste by adding a backends, colorspaces and/or filters.

Having thoughts or suggestios is also very welcome.

TODOs

for more, grep the src for TODO rg TODO

release binaries with a CI, figure out woodkeeper codeberg CI
Think about using k means algo similar to pigmnts (just without seg faulting :p)
use thiserror for errors in the modules (there aren't that many)

wallust 2.5.0