docs: add whale, candle, fairground, rain and fireworks samples with measured mask coverage

2026-09-22 11:57:49 +02:00
parent e87d062503
commit 5e2497a62d
11 changed files with 122 additions and 1 deletions
@@ -11,6 +11,15 @@ tools/ash-wallpaper.sh photo.jpg              # -> photo-ash.png
 tools/ash-wallpaper.sh photo.jpg out.png      # custom output path
 ```

+> **Be realistic about the defaults.** This is a ~50-line ImageMagick script,
+> not an AI — it applies one fixed rule (*keep warm, high-saturation pixels;
+> ash everything else*) to your photo. The default settings are tuned for the
+> classic cases (fire, sunsets, lamps). For anything else, expect to tune: the
+> samples below were all post-processed in 2–3 iterations of `HUE_MAX` /
+> `SAT_MIN` / `SAT_MAX`. A motif with little warm colour (e.g. a whale) simply
+> has little to keep — no parameter will invent highlights that aren't in the
+> source.
+
 Requirements: ImageMagick 6.9+ or 7 (`convert` / `magick`). 4K input takes ~10s.
 All knobs are environment variables read once per run — tune one, rerun,
 compare.
@@ -91,7 +100,11 @@ tools/ash-wallpaper.sh campfire.jpg
 Source: [“Closeup of raging flames in a large bonfire”](https://commons.wikimedia.org/wiki/File:Closeup_of_raging_flames_in_a_large_bonfire._-_Flickr_-_shixart1985.jpg)
 by Nenad Stojkovic, [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/).

-### Autumn foliage
+### Autumn foliage — warm-dominated scene
+
+The whole park is bathed in warm orange, so ~90 % of the frame is "warm":
+like the fireworks case below, the result stays close to the original. Narrow
+the band (`HUE_MAX=8%`) to let only the saturated ember oranges through:

 ```sh
 tools/ash-wallpaper.sh autumn.jpg
@@ -135,6 +148,114 @@ SAT_MIN=18% EMBER_BOOST=150 tools/ash-wallpaper.sh portrait.jpg
 Source: [“Woman redhead natural portrait 1”](https://commons.wikimedia.org/wiki/File:Woman_redhead_natural_portrait_1.jpg)
 by dusdin (Flickr), cropped by Gridge, [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/).

+### Candle light
+
+A dark frame with a warm source — the ideal case; the flame and its glow stay,
+everything else turns to ash:
+
+```sh
+EMBER_BOOST=120 tools/ash-wallpaper.sh candles.jpg
+```
+
+| Original | Ash |
+|---|---|
+| ![candles original](../images/samples/candles-original.jpg) | ![candles ash](../images/samples/ash-candles.jpg) |
+
+Source: [“Alive”](https://commons.wikimedia.org/wiki/File:Alive_(61565557).jpeg)
+by Ranit Sanyal, [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/).
+
+### Fairground at night
+
+Neon rides: the white structure greys out, the warm cabin lighting and the red
+LED strips survive. Uses the night recipe:
+
+```sh
+HUE_MAX=17% SAT_MIN=8% SAT_MAX=60% SENSITIVITY=4x50% \
+  tools/ash-wallpaper.sh kirmes.jpg
+```
+
+| Original | Ash |
+|---|---|
+| ![fairground original](../images/samples/kirmes-original.jpg) | ![fairground ash](../images/samples/ash-kirmes.jpg) |
+
+Source: [“Nighttime ferris wheel gondolas … Pattaya fairground”](https://commons.wikimedia.org/wiki/File:DFC_4677_Nighttime_ferris_wheel_gondolas_glow_against_the_dark_sky_at_a_Pattaya_fairground_in_Nong_Pla_Lai_Bang_Lamung_District.jpg)
+by PattayaPatrol, [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
+
+### Rainy night in Moscow
+
+Red neon and traffic-light reflections are all the colour left — the same
+night recipe as above:
+
+```sh
+HUE_MAX=17% SAT_MIN=8% SAT_MAX=60% SENSITIVITY=4x50% \
+  tools/ash-wallpaper.sh rain.jpg
+```
+
+| Original | Ash |
+|---|---|
+| ![rain original](../images/samples/rain-original.jpg) | ![rain ash](../images/samples/ash-rain.jpg) |
+
+Source: [“Late autumn rainy night in Moscow”](https://commons.wikimedia.org/wiki/File:Late_autumn_rainy_night_in_Moscow_(54889230493).jpg)
+by kishjar?, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+### Humpback whale — the low-highlight case
+
+A daylight scene with almost no warm colour: only 0.4 % of the frame sits in
+the warm band, so the result is (intentionally) almost fully grey. Nothing is
+broken — there is simply little for the script to keep:
+
+```sh
+tools/ash-wallpaper.sh whale.jpg
+```
+
+| Original | Ash |
+|---|---|
+| ![whale original](../images/samples/whale-original.jpg) | ![whale ash](../images/samples/ash-whale.jpg) |
+
+Source: [“Humpback Breaching”](https://commons.wikimedia.org/wiki/File:HIHWNMS_-_Humpback_Breaching_(33591142200).jpg)
+by NOAA National Marine Sanctuaries — public domain.
+
+### Fireworks — the negative case
+
+Here the *whole* sky is lit red by smoke, so 96 % of the pixels are "warm" and
+the mask covers everything: the image is barely greyscaled at all. When the
+warm colour is the background rather than an accent, the effect has nothing to
+work with. Pick a different shot, or narrow the band (`HUE_MAX=8%`) to keep
+only the brightest sparks:
+
+```sh
+tools/ash-wallpaper.sh fireworks.jpg
+```
+
+| Original | Ash |
+|---|---|
+| ![fireworks original](../images/samples/fireworks-original.jpg) | ![fireworks ash](../images/samples/ash-fireworks.jpg) |
+
+Source: [“Anjuna Beach, Goa, New Year's Eve, Fireworks in the sky”](https://commons.wikimedia.org/wiki/File:Anjuna_Beach,_Goa,_India,_New_Year%27s_Eve,_Fireworks_in_the_sky.jpg)
+by Vyacheslav Argenberg, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+### How much of each frame survived
+
+The share of pixels the warmth mask keeps (measured with the **default** gate;
+the night-recipe samples were run with a wider band). A quick way to read the
+samples above, and a useful sanity check when tuning your own photo:
+
+| Motif | Warm-pixel share (default) | Result |
+|---|---|---|
+| Humpback whale | 0.4 % | almost fully ash |
+| Fairground | 4.2 % | ash with neon accents |
+| City at night (ISS) | 17.0 % | ash with a glowing street grid |
+| Rainy night Moscow | 17.2 % | ash with red neon |
+| Sunset | 19.6 % | ash with a warm horizon |
+| Campfire | 40.6 % | dark ash, glowing flames |
+| Redhead portrait | 47.1 % | ash with warm hair/lips |
+| Candle light | 73.2 % | dark ash with a glowing flame |
+| Autumn foliage | 90.0 % | barely greyed — warm *is* the scene |
+| Fireworks | 96.4 % | barely greyed — warm *is* the scene |
+
+Rule of thumb: below ~25 % the effect is pronounced; above ~70 % the script
+has little to grey out and you should narrow `HUE_MAX` or pick another frame.
+
 ## Recipes

 ```sh