17 KiB
| obj | website | repo | rev |
|---|---|---|---|
| application | https://explosion-mental.codeberg.page/wallust | https://codeberg.org/explosion-mental/wallust | 2025-05-28 |
wallust
wallust is a command line tool for creating 16 color palettes, since it was the original intent of pywal, the tool that inspired the creation of wallust.
Parameters
Alpha
Alpha value for templating (default: 100).
This value doesn't do anything other than represent the variable called alpha in templates. This is simply a left over of niche use cases.
To edit this value:
Config file: alpha = 50
Cli: wallust run image.png --alpha 50
Backend
Allows you to choose which method to use in order to parse the image.
| Backends | Description |
|---|---|
| Full | Read and return the whole image pixels (more precision, slower) |
| Resized | Resizes the image before parsing, mantaining it's aspect ratio |
| Wal | Uses image magick convert to generate the colors, like pywal |
| Thumb | Faster algo hardcoded to 512x512 (no ratio respected) |
| FastResize | A much faster resize algo that uses SIMD. For some reason it fails on some images where resized doesn't, for this reason it doesn't replace but rather it's a new option. |
| Kmeans | Kmeans is an algo that divides and picks pixels all around the image, giving a more diverse look. |
To edit this value:
Config file: backend = "full"
Cli: wallust run image.png --backend full
Check Constrast
Ensures a "readable contrast". Should only be enabled when you notice an unreadable contrast frequently happening with your images. The reference color for the contrast is the background color. (default: disabled)
To edit this value:
Config file: check_contrast = true
Cli: wallust run image.png --check-contrast
color_space
What colorspace to use to gather the most prominent colors.
| Name | Description |
|---|---|
| lab | Uses Cie L a b color space. (mixed and ansi) |
| lch | CIE Lch, you can understand this color space like LAB but with chrome and hue added, which Could help when sorting. (mixed) |
There are two variants:
- mixed, which mixes colors when collecting them into a histogram.
- ansi, Tries to get a full color pallete similar to the one of a tty, this works best with ansidark palette.
Below, is a complete overview of all colorspaces variations:
| Color Space | Description |
|---|---|
| Lab | Uses Cie Lab color space |
| LabMixed | Variant of lab that mixes the colors gathered, if not enough colors it fallbacks to usual lab (not recommended in small images) |
| Lch | CIE Lch, you can understand this color space like LAB but with chrome and hue added. Could help when sorting. |
| LchMixed | CIE Lch, you can understand this color space like LAB but with chrome and hue added. Could help when sorting. |
| LchAnsi | Variant of Lch which preserves 8 colors: black, red, green, yellow, blue, magenta, cyan and gray. This works best with 'darkansi' palette, allowing a constant color order. |
To edit this value:
Config file: color_space = "lchmixed"
Cli: wallust run image.png --colorspace lchmixed
Enviromental Variables in templates/targets paths
Allows you to have shell variables in your paths. For example:
# using XDG var
pywal = { src = "pywal", dst = "${XDG_HOME_CONFIG}/templates/pywal-result/", pywal = true }
To avoid possible security issues, this flag is disabled by default.
To edit this value:
Config file: env_vars = true
Fallback Generator
This field chooses a method to use when the gathered colors aren't enough:
| Name | Description |
|---|---|
interpolation |
(default) Tries to pick two colors and built gradients over them |
complementary |
Uses the complementary colors of two colors, or more (if needed), colors. |
To edit this value:
Config file: fallback_generator = "complementary"
Cli: wallust run image.png --fallback-generator complementary
Palette
Uses the colors gathered from color_space in a way that makes sense, resulting in a scheme palette.
| Name | Description |
|---|---|
| ansidark | Dark ansi colors, works best with lchansi and orders it's colors to preserve a constant tty like order: color0 -> black, color1 -> redish, color2 -> greenish, and so on. |
| dark | Dark colors dark background and light contrast. (16, comp, comp16) |
| harddark | Same as dark with hard hue colors. (16, comp, comp16) |
| light | Light bg dark fg. (16, comp, comp16) |
| softdark | Variant of softlight uses the lightest colors and a dark background could be interpreted as dark inversed. (16, comp, comp16) |
| softlight | Light with soft pastel colors counterpart of harddark. (16, comp, comp16) |
Palette Variations:
There are some variants to the principal palettes schemes which you can use by appending the variant to the name e.g. 'dark16', 'lightcomp', 'harddarkcomp16' and so on, each palette indicates, in parenthesis, which variants are avaliable.
| Name | Description |
|---|---|
| 16 | Makes shades of colors, creating the ilusion of 16 different colors. |
| comp | Stands for Complementary and completly changes the palette to it's complementary counterpart. |
| comp16 | Complementary palette with 16 shades, basically a combination of the above. |
To edit this value:
Config file: palette = darkcomp16
Cli: wallust run image.png --palette darkcomp16
Saturation
Color saturation, usually something higher than 50 increases the saturation and below decreases it (on a scheme with strong and vivid colors).
Possible values: 1 - 100 (default: disabled)
To edit this value:
Config file: saturate = 20
Cli: wallust run image.png --saturation 20
Threshold
Wallust automatically uses the best threshold, heuristically, if this variable isn't defined (default behaviour).
If you really want to define this variable, keep in mind the following. Thershold is the difference between similar colors , used inside the colorspace.
Each colorspace may have different results with different thresholds, meaning you should try which one works for you best.
An overall table looks like this:
| 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. |
To edit this value:
Config file: threshold = 10
Cli: wallust run image.png --threshold 18
Configuration
While wallust can work out without a config file, it results useful to define constant options in a file than giving them each time as a cli flag. This is why all parameters are optional.
Without a config file, wallust will choose to default implementations. That being said, you can start editing your config file.
The config file is divided into two parts:
- global space
- templates space
Inside the global space you can define any parameter that you want.
To enter the templates space, however, requires a [templates] header. Below this, you can only define templates.
Defining a template in the config file
Templates are optional and defined inside the [templates] header. Here it's recommended to use single quotes (') instead of double quotes (") since the first one, by the toml format, ignores backslashes (\) as escape codes, allowing you to define Widows like paths, e.g. C:\Users\Desktop\.
Template definitions have the following fields:
template: A relative path that points to a file where wallust.toml is located, usually at ~/.config/wallust/templates. This file can also be a directory, which will be templated non-recursively (only the first recursion, likedu ... --max-depth 1)target: Absolute path in which to place a file with generated templated values. This field CAN expand the ~ as the $HOME enviromental variable. If template is a directory, this must correspond and be one.
Example:
# Let's keep good old pywal look and feel
backend = "wal"
#color_space = "lch" # idc about this one..
#threshold = "20" # neither about this, since I read wallust does it automagically..
# classic look
palette = "dark16"
# let's keep the contrast very very very clear.
check_contrast = true
[templates]
# dunst templates
dunst.template = "dunstrc.monitor"
dunst.target = "~/.config/dunst/dunstrc"
# one liner for zathura
zathura = { template = 'zath', target = '~/.config/zathura/zathurarc' }
# even a shorter way
glava = { src = 'glava.glsl', dst = '~/.config/glava/rc.glsl' }
# or splited in the dotted syntax
res.src = "xres"
res.dst = "~/.config/Xresources"
# old times, good times. Here I put old pywal templates.
# NOTE THAT BOTH scr AND dst ARE DIRECTORIES!
pywal = { src = "templates/", dst = '~/.cache/wal/', pywal = true }
Templates
A template is simply a file that has placeholders in order to replace them with values. In wallust case, these values can range from either the colors generated, the image/theme served or the backend used. These values are represented by variables, which you can look up inside placeholders.
By using templates you can apply the colors to every program that uses a config file.
There are some templates for some known programs here. If you have a template you want to share, that is the place.
Template Syntax
Here is an overview of the general syntax of a template.
You reference variables in the following syntax:
{{color0}}
For applying a filter you use the pipe character (|) like this:
{{background | strip}}
And if the filter requires an argument:
{{background | lighten(0.3)}}
Remember that filters require a valid type to apply to in these examples we are using colors, which can even be defined literally:
{{ "#4ff4ff" | lighten(0.3)}}
For both, being applied to or as an argument of a filter:
{{ color2 | blend("4ff4ff")}}
You can chain multiple filters, this is why the return type of the filter is important.
{# This will get a color without the initial '#',
0.5 lighter than before and it's complementary variant. }
{{ color2 | strip | lighten(0.5) | complementary}}
If you need to write a literal {{, that doesn't references any variable, you can write literals inside the delimiters:
{{ "{{" }} {{ "}}" }}
You can also use control flow expressions with {% %} delimiters:
{% if backend == "wal" %}
I am using the '{{backend}}' backend, getting a pywal like scheme.
{% elif backend == "fastresize" %}
This backend is called "{{palette}}" and, uses SIMD optimizations and is so fast!
{% else %}
I don't care about any other backends. Be happy!
{% endif %}
Or inline them:
{{ "I'm using the kmeans algo!" if backend == "kmeans" else "Some backend is in use" }}
And yes, you can comment inside your template, the comments won't be rendered in the final target file:
{# This won't be visible! #}
There are more control flow instructions, like the for loop:
{# This will generate color0 = .. to color18,
since `colors` contains background, foreground and cursor variables #}
{% for c in colors %}
color{{- loop.index }} = {{c-}}
{% endfor %}
You can add a minus sign (-) at the start or the end of the delimiters to supress vertical spacing.
The syntax comes from the library being used, which is minijinja, a subset of the template engine 'Jinja2'.
Template Variables
The color types are formated like HEX rgb (e.g. #0A0B0C) by default. However a color literal can be represented in multiple ways, like HEXA rgba (e.g. #0A0B0CFF, where FF is the transparency value) or HEX rgb without the leading # (0a0b0c).
Avaliable values:
color0color1color2color3color4color5color6color7color8color9color10color11color12color13color14color15backgroundforegroundcursorcolors
Additionally, this variable colors returns a vector of all the presented colors in the following order:
Starts with color0 to color15, background, foreground and at the end, (index 18 if starting from 0), cursor.
Other avaliable variables:
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 to 100, displays it from 0.00 to 1.00.
Template Filters
The Jinja2 format calls them 'filters', making a distincion from 'functions'.
hexa: Outputs the color in hexa format: e.g#0A0B0CFF, whereFFis the alpha value.
Example:
{{ color5 | hexa }}
rgb: Output the color in rgb, separated by comas. (e.g.10,11,12)xrgb: Output the color in xrgb, separated by slashes. (e.g0A/0B/0C)strip: Output the color in hex, just like by default, but removes the leading #. (e.g.0A0B0C)red: Outputs only the red value. (e.g.10)green: Outputs only the green value. (e.g.11)blue: Outputs only the blue value. (e.g.12)complementary: Returns the respective complementary color.blend: Takes another color as input, to blend it for the filtered color.
Example:
{{ color2 | blend(color0) | blend("#EEDDFF") }}
lighten: Takes a float (decimal value) as input, from 0.1 to 1.0, that corresponds to the amount to lighten the color by.
Example:
{{ color0 | lighten(0.2) }}
darken: Takes a float (decimal value) as input, from 0.1 to 1.0, that corresponds to the amount to darken the color by.saturate: Takes a float (decimal value) as input, from 0.1 to 1.0, that corresponds to the amount to saturate the color by.
zathurarc config sample
# colors
set default-bg "{{background}}"
# complementary foreground, but keep it light
set default-fg "{{foreground | complementary | lighten(0.5)}}"
# make it a bit lighter than background
set statusbar-bg "{{background | lighten(0.3)}}"
# make it darken by blending to a darken color
set statusbar-fg "{{foreground | blend("#eeeeee")}}"
# use it's complementary
set inputbar-bg "{{background | complementary}}"