# Hellwal - Fast, Extensible Color Palette Generator
### Star History
Click to expand star history
## Installation
1. **Archlinux**:
```sh
yay -S hellwal
```
2. **Mac/Linux via Homebrew**:
```sh
brew install hellwal
```
3. **NixOS**, nixpkgs **unstable**:
```nix
environment.systemPackages = [
pkgs.hellwal
];
```
## Building
Clone git repo, run make command and you are ready to go! - you just need a C compiler and gnumake!
```sh
git clone https://github.com/danihek/hellwal && cd hellwal && make
```
## How to use?
Run this with your wallpaper image:
```sh
hellwal -i [image]
```
You can also randomly pick an image from a given directory like this:
```sh
hellwal -i --random
```
Generated templates are saved in `~/.cache/hellwal/`.
## Templates
**[INFO]** - if you got hellwal from the **AUR**, examples of default templates can be
found in `/usr/share/docs/`.
There are also examples in the [templates folder](./templates). They look more-less like this:
```sh
# Main
background='%%background%%'
foreground='%%foreground%%'
# Path
wallpaper_path='%%wallpaper%%'
# Colors
color0='%%color0.hex%%'
color1='%%color1.hex%%'
# ... and so on and so forth.
color15='%%color15.hex%%'
# RGB
backgroundRGB='%%background.rgb%%'
foregroundRGB='%%foreground.rgb%%'
color15butRGB='%%color15.rgb%%'
```
You can get any generated color for values 0 to 15.
After the color keyword, you can specify the format: hex, rgb, or a single rgb channel.
By default, the template output is in hex.
### Available color template formats:
| Type | Input | Output |
| ---- | ---------- | ------- |
| hex | color0.hex | 000000 |
| rgb | color0.rgb | 0, 0, 0 |
| r | color0.r | 0 |
| g | color0.g | 0 |
| b | color0.b | 0 |
### Additional variables accepted by templates
Alongside colors, you can specify some variables to make them more suitable for your needs.
For now these variables are available:
| Variable | Description | Usage |
| -------- | ---------------------- | ---------------------------- |
| alpha | Set transparency value | `%% color1.hex alpha=0.5 %%` |
`alpha` is ignored for single rgb channels.
### Color operations and filters
Chain HSL (hue, saturation, lightness) adjustments and RGB filters without changing
the base palette. Operations apply from left to right:
```text
%% color1.saturate(0.2).lighten(0.1).hex %%
%% background.sepia(0.5).contrast(1.2).rgb alpha=0.8 %%
```
| Operation | Description |
| --- | --- |
| `saturate(x)` / `desaturate(x)` | Add / subtract saturation by `x` (0–1). |
| `lighten(x)` / `darken(x)` | Add / subtract lightness by `x` (0–1). |
| `saturation(x)` / `lightness(x)` | Set saturation / lightness to `x` (0–1). |
| `rotate(degrees)` | Rotate hue in either direction, wrapping at 360°. |
| `complement()` | Rotate hue by 180°. |
| `grayscale()` | Remove saturation while preserving lightness. |
| `invert()` | Invert each RGB channel (`255 - channel`). |
| `sepia(amount)` | Apply a sepia tint: 0 is unchanged, 1 is full sepia. |
| `contrast(factor)` | Scale RGB contrast around mid-gray: 0 is gray, 1 is unchanged. |
| `brightness(factor)` | Multiply RGB channels: 0 is black, 1 is unchanged. |
Factors must be nonnegative; all arguments must be finite. Results clamp to the
valid color range after each operation. HSL adjustments add percentage points:
`lighten(0.2)` adds 20 points of lightness. RGB filters work on sRGB channels.
Use `color0`–`color15` or the existing color aliases. Finish the chain with `.hex`,
`.rgb`, `.r`, `.g`, or `.b` (default: hex), then optionally append `alpha=0.5`.
Hex output omits `#`; alpha is ignored for individual channels. Invalid operation
expressions warn and remain visible in the generated file.
## JSON
You can use the `--json` argument to suppress any other output and write colors to `stdout` in JSON format.
You can then manipulate the output with `jq`. For example:
```sh
hellwal -i [wallpaper] --json | jq '.'
```
## Themes
You can set your own theme, re-run it anytime and apply it to your config or other programs!
It can be a previously generated palette from an image,
[gruvbox](https://github.com/morhetz/gruvbox),
[Tokyo Night](https://github.com/tokyo-night/tokyo-night-vscode-theme),
or anything you want! For example, gruvbox theme:
```sh
%% color0 = #282828 %%
%% color1 = #cc241d %%
%% color2 = #98971a %%
%% color3 = #d79921 %%
%% color4 = #458588 %%
%% color5 = #b16286 %%
%% color6 = #689d6a %%
%% color7 = #a89984 %%
%% color8 = #928374 %%
%% color9 = #fb4934 %%
%% color10 = #b8bb26 %%
%% color11 = #fabd2f %%
%% color12 = #83a598 %%
%% color13 = #d3869b %%
%% color14 = #8ec07c %%
%% color15 = #ebdbb2 %%
```
Save the text above as a file or copy [gruvbox](./themes/gruvbox.hellwal) from this repo and
just run hellwal:
```sh
hellwal --theme ./themes/gruvbox.hellwal
```
I recommend putting all themes in the default theme folder `~/.config/hellwal/themes`.
This way, you can provide the theme name without specifying the path, and hellwal will pick it
up automatically. Of course if you want, you can also set a different theme folder.
For example:
```sh
hellwal -t gruvbox.hellwal --theme-folder ~/dotfiles/configs/hellwal/themes
```
### Replace selected theme colors with image colors
```sh
hellwal -i wallpaper.jpg -t gruvbox.hellwal --override-colors color1,color2,background
```
This copies matching image-palette slots into the theme: image color1 replaces
theme color1, and so on. Select `color0`–`color15`, `background` (color0), or
`foreground`, `cursor`, and `border` (all color15). Separate names with commas;
duplicates are harmless, and repeated `--override-colors` options combine their
selections. Empty or unknown selectors are errors.
Image colors are sorted and their bright variants prepared before copying.
Without adjustment flags, unselected theme colors stay unchanged and mixed mode
does **not** automatically darken the palette. Explicit modes, inversion, offsets,
grayscale, static foreground/background, and contrast checks apply to the **whole
merged palette afterward**, so they can also change unselected colors. For example:
```sh
hellwal -i wallpaper.jpg -t gruvbox.hellwal --override-colors color1,color2 --light
```
Both `--image` and `--theme` are required. Theme paths, named themes, and
`--theme-folder` work as usual. With `--random`, only the image is chosen randomly;
the specified theme stays fixed. `wallpaper` in templates/JSON refers to the image.
The source theme is never rewritten, and only the raw image palette is cached.
Combining image and theme without `--override-colors` remains an error, and
`--dominant-background` still cannot be combined with themes.
## NEON Mode
Neon mode boosts colors to make them look more vibrant and bold. Sometimes it's a pain in the EYE,
but it often looks better. Turned **off** by default.
```sh
hellwal -i [wallpaper] --neon-mode
```
## Modes
You can select `-d`/`--dark` or `-l`/`--light` mode on any given image, theme, etc., no
matter if it's generated from an image or from a theme file. There is also `--color` mode.
### Dark mode (on by default)
```sh
hellwal -i [wallpaper] --dark
```
#### Dominant background
Use the wallpaper's most common color for the background instead of the
darkest palette color:
```sh
hellwal -i [wallpaper] --dominant-background
```
### Light mode
```sh
hellwal -i [wallpaper] --light
```
### color mode (crazyy one)
```sh
hellwal -i [wallpaper] --color
```
The best thing about it is that you are able to combine all of these together. Usually it's
not a good idea, but sometimes you can achieve some crazy color combinations!
```sh
hellwal -i [wallpaper] --color --light --dark
```
---
Also, you have a couple of cool arguments to manipulate how colors will be computed:
- you can darken all colors by specifying `--dark-offset` from 0-1 (the higher the value, the darker the colors):
```sh
hellwal -i [wallpaper] --light --dark-offset 0.5
```
- same with `--bright-offset` (the higher the value, the brighter the colors):
```sh
hellwal -i [wallpaper] --bright-offset 0.5
```
- invert colors with `--invert`:
```sh
hellwal -i [wallpaper] --light --invert
```
- specify grayscale, if you want monochromatic colors, with `--gray-scale`:
```sh
hellwal -i [wallpaper] --color --gray-scale 0.8
```
- ensure colors are readable against the background with `--check-contrast`:
```sh
hellwal -i [wallpaper] --check-contrast
```
## Scripts
With `--script` or `-s` you can run a script (or any shell command) after hellwal.
**Note**: it will only run if hellwal does not encounter any errors.
### On a side note:
If you want your new terminals to open with a previously generated or specified color palette,
add these templates to your `~/.config/hellwal/templates/` folder:
- [variables.sh](./templates/variables.sh)
- [terminal.sh](./templates/terminal.sh)
Run hellwal with an image or theme to generate the output scripts from the templates.
Then in `.bashrc`, add following lines:
```sh
source ~/.cache/hellwal/variables.sh
sh ~/.cache/hellwal/terminal.sh
```
### Alternatively if you use fish:
- [variablesfish.fish](./templates/variablesfish.fish)
- [terminal.sh](./templates/terminal.sh)
Then add this to your fish config:
```sh
source ~/.cache/hellwal/variablesfish.fish
sh ~/.cache/hellwal/terminal.sh
```
# Showcase
# Special thanks:
- [dylanaraps](https://github.com/dylanaraps) - for [pywal](https://github.com/dylanaraps/pywal) and other amazing stuff he created.