omarchy-ash-theme/tools/ash-wallpaper.md

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

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

# 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

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:

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.