From 4ca243c13d21923cc97c00a960e42951b3e4cc15 Mon Sep 17 00:00:00 2001 From: Richard Zink Date: Tue, 22 Sep 2026 11:29:55 +0200 Subject: [PATCH] docs: detailed ash-wallpaper usage guide with parameter reference and recipes --- README.md | 6 +-- tools/ash-wallpaper.md | 110 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 113 insertions(+), 3 deletions(-) create mode 100644 tools/ash-wallpaper.md diff --git a/README.md b/README.md index d6e2623..993fde9 100644 --- a/README.md +++ b/README.md @@ -65,9 +65,9 @@ tools/ash-wallpaper.sh photo.jpg # -> photo-ash.png, dark base PRESET=light tools/ash-wallpaper.sh photo.jpg # light variant base ``` -Tuning via environment variables: `HUE_MAX`/`HUE_MIN` (width of the warm hue -band), `SAT_MIN`/`SAT_MAX` (how colourful a pixel must be to survive), -`EMBER_BOOST` (saturation of highlights), `BASE_LO`/`BASE_HI` (grey ramp). +See **[tools/ash-wallpaper.md](tools/ash-wallpaper.md)** for the full +parameter guide, hue reference of the Ash palette and ready-made recipes +(sunsets, night cities, portraits, near-monochrome). ## Regenerating from the palette diff --git a/tools/ash-wallpaper.md b/tools/ash-wallpaper.md new file mode 100644 index 0000000..4b8630b --- /dev/null +++ b/tools/ash-wallpaper.md @@ -0,0 +1,110 @@ +# `ash-wallpaper.sh` — guide + +Turns a color photo into an **Ash** wallpaper: the image is reduced to +Ash-tinted greys, while warm *ember/gold* highlights (sunsets, fire, lamps, +skin tones) are selectively kept — the "Pleasantville" effect. + +## Quick start + +```sh +tools/ash-wallpaper.sh photo.jpg # -> photo-ash.png (dark base) +PRESET=light tools/ash-wallpaper.sh photo.jpg # -> light Ash base +``` + +Requirements: ImageMagick 6.9+ or 7 (`convert` / `magick`). 4K input takes ~1s. +All knobs are environment variables read once per run — tune one, rerun, +compare. + +## How it works + +1. **Hue band** — the photo's HSL hue channel is thresholded: pixels with + `hue ≤ HUE_MAX` or `hue ≥ HUE_MIN` form the "warm" band (reds, oranges, + golds; the wrap-around at HUE_MIN catches pure crimson reds). +2. **Saturation gate** — inside that band, a saturation ramp decides how much + of the pixel survives: nothing below `SAT_MIN`, everything from `SAT_MAX`. + This is what keeps dull, near-grey warmish pixels as ash. +3. **Softening** — the combined mask is blurred, then re-sharpened with + `SENSITIVITY` so highlights fade into the greys instead of showing hard + cut-out edges. +4. **Base** — a desaturated copy is tinted along the Ash grey ramp + (`BASE_LO` shadows → `BASE_HI` highlights). +5. **Composite** — the original photo, with saturation multiplied by + `EMBER_BOOST`, is laid over the base through the mask. + +## Parameters + +| Variable | Default | Meaning | +|---|---|---| +| `PRESET` | `dark` | Grey ramp of the base. `dark` = `#100f12 → #f3ede1` (void→chalk), `light` = `#b7ae98 → #f2ecdf` (stone→paper). | +| `HUE_MAX` | `13%` | Upper edge of the warm band, in percent of the hue circle (360°). `13%` ≈ 47°, so reds, orange, ember and gold survive; yellows from ≈47° and all greens/blues fall out. | +| `HUE_MIN` | `94%` | Lower edge of the wrap-around band (`≥ 338°`). Catches deep crimson/cherry reds whose hue sits just below 360°. | +| `SAT_MIN` | `12%` | Saturation (HSL) below which a pixel becomes full grey, no matter its hue. Raise to make the image more monochrome (e.g. muted/desaturated photos: `18–25%`). | +| `SAT_MAX` | `45%` | Saturation at which the highlight is fully kept. Pastel skies/candle-lit scenes peak below 45% — lower it (`25–35%`) to let soft colour through; raise it (`55–70%`) to keep only the most saturated embers. | +| `SENSITIVITY` | `8x45%` | `-sigmoidal-contrast` applied to the mask: `contrast x midpoint`. Higher contrast → crisper, more cut-out-looking highlights; lower (e.g. `3x50%`) → dreamier, feathered bleed. The midpoint shifts the whole mask: `>50%` = only the most certain warm pixels, `<50%` = more generous. | +| `EMBER_BOOST` | `130` | Saturation multiplier (%) on the surviving pixels, so the remaining embers read against all that ash. `100` = untouched colours, `160+` = intense glow. Applied to *all* channels of those pixels, so already-saturated fire can clip — reduce if it looks neon. | +| `BASE_LO` / `BASE_HI` | from preset | Exact endpoints of the grey ramp. Any colour works, e.g. `BASE_LO=#1c1b1f BASE_HI=#e6dfd1` for a flatter panel→bone ramp. | + +### Where the Ash palette sits in the hue wheel + +For reference when widening/narrowing the band (hue in IM percent ≈ degrees/360): + +| Colour | Hex | Hue | In band at defaults? | +|---|---|---|---| +| blood | `#c15c46` | 11° (3%) | ✅ | +| rust | `#a86a48` | 21° (6%) | ✅ | +| ember | `#e0914f` | 27° (8%) | ✅ | +| gold | `#d6b46a` | 41° (11%) | ✅ | +| pure yellow | — | 60° (17%) | ❌ (needs `HUE_MAX=17%`) | +| moss | `#8f9a5c` | 69° (19%) | ❌ | +| steel | `#7c9aa1` | 187° (52%) | ❌ | +| rot | `#b47e99` | 330° (92%) | ❌ (needs `HUE_MIN=88%` — usually you *don't* want this) | +| violet | `#a585ac` | 292° (81%) | ❌ | + +## Recipes + +```sh +# Warm sunset landscape, keep the drama (dark preset is the default) +tools/ash-wallpaper.sh sunset.jpg + +# Night city: street lamps are soft yellow-orange, need a wider + softer gate +HUE_MAX=17% SAT_MIN=8% SAT_MAX=60% SENSITIVITY=4x50% tools/ash-wallpaper.sh city.jpg + +# Portrait: only eyes/lips/warm skin glow, everything else ash +SAT_MIN=18% EMBER_BOOST=150 tools/ash-wallpaper.sh portrait.jpg + +# Almost pure grey with faint traces of ember +SAT_MIN=20% SAT_MAX=70% EMBER_BOOST=100 tools/ash-wallpaper.sh photo.jpg + +# Light-themed desktop +PRESET=light tools/ash-wallpaper.sh beach.jpg +``` + +## Batch generation + +```sh +for f in ~/Pictures/vacation/*.jpg; do + tools/ash-wallpaper.sh "$f" +done +``` + +## Using the results + +Drop the generated files into the theme or user backgrounds folder — Omarchy +cycles through them with `Super+Ctrl+Space`: + +```sh +mkdir -p ~/.config/omarchy/backgrounds/ash-dark +cp photo-ash.png ~/.config/omarchy/backgrounds/ash-dark/ +``` + +## Troubleshooting + +- **Highlights cut with hard edges** → lower the `SENSITIVITY` contrast + (first number), e.g. `4x45%`. +- **A warm object disappears** → its hue is outside the band (check the table + above) or its saturation is below `SAT_MIN`. +- **Grey areas look slightly tinted/brown** → those pixels are just inside the + band; raise `SAT_MIN`. +- **Fire/embers look clipped and neon** → lower `EMBER_BOOST` towards 100. +- **Image too bright/dark after tinting** → adjust `BASE_LO`/`BASE_HI` instead + of editing the photo.