wallust - Generate colors from an image

gif

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

Major version 3.0.0 is closer than ever, check how to prepare for v3 for future changes.

Usage

wallust run my_wallpaper.png

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

Features

Sets terminal colors on all active terminals
- *NIX: ASCII escape sequences
- MacOS: iTerm2 sequences
- Windows: Adds a color scheme for the windows terminal
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 cs subcommand
Built-in pywal themes with the theme subcommand (can be disabled with compile-time features) wallust theme --help to list possible themes
Configuration file, wallust.toml:
- When no config file, the default config file will be generated
- Optional templating with two different engines:
  - Default is using usual {variable}
  - By enabling new_engine = true, you use {{variable}}
- Configurable methods for backends, colorspaces and palettes (chart below)
- Configurable threshold
- 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 with a threshold
Palette	Makes a scheme palette with the gathered colors, (e.g. sets light background)

Make sure to read the sample config file for more documentation.

Threshold

Default is 20 with a more colorful approach, 19 is also suggested.

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

Terminal colors

By default, wallust will send these sequences to all open terminals:

/dev/pts/ on Linux
/dev/ttys00 on MacOS
ps to search active terminals on OpenBSD
Updates settings.json on Windows Terminal, to enable this scheme for the first time you will have to selected it manually

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

NOTE: You can enable a new method by using new_engine = true inside a template This "new engine" difers by using double brackets like {{variable}} instead of one like {variable} (as in the example below), which helps with file formats that use brackets like json. With the new_engine enabled you can escape and produce a literal {{ by {{{{}}, and for }} you escape it with {{}}}}.

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}"

You can find examples at pywal templates or wpgtk templates

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

[templates]
zathura.template = "zathurarc"
zathura.target = '~/.config/zathura/zathurarc'
# or, alternatively, like:
#zathura = { src = 'zathurarc', dst = '~/.config/zathura/zathurarc' }

The name after doesn't really matters, in this case zathura, and is used as an identifier for the user.

Variables and Methods

wallpaper: The full path to the current wallpaper, colorscheme file or the name of the theme in use.
backend: Current backend being used.
colorspace: Current colorspace being used.
palette: Current palette being used.
alpha: Default to 100, can be modified in the config file or with --alpha/-a.
alpha_dec: instead of [0..=100], displays it from 0.00 to 1.00.
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 colors from color0 to color15, background, foreground and cursor.

Installation

wallust doesn't require third party packages, but has an optional dependency: imagemagick to use the wal backend (just like pywal). Other methods are built in.

Distros Packages

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

Arch User Repository (AUR)

Using an Arch based distro, you can use the wallust or wallust-git packages.

wallust fetches the latest stable version from static.crates.io, which mirrors the master branch. Prefer this package.
wallust-git fetches the latest unstable version from the dev branch.

Either can be installed on an Arch based distro with the following commands:

git clone https://aur.archlinux.org/wallust.git # Or wallust-git.git
cd wallust # or wallust-git
makepkg -si

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

The master branch is stable

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

Packaging

Binary-based distros can grab the latest pre-compiled binary from the releases page.

Source-based distros, if they wish to build wallust from source, must ensure that the following dependencies are available:

Build Dependencies:
1. Rust (cargo, rustc)
Runtime Dependencies
1. imagemagick is required only for the wal backend, such limiting should be mentined and considered an optional dependency, since all other backends work without it.

Contribute!

Use the dev branch

Show some of your taste by adding a backend, colorspace, palette, and/or colorscheme.

Having thoughts or suggestios is also very welcome.

TODOs

for more, grep the src for TODO rg TODO

automate binary releases with a CI, figure out woodkeeper codeberg CI
use thiserror for errors in the modules (there aren't that many)
shell completions and man page (allows up readme)

wallust 2.10.0