The working thread

cd ~/work/pixelart-studies/pedagogy && ls -la shared observation 2>&1; cat shared/TASK.md

# output:
observation:
total 0
drwxr-xr-x  2 user  staff   64 Sep 25 18:02 .
drwxr-xr-x  7 user  staff  224 Sep 25 18:02 ..

shared:
total 784
drwxr-xr-x  4 user  staff     128 Sep 25 18:02 .
drwxr-xr-x  7 user  staff     224 Sep 25 18:02 ..
-rw-r--r--  1 user  staff    1014 Sep 25 18:02 TASK.md
-rw-------  1 user  staff  393362 Sep 25 18:02 ferrari_alpine_tarn_dusk.png
# The task (identical for every study)

Paint, as painterly pixel art in the manner of Mark Ferrari (see ferrari_alpine_tarn_dusk.png beside this file):

**A granite boulder resting in a grass bank at the edge of a still mountain tarn, at dusk.**

- Boulder: 1–3 m, rounded by weathering, partly sunk in the bank. Grass and sedge grow up around its foot.
- The bank slopes gently down to the water's edge. The water reflects the boulder, bank and sky.
- Light: low sun from the left, warm; the sky is pink to violet.
- Frame: 320×180 native pixels, shown upscaled 3× with nearest neighbour. Palette of at most 32 colours, chosen deliberately.
- Camera: a low angle, about 10° down, a few metres away.

The deliverable is a METHOD, not one image. Write a program that paints this subject from parameters, and output SHEETS that sweep them:

- boulder size (small / medium / large);
- light direction (left, front, right, back-lit);
- distance (close, 10 m, 40 m);
- random seed.

Every cell should look painted.

cd ~/work/pixelart-studies/pedagogy && python3 -c "
from PIL import Image; import numpy as np
im=Image.open('shared/ferrari_alpine_tarn_dusk.png'); print(im.size, im.mode)
a=np.array(im.convert('RGB')); c=np.unique(a.reshape(-1,3),axis=0,return_counts=True); print(len(c[0]))
# detect scale
d=np.abs(np.diff(a.astype(int),axis=1)).sum(2)>0; print(d.mean())
"; which curl python3; python3 -c "import scipy, skimage; print('ok')"

# output:
(1268, 938) RGBA
172
0.2887653288411926
/usr/bin/curl
~/miniconda3/bin/python3
ok

cd ~/work/pixelart-studies/pedagogy && python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('shared/ferrari_alpine_tarn_dusk.png').convert('RGB')).astype(int)
# horizontal run lengths
row=a[800]; ch=np.any(row[1:]!=row[:-1],axis=1); idx=np.where(ch)[0]; print(np.diff(idx)[:60])
col=a[:,300]; ch=np.any(col[1:]!=col[:-1],axis=1); idx=np.where(ch)[0]; print(np.diff(idx)[:60])
c,n=np.unique(a.reshape(-1,3),axis=0,return_counts=True); o=np.argsort(-n); print(len(c)); print([ (tuple(c[i]),n[i]) for i in o[:48]])
"

# output:
[4 8 2 4 2 4 2 2 2 2 2 2 2 6 2 2 2 6 4 2 2 2 6 2 2 8 2 2 4 2 2 4 6 2 2 2 2
 6 2 2 2 2 2 6 4 2 2 4 4 6 4 2 2 2 6 2 2 2 6 4]
[ 2  6  2  2  2  2  2  2  2  2  2  2  2  2  6  2  2  2  4  2  2  2  2  2
  2  4  2  2  4 10  2  2  2  2  2 14  2  2  4 18  2  2  2 12  2 10  2  2
  2  2  2  2  2 10  4 18  2  4  2 10]
172
[((0, 0, 0), 231736), ((136, 101, 50), 73240), ((62, 59, 23), 63156), ((196, 131, 70), 56148), ((28, 31, 4), 55316), ((207, 161, 186), 52260), ((115, 92, 35), 46832), ((46, 43, 32), 40992), ((200, 165, 193), 33028), ((66, 63, 42), 30004), ((196, 134, 76), 24728), ((213, 162, 179), 24444), ((217, 162, 175), 24116), ((25, 31, 4), 23964), ((58, 55, 48), 23960), ((224, 162, 175), 22448), ((28, 31, 24), 21304), ((106, 80, 40), 20532), ((227, 162, 168), 19296), ((235, 167, 165), 17276), ((10, 34, 10), 15108), ((235, 167, 161), 14532), ((103, 84, 109), 13332), ((68, 52, 74), 11056), ((235, 170, 158), 10900), ((87, 68, 43), 10868), ((49, 39, 54), 9972), ((28, 31, 20), 9360), ((79, 60, 63), 8788), ((239, 141, 114), 7496), ((128, 85, 106), 7404), ((68, 56, 74), 6652), ((60, 63, 45), 6228), ((178, 152, 188), 6032), ((106, 80, 59), 5768), ((236, 174, 155), 5552), ((103, 80, 87), 5528), ((173, 141, 165), 5008), ((132, 93, 110), 4724), ((194, 168, 186), 4464), ((88, 72, 93), 3300), ((64, 48, 55), 3248), ((217, 166, 175), 3160), ((190, 164, 186), 3124), ((243, 175, 155), 3092), ((61, 48, 69), 2892), ((53, 40, 58), 2716), ((87, 68, 97), 2664)]

cd ~/work/pixelart-studies/pedagogy/observation && mkdir -p refs studies ferrari out && python3 -c "
from PIL import Image; import numpy as np
im=Image.open('../shared/ferrari_alpine_tarn_dusk.png'); a=np.array(im); print(np.unique(a[...,3],return_counts=True))
n=a[::2,::2]; Image.fromarray(n).save('ferrari/native.png'); print(n.shape)
rgb=n[...,:3].reshape(-1,3); c,k=np.unique(rgb[n[...,3].reshape(-1)>0],axis=0,return_counts=True); print(len(c))
"

# output:
(array([255], dtype=uint8), array([1189384]))
(469, 634, 4)
172

curl -s -A "PixelStudy/1.0 ((email))" "https://commons.wikimedia.org/w/api.php?action=query&list=search&srsearch=granite+boulder+lake+sunset&srnamespace=6&srlimit=20&format=json" | python3 -c "import json,sys; [print(r['title']) for r in json.load(sys.stdin)['query']['search']]"

# output:
File:Breakers and granite (IA cu31924014340453).pdf
File:Breakers and granite (IA breakersgranit00fletrich).pdf
File:The Granite monthly - a magazine of literature, history and state progress (IA granitemonthlyma1910conc).pdf
File:The Granite monthly - a magazine of literature, history and state progress (IA granitemonthlyma1898conc).pdf
File:The story of a boulder; or, Gleanings from the note-book of a field geologist (IA storyofboulderor00geikrich).pdf
File:A summer in New Hampshire; out-of-door songs for all who love the granite state; (IA summerinnewhamps00curr).pdf
File:Wayside notes on the Sunset route (IA sunsetwaysidenot00soutrich).pdf
File:Wayside notes along Sunset route, east bound (IA waysidenotesalon00soutrich).pdf
File:Lake Sunapee.. (IA lakesunapee00bost).pdf
File:Conneaut Lake (IA conneautlake00lave).pdf
File:Exploration and survey of the Valley of the Great Salt Lake of Utah - including a reconnoissance of a new route through the Rocky Mountains. (IA explorationsurve002stan).pdf
File:Lake scenery of England (IA lakesceneryofeng00pynerich).pdf
File:Como and Italian lake-land (IA comoitalianlakel00lunduoft).pdf
File:Cooperstown and Otsego Lake; descriptive sketch of the village made famous by J. Fenimore Cooper, in his Leatherstocking Tales, with views of village and lake (IA cooperstownotseg00coop).pdf
File:Salt Lake City, with a sketch of the route of the Union and Central Pacific Railroads, from Omaha to Salt Lake City, and from Ogden to San Francisco (IA saltlakecitywith00sava).pdf
File:Brochure of Owl's Head Mountain House, Lake Memphremagog (IA brochureofowlshe00unse).pdf
File:Brochure of Owl's head mountain house, Lake Memphremagog .. (IA brochureofowlshe00owls).pdf
File:The lake regions of Central Africa - a picture of exploration (IA lakeregionsofcen21860burt).pdf
File:Scenic gems of the White Mountains (1900) (14783453065).jpg
File:Cooperstown and Otsego Lake; descriptive sketch of the village made famous (IA cooperstownotseg00coo).pdf

mkdir -p ~/work/pixelart-studies/pedagogy/observation/refs/cand && cat > ~/work/pixelart-studies/pedagogy/observation/fetch_refs.py <<'EOF'
# Search Wikimedia Commons and download 800px thumbnails of candidate reference photos.
import json, sys, os, re, urllib.request, urllib.parse, time
UA = {"User-Agent": "PixelStudy/1.0 (painting study; contact via commons)"}
OUT = os.path.join(os.path.dirname(__file__), "refs", "cand")
def get(url):
    req = urllib.request.Request(url, headers=UA)
    return urllib.request.urlopen(req, timeout=60).read()
def search(q, n=12):
    p = dict(action="query", generator="search", gsrsearch=q + " filetype:bitmap", gsrnamespace=6,
             gsrlimit=n, prop="imageinfo", iiprop="url|extmetadata", iiurlwidth=800, format="json")
    d = json.loads(get("https://commons.wikimedia.org/w/api.php?" + urllib.parse.urlencode(p)))
    return list(d.get("query", {}).get("pages", {}).values())
if __name__ == "__main__":
    tag = sys.argv[1]; q = " ".join(sys.argv[2:])
    for i, pg in enumerate(search(q)):
        ii = pg["imageinfo"][0]; url = ii.get("thumburl") or ii["url"]
        name = re.sub(r"[^A-Za-z0-9]+", "_", pg["title"][5:])[:60]
        fn = os.path.join(OUT, f"{tag}_{i:02d}_{name}.jpg")
        if os.path.exists(fn): continue
        try:
            open(fn, "wb").write(get(url)); print(fn, pg["title"])
            lic = ii.get("extmetadata", {}).get("LicenseShortName", {}).get("value", "?")
            art = re.sub("<[^>]+>", "", ii.get("extmetadata", {}).get("Artist", {}).get("value", "?"))
            with open(os.path.join(OUT, "credits.tsv"), "a") as f: f.write(f"{os.path.basename(fn)}\t{pg['title']}\t{art.strip()}\t{lic}\t{ii['descriptionurl']}\n")
        except Exception as e: print("ERR", e)
        time.sleep(0.5)
EOF
cd ~/work/pixelart-studies/pedagogy/observation && for q in "boulder:glacial erratic boulder grass" "tarn:alpine tarn boulder" "bldsun:boulder evening light meadow" "granite:granite boulder meadow" "lakeshore:mountain lake shore grass reflection" "sedge:sedge lake shore" "dusk:mountain lake dusk reflection" "sierra:Sierra Nevada lake granite boulders sunset"; do nice -n 10 python3 fetch_refs.py ${q%%:*} ${q#*:} 2>&1 | tail -3; done; ls refs/cand | wc -l

# output:
~/work/pixelart-studies/pedagogy/observation/refs/cand/boulder_00_Glacial_erratic_at_Martha_Lake_Airport_Park_jpg.jpg File:Glacial erratic at Martha Lake Airport Park.jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand/tarn_00_Rock_climbing_in_the_English_Lake_District_1900_14590762138_.jpg File:Rock-climbing in the English Lake District (1900) (14590762138).jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand/tarn_01_Tarn_GeoDIL_number_2202_jpg.jpg File:Tarn (GeoDIL number - 2202).jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand/tarn_02_The_Quarterly_journal_of_the_Geological_Society_of_London_18.jpg File:The Quarterly journal of the Geological Society of London (1862) (14577808939).jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand/granite_09_Tuolumne_Meadows_Lyell_Fork_of_the_Tuolumne_River_05_jpg.jpg File:Tuolumne Meadows - Lyell Fork of the Tuolumne River - 05.jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand/granite_10_Tuolumne_Meadows_Lyell_Fork_of_the_Tuolumne_River_06_JPG.jpg File:Tuolumne Meadows - Lyell Fork of the Tuolumne River - 06.JPG
~/work/pixelart-studies/pedagogy/observation/refs/cand/granite_11_Tuolumne_Meadows_bw_jpg.jpg File:Tuolumne Meadows bw.jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand/lakeshore_01_Canoe_parked_on_the_shore_of_an_Idaho_mountain_lake_at_sunri.jpg File:Canoe parked on the shore of an Idaho mountain lake at sunrise - Flickr - Knowles Gallery.jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand/lakeshore_02_Morning_in_the_Meadow_Lake_Mary_CA_2016_32750834010_jpg.jpg File:Morning in the Meadow, Lake Mary, CA 2016 (32750834010).jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand/lakeshore_03_Tree_reflection_Flickr_ohefin_jpg.jpg File:Tree reflection - Flickr - ohefin.jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand/sedge_09_The_book_of_grasses_an_illustrated_guide_to_the_common_grass.jpg File:The book of grasses - an illustrated guide to the common grasses, and the most common of the rushes and sedges (1912) (14740595036).jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand/sedge_10_Upper_Lake_in_Glendalough_Wicklow_Ireland_jpg.jpg File:Upper Lake in Glendalough, Wicklow, Ireland.jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand/sedge_11_Wetland_Grasses_8235708195_jpg.jpg File:Wetland Grasses (8235708195).jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand/dusk_09_Nautical_twilight_sunset_over_Sandy_Lake_DSCF3005_jpg.jpg File:Nautical twilight sunset over Sandy Lake (DSCF3005).jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand/dusk_10_Padarn_lake_mirror_view_at_dusk_38057969665_jpg.jpg File:Padarn lake mirror view at dusk. (38057969665).jpg

cd ~/work/pixelart-studies/pedagogy/observation && for q in "rock:rock lake shore golden hour" "erratic:erratic boulder sunset" "boulders2:boulder field alpine meadow evening" "still:still lake reflection mountain evening" "grassbank:grassy bank pond reflection" "lakegrass:lake shore grass sunset" "bldlake:boulder in lake reflection" "alpen:Bergsee Felsblock Abendlicht" "sunrisebld:boulder sunrise light" "backlit:backlit grass sunset" "ponds:tarn Lake District evening" "yosemite:Tuolumne Meadows boulder sunset"; do nice -n 10 python3 fetch_refs.py ${q%%:*} ${q#*:} >/dev/null 2>&1; done; ls refs/cand/*.jpg | wc -l
cat > contact.py <<'EOF'
import sys, glob, os
from PIL import Image, ImageDraw
files = sorted(glob.glob(sys.argv[1])); out = sys.argv[2]; W = 256; cols = 6
rows = (len(files)+cols-1)//cols; sheet = Image.new("RGB", (cols*W, rows*(W+14)), "white"); d = ImageDraw.Draw(sheet)
for i, f in enumerate(files):
    try: im = Image.open(f).convert("RGB")
    except Exception: continue
    im.thumbnail((W, W)); x, y = (i%cols)*W, (i//cols)*(W+14)
    sheet.paste(im, (x, y)); d.text((x+2, y+W), f"{i} {os.path.basename(f)[:38]}", fill="black")
sheet.save(out); print(len(files))
EOF
python3 contact.py 'refs/cand/*.jpg' studies/contact_all.png

# output:
94
94

cd ~/work/pixelart-studies/pedagogy/observation && python3 -c "
from PIL import Image; im=Image.open('studies/contact_all.png'); w,h=im.size; print(w,h)
n=3; 
for i in range(n): im.crop((0,i*h//n,w,(i+1)*h//n)).save(f'studies/contact_{i}.png')"

# output:
1536 4320

cd ~/work/pixelart-studies/pedagogy/observation && mkdir -p refs/cand2 && sed -i '' 's#"refs", "cand"#"refs", os.environ.get("CAND","cand")#' fetch_refs.py && for q in "a:boulder golden hour grass" "b:rock meadow sunset light" "c:Joshua Tree boulders sunset" "d:alpine lake sunset shore rocks" "e:boulder sunset Sierra" "f:erratic boulder evening" "g:mountain lake alpenglow reflection shore" "h:lake shore rocks evening light reflection" "i:granite boulder sunset" "j:meadow boulder late afternoon" "k:rock in grass shadow" "l:tarn sunset" "m:Bergsee Sonnenuntergang Ufer" "n:boulder backlit sunset" "o:stone meadow sunrise"; do CAND=cand2 nice -n 10 python3 fetch_refs.py ${q%%:*} ${q#*:} >/dev/null 2>&1; done; ls refs/cand2/*.jpg | wc -l; python3 contact.py 'refs/cand2/*.jpg' studies/contact2.png; python3 -c "
from PIL import Image; im=Image.open('studies/contact2.png'); w,h=im.size; n=(h+1439)//1440
for i in range(n): im.crop((0,i*1440,w,min(h,(i+1)*1440))).save(f'studies/contact2_{i}.png')
print(n)"

# output:
57
57
2

cd ~/work/pixelart-studies/pedagogy/observation && mkdir -p refs/cand3 && for q in "a:boulder lake edge grass" "b:pond bank grass evening reflection" "c:alpine lake grass shore evening" "d:boulder meadow alpine lake" "e:lake shore stones reflection calm evening" "f:glacial erratic lake shore" "g:rock grass lake Norway evening" "h:Scotland lochan boulder" "i:boulder heather sunset" "j:lake reflection grass bank sunset Flickr"; do CAND=cand3 nice -n 10 python3 fetch_refs.py ${q%%:*} ${q#*:} >/dev/null 2>&1; done; ls refs/cand3/*.jpg | wc -l; python3 contact.py 'refs/cand3/*.jpg' studies/contact3.png; python3 -c "
from PIL import Image; im=Image.open('studies/contact3.png'); w,h=im.size; n=(h+1439)//1440
for i in range(n): im.crop((0,i*1440,w,min(h,(i+1)*1440))).save(f'studies/contact3_{i}.png')
print(n)"

# output:
7
7
1

cd ~/work/pixelart-studies/pedagogy/observation && for q in "k:lochan boulder" "l:lake boulder reflection" "m:tarn reflection" "n:erratic lake" "o:pond reflection sunset grass" "p:lake shore sedge" "q:mossy boulder meadow" "r:alpine lake evening" "s:boulder grass shadow" "t:rock reflection calm lake" "u:mountain pond grass"; do CAND=cand3 nice -n 10 python3 fetch_refs.py ${q%%:*} ${q#*:} >/dev/null 2>&1; done; ls refs/cand3/*.jpg | wc -l; python3 contact.py 'refs/cand3/*.jpg' studies/contact3.png; python3 -c "
from PIL import Image; im=Image.open('studies/contact3.png'); w,h=im.size; n=(h+1439)//1440
for i in range(n): im.crop((0,i*1440,w,min(h,(i+1)*1440))).save(f'studies/contact3_{i}.png')
print(n)"

# output:
7
7
1

cd ~/work/pixelart-studies/pedagogy/observation && CAND=cand3 python3 fetch_refs.py k lochan boulder

# output:
~/work/pixelart-studies/pedagogy/observation/refs/cand3/k_00_Boulder_near_Lochan_Bealach_Cornaidh_geograph_org_uk_212915_.jpg File:Boulder, near Lochan Bealach Cornaidh - geograph.org.uk - 212915.jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand3/k_01_Boulder_and_lochan_below_Coire_a_Bh_steir_geograph_org_uk_54.jpg File:Boulder and lochan below Coire a' Bhàsteir - geograph.org.uk - 5405621.jpg
ERR HTTP Error 429: Too many requests - please contact noc@wikimedia.org to discuss a less disruptive approach or instead use thumbnail images in sizes listed on https://w.wiki/GHai. (0c640b1)
~/work/pixelart-studies/pedagogy/observation/refs/cand3/k_03_Boulders_in_Lochan_Uaine_geograph_org_uk_8353748_jpg.jpg File:Boulders in Lochan Uaine - geograph.org.uk - 8353748.jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand3/k_04_Boulders_on_slope_and_in_lochan_geograph_org_uk_5538404_jpg.jpg File:Boulders on slope and in lochan - geograph.org.uk - 5538404.jpg
ERR HTTP Error 429: Too many requests - please contact noc@wikimedia.org to discuss a less disruptive approach or instead use thumbnail images in sizes listed on https://w.wiki/GHai. (0c640b1)
ERR HTTP Error 429: Too many requests - please contact noc@wikimedia.org to discuss a less disruptive approach or instead use thumbnail images in sizes listed on https://w.wiki/GHai. (0c640b1)
~/work/pixelart-studies/pedagogy/observation/refs/cand3/k_07_Large_boulder_view_towards_Lochan_Meall_a_Phuill_geograph_or.jpg File:Large boulder ^ view towards Lochan Meall a' Phuill - geograph.org.uk - 2398569.jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand3/k_08_Large_boulder_east_of_Lochan_Caol_Fada_geograph_org_uk_28569.jpg File:Large boulder east of Lochan Caol Fada - geograph.org.uk - 2856939.jpg
~/work/pixelart-studies/pedagogy/observation/refs/cand3/k_09_Prominent_boulder_by_Lochan_na_h_Earba_geograph_org_uk_45209.jpg File:Prominent boulder by Lochan na h-Earba - geograph.org.uk - 4520995.jpg
ERR HTTP Error 429: Too many requests - please contact noc@wikimedia.org to discuss a less disruptive approach or instead use thumbnail images in sizes listed on https://w.wiki/GHai. (0c640b1)
ERR HTTP Error 429: Too many requests - please contact noc@wikimedia.org to discuss a less disruptive approach or instead use thumbnail images in sizes listed on https://w.wiki/GHai. (0c640b1)

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s=open('fetch_refs.py').read()
s=s.replace('iiurlwidth=800','iiurlwidth=960').replace('time.sleep(0.5)','time.sleep(2.5)')
s=s.replace('''def get(url):
    req = urllib.request.Request(url, headers=UA)
    return urllib.request.urlopen(req, timeout=60).read()''','''def get(url, tries=4):
    for t in range(tries):
        try:
            req = urllib.request.Request(url, headers=UA)
            return urllib.request.urlopen(req, timeout=60).read()
        except urllib.error.HTTPError as e:
            if e.code != 429 or t == tries-1: raise
            time.sleep(15*(t+1))''')
s=s.replace('import json, sys, os, re, urllib.request','import json, sys, os, re, urllib.request, urllib.error')
open('fetch_refs.py','w').write(s)
EOF
for q in "k:lochan boulder" "l:lake boulder reflection" "m:tarn reflection" "n:erratic lake" "o:pond reflection sunset grass" "p:lake shore sedge" "q:mossy boulder meadow" "r:alpine lake evening" "s:boulder grass shadow" "t:rock reflection calm lake" "u:mountain pond grass"; do CAND=cand3 nice -n 10 python3 fetch_refs.py ${q%%:*} ${q#*:} 2>&1 | grep -c ERR; done; ls refs/cand3/*.jpg | wc -l

# output:
Command did not complete within its 600s timeout and was moved to the background (ID: bz21iobin). Output is being written to: (tmp) You will be notified when it completes. To check interim output, use Read on that file path.
Session cwd remains ~/work/pixelart-studies/moodboards; directory changes made by the backgrounded command do not apply to subsequent commands.

cd ~/work/pixelart-studies/pedagogy/observation && python3 -c "
from PIL import Image
im=Image.open('ferrari/native.png').convert('RGB')
def c(name,box,s=4): im.crop(box).resize(((box[2]-box[0])*s,(box[3]-box[1])*s),Image.NEAREST).save('ferrari/crop_'+name+'.png')
c('leftgrass',(0,240,200,380))
c('waterEdge',(130,330,330,469))
c('rightgrass',(330,330,634,469))
c('island',(250,250,420,310))
c('farbank',(60,200,300,270))
c('reflection',(180,280,380,400))
c('mountain',(180,60,420,190))
"

# output:
(Bash completed with no output)

cat (tmp) ls ~/work/pixelart-studies/pedagogy/observation/refs/cand3/*.jpg | wc -l

# output:
0
0
4
1
0
0
0
      75

cd ~/work/pixelart-studies/pedagogy/observation && python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('ferrari/native.png').convert('RGB')).astype(int)
col=a[:130,330]; prev=None
for y,c in enumerate(col):
  if prev is None or (c!=prev).any(): print(y,tuple(c)); prev=c
" | head -80

# output:
0 (200, 165, 193)
10 (207, 161, 186)
11 (200, 165, 193)
12 (207, 161, 186)
13 (200, 165, 193)
14 (207, 161, 186)
15 (200, 165, 193)
16 (207, 161, 186)
17 (200, 165, 193)
18 (207, 161, 186)
19 (200, 165, 193)
20 (207, 161, 186)
21 (200, 165, 193)
22 (207, 161, 186)
23 (200, 165, 193)
24 (207, 161, 186)
25 (200, 165, 193)
26 (207, 161, 186)
34 (213, 162, 179)
35 (207, 161, 186)
36 (213, 162, 179)
37 (207, 161, 186)
38 (213, 162, 179)
46 (217, 162, 175)
47 (213, 162, 179)
48 (217, 162, 175)
49 (213, 162, 179)
50 (217, 162, 175)
58 (224, 162, 175)
59 (217, 162, 175)
60 (224, 162, 175)
61 (217, 162, 175)
62 (224, 162, 175)
68 (227, 162, 168)
69 (224, 162, 175)
70 (227, 162, 168)
71 (224, 162, 175)
72 (227, 162, 168)
73 (224, 162, 175)
74 (227, 162, 168)
78 (235, 167, 165)
79 (227, 162, 168)
80 (235, 167, 165)
81 (227, 162, 168)
82 (235, 167, 165)
83 (227, 162, 168)
84 (235, 167, 165)
90 (235, 167, 161)
91 (235, 167, 165)
92 (103, 84, 109)
94 (194, 168, 186)
95 (190, 164, 186)
96 (189, 160, 185)
97 (189, 160, 189)
98 (181, 152, 188)
99 (103, 84, 109)
101 (181, 152, 188)
102 (185, 156, 189)
103 (189, 160, 189)
104 (189, 160, 185)
106 (189, 160, 189)
107 (185, 156, 189)
111 (189, 160, 185)
112 (190, 164, 186)
116 (194, 168, 186)
117 (190, 164, 186)
118 (194, 168, 186)
119 (190, 164, 186)
121 (189, 160, 185)
122 (185, 156, 189)
123 (181, 152, 188)
125 (178, 152, 188)
126 (181, 152, 188)
128 (185, 156, 189)
129 (181, 152, 188)

cd ~/work/pixelart-studies/pedagogy/observation && python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('ferrari/native.png').convert('RGB')).astype(int)
H,W,_=a.shape
def runs(reg,axis):
  if axis==0: reg=reg.transpose(1,0,2)
  L=[]
  for r in reg:
    ch=np.where(np.any(r[1:]!=r[:-1],axis=1))[0]; L+=list(np.diff(ch))
  return np.mean(L) if L else 0
for y0 in range(220,469,20):
  reg=a[y0:y0+20,0:110]; regR=a[y0:y0+20,520:634]
  print(y0,'L vert %.2f horiz %.2f'%(runs(reg,0),runs(reg,1)),' R vert %.2f horiz %.2f'%(runs(regR,0),runs(regR,1)), 'ncol',len(np.unique(reg.reshape(-1,3),axis=0)))
"

# output:
220 L vert 1.97 horiz 1.89  R vert 1.65 horiz 1.69 ncol 9
240 L vert 1.63 horiz 1.59  R vert 1.43 horiz 1.52 ncol 9
260 L vert 2.19 horiz 2.36  R vert 1.55 horiz 1.77 ncol 4
280 L vert 2.18 horiz 1.65  R vert 1.77 horiz 1.39 ncol 5
300 L vert 2.90 horiz 1.50  R vert 3.36 horiz 1.76 ncol 15
320 L vert 2.78 horiz 1.75  R vert 2.89 horiz 1.52 ncol 5
340 L vert 3.04 horiz 1.51  R vert 2.88 horiz 1.30 ncol 4
360 L vert 3.10 horiz 1.68  R vert 2.89 horiz 1.31 ncol 4
380 L vert 3.04 horiz 1.64  R vert 3.25 horiz 1.58 ncol 4
400 L vert 3.24 horiz 1.75  R vert 3.00 horiz 2.21 ncol 4
420 L vert 2.99 horiz 1.57  R vert 3.33 horiz 1.81 ncol 4
440 L vert 3.69 horiz 1.55  R vert 3.74 horiz 1.47 ncol 3
460 L vert 2.43 horiz 1.67  R vert 2.20 horiz 1.41 ncol 3

sleep 60; cat (tmp) ls ~/work/pixelart-studies/pedagogy/observation/refs/cand3/*.jpg | wc -l

# output:
<tool_use_error>Blocked: sleep 60 followed by: cat (tmp) ls ~/work/pixelart-studies/pedagogy/observation/refs/cand3/*.jpg wc -l. To wait for a condition, use Monitor with an until-loop (e.g. `until <check>; do sleep 2; done`). To wait for a command you started, use run_in_background: true. Do not chain shorter sleeps to work around this block.</tool_use_error>

cd ~/work/pixelart-studies/pedagogy/observation && python3 contact.py 'refs/cand3/*.jpg' studies/contact3.png; python3 -c "
from PIL import Image; im=Image.open('studies/contact3.png'); w,h=im.size; n=(h+1439)//1440
for i in range(n): im.crop((0,i*1440,w,min(h,(i+1)*1440))).save(f'studies/contact3_{i}.png')
print(n)"

# output:
84
3

cd ~/work/pixelart-studies/pedagogy/observation/refs && ls cand2 | grep -E "^(c_0[0-7]|e_00|i_0[1-4]|l_05)" ; ls cand3 | grep -E "^(k_0[1789]|k_03|n_10|n_04|m_01|o_02|o_04|o_00|n_08|n_02)"; ls cand | grep -E "^(bldlake_0[156]|lakegrass_07|lakeshore_02|dusk_0[056]|sedge_0[17]|lakegrass_03|granite_0[23]|sedge_11|lakegrass_09|bldlake_11)"

# output:
c_00_Boulders_at_Split_Rock_Trail_50730155868_jpg.jpg
c_01_Boulders_at_Split_Rock_Trail_50730883751_jpg.jpg
c_02_Boulders_at_Split_Rock_Trail_50730884336_jpg.jpg
c_03_Joshua_Tree_Silhoette_49623641476_jpg.jpg
c_04_Joshua_tree_Yucca_brevifolia_51308534677_jpg.jpg
c_05_Silhouette_of_a_Joshua_Tree_53416699411_jpg.jpg
c_06_Sunset_boulders_52012488677_jpg.jpg
c_07_Sunset_boulders_52013573473_jpg.jpg
e_00_Alabama_Hills_at_Sunset_jpg.jpg
i_01_Granite_boulder_formations_near_the_Monsanto_Castle_at_sunri.jpg
i_02_Granite_boulder_formations_near_the_Monsanto_Castle_at_sunri.jpg
i_03_Granite_boulder_formations_near_the_Monsanto_Castle_at_sunri.jpg
i_04_Granite_boulder_formations_near_the_Monsanto_Castle_at_sunri.jpg
l_05_Mockerkin_Tarn_viewed_from_Mockerkin_geograph_org_uk_80609_j.jpg
k_01_Boulder_and_lochan_below_Coire_a_Bh_steir_geograph_org_uk_54.jpg
k_03_Boulders_in_Lochan_Uaine_geograph_org_uk_8353748_jpg.jpg
k_07_Large_boulder_view_towards_Lochan_Meall_a_Phuill_geograph_or.jpg
k_08_Large_boulder_east_of_Lochan_Caol_Fada_geograph_org_uk_28569.jpg
k_09_Prominent_boulder_by_Lochan_na_h_Earba_geograph_org_uk_45209.jpg
m_01_Blea_Tarn_Langdale_reflections_2_geograph_org_uk_2055100_jpg.jpg
n_02_Gazzam_Lake_Nature_Preserve_04_glacial_erratic_just_off_main.jpg
n_04_Glacial_erratic_at_Martha_Lake_Airport_Park_jpg.jpg
n_08_Lawrence_Lake_erratic_2_jpg.jpg
n_10_Martha_Lake_Erratic_2015_1_jpg.jpg
o_00_D_lmen_Kirchspiel_Oedlerteich_2016_1949_jpg.jpg
o_02_Landscape_of_lake_and_clouds_jpg.jpg
o_04_Sunset_in_Upper_Silesia_in_Mys_owice_in_the_area_of_the_post.jpg
bldlake_01_Calmmetry_233248329_jpeg.jpg
bldlake_05_Lake_Billy_Chinook_Jefferson_County_Oregon_scenic_images_jef.jpg
bldlake_06_Misty_October_morning_Elterwater_geograph_org_uk_4202657_jpg.jpg
bldlake_11__26_jpg.jpg
dusk_00_Cameron_Lake_BC_Canada_JPG.jpg
dusk_05_Lake_Ceknica_2013_8568169722_jpg.jpg
dusk_06_Lake_Cerknica_2013_8567069833_jpg.jpg
granite_02_A_Land_of_Granite_Lembert_Dome_Yosemite_NP_5_15_25770995343_.jpg
granite_03_Cloudy_Morning_Tuolumne_Meadows_Yosemite_5_20_15a_1835465920.jpg
lakegrass_03_Morning_in_the_Meadow_Lake_Mary_CA_2016_32750834010_jpg.jpg
lakegrass_07_Solenoye_lake_shore_jpg.jpg
lakegrass_09_The_Adirondack_or_Life_in_the_woods_1864_14579246830_jpg.jpg
lakeshore_02_Morning_in_the_Meadow_Lake_Mary_CA_2016_32750834010_jpg.jpg
sedge_01_Carex_atrata_Carex_microptera_3215_Flickr_andrey_zharkikh_jp.jpg
sedge_07_Sedges_Cyperaceae_on_the_shores_of_Lake_St_Lucia_44757028380.jpg
sedge_11_Wetland_Grasses_8235708195_jpg.jpg

cd ~/work/pixelart-studies/pedagogy/observation/refs && cp_(){ cp "$1" "$2"; grep -h "$(basename "$1")" cand*/credits.tsv | sed "s#^#$2\t#" >> credits.tsv; }
: > credits.tsv
cp_ cand2/c_00_Boulders_at_Split_Rock_Trail_50730155868_jpg.jpg r01_splitrock_boulders_lowsun_a.jpg
cp_ cand2/c_01_Boulders_at_Split_Rock_Trail_50730883751_jpg.jpg r02_splitrock_boulders_lowsun_b.jpg
cp_ cand2/c_02_Boulders_at_Split_Rock_Trail_50730884336_jpg.jpg r03_splitrock_boulders_lowsun_c.jpg
cp_ cand2/c_06_Sunset_boulders_52012488677_jpg.jpg r04_sunset_boulders_a.jpg
cp_ cand2/c_07_Sunset_boulders_52013573473_jpg.jpg r05_sunset_boulders_b.jpg
cp_ cand2/e_00_Alabama_Hills_at_Sunset_jpg.jpg r06_alabama_hills_dusk.jpg
cp_ cand2/i_01_Granite_boulder_formations_near_the_Monsanto_Castle_at_sunri.jpg r07_monsanto_granite_dusk_a.jpg
cp_ cand2/i_02_Granite_boulder_formations_near_the_Monsanto_Castle_at_sunri.jpg r08_monsanto_granite_dusk_b.jpg
cp_ cand2/i_03_Granite_boulder_formations_near_the_Monsanto_Castle_at_sunri.jpg r09_monsanto_granite_dusk_c.jpg
cp_ cand3/k_09_Prominent_boulder_by_Lochan_na_h_Earba_geograph_org_uk_45209.jpg r10_boulder_by_lochan_grassfoot.jpg
cp_ cand3/k_07_Large_boulder_view_towards_Lochan_Meall_a_Phuill_geograph_or.jpg r11_boulder_moor_distance_a.jpg
cp_ cand3/k_08_Large_boulder_east_of_Lochan_Caol_Fada_geograph_org_uk_28569.jpg r12_boulder_moor_distance_b.jpg
cp_ cand3/n_10_Martha_Lake_Erratic_2015_1_jpg.jpg r13_erratic_in_lawn.jpg
cp_ cand3/k_01_Boulder_and_lochan_below_Coire_a_Bh_steir_geograph_org_uk_54.jpg r14_boulder_and_lochan.jpg
cp_ cand3/k_03_Boulders_in_Lochan_Uaine_geograph_org_uk_8353748_jpg.jpg r15_boulders_in_lochan.jpg
cp_ cand/bldlake_01_Calmmetry_233248329_jpeg.jpg r16_tarn_boulder_reflection.jpg
cp_ cand/bldlake_05_Lake_Billy_Chinook_Jefferson_County_Oregon_scenic_images_jef.jpg r17_boulders_water_warmlight.jpg
cp_ cand/bldlake_06_Misty_October_morning_Elterwater_geograph_org_uk_4202657_jpg.jpg r18_boulder_still_water.jpg
cp_ cand3/m_01_Blea_Tarn_Langdale_reflections_2_geograph_org_uk_2055100_jpg.jpg r19_tarn_bank_reflection.jpg
cp_ cand3/o_02_Landscape_of_lake_and_clouds_jpg.jpg r20_grassbank_lake_sunset.jpg
cp_ cand3/o_04_Sunset_in_Upper_Silesia_in_Mys_owice_in_the_area_of_the_post.jpg r21_riverbank_pink_dusk.jpg
cp_ cand/lakegrass_07_Solenoye_lake_shore_jpg.jpg r22_lakeshore_grass_lowsun.jpg
cp_ cand/lakegrass_03_Morning_in_the_Meadow_Lake_Mary_CA_2016_32750834010_jpg.jpg r23_meadow_lake_lowsun.jpg
cp_ cand/dusk_00_Cameron_Lake_BC_Canada_JPG.jpg r24_lake_pink_dusk_reflection.jpg
cp_ cand/dusk_06_Lake_Cerknica_2013_8567069833_jpg.jpg r25_misc_dusk_06.jpg
cp_ cand/sedge_07_Sedges_Cyperaceae_on_the_shores_of_Lake_St_Lucia_44757028380.jpg r26_sedge_shore.jpg
cp_ cand/bldlake_11__26_jpg.jpg r27_boulders_in_meadow.jpg
cp_ cand/granite_03_Cloudy_Morning_Tuolumne_Meadows_Yosemite_5_20_15a_1835465920.jpg r28_tuolumne_boulders_meadow.jpg
ls r*.jpg | wc -l; cut -f1,4,5 credits.tsv | head -40

# output:
28
r01_splitrock_boulders_lowsun_a.jpg Joshua Tree National Park   Public domain
r02_splitrock_boulders_lowsun_b.jpg Joshua Tree National Park   Public domain
r03_splitrock_boulders_lowsun_c.jpg Joshua Tree National Park   Public domain
r04_sunset_boulders_a.jpg   Joshua Tree National Park   Public domain
r05_sunset_boulders_b.jpg   Joshua Tree National Park   Public domain
r06_alabama_hills_dusk.jpg  Bureau of Land Management California    Public domain
r07_monsanto_granite_dusk_a.jpg Jules Verne Times Two   CC BY-SA 4.0
r08_monsanto_granite_dusk_b.jpg Jules Verne Times Two   CC BY-SA 4.0
r09_monsanto_granite_dusk_c.jpg Jules Verne Times Two   CC BY-SA 4.0
r10_boulder_by_lochan_grassfoot.jpg Jim Barton  CC BY-SA 2.0
r11_boulder_moor_distance_a.jpg Leslie Barrie   CC BY-SA 2.0
r12_boulder_moor_distance_b.jpg Leslie Barrie   CC BY-SA 2.0
r13_erratic_in_lawn.jpg Brianhe CC BY-SA 4.0
r14_boulder_and_lochan.jpg  Ian Taylor  CC BY-SA 2.0
r15_boulders_in_lochan.jpg  Anne Burgess    CC BY-SA 2.0
r16_tarn_boulder_reflection.jpg Jaroslav Jelinek    CC BY 3.0
r17_boulders_water_warmlight.jpg    Gary Halvorson, Oregon State Archives   Attribution
r18_boulder_still_water.jpg Karl and Ali    CC BY-SA 2.0
r19_tarn_bank_reflection.jpg    Peter S CC BY-SA 2.0
r20_grassbank_lake_sunset.jpg   Mshuang2    CC0
r21_riverbank_pink_dusk.jpg Krzysztof Popławski CC BY-SA 4.0
r22_lakeshore_grass_lowsun.jpg  This photo was taken by Anton Zelenov.
r23_meadow_lake_lowsun.jpg  inkknife_2000 (7.5 million views +) CC BY-SA 2.0
r24_lake_pink_dusk_reflection.jpg   Wasrts  CC BY-SA 3.0
r25_misc_dusk_06.jpg    why 137 from Trieste, Italy CC BY 2.0
r26_sedge_shore.jpg Bernard DUPONT from FRANCE  CC BY-SA 2.0
r27_boulders_in_meadow.jpg  Petrovskyz  CC BY-SA 4.0
r28_tuolumne_boulders_meadow.jpg    inkknife_2000 (7.5 million views +) CC BY-SA 2.0

mkdir -p ~/work/pixelart-studies/pedagogy/observation/studies && cat > ~/work/pixelart-studies/pedagogy/observation/blockin.py <<'EOF'
"""Observational study: greyscale block-in of a photo's big shapes and values.
photo -> luminance -> edge-preserving simplification (SLIC superpixels, mean value)
-> quantize to N value steps (k-means in luminance) -> side-by-side with the photo.
This is the squint: what are the 3-5 big value masses, and where are the edges between them?"""
import sys, os, numpy as np
from PIL import Image, ImageDraw
from skimage.segmentation import slic
from skimage.color import rgb2lab
from sklearn.cluster import KMeans
os.environ.setdefault("OMP_NUM_THREADS", "4")

def blockin(path, nvals=4, nseg=180, W=480):
    im = Image.open(path).convert("RGB"); im.thumbnail((W, W))
    a = np.asarray(im) / 255.0
    L = rgb2lab(a)[..., 0] / 100.0
    seg = slic(a, n_segments=nseg, compactness=12, start_label=0)
    Ls = np.zeros_like(L)
    for s in np.unique(seg): Ls[seg == s] = L[seg == s].mean()
    km = KMeans(nvals, n_init=4, random_state=0).fit(Ls.reshape(-1, 1))
    cent = np.sort(km.cluster_centers_.ravel()); lab = np.argmin(np.abs(Ls[..., None] - cent), -1)
    grey = np.linspace(0.08, 0.95, nvals)[lab]
    return im, (L * 255).astype(np.uint8), (grey * 255).astype(np.uint8), cent

if __name__ == "__main__":
    out = sys.argv[1]; paths = sys.argv[2:]; rows = []
    for p in paths:
        im, L, g, cent = blockin(p)
        w, h = im.size; row = Image.new("RGB", (w*3+8, h+16), "white")
        row.paste(im, (0, 0)); row.paste(Image.fromarray(L).convert("RGB"), (w+4, 0)); row.paste(Image.fromarray(g).convert("RGB"), (2*w+8, 0))
        ImageDraw.Draw(row).text((2, h+2), os.path.basename(p) + "  value centres L*=" + " ".join(f"{c*100:.0f}" for c in cent), fill="black")
        rows.append(row)
    W = max(r.size[0] for r in rows); H = sum(r.size[1] for r in rows)
    sheet = Image.new("RGB", (W, H), "white"); y = 0
    for r in rows: sheet.paste(r, (0, y)); y += r.size[1]
    sheet.save(out)
EOF
cd ~/work/pixelart-studies/pedagogy/observation && OMP_NUM_THREADS=4 nice -n 10 python3 blockin.py studies/blockin_boulders.png refs/r02*.jpg refs/r10*.jpg refs/r13*.jpg refs/r11*.jpg && OMP_NUM_THREADS=4 nice -n 10 python3 blockin.py studies/blockin_water.png refs/r19*.jpg refs/r20*.jpg refs/r25*.jpg refs/r18*.jpg && OMP_NUM_THREADS=4 nice -n 10 python3 blockin.py studies/blockin_dusk.png refs/r06*.jpg refs/r07*.jpg refs/r23*.jpg refs/r22*.jpg && echo ok

# output:
ok

cd ~/work/pixelart-studies/pedagogy/observation && cat > blockin.py <<'EOF'
"""Observational study: greyscale block-in of a photo's big shapes and values.
The squint, done by program:
  panel 1  the photo
  panel 2  2-value notan: light family vs shadow family (Otsu split of blurred luminance)
  panel 3  4-value block-in at 80 px wide (median-filtered, multi-Otsu), shown nearest-neighbour
  panel 4  the same 4 values, but at 320 px wide - what survives at the task's native resolution
Printed: the L* centre of each value mass, so observations carry numbers."""
import sys, os, numpy as np
from PIL import Image, ImageDraw, ImageFilter
from skimage.color import rgb2lab
from skimage.filters import threshold_multiotsu, threshold_otsu

def lum(im): return rgb2lab(np.asarray(im) / 255.0)[..., 0]

def quant(L, k):
    t = threshold_multiotsu(L, classes=k); q = np.digitize(L, t)
    cent = [L[q == i].mean() for i in range(k)]
    return q, cent

def panels(path, W=400):
    im = Image.open(path).convert("RGB"); im.thumbnail((W, W)); w, h = im.size
    L = lum(im.filter(ImageFilter.GaussianBlur(w / 120)))
    t = threshold_otsu(L); notan = np.where(L > t, 230, 40).astype(np.uint8)
    out = [im, Image.fromarray(notan).convert("RGB")]
    for sw in (80, 320 * w // W if False else 160):
        small = im.resize((sw, max(1, sw * h // w)), Image.LANCZOS).filter(ImageFilter.MedianFilter(3))
        Ls = lum(small); q, cent = quant(Ls, 4)
        grey = np.array([30, 95, 165, 235], np.uint8)[q]
        out.append(Image.fromarray(grey).convert("RGB").resize((w, h), Image.NEAREST))
    return out, cent, t

if __name__ == "__main__":
    dst = sys.argv[1]; rows = []
    for p in sys.argv[2:]:
        ps, cent, t = panels(p); w, h = ps[0].size
        row = Image.new("RGB", (4 * w + 12, h + 14), "white")
        for i, q in enumerate(ps): row.paste(q, (i * (w + 4), 0))
        ImageDraw.Draw(row).text((2, h + 1), f"{os.path.basename(p)}   light/shadow split L*={t:.0f}   4-value centres L*=" + " ".join(f"{c:.0f}" for c in cent), fill="black")
        rows.append(row)
    Wd = max(r.size[0] for r in rows); sheet = Image.new("RGB", (Wd, sum(r.size[1] for r in rows)), "white"); y = 0
    for r in rows: sheet.paste(r, (0, y)); y += r.size[1]
    sheet.save(dst)
EOF
nice -n 10 python3 blockin.py studies/blockin_boulders.png refs/r02*.jpg refs/r10*.jpg refs/r13*.jpg refs/r11*.jpg && nice -n 10 python3 blockin.py studies/blockin_water.png refs/r19*.jpg refs/r20*.jpg refs/r25*.jpg refs/r18*.jpg && nice -n 10 python3 blockin.py studies/blockin_dusk.png refs/r06*.jpg refs/r07*.jpg refs/r23*.jpg refs/r16*.jpg && echo ok

# output:
ok

cd ~/work/pixelart-studies/pedagogy/observation && python3 -c "
from PIL import Image; import numpy as np
from skimage.color import rgb2lab
def L(p,pts,r=6):
  a=np.asarray(Image.open(p).convert('RGB'))/255.; lab=rgb2lab(a); print(p.split('/')[-1], a.shape[:2])
  for n,(x,y) in pts.items():
    v=lab[y-r:y+r,x-r:x+r].reshape(-1,3).mean(0); c=(a[y-r:y+r,x-r:x+r].reshape(-1,3).mean(0)*255).astype(int); print('  %-22s L*=%5.1f a=%5.1f b=%5.1f rgb=%s'%(n,v[0],v[1],v[2],tuple(c)))
L('refs/r25_misc_dusk_06.jpg',{'sky low (horizon)':(850,285),'refl of sky low':(850,325),'sky mid':(500,150),'refl sky mid (mirr.)':(500,460),'sky top':(500,15),'water nearest':(500,620),'hill':(200,230),'refl hill':(200,370),'far-shore line':(560,305)})
L('refs/r19_tarn_bank_reflection.jpg',{'boulder lit top':(700,300),'boulder shadow lower':(680,440),'boulder refl':(640,560),'sky':(300,50),'water sky refl':(300,470),'grass sunlit right':(900,400),'contact under boulder':(560,470)})
L('refs/r02_splitrock_boulders_lowsun_b.jpg',{'lit face':(330,360),'terminator':(385,350),'shadow side':(405,370),'big lit':(700,200),'big shadow (overhang)':(760,330),'ground shadow':(600,560),'contact crevice':(360,418),'sky':(200,200)})
L('refs/r18_boulder_still_water.jpg',{'stone top':(540,420),'stone side':(520,470),'stone refl':(530,530),'water':(300,480),'water near':(300,580)})
"

# output:
r25_misc_dusk_06.jpg (634, 960)
  sky low (horizon)      L*= 36.1 a=  6.7 b=-12.9 rgb=(85, 82, 105)
  refl of sky low        L*= 33.6 a=  6.8 b=-11.5 rgb=(80, 76, 97)
  sky mid                L*= 86.4 a=  9.9 b=  8.1 rgb=(241, 209, 201)
  refl sky mid (mirr.)   L*= 54.8 a= 15.4 b=  9.8 rgb=(162, 121, 114)
  sky top                L*= 85.0 a=  8.6 b= -3.5 rgb=(226, 207, 219)
  water nearest          L*= 24.5 a=  6.8 b= -4.1 rgb=(65, 54, 64)
  hill                   L*= 18.9 a=  5.7 b=-18.4 rgb=(37, 44, 72)
  refl hill              L*= 12.5 a=  4.2 b=-13.9 rgb=(26, 31, 51)
  far-shore line         L*= 36.4 a=  9.1 b= -5.3 rgb=(98, 83, 95)
r19_tarn_bank_reflection.jpg (720, 960)
  boulder lit top        L*= 60.2 a=  5.2 b= 20.4 rgb=(167, 142, 110)
  boulder shadow lower   L*= 28.5 a=  6.1 b= 19.9 rgb=(85, 63, 37)
  boulder refl           L*= 14.9 a=  3.3 b= 16.9 rgb=(49, 35, 9)
  sky                    L*= 99.7 a= -0.0 b=  0.0 rgb=(254, 254, 254)
  water sky refl         L*= 77.9 a= -1.7 b=  1.6 rgb=(190, 193, 189)
  grass sunlit right     L*= 45.2 a=-14.4 b= 46.1 rgb=(105, 112, 17)
  contact under boulder  L*= 31.5 a= -1.9 b= 20.6 rgb=(83, 75, 41)
r02_splitrock_boulders_lowsun_b.jpg (640, 960)
  lit face               L*= 58.3 a= 16.2 b= 40.0 rgb=(185, 128, 70)
  terminator             L*= 24.9 a=  9.5 b= 18.0 rgb=(81, 53, 31)
  shadow side            L*= 37.0 a= 18.8 b= 33.1 rgb=(127, 74, 33)
  big lit                L*= 80.7 a=  8.2 b= 51.3 rgb=(242, 192, 103)
  big shadow (overhang)  L*= 15.8 a= 12.2 b= 19.0 rgb=(61, 32, 9)
  ground shadow          L*= 25.9 a=  6.9 b= 16.6 rgb=(79, 57, 36)
  contact crevice        L*= 33.6 a=  8.1 b= 26.1 rgb=(104, 74, 36)
  sky                    L*= 82.9 a=-22.6 b=-13.1 rgb=(136, 219, 230)
r18_boulder_still_water.jpg (600, 800)
  stone top              L*= 37.5 a=  2.5 b= 12.5 rgb=(100, 87, 69)
  stone side             L*= 10.7 a=  3.5 b=  0.1 rgb=(33, 27, 28)
  stone refl             L*=  4.9 a=  0.7 b= -1.0 rgb=(16, 15, 17)
  water                  L*= 47.3 a=  0.6 b= -3.9 rgb=(110, 112, 118)
  water near             L*= 39.5 a=  1.6 b= -3.2 rgb=(93, 92, 98)

cd ~/work/pixelart-studies/pedagogy/observation && cat > studies_profiles.py <<'EOF'
"""Observational measurements on the reference photos:
 A. light across a rounded boulder (luminance profile lit side -> terminator -> shadow side -> contact)
 B. water: vertical L* profile of sky and its reflection (r25), sky vs water
 C. grass: texture anisotropy (vertical vs horizontal run structure) against depth, in a photo (r22)
    -- the same statistic I measured in Ferrari's grass, so nature and translation can be compared
 D. distance: a lit boulder resampled to the pixel sizes it would occupy at 320x180 native"""
import numpy as np, matplotlib; matplotlib.use("Agg"); import matplotlib.pyplot as plt
from PIL import Image
from skimage.color import rgb2lab
def lab(p): a = np.asarray(Image.open(p).convert("RGB")) / 255.; return a, rgb2lab(a)
fig, ax = plt.subplots(2, 3, figsize=(15, 8.5))
# A: r02 small boulder, horizontal scanlines
a, l = lab("refs/r02_splitrock_boulders_lowsun_b.jpg")
for y, c in [(345, "C0"), (370, "C1"), (395, "C2")]:
    ax[0, 0].plot(np.arange(280, 430), l[y-2:y+3, 280:430, 0].mean(0), c, label=f"row {y}")
ax[0, 0].set_title("A  r02 boulder: L* left->right (sun from left)"); ax[0, 0].legend(); ax[0, 0].set_xlabel("x px")
ax[0, 1].imshow(a[300:430, 270:440]); [ax[0, 1].axhline(y-300, color=c, lw=.8) for y, c in [(345, "C0"), (370, "C1"), (395, "C2")]]; ax[0, 1].set_title("A  the boulder, scanlines")
# vertical profile down the lit face into the ground contact
ax[0, 2].plot(np.arange(300, 440), l[300:440, 322:330, 0].mean(1), "C3", label="r02 lit face, down to ground")
a19, l19 = lab("refs/r19_tarn_bank_reflection.jpg")
ax[0, 2].plot(np.arange(220, 720) * 140 / 500 + 300, l19[220:720, 690:700, 0].mean(1), "C4", label="r19 boulder->waterline->reflection (rescaled y)")
ax[0, 2].set_title("A'  vertical: top light -> base -> contact"); ax[0, 2].legend(fontsize=8)
# B: water r25
a25, l25 = lab("refs/r25_misc_dusk_06.jpg"); col = l25[:, 100:180, 0].mean(1); wl = 306
ax[1, 0].plot(np.arange(len(col)), col, "k", label="L* down column x=100..180")
ax[1, 0].axvline(wl, color="r", lw=.8); 
sky = col[:wl][::-1]; wat = col[wl:wl + len(sky)]; n = min(len(sky), len(wat))
ax[1, 0].plot(np.arange(wl, wl + n), sky[:n], "C0--", label="sky mirrored about waterline")
ax[1, 0].set_title("B  r25: sky vs its reflection"); ax[1, 0].legend(fontsize=8); ax[1, 0].set_xlabel("y px")
# C: anisotropy vs depth in grass photo and in Ferrari
def aniso(reg):
    g = reg.astype(float); gx = np.abs(np.diff(g, axis=1)).mean(); gy = np.abs(np.diff(g, axis=0)).mean(); return gx / (gy + 1e-6)
a22, l22 = lab("refs/r22_lakeshore_grass_lowsun.jpg"); ys = np.arange(300, 940, 40)
ax[1, 1].plot((ys - 300) / 640, [aniso(l22[y:y+40, 50:900, 0]) for y in ys], "C2o-", label="photo r22 grass (bank->foreground)")
f = np.asarray(Image.open("ferrari/native.png").convert("L")).astype(float); yf = np.arange(220, 460, 20)
ax[1, 1].plot((yf - 220) / 240, [aniso(f[y:y+20, 0:110]) for y in yf], "C1s-", label="Ferrari left grass (far->near)")
ax[1, 1].set_title("C  grass texture: |d/dx| / |d/dy|  (1 = isotropic, >1 = vertical strokes)"); ax[1, 1].set_xlabel("depth fraction, far -> near"); ax[1, 1].legend(fontsize=8)
# D: distance resample
b = Image.open("refs/r02_splitrock_boulders_lowsun_b.jpg").convert("RGB").crop((280, 305, 425, 425))
canvas = Image.new("RGB", (330, 130), "white"); x = 0
for h in (100, 40, 10, 4):
    s = b.resize((max(1, int(h * 145 / 120)), h), Image.BOX)
    big = s.resize((s.size[0] * (100 // h) if h < 100 else s.size[0], 100 if h < 100 else h), Image.NEAREST)
    canvas.paste(big, (x, 0)); x += big.size[0] + 6
ax[1, 2].imshow(canvas); ax[1, 2].set_title("D  same boulder at 100, 40, 10, 4 px tall (shown same size)")
for a_ in ax.ravel(): a_.grid(alpha=.3)
plt.tight_layout(); plt.savefig("studies/measurements.png", dpi=90)
EOF
nice -n 10 python3 studies_profiles.py && echo ok

# output:
ok

cd ~/work/pixelart-studies/pedagogy/observation && python3 -c "
from PIL import Image
im=Image.open('ferrari/native.png').convert('RGB')
def c(name,box,s=6): im.crop(box).resize(((box[2]-box[0])*s,(box[3]-box[1])*s),Image.NEAREST).save('ferrari/crop_'+name+'.png')
c('stones',(225,385,330,450))
c('rightbank_lip',(400,230,634,300),4)
c('grass_tips_on_water',(180,340,280,420),6)
"

# output:
(Bash completed with no output)

cat (tmp) | tr '\n' ' '; python3 -c "import sklearn, scipy; print(sklearn.__version__, scipy.__version__)"; sysctl -n hw.ncpu

# output:
0 0 4 1 0 0 0 0 1 2 1      121  [exited with code 0] 1.6.1 1.14.0
14

"""
tarn.py -- paint "a granite boulder in a grass bank at the edge of a still mountain tarn, at dusk"
as painterly pixel art, from parameters.

Two stages, mirroring the study method:

  1. OBSERVE  (render_observation)  a small physical model of the scene, carrying what the photos
     showed: low warm sun + violet sky fill + warm bounce from lit grass; a rough-surface terminator
     (flat light plateau, sharp drop, core-shadow dip before the bounce-lit shadow side); contact
     occlusion; long cast shadows at 5 deg sun; tussock-scale grass masses that catch light on
     their sun-facing tops; water as a Fresnel mirror (reflections darker, showing the UNDERSIDE of
     things, darkening toward the viewer); aerial perspective on distant land.
     Output: a per-pixel G-buffer and a continuous colour image at 320x180.

  2. TRANSLATE (paint)  that observation into Ferrari's language:
     - a 32-colour palette built from the model's own canonical light states (ramps per material)
     - sky: flat bands of adjacent ramp colours joined by 50% checkerboard strips
     - grass: stipple in the distance, vertical 1-px blades near, blade length ~ 1/distance,
       blades dark at the root and light at the tip, dark "gap" blades interleaved, painted far to
       near so near tips overlap the water and the boulder's foot
     - boulder: few values, sharp light/shadow split, dither only across the terminator, a 1-px
       rim where the silhouette faces the sun, darkest accent at the contact line, sparse speckle
     - water: the same scene mirrored and darkened, broken into horizontal dashes by
       horizontally-correlated ripple noise, light wind-lines, a light line at the far shore
     - far trees and mountains: flat facets, lit edges, heavy aerial perspective

Parameters: size (small|medium|large), light (left|front|right|back), distance (close|10m|40m), seed.
"""
import os, sys, math, argparse
import numpy as np
from PIL import Image, ImageDraw
from skimage.color import rgb2lab, lab2rgb

W, H = 320, 180
HFOV = math.radians(60.0)
PITCH = math.radians(-10.0)
EYE_H = 1.25                         # camera eye height above its local ground (m) - "low angle"
SUN_EL = math.radians(4.5)           # dusk: sun just above the ridge line
SIZES = {"small": 1.1, "medium": 1.9, "large": 2.9}                 # boulder long axis, m
DISTS = {"close": 5.5, "10m": 10.0, "40m": 40.0}                   # camera -> boulder, m
LIGHTS = {"left": -80.0, "front": 172.0, "right": 80.0, "back": -12.0}  # sun azimuth rel. to view, deg

# --------------------------------------------------------------------------------------------
# noise
# --------------------------------------------------------------------------------------------
M32 = np.uint64(0xFFFFFFFF)

def _hash(ix, iy, iz, seed):
    h = (ix.astype(np.int64).astype(np.uint64) * np.uint64(73856093)) ^ \
        (iy.astype(np.int64).astype(np.uint64) * np.uint64(19349663)) ^ \
        (iz.astype(np.int64).astype(np.uint64) * np.uint64(83492791)) ^ np.uint64(seed * 2654435761 & 0xFFFFFFFF)
    h &= M32
    h ^= h >> np.uint64(13); h = (h * np.uint64(1274126177)) & M32; h ^= h >> np.uint64(16)
    return (h & np.uint64(0xFFFFFF)).astype(np.float64) / float(0xFFFFFF)

def vnoise3(x, y, z, seed=0):
    ix, iy, iz = np.floor(x), np.floor(y), np.floor(z)
    fx, fy, fz = x - ix, y - iy, z - iz
    ux, uy, uz = fx * fx * (3 - 2 * fx), fy * fy * (3 - 2 * fy), fz * fz * (3 - 2 * fz)
    r = 0.0
    for dx in (0, 1):
        for dy in (0, 1):
            for dz in (0, 1):
                w = (ux if dx else 1 - ux) * (uy if dy else 1 - uy) * (uz if dz else 1 - uz)
                r = r + w * _hash(ix + dx, iy + dy, iz + dz, seed)
    return r * 2 - 1

def vnoise2(x, y, seed=0):
    return vnoise3(x, y, np.zeros_like(x) + 0.5, seed)

def fbm2(x, y, seed=0, oct=4, lac=2.0, gain=0.5):
    a, f, s = 1.0, 1.0, 0.0
    for o in range(oct):
        s = s + a * vnoise2(x * f, y * f, seed + 17 * o); a *= gain; f *= lac
    return s

def fbm3(x, y, z, seed=0, oct=3):
    a, f, s = 1.0, 1.0, 0.0
    for o in range(oct):
        s = s + a * vnoise3(x * f, y * f, z * f, seed + 31 * o); a *= 0.5; f *= 2.0
    return s

def norm(v):
    return v / (np.linalg.norm(v, axis=-1, keepdims=True) + 1e-12)

def smoothstep(a, b, x):
    t = np.clip((x - a) / (b - a), 0, 1); return t * t * (3 - 2 * t)

# --------------------------------------------------------------------------------------------
# scene
# --------------------------------------------------------------------------------------------
class Scene:
    def __init__(self, size="medium", light="left", distance="10m", seed=0, tree_density=0.55):
        self.seed = seed; rng = np.random.default_rng(seed)
        self.rng = rng
        self.D = DISTS[distance]
        self.size = size; self.light = light; self.distance = distance
        a = SIZES[size] / 2 * rng.uniform(0.9, 1.1)
        self.a = a
        # weathered granite corestone: a rounded block ("woolsack"), long axis a
        self.half = a * np.array([1.0, rng.uniform(0.62, 0.78), rng.uniform(0.72, 0.9)])
        self.rr = 0.62 * self.half.min()
        self.byaw = rng.uniform(-0.7, 0.7)
        self.sink = rng.uniform(0.25, 0.4)
        self.crack = rng.uniform() < 0.55 and size != "small"
        self.crack_n = norm(np.array([rng.uniform(-1, 1), rng.uniform(-0.3, 0.3), rng.uniform(-0.4, 0.4)]))
        self.crack_o = rng.uniform(-0.35, 0.35) * a
        self.bx, self.bz = 0.0, self.D
        self.shore_wob = rng.uniform(0, 100)
        self.tarn_w = rng.uniform(70, 110)
        self.zfar = self.D + self.tarn_w
        self.tree_density = tree_density
        # boulder centre y: ground at its footprint minus sink
        g = self.ground_h(np.array([self.bx]), np.array([self.bz]))[0]
        self.by = g + self.half[1] * (1 - 2 * self.sink)
        # camera
        cg = self.ground_h(np.array([0.0]), np.array([0.0]))[0]
        self.eye = np.array([0.0, cg + EYE_H, 0.0])
        self.yaw = -math.atan(0.16 * math.tan(HFOV / 2)) + rng.uniform(-0.03, 0.03)
        az = math.radians(LIGHTS[light]) + rng.uniform(-0.08, 0.08) + self.yaw
        self.sun = norm(np.array([math.sin(az) * math.cos(SUN_EL), math.sin(SUN_EL), math.cos(az) * math.cos(SUN_EL)]))
        # light colours (linear): warm low sun, violet sky fill; bounce from sunlit grass
        self.sunC = np.array([1.00, 0.56, 0.30]) * 3.2
        self.skyC = np.array([0.36, 0.30, 0.52]) * 0.85
        self.grassA = np.array([0.30, 0.26, 0.10])
        self.rockA = np.array([0.46, 0.42, 0.38])
        self.bounceC = self.grassA * self.sunC * 0.28 + self.grassA * self.skyC * 0.5
        sh = np.array([self.sun[0], 0, self.sun[2]]); sh = sh / (np.linalg.norm(sh) + 1e-9)
        self.bdir = norm(np.array([-sh[0] * 0.6, -1.0, -sh[2] * 0.6]))  # bounce ARRIVES from below / far side
        self.waterBody = np.array([0.030, 0.024, 0.034])

    # ---- terrain -----------------------------------------------------------------------
    def shore_x(self, v):
        """x of the shoreline (boulder-relative) as a function of v = z - zb. water where u < shore."""
        a = self.a
        s = np.where(v < 0, -0.15 * a + 0.36 * v, -0.15 * a + 1.6 * v)
        s = s + 0.25 * a * fbm2(v * 0.35 + self.shore_wob, np.zeros_like(v) + 3.3, self.seed + 5, 3)
        return s

    def shore_d(self, x, z):
        """signed horizontal distance to the shore, + on the bank"""
        u = x - self.bx; v = z - self.bz
        s = self.shore_x(v)
        slope = np.where(v < 0, 0.36, 1.6)
        return (u - s) / np.sqrt(1 + slope ** 2)

    def ground_h(self, x, z, detail=True):
        d = self.shore_d(x, z)
        lip = 0.22
        bank = -0.06 + (lip + 0.06) * smoothstep(0.0, 0.35, d) + 0.05 * np.clip(d, 0, 40)
        if detail:
            t = fbm2(x * 0.9, z * 0.9, self.seed + 11, 3)      # tussocks, ~1 m
            t2 = fbm2(x * 3.1, z * 3.1, self.seed + 12, 2)     # clumps
            bank = bank + (0.10 * t + 0.035 * t2) * smoothstep(0.1, 0.8, d)
        under = -0.06 + 0.35 * d
        return np.where(d >= 0, bank, np.maximum(under, -1.5))

    # ---- boulder SDF --------------------------------------------------------------------
    def boulder_sdf(self, p):
        c, s = math.cos(self.byaw), math.sin(self.byaw)
        q = p - np.array([self.bx, self.by, self.bz])
        lx = c * q[..., 0] - s * q[..., 2]; lz = s * q[..., 0] + c * q[..., 2]; ly = q[..., 1]
        L = np.stack([lx, ly, lz], -1)
        b = self.half - self.rr
        qq = np.abs(L) - b
        out = np.linalg.norm(np.maximum(qq, 0), axis=-1) + np.minimum(qq.max(-1), 0) - self.rr
        a = self.a
        disp = 0.075 * a * fbm3(lx * 1.1 / a, ly * 1.1 / a, lz * 1.1 / a, self.seed + 21, 3) \
            + 0.018 * a * fbm3(lx * 5 / a, ly * 5 / a, lz * 5 / a, self.seed + 22, 2)
        out = out + disp
        if self.crack:
            slab = np.abs(L @ self.crack_n - self.crack_o) - 0.018 * a
            out = np.maximum(out, -slab)
        return out

    def scene_sdf(self, p):
        tg = (p[..., 1] - self.ground_h(p[..., 0], p[..., 2])) * 0.55
        return np.minimum(tg, self.boulder_sdf(p))

    def material_at(self, p):
        return np.where(self.boulder_sdf(p) < (p[..., 1] - self.ground_h(p[..., 0], p[..., 2])), 2, 1)  # 2 rock, 1 grass

    def normal(self, p, mat):
        e = 0.004 * max(self.a, 1.0)
        n = np.zeros_like(p)
        # rock: SDF gradient; grass: heightfield gradient
        for i in range(3):
            dp = np.zeros(3); dp[i] = e
            n[..., i] = self.boulder_sdf(p + dp) - self.boulder_sdf(p - dp)
        hx = self.ground_h(p[..., 0] + 0.03, p[..., 2]) - self.ground_h(p[..., 0] - 0.03, p[..., 2])
        hz = self.ground_h(p[..., 0], p[..., 2] + 0.03) - self.ground_h(p[..., 0], p[..., 2] - 0.03)
        ng = np.stack([-hx, np.full_like(hx, 0.06), -hz], -1)
        return norm(np.where((mat == 2)[..., None], n, ng))

    # ---- marching -----------------------------------------------------------------------
    def march(self, o, d, tmax, steps=260):
        """sphere-trace the near scene (bank + boulder) up to tmax (per ray). returns t, hit mask"""
        t = np.full(d.shape[:-1], 0.02); hit = np.zeros(d.shape[:-1], bool); alive = np.ones_like(hit)
        for _ in range(steps):
            idx = np.nonzero(alive)
            if idx[0].size == 0: break
            p = o[idx] + d[idx] * t[idx][..., None] if o.ndim > 1 else o + d[idx] * t[idx][..., None]
            h = self.scene_sdf(p)
            eps = 0.0015 * t[idx] + 0.002
            h_hit = h < eps
            hit[tuple(i[h_hit] for i in idx)] = True
            t[idx] = t[idx] + np.maximum(h, 0.004 + 0.002 * t[idx])
            done = h_hit | (t[idx] > tmax[idx])
            alive[tuple(i[done] for i in idx)] = False
        hit &= t <= tmax + 1e-6
        return t, hit

    def soft_shadow(self, p, n):
        o = p + n * 0.03
        res = np.ones(p.shape[:-1]); t = np.full(p.shape[:-1], 0.05)
        for _ in range(72):
            q = o + self.sun * t[..., None]
            h = self.scene_sdf(q)
            res = np.minimum(res, 10.0 * h / t)
            t = t + np.clip(h, 0.04, 1.5)
            if np.all((t > 45) | (res < 0.02)): break
        return np.clip(res, 0, 1)

    def ao(self, p, n):
        occ = np.zeros(p.shape[:-1]); sc = 1.0
        for i, dd in enumerate((0.04, 0.1, 0.2, 0.35, 0.55)):
            dd = dd * max(self.a, 0.8)
            occ += (dd - self.scene_sdf(p + n * dd)) * sc; sc *= 0.7
        return np.clip(1 - 1.4 * occ / max(self.a, 0.8), 0, 1)

    # ---- camera -------------------------------------------------------------------------
    def basis(self):
        cy, sy, cp, sp = math.cos(self.yaw), math.sin(self.yaw), math.cos(PITCH), math.sin(PITCH)
        fwd = np.array([sy * cp, sp, cy * cp]); right = np.array([cy, 0, -sy]); up = np.cross(fwd, right)
        return fwd, right, -up if up[1] < 0 else up

    def rays(self):
        fwd, right, up = self.basis()
        th = math.tan(HFOV / 2); tv = th * H / W
        xs = ((np.arange(W) + 0.5) / W * 2 - 1) * th
        ys = (1 - (np.arange(H) + 0.5) / H * 2) * tv
        X, Y = np.meshgrid(xs, ys)
        return norm(fwd + X[..., None] * right + Y[..., None] * up)

    def project(self, pts, is_dir=False):
        fwd, right, up = self.basis()
        v = pts if is_dir else pts - self.eye
        zc = v @ fwd; xc = v @ right; yc = v @ up
        th = math.tan(HFOV / 2); tv = th * H / W
        px = (xc / zc / th + 1) / 2 * W - 0.5
        py = (1 - yc / zc / tv) / 2 * H - 0.5
        return px, py, zc

    # ---- sky ----------------------------------------------------------------------------
    def sky(self, d):
        """continuous dusk sky (linear rgb). observed: pink-peach at the horizon, violet overhead,
        warm glow toward the sun, a pinker band opposite (belt of Venus)."""
        el = np.arcsin(np.clip(d[..., 1], -1, 1))
        e = np.clip(el, 0, None)
        cosg = np.clip(d @ self.sun, -1, 1)
        zen = np.array([0.30, 0.24, 0.48]); mid = np.array([0.62, 0.40, 0.58]); hor = np.array([0.95, 0.56, 0.48])
        t1 = smoothstep(0.0, 0.42, e)[..., None]
        base = hor * (1 - t1) + mid * t1
        t2 = smoothstep(0.12, 0.9, e)[..., None]
        base = base * (1 - t2) + zen * t2
        glow = np.exp(-(1 - cosg) / 0.10)[..., None] * np.array([1.0, 0.62, 0.30]) * 1.4 * np.exp(-e / 0.25)[..., None]
        halo = np.exp(-(1 - cosg) / 0.6)[..., None] * np.array([0.35, 0.18, 0.06]) * np.exp(-e / 0.4)[..., None]
        belt = np.exp(-((el - 0.10) / 0.07) ** 2)[..., None] * smoothstep(0.2, -0.6, cosg)[..., None] * np.array([0.10, 0.02, 0.06])
        disk = (cosg > math.cos(math.radians(0.9)))[..., None] * np.array([3.0, 2.3, 1.2])
        c = (base + glow + halo + belt) * 0.62 + disk
        return c

    # ---- far layers ---------------------------------------------------------------------
    def mountain_ridge(self, az):
        """ridge elevation (rad) per azimuth: distant granite range, ~3 km"""
        r = 0.045 + 0.055 * (0.5 + 0.5 * fbm2(az * 3.0 + self.seed * 0.37, np.zeros_like(az) + 1.7, self.seed + 40, 5))
        r = r + 0.03 * np.maximum(0, fbm2(az * 1.3 + 9.1, np.zeros_like(az), self.seed + 41, 3))
        return r

    def far_layer(self, d):
        """sky + mountains, as a function of direction. returns linear rgb and mask (1 mountain)"""
        az = np.arctan2(d[..., 0], d[..., 2]); el = np.arcsin(np.clip(d[..., 1], -1, 1))
        ridge = self.mountain_ridge(az)
        mnt = el < ridge
        sky = self.sky(d)
        # faceted granite range: ridged noise in angle space -> pseudo normal
        k = 1 / 0.012
        def R(a, e):
            f = 1 - np.abs(fbm2(a * 9 + 3.1, e * 14 + 1.3, self.seed + 43, 4))
            return f * 0.6 + (ridge - e) * 3
        ea, ee = 0.0015, 0.0015
        gx = (R(az + ea, el) - R(az - ea, el)) / (2 * ea) / k
        gy = (R(az, el + ee) - R(az, el - ee)) / (2 * ee) / k
        fwd, right, up = self.basis()
        # face normal: facing camera (-view dir), tilted by gradients
        vd = norm(np.stack([d[..., 0], np.zeros_like(el), d[..., 2]], -1))
        side = np.stack([vd[..., 2], np.zeros_like(el), -vd[..., 0]], -1)
        n = norm(-vd + side * (-gx)[..., None] * 1.3 + np.array([0, 1, 0]) * (0.45 - 0.4 * gy)[..., None])
        ndl = np.clip(n @ self.sun, 0, 1) ** 0.7
        snow = (fbm2(az * 22, el * 30, self.seed + 44, 3) + 0.9 * (el - ridge + 0.04) / 0.04 > 0.55) & (n[..., 1] > 0.35)
        alb = np.where(snow[..., None], np.array([0.80, 0.78, 0.86]), np.array([0.34, 0.30, 0.32]))
        col = alb * (self.sunC * 0.55 * ndl[..., None] + self.skyC * 1.3 * (0.5 + 0.5 * n[..., 1:2]))
        # aerial perspective: 3 km of dusk air
        hz = self.sky(norm(np.stack([d[..., 0], np.full_like(el, 0.02), d[..., 2]], -1)))
        col = col * 0.5 + hz * 0.5
        return np.where(mnt[..., None], col, sky), mnt

    def far_waterline_y(self):
        xs = np.linspace(-2000, 2000, 801)
        px, py, zc = self.project(np.stack([xs, np.zeros_like(xs), np.full_like(xs, self.zfar)], -1))
        return px, py

    def mid_layer(self):
        """far shore bank + conifers, painted as marks on an extended canvas (rows -140..H).
        returns colour canvas (linear rgb), alpha, and the offset."""
        OFF = 140
        HH = H + OFF
        col = np.zeros((HH, W, 3)); al = np.zeros((HH, W))
        mark = np.zeros((HH, W), np.int8)  # 1 bank, 2 tree dark, 3 tree lit, 4 tree mid
        rng = np.random.default_rng(self.seed + 99)
        # far bank: ground rising from waterline over 35 m by ~3 m
        zf = self.zfar
        xs = (np.arange(W) + 0.5)
        th = math.tan(HFOV / 2)
        fwd, right, up = self.basis()
        # per column: waterline row and bank-top row
        rays = self.rays()[0]
        # world x at far plane per column (approx)
        colx = []
        for zz, hh in ((zf, 0.0), (zf + 35, 3.0)):
            pts = []
            for i in range(W):
                d = rays[i]; tt = (zz - self.eye[2]) / d[2]; pts.append(self.eye + d * tt)
            pts = np.array(pts); pts[:, 1] = hh
            colx.append(self.project(pts)[1])
        y_wl, y_top = colx
        bank_top_noise = fbm2(xs * 0.05 + self.seed, np.zeros_like(xs), self.seed + 60, 3) * 1.5
        for x in range(W):
            y0 = int(round(y_wl[x])) + OFF; y1 = int(round(y_top[x] + bank_top_noise[x])) + OFF
            y0 = min(max(y0, 0), HH - 1); y1 = min(max(y1, 0), y0)
            mark[y1:y0 + 1, x] = 1
        # conifers: rooted along the far bank, heights in metres -> pixels
        dist = zf + 12 - self.eye[2]
        pix_ang = HFOV / W
        n_trees = int(W / 6 * self.tree_density)
        xs_t = rng.uniform(-30, W + 30, n_trees)
        # clump them: keep trees where a low-freq noise is high
        keep = fbm2(xs_t * 0.02 + self.seed * 0.1, np.zeros_like(xs_t), self.seed + 61, 2) > -0.15
        xs_t = np.sort(xs_t[keep])
        sunx = self.sun @ right  # + sun to the right on screen
        back = (self.sun @ fwd) > 0.3
        for x0 in xs_t:
            hm = rng.uniform(7, 19) * (1 if rng.uniform() > 0.2 else 0.5)
            hp = hm / dist / pix_ang
            xi = int(round(x0)); base = int(round(np.interp(x0, np.arange(W), y_top))) + OFF + rng.integers(0, 3)
            wmax = max(1.5, hp * rng.uniform(0.22, 0.3))
            tier = max(2, int(round(hp / rng.uniform(5, 8))))
            for r in range(int(hp)):
                y = base - int(hp) + r
                if y < 0 or y >= HH: continue
                f = r / hp
                ph = (r % tier) / tier
                hw = wmax * f * (0.55 + 0.45 * ph) + (0.5 if r > 1 else 0)
                jitter = rng.uniform(-0.6, 0.6)
                xa = int(round(x0 - hw + jitter)); xb = int(round(x0 + hw + jitter))
                for x in range(max(xa, 0), min(xb, W - 1) + 1):
                    m = 2
                    edge_sun = (x == xb and sunx > 0.2) or (x == xa and sunx < -0.2)
                    if edge_sun and ph > 0.25: m = 3
                    elif rng.uniform() < 0.18: m = 4
                    if back and (x == xa or x == xb) and ph > 0.5 and rng.uniform() < 0.5: m = 3
                    mark[y, x] = m
            # trunk visible below lowest tier sometimes
        # colours for marks (linear), light model applied to canonical states
        bankC = self.grassA * (self.sunC * 0.30 * max(0.0, -self.sun @ np.array([0, 0, 1.0]) * 0.5 + 0.35) + self.skyC * 0.9)
        treeA = np.array([0.10, 0.12, 0.05])
        treeD = treeA * self.skyC * 0.6
        treeM = treeA * (self.skyC * 1.0 + self.sunC * 0.05)
        treeL = self.grassA * (self.sunC * 0.35 + self.skyC)
        haze = self.sky(norm(np.array([0.0, 0.02, 1.0])))
        amt = min(0.55, (zf / 260.0))
        cols = {1: bankC, 2: treeD, 3: treeL, 4: treeM}
        for m, c in cols.items():
            cc = c * (1 - amt * 0.6) + haze * amt * 0.6 * (0.35 if m != 1 else 0.5)
            col[mark == m] = cc; al[mark == m] = 1
        # stipple on bank: tussock light/dark flecks
        bankmask = mark == 1
        nz = rng.uniform(size=bankmask.shape)
        col[bankmask & (nz < 0.25)] *= 0.62
        col[bankmask & (nz > 0.85)] *= 1.3
        return col, al, mark, OFF

    # ---- shading of near-scene hits -----------------------------------------------------
    def shade(self, p, mat, n, vdir):
        vis = self.soft_shadow(p, n)
        ao = self.ao(p, n)
        ndl = np.clip(n @ self.sun, 0, 1)
        rock = mat == 2
        # rough granite: flatter lit plateau and sharper drop at the terminator than Lambert
        sun_rock = ndl ** 0.55
        # grass: a volume of near-vertical blades: some light even on flat ground at 5 deg sun,
        # plus strong light on tussock slopes that face the sun
        sun_grass = 0.22 + 1.05 * ndl
        sunk = np.where(rock, sun_rock, sun_grass) * vis
        skyk = (0.55 + 0.45 * n[..., 1]) * ao
        bnc = np.clip(n @ self.bdir * -1.0, 0, 1)  # bdir points down; faces looking down/away catch it
        bnc = np.clip(n @ (-self.bdir), 0, 1) * ao
        alb = np.where(rock[..., None], self.rockA, self.grassA)
        # albedo variation: drier/greener patches in grass; lichen-mottle on rock
        var = fbm2(p[..., 0] * 0.35, p[..., 2] * 0.35, self.seed + 70, 3)
        alb = alb * (1 + 0.18 * var[..., None] * np.where(rock[..., None], 0.4, 1.0))
        dry = np.clip(0.5 + 0.8 * fbm2(p[..., 0] * 0.12 + 5, p[..., 2] * 0.12, self.seed + 71, 2), 0, 1)
        grass_tint = np.array([1.12, 1.0, 0.72]) * dry[..., None] + np.array([0.85, 1.02, 1.1]) * (1 - dry[..., None])
        alb = np.where(rock[..., None], alb, alb * grass_tint)
        # back-light translucency of grass blades
        trans = np.where(rock, 0, np.clip(-(vdir @ self.sun), 0, 1) ** 3 * vis * 0.9)
        light = self.sunC * (sunk + trans)[..., None] + self.skyC * skyk[..., None] + self.bounceC * bnc[..., None] * np.where(rock, 1.0, 0.3)[..., None]
        col = alb * light
        return col, dict(vis=vis, ao=ao, ndl=ndl, trans=trans)

# --------------------------------------------------------------------------------------------
# stage 1: observation render
# --------------------------------------------------------------------------------------------
SKY, WATER, GRASS, ROCK, FAR = 0, 3, 1, 2, 4

def render_observation(sc):
    d = sc.rays()
    o = sc.eye
    # water plane and far plane bounds
    tw = np.where(d[..., 1] < -1e-6, (0 - o[1]) / np.minimum(d[..., 1], -1e-6), np.inf)
    tfar = np.where(d[..., 2] > 1e-6, (sc.zfar - o[2]) / np.maximum(d[..., 2], 1e-6), np.inf)
    tmax = np.minimum(np.minimum(tw, tfar), 400.0)
    t, hit = sc.march(np.broadcast_to(o, d.shape).copy(), d, tmax)
    p = o + d * t[..., None]
    mat = np.full((H, W), SKY, np.int8)
    water = (~hit) & (tw < tfar)
    mat[water] = WATER
    matn = sc.material_at(p)
    mat[hit] = matn[hit]
    depth = np.where(hit, t, np.where(water, tw, np.inf))
    col = np.zeros((H, W, 3))
    info = {k: np.zeros((H, W)) for k in ("vis", "ao", "ndl", "trans")}
    nrm = np.zeros((H, W, 3))
    if hit.any():
        n = sc.normal(p[hit], mat[hit])
        c, inf = sc.shade(p[hit], mat[hit], n, d[hit])
        col[hit] = c; nrm[hit] = n
        for k in info: info[k][hit] = inf[k]
    # far: mid layer (bank, trees) over far layer (sky, mountains)
    midc, mida, midm, OFF = sc.mid_layer()
    farc, mnt = sc.far_layer(d)
    far = (~hit) & (~water)
    col[far] = farc[far]
    mat[far & mnt] = FAR
    mid_here = (mida[OFF:OFF + H] > 0) & far
    col[mid_here] = midc[OFF:OFF + H][mid_here]
    mat[mid_here] = FAR + 1   # 5 = far shore bank/trees
    # water: Fresnel mirror of everything, with horizontally-correlated ripple normals
    refl_mat = np.full((H, W), -1, np.int8)
    if water.any():
        pw = o + d[water] * tw[water][..., None]
        rng = np.random.default_rng(sc.seed + 5)
        yy, xx = np.nonzero(water)
        # ripple: elongated noise (long in x, short in y) -> horizontal streaks
        rip = fbm2(xx * 0.06 + sc.seed, yy * 0.9, sc.seed + 80, 3)
        amp = math.radians(0.35)
        nrm_w = norm(np.stack([np.zeros_like(rip), np.ones_like(rip), rip * amp * 2.0], -1))
        dv = d[water]
        dr = dv - 2 * (dv @ np.array([0, 1.0, 0]))[..., None] * nrm_w * 0 - 2 * np.sum(dv * nrm_w, -1)[..., None] * nrm_w
        dr = norm(dr)
        # wind lines: sparse horizontal segments where the surface tilts -> sees higher sky
        wl = np.zeros(len(yy))
        segs = rng.integers(0, 1, 1)
        wmask = np.zeros((H, W))
        nseg = int(0.04 * water.sum() / 20) + 3
        for _ in range(nseg):
            ys = rng.integers(0, H); xs0 = rng.integers(0, W); L = int(rng.integers(6, 50) * (1.0 - ys / H * 0.6))
            wmask[ys, xs0:xs0 + L] = 1
        wl = wmask[yy, xx]
        dr = norm(dr + np.stack([np.zeros_like(wl), wl * math.radians(2.5), np.zeros_like(wl)], -1))
        tmx = np.full(len(yy), 200.0)
        tfar_r = np.where(dr[:, 2] > 1e-6, (sc.zfar - pw[:, 2]) / np.maximum(dr[:, 2], 1e-6), np.inf)
        tmx = np.minimum(tmx, tfar_r)
        tr, hr = sc.march(pw + dr * 0.01, dr, tmx, steps=200)
        rc = np.zeros((len(yy), 3))
        rmat = np.full(len(yy), -1, np.int8)
        if hr.any():
            ph = pw[hr] + dr[hr] * tr[hr][..., None]
            mh = sc.material_at(ph)
            nh = sc.normal(ph, mh)
            ch, _ = sc.shade(ph, mh, nh, dr[hr])
            rc[hr] = ch; rmat[hr] = mh
        miss = ~hr
        if miss.any():
            # mid layer via its point on the far plane; else far layer by direction
            q = pw[miss] + dr[miss] * np.minimum(tfar_r[miss], 1e5)[..., None]
            qpx, qpy, qz = sc.project(q)
            qx = np.clip(np.round(qpx).astype(int), 0, W - 1); qy = np.round(qpy).astype(int) + OFF
            okm = (qy >= 0) & (qy < H + OFF) & np.isfinite(tfar_r[miss]) & (qz > 0)
            qy = np.clip(qy, 0, H + OFF - 1)
            midhit = okm & (mida[qy, qx] > 0)
            fc, fm = sc.far_layer(dr[miss])
            cm = np.where(midhit[..., None], midc[qy, qx], fc)
            rc[miss] = cm
            rmat[miss] = np.where(midhit, 5, np.where(fm, FAR, SKY))
        # Fresnel (Schlick, n=1.33) on the rippled normal
        cos_i = np.clip(-np.sum(dv * nrm_w, -1), 0, 1)
        R = 0.02 + 0.98 * (1 - cos_i) ** 5
        col[water] = rc * R[..., None] + sc.waterBody * (1 - R[..., None]) * (sc.skyC / sc.skyC.mean())
        refl_mat[water] = rmat
    return dict(col=col, mat=mat, depth=depth, nrm=nrm, refl_mat=refl_mat, midmark=midm[OFF:OFF + H], **info)

# --------------------------------------------------------------------------------------------
# tone + colour helpers
# --------------------------------------------------------------------------------------------
EXPOSURE = 1.0

def tone(c):
    c = np.maximum(c, 0) * EXPOSURE
    c = c / (1 + 0.35 * c)                 # gentle shoulder
    return np.where(c <= 0.0031308, 12.92 * c, 1.055 * np.power(np.clip(c, 0, None), 1 / 2.4) - 0.055).clip(0, 1)

def to_lab(srgb):
    return rgb2lab(np.asarray(srgb, float).reshape(-1, 1, 3)).reshape(np.shape(srgb))

# --------------------------------------------------------------------------------------------
# stage 2a: palette from canonical light states
# --------------------------------------------------------------------------------------------
def kmeans_ramp(samples_srgb, k, key, seed=0):
    from sklearn.cluster import KMeans
    lab = to_lab(samples_srgb)
    if len(lab) < k: k = max(1, len(lab))
    km = KMeans(k, n_init=3, random_state=seed).fit(lab)
    cen = km.cluster_centers_
    order = np.argsort(key(cen, km, lab))
    return lab2rgb(cen[order].reshape(-1, 1, 3)).reshape(-1, 3).clip(0, 1)

def build_palette(sc, obs):
    """32 colours, allotted by material:  sky 8, grass 9, rock 7, far 4, water 3, sun/accent 1.
    grass and rock ramps are the light model evaluated at canonical light states (what the photos
    showed: contact / core / bounce-lit shadow / half / lit / rim for rock; gap / shadow / lit /
    lit-tip for grass). sky, far and water ramps are k-means of the observed continuous colours."""
    pal = {}
    s = sc
    # ---- grass: states (sun, sky, bounce, ao)
    gA = s.grassA
    dry = gA * np.array([1.12, 1.0, 0.72])
    states_g = [(0.0, 0.18, 0.05, gA * 0.8), (0.0, 0.45, 0.2, gA), (0.0, 0.8, 0.4, gA), (0.10, 1.0, 0.5, gA),
                (0.25, 1.0, 0.5, dry), (0.45, 1.0, 0.5, dry), (0.75, 1.0, 0.5, dry), (1.05, 1.0, 0.5, dry), (1.5, 1.0, 0.5, dry * 1.1)]
    pal["grass"] = np.array([tone(a * (s.sunC * su + s.skyC * sk + s.bounceC * 0.3 * b)) for su, sk, b, a in states_g])
    # ---- rock
    rA = s.rockA
    states_r = [(0.0, 0.10, 0.05), (0.0, 0.30, 0.15), (0.0, 0.62, 0.35), (0.0, 0.85, 0.8), (0.30, 0.85, 0.3), (0.62, 0.85, 0.1), (1.0, 0.9, 0.0)]
    pal["rock"] = np.array([tone(rA * (s.sunC * su + s.skyC * sk + s.bounceC * b)) for su, sk, b in states_r])
    # ---- sky (visible sky + what water reflects)
    col = obs["col"]; mat = obs["mat"]
    sky_px = tone(col[mat == SKY]) if (mat == SKY).any() else np.zeros((1, 3))
    # sample the sky up to 40 deg elevation too (reflected in near water)
    fwd, right, up = s.basis()
    az = np.linspace(-0.6, 0.6, 30) + s.yaw; el = np.linspace(0.0, 0.7, 40)
    A, E = np.meshgrid(az, el)
    dd = np.stack([np.sin(A) * np.cos(E), np.sin(E), np.cos(A) * np.cos(E)], -1).reshape(-1, 3)
    sk = s.sky(dd); sk = sk[(dd @ s.sun) < math.cos(math.radians(1.5))]
    samp = np.concatenate([sky_px, tone(sk)])
    pal["sky"] = kmeans_ramp(samp, 8, lambda c, km, lab: c[:, 0], s.seed)
    far_px = col[(mat == FAR)]
    pal["far"] = kmeans_ramp(tone(far_px), 4, lambda c, km, lab: c[:, 0], s.seed) if len(far_px) > 8 else \
        kmeans_ramp(tone(s.far_layer(dd[:200])[0]), 4, lambda c, km, lab: c[:, 0], s.seed)
    wat = col[mat == WATER]
    pal["water"] = kmeans_ramp(tone(wat), 3, lambda c, km, lab: c[:, 0], s.seed) if len(wat) > 8 else np.zeros((3, 3))
    back_sun = (s.sun @ s.basis()[0]) > 0.3
    pal["accent"] = np.array([tone(s.sunC * 0.9)]) if back_sun else np.array([tone(rA * (s.sunC * 1.3 + s.skyC))])
    return pal

# --------------------------------------------------------------------------------------------
# stage 2b: painting
# --------------------------------------------------------------------------------------------
BAYER2 = np.array([[0, 2], [3, 1]]) / 4.0

class Painter:
    def __init__(self, sc, obs, pal):
        self.sc, self.obs, self.pal = sc, obs, pal
        self.names = ["sky", "grass", "rock", "far", "water", "accent"]
        cols = []; self.ramp_idx = {}
        for n in self.names:
            i0 = len(cols); cols += list(pal[n]); self.ramp_idx[n] = np.arange(i0, len(cols))
        self.P = np.clip(np.array(cols), 0, 1)
        assert len(self.P) <= 32, len(self.P)
        self.Plab = to_lab(self.P)
        self.img = np.zeros((H, W), np.int16)
        self.rng = np.random.default_rng(sc.seed + 1234)
        yy, xx = np.mgrid[0:H, 0:W]; self.yy, self.xx = yy, xx
        self.checker = ((xx + yy) & 1).astype(float)

    def ramp_pos(self, lab, ramp):
        """position along a ramp polyline (in Lab) -> float index"""
        R = self.Plab[self.ramp_idx[ramp]]
        best = np.full(lab.shape[:-1], np.inf); pos = np.zeros(lab.shape[:-1])
        if len(R) == 1: return pos
        for i in range(len(R) - 1):
            a, b = R[i], R[i + 1]; ab = b - a
            t = np.clip(((lab - a) @ ab) / (ab @ ab + 1e-9), 0, 1)
            dist = np.linalg.norm(lab - (a + t[..., None] * ab), axis=-1)
            m = dist < best; best[m] = dist[m]; pos[m] = i + t[m]
        return pos

    def pick(self, ramp, pos, thresh):
        """dither between ramp[floor(pos)] and ramp[floor(pos)+1] using threshold field"""
        idx = self.ramp_idx[ramp]
        i0 = np.clip(np.floor(pos).astype(int), 0, len(idx) - 1)
        f = pos - np.floor(pos)
        i1 = np.clip(i0 + 1, 0, len(idx) - 1)
        return np.where(f > thresh, idx[i1], idx[i0])

    def checker_thresh(self, f_shape_mask=None):
        # 3-level: <1/3 -> A, >2/3 -> B, between -> 50% checker   (Ferrari's sky/water)
        return np.where(self.checker > 0, 0.36, 0.64)

    # ----------------------------------------------------------------------
    def paint(self):
        o = self.obs; sc = self.sc
        srgb = tone(o["col"]); lab = to_lab(srgb)
        mat = o["mat"]
        img = self.img
        # --- sky: bands + checker strips
        m = mat == SKY
        pos = self.ramp_pos(lab, "sky")
        img[m] = self.pick("sky", pos, self.checker_thresh())[m]
        # sun disk/glitter accent
        sunny = m & (srgb.sum(-1) > 2.75)
        if (sc.sun @ sc.basis()[0]) > 0.3: img[sunny] = self.ramp_idx["accent"][0]
        # --- far mountains: facets, checker between, speckle
        m = mat == FAR
        pos = self.ramp_pos(lab, "far")
        th = np.where(self.rng.uniform(size=(H, W)) < 0.5, self.checker_thresh(), self.rng.uniform(0.2, 0.8, (H, W)))
        img[m] = self.pick("far", pos, th)[m]
        # --- far shore bank + trees (mid layer): marks already placed; map colours to grass/far ramps
        m = mat == FAR + 1
        if m.any():
            posg = self.ramp_pos(lab, "grass")
            img[m] = self.pick("grass", posg, self.rng.uniform(0, 1, (H, W)))[m]
        # --- water
        self.paint_water(lab, srgb)
        # --- rock
        self.paint_rock(lab, srgb)
        # --- grass (strokes, far to near, z-tested; overlap water/rock)
        self.paint_grass(lab, srgb)
        return img

    def paint_water(self, lab, srgb):
        o = self.obs; m = o["mat"] == WATER
        if not m.any(): return
        # candidates: all palette colours except accent unless glitter; nearest two, dithered with
        # horizontal-run thresholds (reflections read as horizontal dashes)
        cand = np.concatenate([self.ramp_idx[n] for n in ("sky", "water", "far", "grass", "rock")])
        yy, xx = np.nonzero(m)
        L = lab[m]
        d = np.linalg.norm(L[:, None, :] - self.Plab[cand][None], axis=-1)
        o2 = np.argsort(d, 1)[:, :2]
        a = cand[o2[:, 0]]; b = cand[o2[:, 1]]
        da = d[np.arange(len(L)), o2[:, 0]]; db = d[np.arange(len(L)), o2[:, 1]]
        f = da / (da + db + 1e-9)       # 0 -> a, 0.5 -> between
        # horizontal-run threshold: constant along random runs of 2..6 px
        run = np.zeros((H, W))
        for y in range(H):
            x = 0
            while x < W:
                L_ = self.rng.integers(2, 7); run[y, x:x + L_] = self.rng.uniform(); x += L_
        refl_sky = np.isin(o["refl_mat"][m], (SKY,))
        th = np.where(refl_sky, np.where(self.checker[m] > 0, 0.30, 0.70), 0.15 + 0.7 * run[m])
        # f in [0,.5]: choose b when f > th*0.5
        pick = np.where(f > th * 0.5, b, a)
        self.img[yy, xx] = pick
        # glitter under a back-lit sun
        if (self.sc.sun @ self.sc.basis()[0]) > 0.3:
            g = (srgb[m].sum(-1) > 2.3)
            self.img[yy[g], xx[g]] = self.ramp_idx["accent"][0]
        # far-shore light line: the first water row under the far bank
        mat = o["mat"]
        for x in range(W):
            col = np.nonzero(m[:, x])[0]
            if len(col) == 0: continue
            y0 = col[0]
            if y0 > 0 and mat[y0 - 1, x] in (FAR + 1, FAR, SKY) and self.rng.uniform() < 0.8:
                light = self.ramp_idx["sky"][-3] if len(self.ramp_idx["sky"]) >= 3 else self.ramp_idx["sky"][-1]
                self.img[y0, x] = light

    def paint_rock(self, lab, srgb):
        o = self.obs; m = o["mat"] == ROCK
        if not m.any(): return
        pos = self.ramp_pos(lab, "rock")
        # granite speckle: small-scale noise nudges the ramp position (reads as texture up close)
        n_pix = m.sum()
        spk = self.rng.normal(0, 0.28, (H, W)) * (1.0 if n_pix > 400 else 0.4)
        # lit/shadow family split kept crisp: dither only near the terminator & turning edges
        th = np.where(self.checker > 0, 0.4, 0.6)
        idx = self.pick("rock", np.clip(pos + spk * (pos > 0.8), 0, None), th)
        r = self.ramp_idx["rock"]
        # contact line: occlusion where rock meets ground -> darkest
        ao = o["ao"]
        idx = np.where(m & (ao < 0.45), r[0], idx)
        # rim: silhouette pixels facing the sun get the top value
        nrm = o["nrm"]; ndl = o["ndl"]; vis = o["vis"]
        sun_scr = np.array([self.sc.sun @ self.sc.basis()[1], self.sc.sun @ self.sc.basis()[2]])
        edge = np.zeros_like(m)
        dx = int(np.sign(sun_scr[0])) if abs(sun_scr[0]) > 0.25 else 0
        for ddx, ddy in ((dx, 0), (0, -1)):
            if ddx == 0 and ddy == 0: continue
            sh = np.roll(np.roll(m, -ddy, 0), -ddx, 1)
            edge |= m & ~sh
        rim = edge & (ndl > 0.25) & (vis > 0.5)
        idx = np.where(rim, r[-1], idx)
        # back-light: rim on the top silhouette edge
        if (self.sc.sun @ self.sc.basis()[0]) > 0.3:
            top = m & ~np.roll(m, 1, 0)
            idx = np.where(top & (nrm[..., 1] > 0.2), r[-2], idx)
        self.img[m] = idx[m]

    def paint_grass(self, lab, srgb):
        o = self.obs; sc = self.sc; mat = o["mat"]
        m = mat == GRASS
        if not m.any(): return
        pos = self.ramp_pos(lab, "grass")
        r = self.ramp_idx["grass"]; nr = len(r)
        depth = o["depth"]
        rng = self.rng
        # base: stipple dither (isotropic) - this is what survives in the distance
        base = self.pick("grass", pos, rng.uniform(0, 1, (H, W)))
        self.img[m] = base[m]
        # blade length in px: real blade ~0.3 m, projected; capped
        pix_ang = HFOV / W
        blade_m = 0.28
        Lpx = blade_m / np.maximum(depth, 0.1) / pix_ang * 0.55
        # taller grass/sedge ring at the boulder foot and along the water's lip
        p_world = sc.eye + sc.rays() * np.where(np.isfinite(depth), depth, 0)[..., None]
        bd = sc.boulder_sdf(p_world)
        foot = np.clip(1 - bd / (0.45 * sc.a + 0.15), 0, 1)
        sd = sc.shore_d(p_world[..., 0], p_world[..., 2])
        lipz = np.clip(1 - sd / 0.6, 0, 1)
        Lpx = Lpx * (1 + 1.1 * foot + 0.8 * lipz)
        Lpx = np.clip(Lpx, 0, 14)
        wind = rng.uniform(-0.25, 0.1)
        dep = depth.copy()
        ys, xs = np.nonzero(m & (Lpx >= 1.6))
        order = np.argsort(dep[ys, xs])[::-1]   # far first
        ys, xs = ys[order], xs[order]
        img = self.img
        vis = o["vis"]; trans = o["trans"]
        for y, x in zip(ys, xs):
            L = Lpx[y, x]
            if rng.uniform() > min(1.0, 1.6 / L + 0.15): continue
            p0 = pos[y, x] + rng.normal(0, 0.35)
            gap = rng.uniform() < 0.38
            ln = L * rng.uniform(0.55, 1.25) * (0.7 if gap else 1.0)
            lean = wind + rng.normal(0, 0.18)
            curve = rng.normal(0, 0.02)
            zroot = dep[y, x]
            n = max(1, int(round(ln)))
            lit_tip = (vis[y, x] > 0.5) or (trans[y, x] > 0.2)
            fx = float(x)
            for k in range(n):
                yy = y - k
                if yy < 0: break
                fx += lean + curve * k
                xx = int(round(fx))
                if xx < 0 or xx >= W: break
                # z-test: only paint over things farther than the root
                if dep[yy, xx] < zroot - 0.05 and mat[yy, xx] != GRASS: break
                if mat[yy, xx] == GRASS and dep[yy, xx] < zroot - 0.3: break
                f = k / max(n - 1, 1)
                if gap:
                    pi = p0 - 2.2 + 0.6 * f
                else:
                    pi = p0 - 1.1 + 1.6 * f + (0.9 * f if lit_tip else 0)
                img[yy, xx] = r[int(np.clip(round(pi), 0, nr - 1))]

# --------------------------------------------------------------------------------------------
def paint_scene(size="medium", light="left", distance="10m", seed=0, return_obs=False):
    sc = Scene(size, light, distance, seed)
    obs = render_observation(sc)
    pal = build_palette(sc, obs)
    pt = Painter(sc, obs, pal)
    idx = pt.paint()
    rgb = (pt.P[idx] * 255).round().astype(np.uint8)
    if return_obs:
        return rgb, (tone(obs["col"]) * 255).astype(np.uint8), pt.P, obs
    return rgb

def up3(rgb):
    return np.repeat(np.repeat(rgb, 3, 0), 3, 1)

if __name__ == "__main__":
    ap = argparse.ArgumentParser()
    ap.add_argument("--size", default="medium"); ap.add_argument("--light", default="left")
    ap.add_argument("--distance", default="10m"); ap.add_argument("--seed", type=int, default=0)
    ap.add_argument("--out", default="out/single.png")
    a = ap.parse_args()
    rgb, obsimg, P, obs = paint_scene(a.size, a.light, a.distance, a.seed, True)
    os.makedirs(os.path.dirname(a.out) or ".", exist_ok=True)
    Image.fromarray(up3(rgb)).save(a.out)
    Image.fromarray(up3(obsimg)).save(a.out.replace(".png", "_obs.png"))
    print("colours used:", len(np.unique(rgb.reshape(-1, 3), axis=0)), "palette:", len(P))

cd ~/work/pixelart-studies/pedagogy/observation && time OMP_NUM_THREADS=4 OPENBLAS_NUM_THREADS=4 nice -n 10 python3 tarn.py --out out/t1.png 2>&1 | tail -20

# output:
colours used: 28 palette: 32
OMP_NUM_THREADS=4 OPENBLAS_NUM_THREADS=4 nice -n 10 python3 tarn.py --out  2>  20.57s user 5.41s system 84% cpu 30.632 total
tail -20  0.00s user 0.00s system 0% cpu 30.630 total

cd ~/work/pixelart-studies/pedagogy/observation && cat > ferrari_contours.py <<'EOF'
"""How Ferrari's contours resolve into pixel runs.
For a silhouette edge y_top(x) (first 'object' pixel per column), record the run structure:
horizontal run lengths at constant y, and the size of each vertical step between runs.
Clean steps: run 1 & step 1 = 45 deg; run 2 & step 1 = 2:1; run 1 & step 2 = 1:2, etc."""
import numpy as np
from PIL import Image
from collections import Counter
a = np.array(Image.open("ferrari/native.png").convert("RGB")).astype(int)
def is_sky(c):  # the pink/violet sky ramp: bright, R>=G, B high-ish
    r, g, b = c[..., 0], c[..., 1], c[..., 2]
    return (r > 170) & (g > 140) & (b > 140)
def contour_runs(y_top):
    runs, steps = [], []
    x = 0
    while x < len(y_top):
        x2 = x
        while x2 + 1 < len(y_top) and y_top[x2 + 1] == y_top[x]: x2 += 1
        runs.append(x2 - x + 1)
        if x2 + 1 < len(y_top): steps.append(abs(int(y_top[x2 + 1]) - int(y_top[x])))
        x = x2 + 1
    return runs, steps
def report(name, y_top):
    runs, steps = contour_runs(y_top)
    pairs = Counter(zip(runs[:-1], steps))
    print(f"== {name}: {len(runs)} runs")
    print("   run length hist :", sorted(Counter(runs).items())[:12])
    print("   step size hist  :", sorted(Counter(steps).items())[:10])
    tot = sum(pairs.values())
    print("   top (run,step)  :", [(k, round(v / tot, 2)) for k, v in pairs.most_common(8)])
    # consistency: fraction of consecutive run pairs equal (a clean slope repeats its run length)
    same = np.mean([abs(runs[i] - runs[i + 1]) <= 0 for i in range(len(runs) - 1)])
    print(f"   consecutive equal runs: {same:.2f}")
# mountain ridge vs sky, x 180..420 (native)
S = is_sky(a)
yt = np.array([np.argmax(~S[40:200, x]) + 40 for x in range(190, 440)])
report("mountain ridge (native x190-440)", yt)
# island top edge: grass pixels are yellow-green (g>b)
def is_grass(c): return (c[..., 1] >= c[..., 2] + 8)
G = is_grass(a)
yt = np.array([np.argmax(G[255:300, x]) + 255 for x in range(275, 410)])
report("island mound top (x275-410)", yt)
# left bank edge against water, per row: first non-grass pixel from left in rows 300..380
xr = np.array([np.argmax(~G[y, 60:330]) + 60 for y in range(285, 330)])
report("left bank lip, per row (y285-330)", xr)
EOF
python3 ferrari_contours.py

# output:
== mountain ridge (native x190-440): 154 runs
   run length hist : [(1, 90), (2, 49), (3, 6), (4, 4), (5, 2), (6, 3)]
   step size hist  : [(1, 101), (2, 12), (3, 6), (4, 9), (5, 5), (6, 4), (7, 3), (8, 1), (9, 3), (10, 4)]
   top (run,step)  : [((1, 1), 0.31), ((2, 1), 0.26), ((1, 2), 0.07), ((1, 4), 0.05), ((1, 5), 0.03), ((1, 3), 0.03), ((3, 1), 0.03), ((4, 1), 0.03)]
   consecutive equal runs: 0.54
== island mound top (x275-410): 46 runs
   run length hist : [(1, 33), (2, 4), (5, 3), (6, 1), (7, 2), (8, 1), (9, 1), (42, 1)]
   step size hist  : [(1, 30), (2, 9), (3, 5), (4, 1)]
   top (run,step)  : [((1, 1), 0.53), ((1, 2), 0.11), ((1, 3), 0.07), ((5, 1), 0.07), ((2, 3), 0.04), ((7, 1), 0.04), ((2, 2), 0.04), ((1, 4), 0.02)]
   consecutive equal runs: 0.56
== left bank lip, per row (y285-330): 40 runs
   run length hist : [(1, 37), (2, 2), (4, 1)]
   step size hist  : [(1, 6), (2, 6), (3, 4), (4, 4), (5, 2), (6, 1), (7, 1), (8, 2), (11, 1), (12, 2)]
   top (run,step)  : [((1, 2), 0.15), ((1, 1), 0.13), ((1, 3), 0.1), ((1, 4), 0.1), ((1, 12), 0.05), ((1, 8), 0.05), ((1, 5), 0.05), ((1, 15), 0.05)]
   consecutive equal runs: 0.90

cd ~/work/pixelart-studies/pedagogy/observation && python3 -c "
from PIL import Image; import numpy as np
from collections import Counter
a=np.array(Image.open('ferrari/native.png').convert('RGB'))
def cc(name,box):
  r=a[box[1]:box[3],box[0]:box[2]].reshape(-1,3); c=Counter(map(tuple,r)); n=len(r)
  print(name, len(c),'colours'); print('   ',[(k,round(v/n,3)) for k,v in c.most_common(10)])
cc('island lit+shadow',(280,262,410,292))
cc('island reflection',(290,293,410,305))
cc('stones',(250,405,320,430))
cc('mountain facets',(260,90,380,160))
cc('near grass right',(450,380,634,469))
cc('near grass left',(0,380,150,469))
cc('water refl sky',(300,380,420,420))
"
python3 -c "
from PIL import Image
im=Image.open('~/work/pixelart-studies/pedagogy/observation/ferrari/native.png').convert('RGB')
for n,b in {'island8':(270,255,420,310),'stones8':(240,398,320,440),'facet8':(290,95,370,150)}.items():
  im.crop(b).resize(((b[2]-b[0])*8,(b[3]-b[1])*8),Image.NEAREST).save('~/work/pixelart-studies/pedagogy/observation/ferrari/'+n+'.png')
"

# output:
island lit+shadow 30 colours
    [((106, 80, 40), 0.251), ((196, 134, 76), 0.22), ((28, 31, 20), 0.218), ((60, 63, 45), 0.112), ((0, 0, 0), 0.033), ((58, 55, 48), 0.033), ((136, 101, 50), 0.019), ((46, 43, 32), 0.016), ((11, 11, 1), 0.009), ((66, 48, 38), 0.009)]
island reflection 37 colours
    [((106, 80, 40), 0.349), ((60, 63, 45), 0.06), ((33, 37, 13), 0.05), ((92, 79, 34), 0.048), ((154, 110, 57), 0.042), ((28, 31, 20), 0.04), ((53, 50, 20), 0.036), ((88, 76, 32), 0.035), ((30, 36, 12), 0.035), ((54, 47, 24), 0.03)]
stones 15 colours
    [((103, 80, 87), 0.344), ((217, 159, 169), 0.099), ((198, 152, 170), 0.089), ((64, 48, 55), 0.085), ((131, 101, 112), 0.074), ((183, 164, 189), 0.063), ((154, 119, 136), 0.054), ((180, 144, 167), 0.053), ((219, 160, 170), 0.051), ((108, 82, 91), 0.037)]
mountain facets 29 colours
    [((103, 84, 109), 0.146), ((178, 152, 188), 0.119), ((68, 52, 74), 0.106), ((0, 0, 0), 0.087), ((68, 56, 74), 0.066), ((239, 141, 114), 0.06), ((128, 85, 106), 0.049), ((235, 167, 161), 0.045), ((88, 72, 93), 0.037), ((136, 101, 50), 0.032)]
near grass right 4 colours
    [((0, 0, 0), 0.487), ((62, 59, 23), 0.252), ((28, 31, 4), 0.245), ((66, 63, 42), 0.016)]
near grass left 4 colours
    [((115, 92, 35), 0.482), ((196, 131, 70), 0.321), ((10, 34, 10), 0.162), ((62, 59, 23), 0.036)]
water refl sky 29 colours
    [((28, 31, 4), 0.184), ((66, 63, 42), 0.159), ((62, 59, 23), 0.138), ((173, 141, 165), 0.096), ((213, 181, 205), 0.05), ((180, 144, 167), 0.048), ((198, 152, 170), 0.048), ((217, 159, 169), 0.044), ((224, 192, 210), 0.043), ((198, 172, 201), 0.028)]

"""
pix.py -- small pixel-craft primitives learned from Ferrari's pixels (see translate_studies.py).

 clean_profile   a contour as runs: flat runs, 45 deg (1:1), 2:1, 1:2 ... held consistently
 majority_clean  remove isolated single pixels in a zone map (his zones are shapes, not noise)
 stipple         random-threshold dither between two colours (organic transitions: grass, rock)
 checker         3-level ordered dither: A | 50% checker | B  (smooth things: sky, water, snow)
"""
import numpy as np

def clean_profile(yf, max_run=14):
    """float y per column -> int y per column made of consistent runs.
    |slope| < 1 : horizontal runs of n = round(1/|slope|) px then a 1 px step
    |slope| >= 1: 1 px runs with vertical steps of k = round(|slope|)
    the pattern is held until the contour drifts more than 1 px from the true curve."""
    yf = np.asarray(yf, float); n = len(yf)
    if n == 0: return yf.astype(int)
    out = np.zeros(n, int); y = int(round(yf[0])); out[0] = y
    run_len, run_pos, step = 1, 0, 0
    def choose(x):
        x2 = min(n - 1, x + 3); x1 = max(0, x - 1)
        s = (yf[x2] - yf[x1]) / max(x2 - x1, 1)
        if abs(s) < 1.0 / max_run: return max_run, 0
        if abs(s) < 1: return int(np.clip(round(1 / abs(s)), 1, max_run)), int(np.sign(s))
        return 1, int(np.sign(s) * round(abs(s)))
    run_len, step = choose(0)
    for x in range(1, n):
        run_pos += 1
        if run_pos >= run_len:
            y += step; run_pos = 0
            run_len, step = choose(x)
        # re-sync when drifting
        if abs(y - yf[x]) > 1.0:
            y = int(round(yf[x])); run_pos = 0; run_len, step = choose(x)
        out[x] = y
    return out

def majority_clean(z, iters=1, protect=None):
    """replace pixels that disagree with both horizontal or both vertical neighbours, when those
    neighbours agree with each other (kills single-pixel noise, keeps 1-px lines that run)."""
    z = z.copy()
    for _ in range(iters):
        l = np.roll(z, 1, 1); r = np.roll(z, -1, 1); u = np.roll(z, 1, 0); d = np.roll(z, -1, 0)
        iso_h = (l == r) & (z != l); iso_v = (u == d) & (z != u)
        iso = iso_h & iso_v
        if protect is not None: iso &= ~protect
        z = np.where(iso, l, z)
    return z

def stipple(t, rng, bias=0.0):
    """True where colour B should be used, given fraction t in [0,1] (white-noise threshold)."""
    return t + bias > rng.uniform(0, 1, np.shape(t))

def checker(t, yy, xx):
    """3-level: t<1/3 -> A (False), t>2/3 -> B (True), otherwise 50% checkerboard"""
    c = ((xx + yy) & 1) == 1
    return np.where(t < 1 / 3, False, np.where(t > 2 / 3, True, c))

def hex2rgb(h):
    h = h.lstrip("#"); return np.array([int(h[i:i + 2], 16) for i in (0, 2, 4)], np.uint8)

"""
translate_studies.py -- one observed truth at a time, translated into pixels, shown beside the
photo it came from and beside Ferrari's pixels for the nearest thing in his tarn, all at 8x.

  python translate_studies.py D      -> studies/translate_D.png  etc.
"""
import sys, numpy as np
from PIL import Image, ImageDraw
from pix import clean_profile, majority_clean, stipple, checker, hex2rgb

FER = np.array(Image.open("ferrari/native.png").convert("RGB"))
S = 8

# dusk palette pieces used by the studies (grass from Ferrari's own grass; granite hue-shifted:
# lit toward peach/orange like his lit rock, shadows toward violet like his shadow rock)
C = {k: hex2rgb(v) for k, v in dict(
    rim="F6C8AA", lit="E3A283", half="B48C98", shade="7E6268", core="54435A", contact="241C29",
    g_tan="C4834C", g_ochre="735C23", g_gap="0A220A", g_mid="886532",
    g_dol="3E3B17", g_dk="1C1F04", g_blk="000000",
    w_hi="D9B5CD", w_mid="B690A8", w_lo="8A6E86", w_dk="5A4658",
    sky1="E0A6B0", sky2="CFA2BB").items()}

def photo_crop(path, box, h):
    im = Image.open(path).convert("RGB").crop(box)
    w = int(im.size[0] * h / im.size[1]); return im.resize((w, h), Image.LANCZOS)

def fer_crop(box):
    x0, y0, x1, y1 = box
    return Image.fromarray(FER[y0:y1, x0:x1]).resize(((x1 - x0) * S, (y1 - y0) * S), Image.NEAREST)

def mine(img):
    return Image.fromarray(img).resize((img.shape[1] * S, img.shape[0] * S), Image.NEAREST)

def sheet(name, title, panels):
    h = max(p.size[1] for p, _ in panels)
    w = sum(p.size[0] for p, _ in panels) + 12 * (len(panels) - 1)
    out = Image.new("RGB", (w, h + 40), (245, 245, 240)); d = ImageDraw.Draw(out); x = 0
    for p, cap in panels:
        out.paste(p, (x, 0)); d.text((x + 2, h + 4), cap, fill=(0, 0, 0)); x += p.size[0] + 12
    d.text((2, h + 22), title, fill=(90, 0, 0))
    out.save(f"studies/translate_{name}.png"); print("wrote", name)

def paint(zone, colmap):
    img = np.zeros(zone.shape + (3,), np.uint8)
    for k, c in colmap.items(): img[zone == k] = C[c]
    return img

# -------------------------------------------------------------------------------------------
# D: light wrapping a rounded boulder (sun low, from the left)
# observed (r02 profile): lit plateau, SHARP drop at the terminator, a darker core band just past
# it, then a flatter, warmer bounce-lit shadow side; rim of light where the edge faces the sun.
# Ferrari (mountain facets): each value is a flat plane with a clean stepped edge; lit planes
# carry a brighter 1-px lip along the sun-facing ridge; transitions are short checker strips.
# -------------------------------------------------------------------------------------------
def boulder_zones(w, h, cx, cy, a, b, p=2.6, L=(-0.85, 0.12, 0.5), B=(0.55, -0.75, 0.35), seed=1,
                  crack=True):
    rng = np.random.default_rng(seed)
    yy, xx = np.mgrid[0:h, 0:w].astype(float)
    # silhouette: superellipse; top contour cleaned into runs
    X = (xx + 0.5 - cx) / a; Y = (cy - (yy + 0.5)) / b
    # top contour per column, flattened bottom (sunk in ground)
    xs = (np.arange(w) + 0.5 - cx) / a
    inside_x = np.abs(xs) < 1
    ytop = np.full(w, np.inf)
    ytop[inside_x] = cy - b * (1 - np.abs(xs[inside_x]) ** p) ** (1 / p)
    # break the perfect symmetry: weathered block leans, crest offset
    ytop = ytop + 0.12 * b * np.sin(xs * 2.1 + seed) * inside_x
    yt = np.full(w, 10 ** 6)
    cols = np.nonzero(inside_x)[0]
    yt[cols] = clean_profile(ytop[cols])
    base = cy + 0.35 * b          # the ground cuts it: partly sunk
    inside = (yy >= yt[None, :]) & (yy <= base) & inside_x[None, :]
    # normal of a superellipsoid bulge
    r = np.clip(np.abs(X) ** p + np.abs(Y) ** p, 0, 1)
    gx = np.sign(X) * np.abs(X) ** (p - 1) / a; gy = np.sign(Y) * np.abs(Y) ** (p - 1) / b
    nz = (1 - r) ** (1 / p) * 1.2 + 0.05
    n = np.stack([gx * a, gy * b, nz], -1); n /= np.linalg.norm(n, axis=-1, keepdims=True)
    # big weathered planes: quantise the normal a little (granite reads as planes, not a ball)
    n = n + 0.25 * np.stack([np.round(n[..., 0] * 2) / 2, np.round(n[..., 1] * 2) / 2, n[..., 2] * 0], -1)
    n /= np.linalg.norm(n, axis=-1, keepdims=True)
    L = np.array(L) / np.linalg.norm(L); B = np.array(B) / np.linalg.norm(B)
    ndl = n @ L; nb = n @ B
    z = np.full((h, w), -1)
    z[inside & (ndl > 0.55)] = 5                                   # lit face
    z[inside & (ndl <= 0.55) & (ndl > 0.22)] = 4                   # half: top plane, sky + grazing sun
    z[inside & (ndl <= 0.22) & (nb < 0.25)] = 2                    # core band past the terminator
    z[inside & (ndl <= 0.22) & (nb >= 0.25)] = 3                   # bounce-lit shadow side
    z[inside & (ndl <= 0.22) & (ndl > 0.10) & (nb >= 0.25)] = 2    # terminator itself is core
    z = majority_clean(z, 2)
    # lit/half boundary: 1-px checker strip (a rounded turn, not an edge)
    tb = inside & (np.abs(ndl - 0.55) < 0.06)
    z[tb & (((xx + yy).astype(int) & 1) == 1)] = 5
    # rim: silhouette pixel whose neighbour toward the sun is outside, and faces the sun
    left_out = ~np.roll(inside, 1, 1); up_out = ~np.roll(inside, 1, 0)
    z[inside & (left_out | up_out) & (ndl > 0.35)] = 6
    # speckle: sparse flecks of the neighbouring value (granite grain), only inside big zones
    fl = inside & (rng.uniform(size=z.shape) < 0.05) & (z >= 3) & (z <= 5)
    z[fl] = z[fl] - 1
    # a joint crack: dark 1-px line; its lower lip catches light on the sun side
    if crack:
        x0 = int(cx + 0.15 * a); pts = []
        for i in range(int(0.9 * b * 2)):
            y = int(yt[x0] + 1 + i); x = x0 + i // 2
            if 0 <= y < h and 0 <= x < w and inside[y, x] and y < base - 1:
                z[y, x] = 2 if z[y, x] >= 3 else 1
                if x - 1 >= 0 and inside[y, x - 1] and ndl[y, x - 1] > 0.2: z[y, x - 1] = 6 if ndl[y, x - 1] > 0.5 else 5
    return z, inside, yt, base, ndl

def study_D():
    w, h = 44, 30
    z, inside, yt, base, ndl = boulder_zones(w, h, 22, 20, 17, 14)
    bg = np.full((h, w), 0); bg[:14] = 10
    img = np.zeros((h, w, 3), np.uint8)
    img[:] = C["g_ochre"]; img[:14] = C["sky1"]
    cm = {6: "rim", 5: "lit", 4: "half", 3: "shade", 2: "core", 1: "contact"}
    for k, c in cm.items(): img[z == k] = C[c]
    sheet("D", "D  light on a rounded boulder: flat planes, sharp terminator, core band, bounce-lit shadow, sun-side rim",
          [(photo_crop("refs/r02_splitrock_boulders_lowsun_b.jpg", (280, 305, 425, 425), 240), "photo r02 (sun from left)"),
           (fer_crop((296, 98, 350, 128)), "Ferrari: lit/shadow rock facets 8x"),
           (mine(img), "mine 8x")])

if __name__ == "__main__":
    for s in sys.argv[1:]: globals()["study_" + s]()

cd ~/work/pixelart-studies/pedagogy/observation && python3 translate_studies.py D

# output:
wrote D

cd ~/work/pixelart-studies/pedagogy/observation && python3 -c "
from PIL import Image
im=Image.open('ferrari/native.png').convert('RGB')
for n,b in {'facetA':(200,95,290,140),'facetB':(330,110,420,150)}.items():
  im.crop(b).resize(((b[2]-b[0])*8,(b[3]-b[1])*8),Image.NEAREST).save('ferrari/'+n+'.png')
"

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
import re
s = open("translate_studies.py").read()
new_fn = r'''
def sdf_rbox(P, half, rr, seed=1, bump=0.06):
    q = np.abs(P) - (half - rr)
    d = np.linalg.norm(np.maximum(q, 0), axis=-1) + np.minimum(q.max(-1), 0) - rr
    # low-frequency weathering: a few broad dents (not noise at pixel scale)
    rng = np.random.default_rng(seed)
    for _ in range(4):
        c = rng.normal(0, 1, 3); c /= np.linalg.norm(c); c *= half
        d = d + bump * half.max() * np.exp(-np.sum((P - c) ** 2, -1) / (0.35 * half.max()) ** 2)
    return d

def raycast_boulder(w, h, half, rr, yaw=0.5, tilt=np.radians(12), scale=1.0, cx=None, base_frac=0.35, seed=1):
    """orthographic view of a rounded granite block, camera tilted down; returns normal map + mask.
    the ground plane cuts the block at base_frac of its height (partly sunk)."""
    cx = w / 2 if cx is None else cx
    yy, xx = np.mgrid[0:h, 0:w].astype(float)
    # screen -> world ray origins (orthographic)
    ct, st, cy_, sy_ = np.cos(tilt), np.sin(tilt), np.cos(yaw), np.sin(yaw)
    sx = (xx + 0.5 - cx) / scale; syv = (h * 0.62 - (yy + 0.5)) / scale
    fwd = np.array([0, -st, ct]); up = np.array([0, ct, st]); right = np.array([1.0, 0, 0])
    O = sx[..., None] * right + syv[..., None] * up - fwd * 10
    Rm = np.array([[cy_, 0, -sy_], [0, 1, 0], [sy_, 0, cy_]])
    def f(P):
        Pl = P @ Rm.T
        return sdf_rbox(Pl, half, rr, seed)
    t = np.zeros((h, w)); hit = np.zeros((h, w), bool)
    ground = -half[1] + 2 * half[1] * base_frac
    for _ in range(160):
        P = O + fwd * t[..., None]
        d = f(P)
        hit |= d < 1e-3
        t = np.where(hit, t, t + np.maximum(d, 1e-3))
    P = O + fwd * t[..., None]
    hit &= P[..., 1] > ground
    e = 1e-3; n = np.zeros_like(P)
    for i in range(3):
        dp = np.zeros(3); dp[i] = e; n[..., i] = f(P + dp) - f(P - dp)
    n /= np.linalg.norm(n, axis=-1, keepdims=True) + 1e-9
    return n, hit, P, ground

def boulder_zones(w, h, half, rr, L=(-0.9, 0.12, -0.35), B=(0.5, -0.8, -0.2), yaw=0.55, scale=1.0,
                  seed=1, crack=True, cx=None):
    """zones: 6 rim, 5 lit, 4 half, 3 bounce-lit shadow, 2 core, 1 contact"""
    rng = np.random.default_rng(seed)
    n, inside, P, ground = raycast_boulder(w, h, np.array(half), rr, yaw=yaw, scale=scale, seed=seed, cx=cx)
    L = np.array(L) / np.linalg.norm(L); B = np.array(B) / np.linalg.norm(B)
    ndl = n @ L; nb = n @ B
    yy, xx = np.mgrid[0:h, 0:w]
    z = np.full((h, w), -1)
    z[inside & (ndl > 0.5)] = 5
    z[inside & (ndl <= 0.5) & (ndl > 0.16)] = 4
    z[inside & (ndl <= 0.16) & (nb < 0.3)] = 2
    z[inside & (ndl <= 0.16) & (nb >= 0.3)] = 3
    z[inside & (ndl <= 0.16) & (ndl > 0.02)] = 2      # the terminator band is always core
    z = majority_clean(z, 2)
    # a rounded turn between lit and half: 1-px checker strip; the terminator stays sharp
    tb = inside & (np.abs(ndl - 0.5) < 0.05)
    z[tb & (((xx + yy) & 1) == 1)] = 5
    # rim: silhouette pixels whose sun-side neighbour is outside and which face the sun
    sx = -1 if L[0] < -0.2 else (1 if L[0] > 0.2 else 0)
    out_sun = ~np.roll(inside, -sx, 1) if sx else np.zeros_like(inside)
    out_up = ~np.roll(inside, 1, 0)
    z[inside & (out_sun | out_up) & (ndl > 0.3)] = 6
    # sparse grain flecks, only inside large zones
    fl = inside & (rng.uniform(size=z.shape) < 0.045) & (z >= 3) & (z <= 5)
    z[fl] -= 1
    # contact: the lowest 1 px of the silhouette (occlusion where rock meets ground)
    below_out = ~np.roll(inside, -1, 0)
    z[inside & below_out & (P[..., 1] < ground + 0.12 * half[1] * 2)] = 1
    return z, inside, ndl
'''
s = re.sub(r"def boulder_zones\(.*?\n    return z, inside, yt, base, ndl\n", new_fn.strip("\n") + "\n", s, flags=re.S)
s = s.replace('''    z, inside, yt, base, ndl = boulder_zones(w, h, 22, 20, 17, 14)''', '''    z, inside, ndl = boulder_zones(w, h, (15, 10, 11), 5.5, scale=1.0)''')
s = s.replace('(fer_crop((296, 98, 350, 128)), "Ferrari: lit/shadow rock facets 8x")', '(fer_crop((205, 100, 255, 131)), "Ferrari: rock facets, sun-lit ridges 8x")')
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py D

# output:
wrote D

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
s = s.replace('''    z[inside & (ndl > 0.5)] = 5
    z[inside & (ndl <= 0.5) & (ndl > 0.16)] = 4
    z[inside & (ndl <= 0.16) & (nb < 0.3)] = 2
    z[inside & (ndl <= 0.16) & (nb >= 0.3)] = 3
    z[inside & (ndl <= 0.16) & (ndl > 0.02)] = 2      # the terminator band is always core''',
'''    sh = inside & (ndl <= 0.16)
    z[inside & (ndl > 0.5)] = 5
    z[inside & (ndl <= 0.5) & (ndl > 0.16)] = 4
    z[sh & (nb < 0.3)] = 2                             # core: faces neither sun, sky nor bounce
    z[sh & (nb >= 0.3)] = 3                            # bounce-lit shadow side (warm)
    z[sh & (n[..., 1] > 0.55)] = 4                     # sky-lit top: at 5 deg sun the sky is its light
    z[sh & (ndl > 0.02) & (n[..., 1] <= 0.55)] = 2     # the terminator band is always core''')
s = s.replace("boulder_zones(w, h, (15, 10, 11), 5.5, scale=1.0)", "boulder_zones(w, h, (15, 11, 11), 8.0, scale=1.0)")
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py D

# output:
wrote D

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
s = s.replace('''def study_D():''', '''def boulder_value(n, P, ground, halfy, L, B, sky_w=0.9):
    """continuous ramp coordinate: 1 contact .. 2 core .. 3 bounce-lit shadow .. 4 half .. 5 lit .. 6 rim.
    The lit side and the shadow side are separate ranges: the terminator is a JUMP (observed r02),
    so dithering never crosses it."""
    ndl = n @ L; nb = n @ B; up = n[..., 1]
    lit = 3.7 + 2.0 * np.clip((ndl - 0.15) / 0.75, 0, 1) ** 0.8
    shd = 2.0 + 1.0 * np.clip(nb / 0.6, 0, 1)
    shd = np.maximum(shd, 2.2 + 1.5 * np.clip((up - 0.3) / 0.6, 0, 1) * sky_w)   # sky-lit tops
    v = np.where(ndl > 0.15, np.maximum(lit, shd), shd)
    # contact occlusion: fades the last ~15% of height toward the contact value
    hgt = (P[..., 1] - ground) / (2 * halfy)
    v = v - np.clip(1 - hgt / 0.16, 0, 1) * (v - 1.0) * 0.85
    return v, ndl

def clustered_noise(h, w, rng):
    """threshold field with small clumps (2-px scale) plus fine grain -- Ferrari's rock mixes
    read as strings and clumps, not salt-and-pepper"""
    c = rng.uniform(size=((h + 1) // 2 + 1, (w + 1) // 2 + 1))
    c = np.repeat(np.repeat(c, 2, 0), 2, 1)[:h, :w]
    off = rng.integers(0, 2, size=h)
    for y in range(h): c[y] = np.roll(c[y], off[y])
    return 0.55 * c + 0.45 * rng.uniform(size=(h, w))

def boulder_paint(w, h, half, rr, L=(-0.9, 0.12, -0.35), B=(0.5, -0.8, -0.2), yaw=0.55, seed=1, cx=None, spread=1.0):
    rng = np.random.default_rng(seed)
    n, inside, P, ground = raycast_boulder(w, h, np.array(half), rr, yaw=yaw, seed=seed, cx=cx)
    L = np.array(L) / np.linalg.norm(L); B = np.array(B) / np.linalg.norm(B)
    v, ndl = boulder_value(n, P, ground, half[1], L, B)
    th = clustered_noise(h, w, rng)
    lo = np.floor(v); f = v - lo
    # only the fractional part in the middle band dithers; near-integers stay flat (planes!)
    f2 = np.clip((f - 0.5) * spread + 0.5, 0, 1)
    z = np.where(f2 > th, lo + 1, lo).astype(int)
    z = np.clip(z, 1, 6)
    z[~inside] = -1
    # rim: sun-side silhouette pixels that face the sun
    sx = -1 if L[0] < -0.2 else (1 if L[0] > 0.2 else 0)
    out_sun = ~np.roll(inside, -sx, 1) if sx else np.zeros_like(inside)
    out_up = ~np.roll(inside, 1, 0)
    z[inside & (out_sun | out_up) & (ndl > 0.35)] = 6
    # contact: the lowest silhouette pixel row is always the darkest
    below_out = ~np.roll(inside, -1, 0)
    z[inside & below_out] = 1
    return z, inside

def study_D():''')
s = s.replace('''    z, inside, ndl = boulder_zones(w, h, (15, 11, 11), 8.0, scale=1.0)''', '''    z, inside = boulder_paint(w, h, (15, 11, 11), 8.0)''')
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py D

# output:
wrote D

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
s = s.replace("lit = 3.7 + 2.0 * np.clip((ndl - 0.15) / 0.75, 0, 1) ** 0.8", "lit = 3.75 + 1.25 * np.clip((ndl - 0.15) / 0.45, 0, 1) ** 0.7")
s = s.replace("shd = 2.0 + 1.0 * np.clip(nb / 0.6, 0, 1)", "shd = 2.0 + 1.0 * np.clip((nb - 0.3) / 0.35, 0, 1)")
s = s.replace("shd = np.maximum(shd, 2.2 + 1.5 * np.clip((up - 0.3) / 0.6, 0, 1) * sky_w)", "shd = np.maximum(shd, 2.0 + 2.0 * np.clip((up - 0.45) / 0.4, 0, 1) * sky_w)")
s = s.replace("def boulder_paint(w, h, half, rr, L=(-0.9, 0.12, -0.35), B=(0.5, -0.8, -0.2), yaw=0.55, seed=1, cx=None, spread=1.0):",
              "def boulder_paint(w, h, half, rr, L=(-0.9, 0.12, -0.35), B=(0.5, -0.8, -0.2), yaw=0.55, seed=1, cx=None, spread=2.2):")
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py D

# output:
wrote D

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
s = s.replace('''    th = clustered_noise(h, w, rng)
    lo = np.floor(v); f = v - lo''', '''    th = clustered_noise(h, w, rng)
    # surface grain: weathering flutes run down the fall line -> noise stretched vertically.
    g = rng.uniform(-1, 1, (h // 3 + 2, w + 2))
    g = np.repeat(g, 3, 0)[:h, :w]
    g = np.roll(g, 1, 0) * 0.5 + g * 0.5
    v = v + grain * g * inside
    lo = np.floor(v); f = v - lo''')
s = s.replace("yaw=0.55, seed=1, cx=None, spread=2.2):", "yaw=0.55, seed=1, cx=None, spread=2.2, grain=0.35, crack=True):")
s = s.replace('''    # contact: the lowest silhouette pixel row is always the darkest
    below_out = ~np.roll(inside, -1, 0)
    z[inside & below_out] = 1
    return z, inside''', '''    # a joint crack down the lit face: dark 1-px line (core), sun-side lip catches light
    if crack:
        ys, xs = np.nonzero(inside)
        x0 = int(np.percentile(xs, 55)); ytop = ys[xs == x0].min()
        x = float(x0); dx = rng.uniform(-0.35, 0.35)
        for y in range(ytop, ys.max()):
            xi = int(round(x))
            if not inside[y, xi]: break
            z[y, xi] = min(z[y, xi], 2)
            if xi - 1 >= 0 and inside[y, xi - 1] and z[y, xi - 1] >= 4: z[y, xi - 1] = min(6, z[y, xi - 1] + 1)
            x += dx + rng.normal(0, 0.25)
            if rng.uniform() < 0.12: break
    # contact: the lowest silhouette pixel row is always the darkest
    below_out = ~np.roll(inside, -1, 0)
    z[inside & below_out] = 1
    return z, inside''')
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py D

# output:
wrote D

cd ~/work/pixelart-studies/pedagogy/observation && python3 -c "
from PIL import Image
im=Image.open('ferrari/native.png').convert('RGB')
for n,b in {'treebase':(60,195,200,245),'islandbase':(300,280,420,306)}.items():
  im.crop(b).resize(((b[2]-b[0])*6,(b[3]-b[1])*6),Image.NEAREST).save('ferrari/'+n+'.png')
"

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/observation && cat >> translate_studies.py <<'EOF'

# -------------------------------------------------------------------------------------------
# grass primitive (measured from Ferrari: each lighting family uses 3 colours locally --
# lit: ochre base, tan blades, dark-green gaps; shadow: dark olive base, darker olive blades,
# black gaps. blades are 1-px vertical runs of ~3-4 px, leaning by 1-px steps.)
# -------------------------------------------------------------------------------------------
FAM = {"lit": ("g_ochre", "g_tan", "g_gap"), "shd": ("g_dol", "g_dk", "g_blk")}

def grass_field(img, mask, lit, Lmap, rng, depth=None, occl=None, density=1.0, lean=-0.15, tip_boost=None):
    """paint grass into img where mask. lit: bool map (sunlit family). Lmap: blade length (px).
    blades are painted back-to-front (top rows first) so lower (nearer) blades overlap.
    occl: optional mask of pixels blades may overpaint (e.g. boulder foot, water) - they are
    'behind' the grass."""
    h, w = mask.shape
    for fam, m in (("lit", mask & lit), ("shd", mask & ~lit)):
        base, light, dark = FAM[fam]
        img[m] = C[base]
        t = rng.uniform(size=(h, w))
        img[m & (t < 0.22)] = C[dark]
        img[m & (t > 0.80)] = C[light]
    ys, xs = np.nonzero(mask)
    order = np.argsort(ys)
    can = mask | (occl if occl is not None else False)
    for i in order:
        y, x = ys[i], xs[i]
        L = Lmap[y, x]
        if L < 1.5 or rng.uniform() > density * min(1, 1.8 / L): continue
        fam = "lit" if lit[y, x] else "shd"
        base, light, dark = FAM[fam]
        gap = rng.uniform() < 0.35
        n = int(round(L * rng.uniform(0.6, 1.2)))
        fx = float(x); ln = lean + rng.normal(0, 0.2)
        for k in range(n):
            yy = y - k; xx = int(round(fx))
            if yy < 0 or xx < 0 or xx >= w or not can[yy, xx]: break
            f = k / max(n - 1, 1)
            if gap: c = dark
            else:
                c = light if f > 0.45 else base
                if tip_boost is not None and tip_boost[y, x] and f > 0.7: c = light
            img[yy, xx] = C[c]; fx += ln

# -------------------------------------------------------------------------------------------
# A: the contact -- a boulder sitting IN a grass bank, low sun from the left
# observed (r10, r13): darkest line where rock meets ground; an undercut pocket of near-black on
# the shadow side; grass taller at the foot, overlapping the base; long cast shadow on the grass.
# Ferrari (stones at the waterline): the darkest palette colour as a 1-px line under the form;
# shadowed grass switches to a different 3-colour family, it is not the lit grass darkened.
# -------------------------------------------------------------------------------------------
def study_A():
    w, h = 56, 34
    rng = np.random.default_rng(3)
    img = np.zeros((h, w, 3), np.uint8)
    horizon = 9
    img[:horizon] = C["sky1"]
    z, inside = boulder_paint(w, h, (11, 9, 9), 6.5, cx=22, seed=4)
    # ground occupies everything below the horizon; the boulder cuts it
    ground = np.zeros((h, w), bool); ground[horizon:] = True
    ys, xs = np.nonzero(inside)
    base_y = np.array([ys[xs == x].max() if (xs == x).any() else -1 for x in range(w)])
    # cast shadow: low sun from left -> long shadow to the right, band hugging the base row
    yy, xx = np.mgrid[0:h, 0:w]
    bx0, bx1 = xs.min(), xs.max(); by = ys.max()
    shadow = (xx > bx0 + 0.55 * (bx1 - bx0)) & (np.abs(yy - (by - 1 + (xx - bx1) * 0.06)) < 2.4 + (xx - bx1).clip(0) * 0.03)
    shadow |= inside  # beneath the rock
    lit = ground & ~shadow
    # blade length grows toward the viewer (bottom) and at the rock's foot
    Lmap = 1.0 + (yy - horizon).clip(0) / (h - horizon) * 4.5
    foot = np.zeros((h, w))
    for x in range(bx0 - 3, bx1 + 4):
        if 0 <= x < w:
            yb = base_y[min(max(x, bx0), bx1)]
            foot[yb - 1:yb + 3, x] = 1
    Lmap = Lmap + 3.5 * foot
    grass_field(img, ground & ~inside, lit, Lmap, rng, occl=inside & (yy > ys.max() - 5))
    # rock over grass except where blades overlap later: paint rock first, then re-run blades at foot
    cm = {6: "rim", 5: "lit", 4: "half", 3: "shade", 2: "core", 1: "contact"}
    rock = np.zeros_like(img)
    for k, c in cm.items(): rock[z == k] = C[c]
    img[inside] = rock[inside]
    # the undercut pocket: near-black just under the shadow-side base in the grass
    for x in range(int(bx0 + 0.5 * (bx1 - bx0)), bx1 + 1):
        yb = base_y[x]
        if yb + 1 < h: img[yb + 1, x] = C["g_blk"]
    # blades at the foot, in front of the base, overlap the rock's lowest pixels
    footmask = ground & ~inside & (foot > 0)
    grass_field_front(img, footmask, lit, Lmap, rng, occl=inside)
    sheet("A", "A  contact: darkest line under the rock, black undercut pocket, shadow grass = its own family, tufts overlap the foot",
          [(photo_crop("refs/r10_boulder_by_lochan_grassfoot.jpg", (480, 420, 900, 636), 272), "photo r10 (foot, undercut)"),
           (fer_crop((240, 398, 300, 432)), "Ferrari: stones at the waterline 8x"),
           (mine(img), "mine 8x")])

def grass_field_front(img, mask, lit, Lmap, rng, occl):
    """only blades (no base fill), for tufts overlapping something behind them"""
    h, w = mask.shape
    ys, xs = np.nonzero(mask)
    for i in np.argsort(ys):
        y, x = ys[i], xs[i]
        if rng.uniform() > 0.55: continue
        fam = "lit" if lit[y, x] else "shd"
        base, light, dark = FAM[fam]
        n = int(round(Lmap[y, x] * rng.uniform(0.7, 1.2))); fx = float(x); ln = rng.normal(-0.1, 0.25)
        gap = rng.uniform() < 0.3
        for k in range(n):
            yy = y - k; xx = int(round(fx))
            if yy < 0 or xx < 0 or xx >= w: break
            f = k / max(n - 1, 1)
            img[yy, xx] = C[dark if gap else (light if f > 0.45 else base)]; fx += ln
EOF
python3 translate_studies.py A

# output:
Exit code 1
Traceback (most recent call last):
  File "~/work/pixelart-studies/pedagogy/observation/translate_studies.py", line 203, in <module>
    for s in sys.argv[1:]: globals()["study_" + s]()
                           ~~~~~~~~~^^^^^^^^^^^^^^
KeyError: 'study_A'

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
blk = '''if __name__ == "__main__":
    for s in sys.argv[1:]: globals()["study_" + s]()
'''
s = s.replace(blk, "") + "\n" + blk
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py A

# output:
wrote A

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
s = s.replace('''        img[m] = C[base]
        t = rng.uniform(size=(h, w))
        img[m & (t < 0.22)] = C[dark]
        img[m & (t > 0.80)] = C[light]''', '''        img[m] = C[base]
        t = rng.uniform(size=(h, w))
        far = Lmap < 2.5
        img[m & far & (t < 0.07)] = C[dark]
        img[m & (t > 0.74)] = C[light]''')
s = s.replace('''        gap = rng.uniform() < 0.35
        n = int(round(L * rng.uniform(0.6, 1.2)))''', '''        gap = rng.uniform() < 0.25 and L >= 3
        n = int(round(L * rng.uniform(0.6, 1.2)))''')
s = s.replace("grass_field(img, ground & ~inside, lit, Lmap, rng, occl=inside & (yy > ys.max() - 5))", "grass_field(img, ground & ~inside, lit, Lmap, rng)")
s = s.replace("            foot[yb - 1:yb + 3, x] = 1\n    Lmap = Lmap + 3.5 * foot", "            foot[yb + 1:yb + 3, x] = 1\n    Lmap = Lmap + 1.5 * foot")
s = s.replace('''        if rng.uniform() > 0.55: continue
        fam = "lit" if lit[y, x] else "shd"
        base, light, dark = FAM[fam]
        n = int(round(Lmap[y, x] * rng.uniform(0.7, 1.2)))''', '''        if rng.uniform() > 0.4: continue
        fam = "lit" if lit[y, x] else "shd"
        base, light, dark = FAM[fam]
        n = int(round(min(Lmap[y, x], 5) * rng.uniform(0.7, 1.1)))''')
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py A

# output:
wrote A

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
s = s.replace("        img[m & (t > 0.74)] = C[light]", "        img[m & (t > 0.84)] = C[light]")
s = s.replace("                c = light if f > 0.45 else base\n", "                c = light if f > 0.62 else base\n")
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py A

# output:
wrote A

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
blk = '''if __name__ == "__main__":
    for s in sys.argv[1:]: globals()["study_" + s]()
'''
s = s.replace(blk, "")
s += '''
# -------------------------------------------------------------------------------------------
# B: the lit top of a grass mass (tussock / bank hump), low sun from the left
# observed (r20, r23): the mass is dark in its body and base; light collects on the crest and on
# the sun-facing shoulder, and the blade tips along the silhouette catch it hardest.
# Ferrari (left bank crest, island): a 1-3 px band of the lightest tan right under the crest
# contour; below it the lit colour is STIPPLED into the shadow family with falling density; the
# contour itself is a long flat run with clean 45 / 2:1 shoulders.
# -------------------------------------------------------------------------------------------
def mound(w, h, y_base, cx, half_w, height, rng, flat=0.45):
    xs = np.arange(w) + 0.5
    u = np.clip(np.abs(xs - cx) / half_w, 0, 1)
    prof = np.where(u < flat, 0, ((u - flat) / (1 - flat)) ** 1.6)   # flat crest, curving shoulders
    yt = y_base - height * (1 - prof)
    cols = np.nonzero(np.abs(xs - cx) < half_w)[0]
    out = np.full(w, 10 ** 6); out[cols] = clean_profile(yt[cols])
    return out

def mound_light(h, w, yt, cx, sun_x=-1, band=2.5, falloff=9.0, rng=None):
    """t in [0,1]: how 'lit' each pixel of the mass is. crest band + sun-facing shoulder."""
    yy, xx = np.mgrid[0:h, 0:w]
    d = yy - yt[None, :]
    side = np.clip((cx - xx) * (-sun_x) / max(1, np.ptp(np.nonzero(yt < 10 ** 5)[0])) * 2, -1, 1)  # +1 on sun side
    t = np.clip(1 - d / falloff, 0, 1) * (0.55 + 0.45 * side)
    t = np.where(d < band, np.maximum(t, 0.95), t)
    return t, d

def study_B():
    w, h = 72, 30
    rng = np.random.default_rng(7)
    img = np.zeros((h, w, 3), np.uint8)
    # behind: a farther bank in shadow, fine stipple (it is darker: the lit crest must read against it)
    img[:] = C["g_dol"]; t0 = rng.uniform(size=(h, w))
    img[t0 < 0.3] = C["g_dk"]; img[t0 > 0.9] = C["g_ochre"]
    yt = mound(w, h, 26, 36, 32, 13, rng)
    yy, xx = np.mgrid[0:h, 0:w]
    inside = yy >= yt[None, :]
    t, d = mound_light(h, w, yt, 36)
    # family by stippled threshold: lit colour scattered into the shadow body
    lit = inside & (t > rng.uniform(size=(h, w)))
    Lmap = np.full((h, w), 1.0) + (yy / h) * 2.5
    grass_field(img, inside, lit, Lmap, rng)
    # crest band: the lightest tan dominates the 1-3 px under the contour on the lit part
    crest = inside & (d < 2) & (t > 0.8) & (rng.uniform(size=(h, w)) < 0.8)
    img[crest] = C["g_tan"]
    # blade tips poking above the silhouette, lit
    for x in range(w):
        if yt[x] < 10 ** 5 and rng.uniform() < 0.3 and xx[0, x] < 36 + 20:
            for k in range(1, rng.integers(2, 4)):
                if yt[x] - k >= 0: img[yt[x] - k, x] = C["g_tan"] if k < 3 else C["g_ochre"]
    sheet("B", "B  lit top of a grass mass: crest band of the lightest tan, lit colour stippled down into the shadow family, clean contour runs",
          [(photo_crop("refs/r20_grassbank_lake_sunset.jpg", (240, 420, 560, 580), 240), "photo r20 (tussock tops)"),
           (fer_crop((70, 205, 160, 240)), "Ferrari: bank crest at 8x"),
           (mine(img), "mine 8x")])
''' + "\n" + blk
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py B

# output:
~/work/pixelart-studies/pedagogy/observation/translate_studies.py:324: RuntimeWarning: invalid value encountered in power
  prof = np.where(u < flat, 0, ((u - flat) / (1 - flat)) ** 1.6)   # flat crest, curving shoulders
wrote B

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
s = s.replace('''    img[:] = C["g_dol"]; t0 = rng.uniform(size=(h, w))
    img[t0 < 0.3] = C["g_dk"]; img[t0 > 0.9] = C["g_ochre"]''', '''    img[:] = C["g_dk"]; t0 = rng.uniform(size=(h, w))
    img[t0 < 0.45] = C["g_blk"]; img[t0 > 0.88] = C["g_dol"]''')
s = s.replace("    t, d = mound_light(h, w, yt, 36)", "    t, d = mound_light(h, w, yt, 36, falloff=13.0)")
s = s.replace('''    crest = inside & (d < 2) & (t > 0.8) & (rng.uniform(size=(h, w)) < 0.8)''', '''    # band is thicker on the sun side (3 px) and thins to 1 px on the far shoulder
    bandw = np.clip(3.2 - (xx - 10) / 22.0, 0.6, 3.2)
    crest = inside & (d < bandw) & (rng.uniform(size=(h, w)) < 0.88)''')
s = s.replace("        if yt[x] < 10 ** 5 and rng.uniform() < 0.3 and xx[0, x] < 36 + 20:", "        if yt[x] < 10 ** 5 and rng.uniform() < 0.45 and xx[0, x] < 36 + 24:")
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py B 2>/dev/null

# output:
wrote B

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
s = s.replace('''    # blade tips poking above the silhouette, lit''', '''    # break the band's edges with grass texture: notches of the body's dark into the band's
    # lower edge, and ochre intermediate flecks just beneath it
    under = inside & (d >= bandw) & (d < bandw + 3)
    r_ = rng.uniform(size=(h, w))
    img[under & (r_ < 0.35)] = C["g_tan"]; img[under & (r_ > 0.7)] = C["g_mid"]
    notch = crest & (d >= 1) & (rng.uniform(size=(h, w)) < 0.18)
    img[notch] = C["g_dk"]
    # blade tips poking above the silhouette, lit''')
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py B 2>/dev/null

# output:
wrote B

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
blk = '''if __name__ == "__main__":
    for s in sys.argv[1:]: globals()["study_" + s]()
'''
s = s.replace(blk, "")
s += '''
# -------------------------------------------------------------------------------------------
# C: the bank's lip and its reflection
# observed (r19, r20, r25): the grass ends in a dark line at the water (overhang shadow); the
# reflection hangs straight below, darker than the bank, shorter (we see it from above, the
# mirror shows the underside), simpler; beyond it the water carries the sky one step darker.
# Ferrari (island edge): a 1-px darkest line at the waterline; the reflection is built of
# 1-px HORIZONTAL runs in the bank's own hues shifted down one step; thin light wind-lines of
# sky colour cut across it.
# -------------------------------------------------------------------------------------------
DARKER = {"g_tan": "g_mid", "g_mid": "g_ochre", "g_ochre": "g_dol", "g_gap": "g_blk", "g_dol": "g_dk",
          "g_dk": "g_blk", "g_blk": "g_blk", "sky1": "w_mid", "sky2": "w_mid"}

def reflect_rows(src_keys, y_line, n_rows, rng, compress=0.6, run=(2, 8)):
    """mirror the key-map rows above y_line into n_rows below it, compressed, shifted one value
    step darker, and resampled as horizontal runs"""
    h, w = src_keys.shape
    out = np.empty((n_rows, w), dtype=object)
    for r in range(n_rows):
        sy = int(round(y_line - 1 - r / compress))
        x = 0
        while x < w:
            L = int(rng.integers(run[0], run[1] + 1))
            k = src_keys[max(sy, 0), x] if sy >= 0 else "sky1"
            out[r, x:x + L] = DARKER.get(k, k)
            x += L
    return out

def study_C():
    w, h = 64, 34
    rng = np.random.default_rng(11)
    keys = np.full((h, w), "sky1", dtype=object)
    y_lip = 17
    # bank: a low lit mound falling toward the lip; body built with the B vocabulary
    yt = mound(w, h, y_lip, 22, 34, 9, rng, flat=0.25)
    yy, xx = np.mgrid[0:h, 0:w]
    inside = (yy >= yt[None, :]) & (yy < y_lip)
    t, d = mound_light(h, w, yt, 22, falloff=8.0)
    lit = inside & (t > rng.uniform(size=(h, w)))
    r_ = rng.uniform(size=(h, w))
    keys[inside & lit] = "g_ochre"; keys[inside & lit & (r_ > 0.6)] = "g_tan"; keys[inside & lit & (r_ < 0.1)] = "g_gap"
    keys[inside & ~lit] = "g_dol"; keys[inside & ~lit & (r_ < 0.35)] = "g_dk"
    keys[inside & (d < 2) & (t > 0.7) & (r_ < 0.85)] = "g_tan"
    # far water above the bank (it is the tarn behind): sky reflection
    keys[(~inside) & (yy < y_lip)] = "w_mid"
    keys[(~inside) & (yy < y_lip) & (((xx + yy) & 1) == 1) & (yy < 8)] = "w_hi"
    # the lip: darkest line where grass overhangs water
    for x in range(w):
        if yt[x] < y_lip: keys[y_lip - 1, x] = "g_blk" if rng.uniform() < 0.85 else "g_dk"
    # reflection below, then the sky in the water (darker toward the viewer)
    nref = 9
    ref = reflect_rows(keys, y_lip, nref, rng)
    has_bank = yt < y_lip
    for r in range(nref):
        row = y_lip + r
        keys[row, has_bank] = ref[r, has_bank]
        keys[row, ~has_bank] = "w_mid"
    # sky reflection gradient: w_mid -> w_lo toward the viewer, checker strips between
    for row in range(y_lip, h):
        tt = (row - y_lip) / (h - y_lip)
        for x in range(w):
            if row >= y_lip + int(nref * 0.55 + 4 * (x % 7 == 0)) or not has_bank[x]:
                if row >= y_lip + nref or not has_bank[x]:
                    a, b = ("w_mid", "w_lo") if tt < 0.6 else ("w_lo", "w_dk")
                    f = (tt / 0.6) if tt < 0.6 else (tt - 0.6) / 0.4
                    keys[row, x] = b if (f > 2 / 3 or (f > 1 / 3 and (x + row) & 1)) else a
    # the reflection fades out into the sky-water with a ragged, horizontal-run edge
    for r in range(nref - 3, nref):
        row = y_lip + r
        for x in np.nonzero(has_bank)[0]:
            if rng.uniform() < (r - (nref - 4)) / 4: keys[row, x] = "w_lo"
    # wind lines: 1-px light streaks across the reflection and far water
    for _ in range(4):
        row = rng.integers(y_lip + 1, h - 2); x0 = rng.integers(0, w - 10); L = rng.integers(6, 18)
        keys[row, x0:x0 + L] = "w_hi" if row < y_lip + 6 else "w_mid"
    # overhanging blade tips at the lip, and their reflections as dark ticks
    for x in range(w):
        if has_bank[x] and rng.uniform() < 0.25:
            keys[y_lip - 1, x] = "g_ochre"
            if y_lip < h: keys[y_lip, x] = "g_ochre" if rng.uniform() < 0.5 else keys[y_lip, x]
    img = np.zeros((h, w, 3), np.uint8)
    for k in set(keys.ravel()): img[keys == k] = C[k]
    sheet("C", "C  bank lip and reflection: darkest line at the water, reflection = horizontal runs one step darker and shorter, wind-lines",
          [(photo_crop("refs/r19_tarn_bank_reflection.jpg", (420, 330, 960, 700), 272), "photo r19 (lip, boulder reflection)"),
           (fer_crop((296, 272, 400, 306)), "Ferrari: island edge + reflection 8x"),
           (mine(img), "mine 8x")])
''' + "\n" + blk
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py C 2>/dev/null

# output:
wrote C

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
s = s.replace('''    # the lip: darkest line where grass overhangs water
    for x in range(w):
        if yt[x] < y_lip: keys[y_lip - 1, x] = "g_blk" if rng.uniform() < 0.85 else "g_dk"''', '''    # the lip: the bank's base darkens (overhang shadow)...''' + '''
    for x in range(w):
        if yt[x] < y_lip - 1: keys[y_lip - 1, x] = "g_dk" if rng.uniform() < 0.8 else "g_dol"''')
s = s.replace('''    ref = reflect_rows(keys, y_lip, nref, rng)''', '''    src = keys.copy(); src[y_lip - 1] = src[y_lip - 2]     # mirror the body, not the lip line
    ref = reflect_rows(src, y_lip, nref, rng)''')
s = s.replace('''    # overhanging blade tips at the lip, and their reflections as dark ticks''', '''    # ...and at a middle distance the waterline itself is a LIGHT line: the water right at the
    # edge reflects the sky at grazing angle (r25 spike; Ferrari's island). Near banks flip it.
    for x in np.nonzero(has_bank)[0]:
        if rng.uniform() < 0.75: keys[y_lip, x] = "w_mid"
    # overhanging blade tips at the lip, and their reflections as dark ticks''')
s = s.replace('''DARKER = {"g_tan": "g_mid", "g_mid": "g_ochre", "g_ochre": "g_dol", "g_gap": "g_blk", "g_dol": "g_dk",''', '''DARKER = {"g_tan": "g_mid", "g_mid": "g_ochre", "g_ochre": "g_ochre", "g_gap": "g_dk", "g_dol": "g_dk",''')
s = s.replace('''            keys[y_lip - 1, x] = "g_ochre"
            if y_lip < h: keys[y_lip, x] = "g_ochre" if rng.uniform() < 0.5 else keys[y_lip, x]''', '''            keys[y_lip - 1, x] = "g_ochre"''')
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py C 2>/dev/null

# output:
wrote C

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
s = s.replace('DARKER = {"g_tan": "g_mid",', 'DARKER = {"g_tan": "g_ochre",')
s = s.replace("    yt = mound(w, h, y_lip, 22, 34, 9, rng, flat=0.25)", "    yt = mound(w, h, y_lip, 26, 40, 12, rng, flat=0.3)")
s = s.replace("    t, d = mound_light(h, w, yt, 22, falloff=8.0)", "    t, d = mound_light(h, w, yt, 26, falloff=10.0)")
s = s.replace('''    keys[inside & (d < 2) & (t > 0.7) & (r_ < 0.85)] = "g_tan"''', '''    keys[inside & (d < np.clip(3.2 - (xx - 4) / 16.0, 0, 3.2)) & (r_ < 0.85)] = "g_tan"''')
s = s.replace("    nref = 9", "    nref = 10")
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py C 2>/dev/null

# output:
wrote C

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
blk = '''if __name__ == "__main__":
    for s in sys.argv[1:]: globals()["study_" + s]()
'''
s = s.replace(blk, "")
s += '''
# -------------------------------------------------------------------------------------------
# E: near grass blades against bright water
# observed (r20, r19): where the bank's top meets the water, individual blades read against it;
# the mass behind them is dark; lit blades are light on the sun side.
# Ferrari (near-left grass over the tarn): blades are 1-px lines whose lean is made of EQUAL
# vertical runs (3 down, step 1 = a clean 3:1), tan when lit and dark-green in the gaps; tips
# thin out above the mass contour; at the mass top the tan is densest.
# -------------------------------------------------------------------------------------------
def blade(img_keys, x0, y0, length, lean_run, direction, key_body, key_tip, tip_frac=0.45, allow=None):
    """a blade drawn as equal vertical runs: every lean_run px up, step 1 px sideways."""
    h, w = img_keys.shape
    x = x0
    for k in range(length):
        y = y0 - k
        if y < 0: break
        if lean_run > 0 and k > 0 and k % lean_run == 0: x += direction
        if x < 0 or x >= w: break
        if allow is not None and not allow[y, x]: break
        img_keys[y, x] = key_tip if k >= length * (1 - tip_frac) else key_body

def study_E():
    w, h = 48, 36
    rng = np.random.default_rng(5)
    keys = np.full((h, w), "w_mid", dtype=object)
    yy, xx = np.mgrid[0:h, 0:w]
    keys[(((xx + yy) & 1) == 1) & (yy < 10)] = "w_hi"
    keys[yy < 5] = "w_hi"
    # the bank mass: top contour from lower-left to right, clean runs
    xs = np.arange(w)
    yt = clean_profile(22 + 6 * np.sin(xs / 14.0 + 0.4) + 0.08 * xs)
    body = yy >= yt[None, :]
    r_ = rng.uniform(size=(h, w))
    keys[body] = "g_ochre"; keys[body & (r_ > 0.7)] = "g_tan"; keys[body & (r_ < 0.14)] = "g_gap"
    # blades rooted in the mass, far (upper) first; long ones rise past the contour
    roots = [(x, yt[x] + rng.integers(0, h - yt[x])) for x in range(w) for _ in range(3) if yt[x] < h]
    roots.sort(key=lambda p: p[1])
    for x, y in roots:
        if y >= h: continue
        near = (y - yt.min()) / max(1, h - yt.min())
        L = int(4 + 7 * near * rng.uniform(0.5, 1.2))
        gap = rng.uniform() < 0.3
        run = int(rng.choice([2, 3, 3, 4, 6]))
        blade(keys, x, y, L, run, -1 if rng.uniform() < 0.7 else 1,
              "g_gap" if gap else "g_ochre", "g_gap" if gap else "g_tan")
    img = np.zeros((h, w, 3), np.uint8)
    for k in set(keys.ravel()): img[keys == k] = C[k]
    sheet("E", "E  near blades against water: 1-px blades leaning in equal runs (clean 2:1 / 3:1), tan tips, dark-green gaps",
          [(photo_crop("refs/r20_grassbank_lake_sunset.jpg", (380, 400, 700, 560), 288), "photo r20 (blades vs water)"),
           (fer_crop((185, 345, 245, 381)), "Ferrari: near grass over the tarn 8x"),
           (mine(img), "mine 8x")])
''' + "\n" + blk
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py E 2>/dev/null

# output:
wrote E

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
s = s.replace('''def blade(img_keys, x0, y0, length, lean_run, direction, key_body, key_tip, tip_frac=0.45, allow=None):
    """a blade drawn as equal vertical runs: every lean_run px up, step 1 px sideways."""
    h, w = img_keys.shape
    x = x0
    for k in range(length):
        y = y0 - k
        if y < 0: break
        if lean_run > 0 and k > 0 and k % lean_run == 0: x += direction''', '''def blade(img_keys, x0, y0, length, lean_run, direction, key_body, key_tip, tip_frac=0.45, allow=None, curl=True):
    """a blade drawn as runs of vertical pixels with 1-px sideways steps. The run length shrinks
    toward the tip (a curving blade made only of clean steps: 5,4,3,3,2,2,1...)."""
    h, w = img_keys.shape
    x = x0; pos = 0; run = lean_run
    for k in range(length):
        y = y0 - k
        if y < 0: break
        if k > 0:
            pos += 1
            if run > 0 and pos >= run:
                x += direction; pos = 0
                if curl: run = max(1, run - 1) if k > length * 0.45 else run''')
s = s.replace('''        near = (y - yt.min()) / max(1, h - yt.min())
        L = int(4 + 7 * near * rng.uniform(0.5, 1.2))
        gap = rng.uniform() < 0.3
        run = int(rng.choice([2, 3, 3, 4, 6]))''', '''        near = (y - yt.min()) / max(1, h - yt.min())
        above = y - yt[x]
        L = int((above + 3 + 10 * near) * rng.uniform(0.6, 1.25))
        gap = rng.uniform() < 0.3
        run = int(rng.choice([3, 4, 5, 6, 8]))''')
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py E 2>/dev/null

# output:
wrote E

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
s = s.replace('''        run = int(rng.choice([3, 4, 5, 6, 8]))
        blade(keys, x, y, L, run, -1 if rng.uniform() < 0.7 else 1,
              "g_gap" if gap else "g_ochre", "g_gap" if gap else "g_tan")''', '''        run = int(rng.choice([2, 3, 3, 4, 5]))
        blade(keys, x, y, L, run, -1 if rng.uniform() < 0.7 else 1,
              "g_gap" if gap else ("g_tan" if rng.uniform() < 0.6 else "g_ochre"), "g_gap" if gap else "g_tan", tip_frac=0.7)''')
s = s.replace("                if curl: run = max(1, run - 1) if k > length * 0.45 else run", "                if curl: run = max(1, run - 1) if k > length * 0.3 else run")
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py E 2>/dev/null

# output:
wrote E

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("translate_studies.py").read()
s = s.replace('''        blade(keys, x, y, L, run, -1 if rng.uniform() < 0.7 else 1,''', '''        if gap: L, run = max(2, L // 2), 0
        blade(keys, x, y, L, run, -1 if rng.uniform() < 0.7 else 1,''')
open("translate_studies.py", "w").write(s)
EOF
python3 translate_studies.py E 2>/dev/null

# output:
wrote E

cd ~/work/pixelart-studies/pedagogy/observation && mv tarn.py tarn_v1_first_attempt.py && ls studies/

# output:
blockin_boulders.png
blockin_dusk.png
blockin_water.png
contact2.png
contact2_0.png
contact2_1.png
contact3.png
contact3_0.png
contact3_1.png
contact3_2.png
contact_0.png
contact_1.png
contact_2.png
contact_all.png
measurements.png
translate_A.png
translate_B.png
translate_C.png
translate_D.png
translate_E.png

"""
tarn.py -- paint "a granite boulder resting in a grass bank at the edge of a still mountain tarn,
at dusk" as painterly pixel art in the manner of Mark Ferrari, from parameters.

    size      small | medium | large
    light     left | front | right | back
    distance  close | 10m | 40m
    seed      any int

Two stages (see LESSONS.md):

 1. OBSERVE  -- a small physical model of the scene, carrying what the photographs showed:
    low warm sun + violet sky fill + warm bounce from lit grass; granite's rough terminator; contact
    occlusion; long cast shadows at a 4.5 deg sun; tussock-scale grass masses that catch light on
    their sun-facing tops; water as a Fresnel mirror whose reflections are darker and show the
    underside of things; the far shore and mountains in dusk air.  Output: a G-buffer at 320x180.

 2. TRANSLATE -- the G-buffer is painted with the vocabulary found in the translation studies
    (translate_studies.py), never by quantising a smooth render:
      rock   continuous ramp coordinate with a JUMP at the terminator; flat planes; clustered
             dither only near value boundaries; vertical weathering grain; sun-side 1-px rim;
             darkest colour on the contact row                                   (study D, A)
      grass  two 3-colour families (lit: ochre/tan/dark-green; shadow: dark-olive/darker/black),
             family chosen per pixel by stippling the light amount; a band of the lightest tan
             under every sun-facing mass crest; blades as 1-px lines leaning in equal runs that
             shorten toward the tip; blade length ~ 1/distance                    (study B, E)
      water  the scene mirrored one value step darker, resampled as horizontal runs; checker
             for mirrored sky; light line at far waterlines, dark line at near lips; wind-lines
                                                                                  (study C)
      sky    flat bands of adjacent ramp colours joined by 50% checkerboard strips
      contours: mass tops and the shore are rasterised as consistent runs (flat / 2:1 / 45 deg)
"""
import os, sys, math, argparse
import numpy as np
from PIL import Image
from skimage.color import rgb2lab, lab2rgb
from pix import clean_profile

W, H = 320, 180
HFOV = math.radians(60.0)
PITCH = math.radians(-10.0)
EYE_H = 1.25
SUN_EL = math.radians(4.5)
SIZES = {"small": 1.1, "medium": 1.9, "large": 2.9}
DISTS = {"close": 5.5, "10m": 10.0, "40m": 40.0}
LIGHTS = {"left": -78.0, "front": 168.0, "right": 78.0, "back": -14.0}   # sun azimuth rel. to view

# ---------------------------------------------------------------------------------------------
# noise
# ---------------------------------------------------------------------------------------------
M32 = np.uint64(0xFFFFFFFF)
def _hash(ix, iy, iz, seed):
    h = (ix.astype(np.int64).astype(np.uint64) * np.uint64(73856093)) ^ \
        (iy.astype(np.int64).astype(np.uint64) * np.uint64(19349663)) ^ \
        (iz.astype(np.int64).astype(np.uint64) * np.uint64(83492791)) ^ np.uint64((seed * 2654435761) & 0xFFFFFFFF)
    h &= M32; h ^= h >> np.uint64(13); h = (h * np.uint64(1274126177)) & M32; h ^= h >> np.uint64(16)
    return (h & np.uint64(0xFFFFFF)).astype(np.float64) / float(0xFFFFFF)

def vnoise3(x, y, z, seed=0):
    ix, iy, iz = np.floor(x), np.floor(y), np.floor(z)
    fx, fy, fz = x - ix, y - iy, z - iz
    ux, uy, uz = fx * fx * (3 - 2 * fx), fy * fy * (3 - 2 * fy), fz * fz * (3 - 2 * fz)
    r = 0.0
    for dx in (0, 1):
        for dy in (0, 1):
            for dz in (0, 1):
                w = (ux if dx else 1 - ux) * (uy if dy else 1 - uy) * (uz if dz else 1 - uz)
                r = r + w * _hash(ix + dx, iy + dy, iz + dz, seed)
    return r * 2 - 1

def fbm2(x, y, seed=0, oct=4):
    a, f, s = 1.0, 1.0, 0.0
    for o in range(oct):
        s = s + a * vnoise3(x * f, y * f, np.full_like(np.asarray(x, float), 0.5), seed + 17 * o); a *= 0.5; f *= 2.0
    return s

def fbm3(x, y, z, seed=0, oct=3):
    a, f, s = 1.0, 1.0, 0.0
    for o in range(oct):
        s = s + a * vnoise3(x * f, y * f, z * f, seed + 31 * o); a *= 0.5; f *= 2.0
    return s

def norm(v): return v / (np.linalg.norm(v, axis=-1, keepdims=True) + 1e-12)
def smoothstep(a, b, x):
    t = np.clip((x - a) / (b - a), 0, 1); return t * t * (3 - 2 * t)

# ---------------------------------------------------------------------------------------------
# scene: geometry + light model (stage 1)
# ---------------------------------------------------------------------------------------------
class Scene:
    def __init__(self, size="medium", light="left", distance="10m", seed=0, tree_density=0.5):
        self.seed = seed; rng = np.random.default_rng(seed)
        self.size, self.light, self.distance = size, light, distance
        self.D = DISTS[distance]
        a = SIZES[size] / 2 * rng.uniform(0.9, 1.1); self.a = a
        self.half = a * np.array([1.0, rng.uniform(0.66, 0.82), rng.uniform(0.72, 0.9)])
        self.rr = 0.6 * self.half.min()
        self.byaw = rng.uniform(-0.8, 0.8)
        self.sink = rng.uniform(0.22, 0.36)
        self.crack = (rng.uniform() < 0.6) and size != "small"
        self.crack_n = norm(np.array([rng.uniform(-1, 1), rng.uniform(-0.25, 0.25), rng.uniform(-0.5, 0.5)]))
        self.crack_o = rng.uniform(-0.3, 0.3) * a
        self.dents = [(norm(rng.normal(0, 1, 3)), rng.uniform(0.04, 0.09)) for _ in range(5)]
        # layout: camera on a near bank, looking across an inlet at the boulder standing on the
        # lip of a promontory; the tarn opens behind it to the far shore.
        ndc = 0.22 + rng.uniform(-0.05, 0.05)
        self.bx = ndc * math.tan(HFOV / 2) * self.D
        self.bz = self.D
        self.z1 = max(3.0, 0.3 * self.D)                   # near bank lip
        self.wob = rng.uniform(0, 100)
        self.tarn_w = rng.uniform(70, 110)
        self.zfar = self.D + self.tarn_w
        self.tree_density = tree_density
        g = self.ground_h(np.array([self.bx]), np.array([self.bz]))[0]
        self.by = g + self.half[1] * (1 - 2 * self.sink)
        self.eye = np.array([0.0, self.ground_h(np.array([0.0]), np.array([0.0]))[0] + EYE_H, 0.0])
        self.yaw = rng.uniform(-0.03, 0.03)
        az = math.radians(LIGHTS[light]) + rng.uniform(-0.08, 0.08) + self.yaw
        self.sun = norm(np.array([math.sin(az) * math.cos(SUN_EL), math.sin(SUN_EL), math.cos(az) * math.cos(SUN_EL)]))
        self.back = (self.sun @ self.basis()[0]) > 0.3
        # light (linear rgb). observed: low sun warm-orange, sky fill violet, bounce warm
        self.sunC = np.array([1.00, 0.56, 0.30]) * 3.0
        self.skyC = np.array([0.36, 0.30, 0.52]) * 0.85
        self.grassA = np.array([0.30, 0.26, 0.10])
        self.rockA = np.array([0.46, 0.42, 0.38])
        self.bounceC = self.grassA * self.sunC * 0.28 + self.grassA * self.skyC * 0.5
        sh = np.array([self.sun[0], 0, self.sun[2]]); sh /= np.linalg.norm(sh) + 1e-9
        self.bfrom = norm(np.array([-sh[0] * 0.6, -1.0, -sh[2] * 0.6]))   # direction bounce light travels FROM (below, far side)

    # ---- terrain ------------------------------------------------------------------------
    def bank_field(self, x, z):
        """signed horizontal distance to the shore (+ on land). land = near bank OR promontory."""
        a = self.a
        wob = 0.35 * fbm2(x * 0.25 + self.wob, z * 0.05, self.seed + 5, 3)
        # near bank: lip at z1, curving forward on the right to meet the promontory
        f1 = (self.z1 + wob * max(1.0, self.z1 * 0.15) - z) + 0.45 * np.maximum(0, x - (self.bx + 0.6 * a + 0.12 * self.D))
        # promontory: shore passes just left of the boulder's centre, recedes right behind it,
        # and runs forward-right toward the near bank
        u = x - self.bx; v = z - self.bz
        s = np.where(v < 0, -0.25 * a - 0.9 * v, -0.25 * a + 1.3 * v) + 0.2 * a * fbm2(v * 0.4 + self.wob, u * 0.0 + 1.3, self.seed + 6, 3)
        f2 = (u - s) / np.where(v < 0, 1.35, 1.64)
        return np.maximum(f1, f2)

    def ground_h(self, x, z, detail=True):
        d = self.bank_field(x, z)
        lip = 0.24
        bank = -0.05 + (lip + 0.05) * smoothstep(0.0, 0.3, d) + 0.04 * np.clip(d, 0, 30)
        if detail:
            t = fbm2(x * 0.8, z * 0.8, self.seed + 11, 3)
            t2 = fbm2(x * 2.7, z * 2.7, self.seed + 12, 2)
            bank = bank + (0.12 * t + 0.04 * t2) * smoothstep(0.1, 0.9, d)
        under = -0.05 + 0.35 * d
        return np.where(d >= 0, bank, np.maximum(under, -1.5))

    # ---- boulder ------------------------------------------------------------------------
    def local(self, p):
        c, s = math.cos(self.byaw), math.sin(self.byaw)
        q = p - np.array([self.bx, self.by, self.bz])
        return np.stack([c * q[..., 0] - s * q[..., 2], q[..., 1], s * q[..., 0] + c * q[..., 2]], -1)

    def boulder_sdf(self, p):
        L = self.local(p); a = self.a
        qq = np.abs(L) - (self.half - self.rr)
        d = np.linalg.norm(np.maximum(qq, 0), axis=-1) + np.minimum(qq.max(-1), 0) - self.rr
        for dirn, amp in self.dents:             # broad weathering dents (not pixel noise)
            c = dirn * self.half
            d = d + amp * a * np.exp(-np.sum((L - c) ** 2, -1) / (0.5 * a) ** 2)
        d = d + 0.02 * a * fbm3(L[..., 0] * 3 / a, L[..., 1] * 3 / a, L[..., 2] * 3 / a, self.seed + 22, 2)
        if self.crack:
            slab = np.abs(L @ self.crack_n - self.crack_o) - 0.02 * a
            d = np.maximum(d, -slab)
        return d

    def scene_sdf(self, p):
        return np.minimum((p[..., 1] - self.ground_h(p[..., 0], p[..., 2])) * 0.55, self.boulder_sdf(p))

    def material_at(self, p):
        return np.where(self.boulder_sdf(p) < (p[..., 1] - self.ground_h(p[..., 0], p[..., 2])), 2, 1)

    def normal(self, p, mat):
        e = 0.004 * max(self.a, 1.0); n = np.zeros_like(p)
        for i in range(3):
            dp = np.zeros(3); dp[i] = e
            n[..., i] = self.boulder_sdf(p + dp) - self.boulder_sdf(p - dp)
        hx = self.ground_h(p[..., 0] + 0.03, p[..., 2]) - self.ground_h(p[..., 0] - 0.03, p[..., 2])
        hz = self.ground_h(p[..., 0], p[..., 2] + 0.03) - self.ground_h(p[..., 0], p[..., 2] - 0.03)
        ng = np.stack([-hx, np.full_like(hx, 0.06), -hz], -1)
        return norm(np.where((mat == 2)[..., None], n, ng))

    def march(self, o, d, tmax, steps=260):
        t = np.full(d.shape[:-1], 0.02); hit = np.zeros(d.shape[:-1], bool); alive = np.ones_like(hit)
        for _ in range(steps):
            idx = np.nonzero(alive)
            if idx[0].size == 0: break
            p = o[idx] + d[idx] * t[idx][..., None]
            h = self.scene_sdf(p)
            h_hit = h < 0.0015 * t[idx] + 0.002
            hit[tuple(i[h_hit] for i in idx)] = True
            t[idx] = t[idx] + np.maximum(h, 0.004 + 0.002 * t[idx])
            done = h_hit | (t[idx] > tmax[idx])
            alive[tuple(i[done] for i in idx)] = False
        return t, hit & (t <= tmax + 1e-6)

    def soft_shadow(self, p, n):
        o = p + n * 0.03
        res = np.ones(p.shape[:-1]); t = np.full(p.shape[:-1], 0.05)
        for _ in range(80):
            h = self.scene_sdf(o + self.sun * t[..., None])
            res = np.minimum(res, 10.0 * h / t)
            t = t + np.clip(h, 0.04, 1.5)
            if np.all((t > 50) | (res < 0.02)): break
        return np.clip(res, 0, 1)

    def ao(self, p, n):
        occ = np.zeros(p.shape[:-1]); sc = 1.0; s = max(self.a, 0.8)
        for dd in (0.04, 0.1, 0.2, 0.35, 0.55):
            occ += (dd * s - self.scene_sdf(p + n * dd * s)) * sc; sc *= 0.7
        return np.clip(1 - 1.4 * occ / s, 0, 1)

    # ---- camera -------------------------------------------------------------------------
    def basis(self):
        cy, sy, cp, sp = math.cos(self.yaw), math.sin(self.yaw), math.cos(PITCH), math.sin(PITCH)
        fwd = np.array([sy * cp, sp, cy * cp]); right = np.array([cy, 0, -sy]); up = np.cross(fwd, right)
        return fwd, right, (-up if up[1] < 0 else up)

    def rays(self):
        fwd, right, up = self.basis(); th = math.tan(HFOV / 2); tv = th * H / W
        X, Y = np.meshgrid(((np.arange(W) + 0.5) / W * 2 - 1) * th, (1 - (np.arange(H) + 0.5) / H * 2) * tv)
        return norm(fwd + X[..., None] * right + Y[..., None] * up)

    def project(self, pts, is_dir=False):
        fwd, right, up = self.basis(); v = pts if is_dir else pts - self.eye
        zc = v @ fwd; th = math.tan(HFOV / 2); tv = th * H / W
        return (v @ right / zc / th + 1) / 2 * W - 0.5, (1 - v @ up / zc / tv) / 2 * H - 0.5, zc

    # ---- sky & far ----------------------------------------------------------------------
    def sky(self, d):
        el = np.arcsin(np.clip(d[..., 1], -1, 1)); e = np.clip(el, 0, None)
        cosg = np.clip(d @ self.sun, -1, 1)
        zen = np.array([0.30, 0.24, 0.48]); mid = np.array([0.62, 0.40, 0.58]); hor = np.array([0.95, 0.56, 0.48])
        t1 = smoothstep(0.0, 0.42, e)[..., None]; base = hor * (1 - t1) + mid * t1
        t2 = smoothstep(0.12, 0.9, e)[..., None]; base = base * (1 - t2) + zen * t2
        glow = np.exp(-(1 - cosg) / 0.10)[..., None] * np.array([1.0, 0.62, 0.30]) * 1.4 * np.exp(-e / 0.25)[..., None]
        halo = np.exp(-(1 - cosg) / 0.6)[..., None] * np.array([0.35, 0.18, 0.06]) * np.exp(-e / 0.4)[..., None]
        belt = np.exp(-((el - 0.10) / 0.07) ** 2)[..., None] * smoothstep(0.2, -0.6, cosg)[..., None] * np.array([0.10, 0.02, 0.06])
        disk = (cosg > math.cos(math.radians(0.9)))[..., None] * np.array([3.0, 2.3, 1.2])
        return (base + glow + halo + belt) * 0.62 + disk

    def mountain_ridge(self, az):
        r = 0.045 + 0.055 * (0.5 + 0.5 * fbm2(az * 3.0 + self.seed * 0.37, np.zeros_like(az) + 1.7, self.seed + 40, 5))
        return r + 0.03 * np.maximum(0, fbm2(az * 1.3 + 9.1, np.zeros_like(az), self.seed + 41, 3))

    def far_layer(self, d):
        """sky + distant granite range (3 km, dusk air), by direction. -> linear rgb, mountain mask, lit mask"""
        az = np.arctan2(d[..., 0], d[..., 2]); el = np.arcsin(np.clip(d[..., 1], -1, 1))
        ridge = self.mountain_ridge(az); mnt = el < ridge
        def R(a, e):
            return (1 - np.abs(fbm2(a * 9 + 3.1, e * 14 + 1.3, self.seed + 43, 4))) * 0.6 + (ridge - e) * 3
        ea = 0.0015
        gx = (R(az + ea, el) - R(az - ea, el)) / (2 * ea) * 0.012
        gy = (R(az, el + ea) - R(az, el - ea)) / (2 * ea) * 0.012
        vd = norm(np.stack([d[..., 0], np.zeros_like(el), d[..., 2]], -1))
        side = np.stack([vd[..., 2], np.zeros_like(el), -vd[..., 0]], -1)
        n = norm(-vd + side * (-gx)[..., None] * 1.3 + np.array([0, 1, 0]) * (0.45 - 0.4 * gy)[..., None])
        ndl = np.clip(n @ self.sun, 0, 1) ** 0.7
        snow = (fbm2(az * 22, el * 30, self.seed + 44, 3) + 0.9 * (el - ridge + 0.04) / 0.04 > 0.55) & (n[..., 1] > 0.35)
        alb = np.where(snow[..., None], np.array([0.80, 0.78, 0.86]), np.array([0.34, 0.30, 0.32]))
        col = alb * (self.sunC * 0.55 * ndl[..., None] + self.skyC * 1.3 * (0.5 + 0.5 * n[..., 1:2]))
        hz = self.sky(norm(np.stack([d[..., 0], np.full_like(el, 0.02), d[..., 2]], -1)))
        col = col * 0.5 + hz * 0.5
        return np.where(mnt[..., None], col, self.sky(d)), mnt, mnt & (ndl > 0.35)

    def mid_layer(self):
        """far shore bank + conifers as marks on an extended canvas (rows -OFF..H).
        keys: 1 bank lit, 7 bank shade, 2 tree dark, 3 tree lit edge, 4 tree mid"""
        OFF = 150; HH = H + OFF
        mark = np.zeros((HH, W), np.int8)
        rng = np.random.default_rng(self.seed + 99)
        zf = self.zfar; rays = self.rays()[0]
        rows = []
        for zz, hh in ((zf, 0.0), (zf + 30, 3.0)):
            pts = np.array([self.eye + rays[i] * ((zz - self.eye[2]) / rays[i][2]) for i in range(W)]); pts[:, 1] = hh
            rows.append(self.project(pts)[1])
        y_wl, y_top = rows
        bn = fbm2(np.arange(W) * 0.05 + self.seed, np.zeros(W), self.seed + 60, 3) * 1.5
        yt = clean_profile(y_top + bn)
        for x in range(W):
            y0 = int(round(y_wl[x])) + OFF; y1 = int(yt[x]) + OFF
            y0 = min(max(y0, 0), HH - 1); y1 = min(max(y1, 0), y0)
            mark[y1:y0 + 1, x] = 1
        # shading of the far bank: lit if the sun is not behind it
        fwd, right, up = self.basis()
        if self.back: mark[mark == 1] = 7
        dist = zf + 12 - self.eye[2]; pix_ang = HFOV / W
        xs_t = rng.uniform(-30, W + 30, int(W / 5 * self.tree_density))
        keep = fbm2(xs_t * 0.02 + self.seed * 0.1, np.zeros_like(xs_t), self.seed + 61, 2) > -0.1
        xs_t = np.sort(xs_t[keep])
        sunx = self.sun @ right
        for x0 in xs_t:
            hm = rng.uniform(7, 18) * (1 if rng.uniform() > 0.25 else 0.5)
            hp = hm / dist / pix_ang
            base = int(round(np.interp(x0, np.arange(W), yt))) + OFF + int(rng.integers(0, 3))
            wmax = max(1.5, hp * rng.uniform(0.2, 0.28)); tier = max(2, int(round(hp / rng.uniform(5, 8))))
            for r in range(int(hp)):
                y = base - int(hp) + r
                if y < 0 or y >= HH: continue
                f = r / hp; ph = (r % tier) / tier
                hw = wmax * f * (0.5 + 0.5 * ph) + (0.5 if r > 1 else 0)
                j = rng.uniform(-0.6, 0.6)
                xa = int(round(x0 - hw + j)); xb = int(round(x0 + hw + j))
                for x in range(max(xa, 0), min(xb, W - 1) + 1):
                    m = 2
                    edge_sun = (x == xb and sunx > 0.2) or (x == xa and sunx < -0.2)
                    if edge_sun and ph > 0.25: m = 3
                    elif rng.uniform() < 0.15: m = 4
                    if self.back and (x in (xa, xb)) and ph > 0.5 and rng.uniform() < 0.5: m = 3
                    mark[y, x] = m
        return mark, OFF

    # ---- shading --------------------------------------------------------------------------
    def shade(self, p, mat, n, vdir):
        vis = self.soft_shadow(p, n); ao = self.ao(p, n)
        ndl = np.clip(n @ self.sun, 0, 1); rock = mat == 2
        sunk = np.where(rock, ndl ** 0.55, 0.22 + 1.05 * ndl) * vis
        skyk = (0.55 + 0.45 * n[..., 1]) * ao
        bnc = np.clip(n @ (-self.bfrom), 0, 1) * ao
        alb = np.where(rock[..., None], self.rockA, self.grassA)
        trans = np.where(rock, 0, np.clip(-(vdir @ self.sun), 0, 1) ** 3 * vis * 0.9)
        col = alb * (self.sunC * (sunk + trans)[..., None] + self.skyC * skyk[..., None] + self.bounceC * bnc[..., None])
        return col, dict(vis=vis, ao=ao, ndl=ndl, trans=trans, bnc=np.clip(n @ (-self.bfrom), 0, 1))

# ---------------------------------------------------------------------------------------------
SKY, GRASS, ROCK, WATER, FAR, MID = 0, 1, 2, 3, 4, 5

def observe(sc):
    d = sc.rays(); o = sc.eye
    tw = np.where(d[..., 1] < -1e-6, (0 - o[1]) / np.minimum(d[..., 1], -1e-6), np.inf)
    tfar = np.where(d[..., 2] > 1e-6, (sc.zfar - o[2]) / np.maximum(d[..., 2], 1e-6), np.inf)
    tmax = np.minimum(np.minimum(tw, tfar), 400.0)
    t, hit = sc.march(np.broadcast_to(o, d.shape).copy(), d, tmax)
    p = o + d * t[..., None]
    G = {k: np.zeros((H, W)) for k in ("vis", "ao", "ndl", "trans", "bnc")}
    mat = np.full((H, W), SKY, np.int8)
    water = (~hit) & (tw < tfar); mat[water] = WATER
    mat[hit] = sc.material_at(p)[hit]
    depth = np.where(hit, t, np.where(water, tw, 1e4))
    nrm = np.zeros((H, W, 3)); col = np.zeros((H, W, 3)); pos = p.copy()
    if hit.any():
        n = sc.normal(p[hit], mat[hit]); c, inf = sc.shade(p[hit], mat[hit], n, d[hit])
        nrm[hit] = n; col[hit] = c
        for k in G: G[k][hit] = inf[k]
    mark, OFF = sc.mid_layer()
    farc, mnt, mlit = sc.far_layer(d)
    far = (~hit) & (~water)
    col[far] = farc[far]; mat[far & mnt] = FAR
    midm = mark[OFF:OFF + H]
    mid_here = (midm > 0) & far
    mat[mid_here] = MID
    # water: rippled Fresnel mirror
    R = np.zeros((H, W)); refl = {"mat": np.full((H, W), -1, np.int8), "col": np.zeros((H, W, 3)),
                                  "key": np.zeros((H, W), np.int8), "mlit": np.zeros((H, W), bool),
                                  "vis": np.zeros((H, W)), "ndl": np.zeros((H, W)), "ao": np.ones((H, W)),
                                  "nrm": np.zeros((H, W, 3)), "hgt": np.zeros((H, W)), "bnc": np.zeros((H, W))}
    if water.any():
        yy, xx = np.nonzero(water)
        pw = o + d[water] * tw[water][..., None]
        rng = np.random.default_rng(sc.seed + 5)
        rip = fbm2(xx * 0.05 + sc.seed, yy * 0.8, sc.seed + 80, 3)       # long in x, short in y
        amp = math.radians(0.3)
        nw = norm(np.stack([np.zeros_like(rip), np.ones_like(rip), rip * amp * 2.0], -1))
        # wind lines: sparse 1-px horizontal segments tilted so they see higher (lighter) sky
        wmask = np.zeros((H, W)); ys_w = np.nonzero(water.any(1))[0]
        for _ in range(int(len(ys_w) * 0.35) + 2):
            yrow = rng.choice(ys_w); x0 = int(rng.integers(0, W)); L = int(rng.integers(5, 40))
            wmask[yrow, x0:x0 + L] = 1
        wl = wmask[yy, xx]
        nw = norm(nw + np.stack([np.zeros_like(wl), np.zeros_like(wl), -wl * math.radians(2.5)], -1))
        dv = d[water]
        dr = norm(dv - 2 * np.sum(dv * nw, -1)[..., None] * nw)
        tfr = np.where(dr[:, 2] > 1e-6, (sc.zfar - pw[:, 2]) / np.maximum(dr[:, 2], 1e-6), np.inf)
        tr, hr = sc.march(pw + dr * 0.01, dr, np.minimum(200.0, tfr), steps=200)
        rmat = np.full(len(yy), -1, np.int8); rc = np.zeros((len(yy), 3)); rkey = np.zeros(len(yy), np.int8)
        rml = np.zeros(len(yy), bool)
        rG = {k: np.zeros(len(yy)) for k in ("vis", "ndl", "ao", "bnc", "hgt")}; rG["ao"][:] = 1
        rn = np.zeros((len(yy), 3))
        if hr.any():
            ph = pw[hr] + dr[hr] * tr[hr][..., None]; mh = sc.material_at(ph); nh = sc.normal(ph, mh)
            ch, inf = sc.shade(ph, mh, nh, dr[hr])
            rc[hr] = ch; rmat[hr] = mh; rn[hr] = nh
            for k in ("vis", "ndl", "ao", "bnc"): rG[k][hr] = inf[k]
            rG["hgt"][hr] = ph[:, 1] - sc.ground_h(ph[:, 0], ph[:, 2])
        miss = ~hr
        if miss.any():
            q = pw[miss] + dr[miss] * np.minimum(tfr[miss], 1e5)[..., None]
            qpx, qpy, qz = sc.project(q)
            qx = np.clip(np.round(qpx).astype(int), 0, W - 1); qy = np.round(qpy).astype(int) + OFF
            ok = (qy >= 0) & (qy < H + OFF) & np.isfinite(tfr[miss]) & (qz > 0)
            qy = np.clip(qy, 0, H + OFF - 1)
            midhit = ok & (mark[qy, qx] > 0)
            fc, fm, fl = sc.far_layer(dr[miss])
            rc[miss] = fc; rkey[miss] = np.where(midhit, mark[qy, qx], 0)
            rmat[miss] = np.where(midhit, MID, np.where(fm, FAR, SKY)); rml[miss] = fl
        cos_i = np.clip(-np.sum(dv * nw, -1), 0, 1)
        Rf = 0.02 + 0.98 * (1 - cos_i) ** 5
        R[water] = Rf
        refl["mat"][water] = rmat; refl["col"][water] = rc; refl["key"][water] = rkey; refl["mlit"][water] = rml
        for k in rG: refl[k][water] = rG[k]
        refl["nrm"][water] = rn
    hgt = np.zeros((H, W))
    if hit.any(): hgt[hit] = p[hit][:, 1] - sc.ground_h(p[hit][:, 0], p[hit][:, 2])
    return dict(col=col, mat=mat, depth=depth, nrm=nrm, pos=pos, R=R, refl=refl, midm=midm,
                farlit=mlit, hgt=hgt, **G)

# ---------------------------------------------------------------------------------------------
# palette (32): every entry is the light model evaluated at a canonical light state, or a
# k-means centre of the observed sky / mountains.
# ---------------------------------------------------------------------------------------------
def tone(c):
    c = np.maximum(c, 0); c = c / (1 + 0.35 * c)
    return np.where(c <= 0.0031308, 12.92 * c, 1.055 * np.power(np.clip(c, 0, None), 1 / 2.4) - 0.055).clip(0, 1)

def to_lab(srgb): return rgb2lab(np.asarray(srgb, float).reshape(-1, 1, 3)).reshape(np.shape(srgb))

def kmeans_ramp(samples, k, seed=0):
    from sklearn.cluster import KMeans
    lab = to_lab(samples); k = min(k, len(np.unique(np.round(lab), axis=0)))
    km = KMeans(k, n_init=3, random_state=seed).fit(lab)
    cen = km.cluster_centers_[np.argsort(km.cluster_centers_[:, 0])]
    return lab2rgb(cen.reshape(-1, 1, 3)).reshape(-1, 3).clip(0, 1)

class Palette:
    """named entries. grass families and rock zones come from canonical light states."""
    def __init__(self, sc, obs):
        s = sc; P = {}
        gA = s.grassA; dry = gA * np.array([1.15, 1.0, 0.7]); green = gA * np.array([0.6, 1.0, 0.8])
        sun, sky, bnc = s.sunC, s.skyC, s.bounceC
        # grass lit family (ochre base / tan blade / dark-green gap) + the crest tan
        P["g_crest"] = tone(dry * (sun * 1.30 + sky))
        P["g_tan"] = tone(dry * (sun * 0.80 + sky))
        P["g_ochre"] = tone(dry * (sun * 0.34 + sky * 0.9))
        P["g_gap"] = tone(green * (sun * 0.03 + sky * 0.30))
        # grass shadow family (dark olive base / darker blade / near-black gap)
        P["g_dol"] = tone(gA * (sky * 0.95 + bnc * 0.3))
        P["g_dk"] = tone(gA * (sky * 0.45))
        P["g_blk"] = tone(gA * sky * 0.10)
        P["g_mid"] = tone(dry * (sun * 0.14 + sky * 0.95))          # transition / reflections
        # rock zones: contact / core / bounce-lit shadow / half (sky-lit top) / lit / rim
        rA = s.rockA
        P["r_contact"] = tone(rA * sky * 0.12)
        P["r_core"] = tone(rA * (sky * 0.38 + bnc * 0.1))
        P["r_shade"] = tone(rA * (sky * 0.62 + bnc * 0.9))
        P["r_half"] = tone(rA * (sky * 1.05 + sun * 0.16))
        P["r_lit"] = tone(rA * (sky * 0.8 + sun * 0.62))
        P["r_rim"] = tone(rA * (sky * 0.8 + sun * 1.05))
        # sky ramp (8) from the observed sky incl. the part the near water mirrors
        az = np.linspace(-0.6, 0.6, 30) + s.yaw; el = np.linspace(0.0, 0.7, 40)
        A, E = np.meshgrid(az, el)
        dd = np.stack([np.sin(A) * np.cos(E), np.sin(E), np.cos(A) * np.cos(E)], -1).reshape(-1, 3)
        sk = s.sky(dd); sk = sk[(dd @ s.sun) < math.cos(math.radians(1.5))]
        mat = obs["mat"]; skypx = obs["col"][mat == SKY]
        self.sky = kmeans_ramp(tone(np.concatenate([skypx, sk])), 8, s.seed)
        farpx = obs["col"][mat == FAR]
        if len(farpx) < 16: farpx = s.far_layer(dd[:400] * np.array([1, 0.05, 1]))[0]
        self.far = kmeans_ramp(tone(farpx), 4, s.seed)
        # water: the sky ramp mirrored one and two steps darker, and the deep body
        self.water = np.array([tone(self._lin(self.sky[4]) * 0.55), tone(self._lin(self.sky[2]) * 0.42),
                               tone(self._lin(self.sky[1]) * 0.28), tone(self._lin(self.sky[0]) * 0.16)])
        P["accent"] = tone(sun * 0.9) if s.back else tone(dry * (sun * 1.8 + sky))
        self.named = P
        names = list(P.keys())
        cols = [P[n] for n in names] + list(self.sky) + list(self.far) + list(self.water)
        self.names = names + [f"sky{i}" for i in range(len(self.sky))] + [f"far{i}" for i in range(len(self.far))] + [f"w{i}" for i in range(4)]
        self.rgb = np.clip(np.array(cols), 0, 1)
        assert len(self.rgb) <= 32, len(self.rgb)
        self.lab = to_lab(self.rgb)
        self.i = {n: k for k, n in enumerate(self.names)}

    @staticmethod
    def _lin(c):
        c = np.asarray(c, float); return np.where(c <= 0.04045, c / 12.92, ((c + 0.055) / 1.055) ** 2.4)

    def ids(self, prefix): return np.array([self.i[n] for n in self.names if n.startswith(prefix)])

# ---------------------------------------------------------------------------------------------
# stage 2: translation
# ---------------------------------------------------------------------------------------------
class Painter:
    def __init__(self, sc, obs, pal):
        self.sc, self.o, self.pal = sc, obs, pal
        self.rng = np.random.default_rng(sc.seed + 777)
        self.img = np.zeros((H, W), np.int16)
        yy, xx = np.mgrid[0:H, 0:W]; self.yy, self.xx = yy, xx
        self.chk = ((xx + yy) & 1) == 1

    def I(self, name): return self.pal.i[name]

    # -- helpers ---------------------------------------------------------------------------
    def ramp_pos(self, lab, ids):
        R = self.pal.lab[ids]; best = np.full(lab.shape[:-1], np.inf); pos = np.zeros(lab.shape[:-1])
        for i in range(len(R) - 1):
            a, b = R[i], R[i + 1]; ab = b - a
            t = np.clip(((lab - a) @ ab) / (ab @ ab + 1e-9), 0, 1)
            dd = np.linalg.norm(lab - (a + t[..., None] * ab), axis=-1)
            m = dd < best; best[m] = dd[m]; pos[m] = i + t[m]
        return pos

    def checker3(self, f):
        return np.where(f < 1 / 3, False, np.where(f > 2 / 3, True, self.chk))

    def clustered(self):
        h, w = H, W; r = self.rng
        c = np.repeat(np.repeat(r.uniform(size=(h // 2 + 2, w // 2 + 2)), 2, 0), 2, 1)[:h, :w]
        off = r.integers(0, 2, size=h)
        for y in range(h): c[y] = np.roll(c[y], off[y])
        return 0.55 * c + 0.45 * r.uniform(size=(h, w))

    def hruns(self, lo=2, hi=7):
        run = np.zeros((H, W))
        for y in range(H):
            x = 0
            while x < W:
                L = int(self.rng.integers(lo, hi + 1)); run[y, x:x + L] = self.rng.uniform(); x += L
        return run

    # -- the painting --------------------------------------------------------------------------
    def paint(self):
        o = self.o; mat = o["mat"]
        lab = to_lab(tone(o["col"]))
        # sky: bands + 50% checker strips
        sky_ids = self.pal.ids("sky")
        pos = self.ramp_pos(lab, sky_ids)
        i0 = np.clip(np.floor(pos).astype(int), 0, len(sky_ids) - 1); i1 = np.clip(i0 + 1, 0, len(sky_ids) - 1)
        pick = np.where(self.checker3(pos - np.floor(pos)), sky_ids[i1], sky_ids[i0])
        self.img[mat == SKY] = pick[mat == SKY]
        if self.sc.back:
            sun = (mat == SKY) & (tone(o["col"]).sum(-1) > 2.75); self.img[sun] = self.I("accent")
        # mountains: facets. ramp + clustered dither, lit ridges get the lightest far colour
        far_ids = self.pal.ids("far"); pos = self.ramp_pos(lab, far_ids)
        i0 = np.clip(np.floor(pos).astype(int), 0, 3); i1 = np.clip(i0 + 1, 0, 3)
        f = pos - np.floor(pos); th = self.clustered()
        fm = mat == FAR
        self.img[fm] = np.where(np.clip((f - 0.5) * 1.8 + 0.5, 0, 1) > th, far_ids[i1], far_ids[i0])[fm]
        self.paint_mid(self.o["midm"], mat == MID)
        self.paint_water()
        self.paint_rock()
        self.paint_grass()
        return self.img

    def mid_key_to_idx(self, key, shape):
        r = self.rng.uniform(size=shape)
        out = np.full(shape, self.I("g_dk"))
        out = np.where(key == 1, np.where(r < 0.62, self.I("g_ochre"), np.where(r < 0.82, self.I("g_mid"), self.I("g_dol"))), out)
        out = np.where(key == 7, np.where(r < 0.6, self.I("g_dol"), self.I("g_dk")), out)
        out = np.where(key == 2, np.where(r < 0.7, self.I("g_blk"), self.I("g_dk")), out)
        out = np.where(key == 3, self.I("g_tan") if not self.sc.back else self.I("g_crest"), out)
        out = np.where(key == 4, self.I("g_dol"), out)
        return out

    def paint_mid(self, key, m):
        idx = self.mid_key_to_idx(key, key.shape)
        self.img[m] = idx[m]

    # -- rock (study D, A) -----------------------------------------------------------------
    def rock_value(self, n, vis, ao, bnc, hgt, ndl_sun):
        """ramp coordinate 1 contact .. 2 core .. 3 shade .. 4 half .. 5 lit (6 rim is placed as an
        edge mark). The terminator is a jump: lit side and shadow side are separate ranges."""
        sc = self.sc
        lit_amt = ndl_sun * vis
        lit = 3.75 + 1.25 * np.clip((lit_amt - 0.12) / 0.45, 0, 1) ** 0.7
        shd = 2.0 + 1.0 * np.clip((bnc - 0.3) / 0.35, 0, 1)
        shd = np.maximum(shd, 2.0 + 2.0 * np.clip((n[..., 1] - 0.45) / 0.4, 0, 1) * 0.95)   # sky-lit tops
        v = np.where(lit_amt > 0.12, np.maximum(lit, shd), shd)
        occ = np.clip(1 - (hgt / (0.3 * sc.a + 1e-6)), 0, 1) * 0.8 + (1 - ao) * 1.2
        v = v - np.clip(occ, 0, 1) * (v - 1.0) * 0.8
        return v

    def paint_rock(self):
        o = self.o; m = o["mat"] == ROCK
        if not m.any(): return
        ids = [self.I(k) for k in ("r_contact", "r_contact", "r_core", "r_shade", "r_half", "r_lit", "r_rim")]
        v = self.rock_value(o["nrm"], o["vis"], o["ao"], o["bnc"], o["hgt"], o["ndl"])
        npx = m.sum(); scale = np.sqrt(npx / 3000.0)
        # vertical weathering grain (only where the rock is big enough to carry texture)
        g = self.rng.uniform(-1, 1, (H // 3 + 2, W)); g = np.repeat(g, 3, 0)[:H]
        g = 0.5 * g + 0.5 * np.roll(g, 1, 0)
        v = v + 0.33 * min(1.0, scale) * g
        lo = np.floor(v); f = v - lo
        z = np.where(np.clip((f - 0.5) * 2.2 + 0.5, 0, 1) > self.clustered(), lo + 1, lo).astype(int)
        z = np.clip(z, 1, 5)
        # rim: silhouette pixels on the sun side that face the sun
        fwd, right, up = self.sc.basis()
        sx = self.sc.sun @ right
        dx = -1 if sx < -0.2 else (1 if sx > 0.2 else 0)
        out_sun = ~np.roll(m, -dx, 1) if dx else np.zeros_like(m)
        out_up = ~np.roll(m, 1, 0)
        rim = m & (out_sun | out_up) & (o["ndl"] * o["vis"] > 0.3)
        if self.sc.back:
            rim |= m & out_up & (o["nrm"][..., 1] > 0.25)       # back-light: the top edge glows
        z[rim] = 6
        # contact: lowest boulder pixel in each column touching grass -> darkest
        below = np.roll(o["mat"], -1, 0)
        z[m & (below == GRASS)] = 1
        idx = np.array(ids)[z]
        self.img[m] = idx[m]

    # -- grass (study B, E, A) ---------------------------------------------------------------
    def grass_light(self):
        o = self.o
        t = np.clip(o["vis"] * (0.1 + 1.1 * o["ndl"]) / 0.75, 0, 1)
        t = np.maximum(t, np.clip(o["trans"] * 1.3, 0, 1))
        return t

    def paint_grass(self):
        o = self.o; sc = self.sc; mat = o["mat"]; m = mat == GRASS
        if not m.any(): return
        rng = self.rng; depth = o["depth"]
        t = self.grass_light()
        lit = m & (t > rng.uniform(size=(H, W)))
        I = self.I
        # blade length (px): 0.3 m blades projected; taller at the boulder's foot and the lip
        pix_ang = HFOV / W
        P = o["pos"]
        foot = np.clip(1 - sc.boulder_sdf(P) / (0.4 * sc.a + 0.15), 0, 1) * m
        lipd = sc.bank_field(P[..., 0], P[..., 2])
        lipz = np.clip(1 - lipd / 0.5, 0, 1) * m
        L = 0.3 / np.maximum(depth, 0.1) / pix_ang * 0.5 * (1 + 1.0 * foot + 0.7 * lipz)
        L = np.clip(L, 0, 13)
        # base fill: family base colours, stipple (the far grass is only this)
        r = rng.uniform(size=(H, W))
        base = np.where(lit, I("g_ochre"), I("g_dol"))
        base = np.where(lit & (r > 0.84), I("g_tan"), base)
        base = np.where(~lit & (r < 0.35), I("g_dk"), base)
        far = L < 2.5
        base = np.where(far & lit & (r < 0.07), I("g_gap"), base)
        base = np.where(far & ~lit & (r > 0.93), I("g_blk"), base)
        self.img[m] = base[m]
        # crest bands: grass pixels whose upper neighbour is much farther (a mass top against the
        # land/water behind it) and that face the sun get 1-3 px of the lightest tan
        up_depth = np.roll(depth, 1, 0); up_mat = np.roll(mat, 1, 0)
        top = m & ((up_mat != GRASS) | (up_depth > depth * 1.12 + 0.3))
        top[0] = False
        tl = top & (t > 0.45)
        bandw = np.clip(0.8 + 6.0 / np.maximum(depth, 1.0), 1, 3).astype(int)
        for k in range(3):
            sel = np.roll(tl & (bandw > k), k, 0) & m & lit
            if k == 0: sel = np.roll(tl, 0, 0)
            keep = rng.uniform(size=(H, W)) < (0.9 - 0.2 * k)
            self.img[sel & keep] = I("g_crest") if k == 0 else I("g_tan")
        # blades, far to near, z-tested
        ys, xs = np.nonzero(m & (L >= 1.8))
        order = np.argsort(depth[ys, xs])[::-1]
        img = self.img; wind = -1 if rng.uniform() < 0.6 else 1
        for y, x in zip(ys[order], xs[order]):
            Lp = L[y, x]
            if rng.uniform() > min(1.0, 1.7 / Lp + 0.1): continue
            fam_lit = lit[y, x]
            gap = rng.uniform() < 0.3 and Lp >= 3
            n = max(2, int(round(Lp * rng.uniform(0.6, 1.2))))
            zr = depth[y, x]
            if gap:
                n = max(2, n // 2); run = 0; c_body = c_tip = I("g_gap") if fam_lit else I("g_blk")
            else:
                run = int(rng.choice([2, 3, 3, 4, 5, 6]))
                if fam_lit:
                    c_body = I("g_tan") if rng.uniform() < 0.5 else I("g_ochre"); c_tip = I("g_tan")
                    if t[y, x] > 0.85 and rng.uniform() < 0.4: c_tip = I("g_crest")
                else:
                    c_body = I("g_dk"); c_tip = I("g_dol")
            direc = wind if rng.uniform() < 0.75 else -wind
            xx = x; posr = 0
            for k in range(n):
                yy = y - k
                if yy < 0: break
                if k > 0:
                    posr += 1
                    if run > 0 and posr >= run:
                        xx += direc; posr = 0
                        if k > n * 0.35: run = max(1, run - 1)
                if xx < 0 or xx >= W: break
                if depth[yy, xx] < zr - 0.05 and mat[yy, xx] != GRASS: break
                if mat[yy, xx] == GRASS and depth[yy, xx] < zr - 0.25: break
                img[yy, xx] = c_tip if k >= n * 0.45 else c_body

    # -- water (study C) -----------------------------------------------------------------------
    def paint_water(self):
        o = self.o; sc = self.sc; m = o["mat"] == WATER
        if not m.any(): return
        rf = o["refl"]; rmat = rf["mat"]; I = self.I; rng = self.rng
        Reff = np.clip(0.3 + 0.9 * o["R"], 0, 1)          # observed: near water darker, not black
        # 1) mirrored sky: continuous * R -> sky+water ramps, checker (smooth)
        c = tone(rf["col"] * Reff[..., None] + np.array([0.02, 0.016, 0.03]) * (1 - Reff[..., None]))
        lab = to_lab(c)
        cand = np.concatenate([self.pal.ids("sky"), self.pal.ids("w")])
        cand = cand[np.argsort(self.pal.lab[cand][:, 0])]
        pos = self.ramp_pos(lab, cand)
        i0 = np.clip(np.floor(pos).astype(int), 0, len(cand) - 1); i1 = np.clip(i0 + 1, 0, len(cand) - 1)
        sky_pick = np.where(self.checker3(pos - np.floor(pos)), cand[i1], cand[i0])
        # 2) mirrored things: paint them in their own vocabulary one step darker, resampled as
        #    horizontal runs (reflections read as horizontal dashes)
        run = self.hruns(2, 7)
        thing = np.full((H, W), -1)
        r = rng.uniform(size=(H, W))
        # grass: reflect the families one step down
        gl = (rmat == GRASS)
        tl = np.clip(rf["vis"] * (0.1 + 1.1 * rf["ndl"]) / 0.75, 0, 1)
        litr = tl > run
        thing = np.where(gl & litr, np.where(r < 0.8, I("g_ochre"), I("g_mid")), thing)
        thing = np.where(gl & ~litr, np.where(run < 0.5, I("g_dk"), I("g_blk")), thing)
        # rock: the mirror sees the underside -> mostly core/shade, lit faces one step down
        rl = rmat == ROCK
        v = self.rock_value(rf["nrm"], rf["vis"], rf["ao"], rf["bnc"], rf["hgt"], rf["ndl"]) - 1.0
        rock_ids = np.array([I(k) for k in ("r_contact", "r_contact", "r_core", "r_shade", "r_half", "r_lit", "r_rim")])
        vz = np.clip(np.floor(v + run * 0.8), 1, 5).astype(int)
        thing = np.where(rl, rock_ids[vz], thing)
        # far bank / trees
        ml = rmat == MID
        mk = rf["key"]
        down = {1: I("g_mid"), 7: I("g_dk"), 2: I("g_blk"), 3: I("g_ochre"), 4: I("g_dk")}
        for k, vv in down.items():
            thing = np.where(ml & (mk == k), vv, thing)
        # mountains: far ramp one step down
        fl = rmat == FAR
        far_ids = self.pal.ids("far")
        fpos = self.ramp_pos(to_lab(tone(rf["col"] * 0.7)), far_ids)
        fz = np.clip(np.floor(fpos + run * 0.9).astype(int), 0, 3)
        thing = np.where(fl, far_ids[fz], thing)
        # Fresnel: toward the viewer the reflection sinks into the water body -> dither into w3
        deep = Reff < 0.55
        thing = np.where((thing >= 0) & deep & (run > (Reff - 0.3) / 0.25), I("w3"), thing)
        out = np.where(thing >= 0, thing, sky_pick)
        self.img[m] = out[m]
        # 3) waterlines: first water pixel under something. far shore -> light line; near lip or
        #    rock foot -> dark line (overhang / contact shadow)
        mat = o["mat"]; above = np.roll(mat, 1, 0); dab = np.roll(o["depth"], 1, 0)
        edge = m & (above != WATER); edge[0] = False
        light_line = edge & ((above == MID) | (above == FAR) | ((above == GRASS) & (dab > 25)))
        dark_line = edge & ~light_line & ((above == GRASS) | (above == ROCK))
        self.img[light_line & (rng.uniform(size=(H, W)) < 0.8)] = self.pal.ids("sky")[5]
        self.img[dark_line & (rng.uniform(size=(H, W)) < 0.85)] = I("g_blk")
        # 4) back-lit: glitter path under the sun
        if sc.back:
            g = m & (tone(rf["col"]).sum(-1) > 2.6)
            self.img[g] = I("accent")

# ---------------------------------------------------------------------------------------------
def paint_scene(size="medium", light="left", distance="10m", seed=0, return_all=False):
    sc = Scene(size, light, distance, seed)
    obs = observe(sc)
    pal = Palette(sc, obs)
    idx = Painter(sc, obs, pal).paint()
    rgb = (pal.rgb[idx] * 255).round().astype(np.uint8)
    if return_all: return rgb, (tone(obs["col"]) * 255).astype(np.uint8), pal, obs, sc
    return rgb

def up3(rgb): return np.repeat(np.repeat(rgb, 3, 0), 3, 1)

if __name__ == "__main__":
    ap = argparse.ArgumentParser()
    ap.add_argument("--size", default="medium"); ap.add_argument("--light", default="left")
    ap.add_argument("--distance", default="10m"); ap.add_argument("--seed", type=int, default=0)
    ap.add_argument("--out", default="out/single.png")
    a = ap.parse_args()
    rgb, obsimg, pal, obs, sc = paint_scene(a.size, a.light, a.distance, a.seed, True)
    os.makedirs(os.path.dirname(a.out) or ".", exist_ok=True)
    Image.fromarray(up3(rgb)).save(a.out)
    Image.fromarray(up3(obsimg)).save(a.out.replace(".png", "_obs.png"))
    print("colours used:", len(np.unique(rgb.reshape(-1, 3), axis=0)), "palette:", len(pal.rgb))

cd ~/work/pixelart-studies/pedagogy/observation && OMP_NUM_THREADS=4 OPENBLAS_NUM_THREADS=4 nice -n 10 python3 tarn.py --out out/v2_a.png 2>&1 | tail -8

# output:
colours used: 27 palette: 31

cd ~/work/pixelart-studies/pedagogy/observation && cat > palette_card.py <<'EOF'
"""print and draw the 32-colour palette of one parameter set (named swatches, L* values)"""
import sys, numpy as np
from PIL import Image, ImageDraw
import tarn
def card(size, light, dist, seed, out):
    rgb, obsimg, pal, obs, sc = tarn.paint_scene(size, light, dist, seed, True)
    n = len(pal.rgb); im = Image.new("RGB", (8 * 90, ((n + 7) // 8) * 60), "white"); d = ImageDraw.Draw(im)
    for i, (nm, c) in enumerate(zip(pal.names, pal.rgb)):
        x, y = (i % 8) * 90, (i // 8) * 60
        d.rectangle([x, y, x + 88, y + 40], fill=tuple((c * 255).astype(int)))
        d.text((x + 2, y + 42), f"{nm} L{pal.lab[i][0]:.0f}", fill="black")
    im.save(out)
    for nm, c, l in zip(pal.names, pal.rgb, pal.lab): print(f"{nm:10s} {tuple((c*255).astype(int))}  L*={l[0]:.0f}")
if __name__ == "__main__":
    card(sys.argv[1], sys.argv[2], sys.argv[3], int(sys.argv[4]), sys.argv[5])
EOF
OMP_NUM_THREADS=4 nice -n 10 python3 palette_card.py medium left 10m 0 out/palette_left.png

# output:
g_crest    (250, 190, 92)  L*=81
g_tan      (218, 162, 79)  L*=71
g_ochre    (167, 121, 62)  L*=54
g_gap      (50, 50, 29)  L*=20
g_dol      (93, 76, 58)  L*=34
g_dk       (56, 47, 38)  L*=21
g_blk      (24, 19, 14)  L*=6
g_mid      (130, 96, 54)  L*=44
r_contact  (34, 29, 38)  L*=12
r_core     (72, 60, 71)  L*=27
r_shade    (122, 97, 95)  L*=44
r_half     (154, 126, 127)  L*=56
r_lit      (221, 177, 150)  L*=76
r_rim      (255, 209, 173)  L*=87
accent     (255, 211, 103)  L*=87
sky0       (133, 115, 145)  L*=51
sky1       (147, 124, 149)  L*=55
sky2       (160, 133, 150)  L*=59
sky3       (173, 142, 149)  L*=62
sky4       (186, 150, 147)  L*=65
sky5       (187, 152, 146)  L*=66
sky6       (189, 154, 145)  L*=67
sky7       (193, 157, 146)  L*=68
far0       (157, 127, 125)  L*=56
far1       (168, 134, 130)  L*=59
far2       (168, 140, 148)  L*=61
far3       (191, 158, 159)  L*=68
w0         (136, 111, 108)  L*=49
w1         (105, 87, 98)  L*=39
w2         (79, 66, 80)  L*=30
w3         (54, 46, 59)  L*=20

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("tarn.py").read()
# sky: brighter, more chroma (Ferrari's sky sits at L*72-78, pink to violet)
s = s.replace("zen = np.array([0.30, 0.24, 0.48]); mid = np.array([0.62, 0.40, 0.58]); hor = np.array([0.95, 0.56, 0.48])",
              "zen = np.array([0.50, 0.36, 0.72]); mid = np.array([0.86, 0.50, 0.66]); hor = np.array([1.05, 0.58, 0.48])")
s = s.replace("return (base + glow + halo + belt) * 0.62 + disk", "return (base + glow + halo + belt) * 0.78 + disk")
# light: land darker than sky at dusk (notan: sky = light family)
s = s.replace("self.sunC = np.array([1.00, 0.56, 0.30]) * 3.0", "self.sunC = np.array([1.00, 0.52, 0.28]) * 2.3")
s = s.replace("self.rockA = np.array([0.46, 0.42, 0.38])", "self.rockA = np.array([0.50, 0.43, 0.38])")
# palette: grass families. lit = dry straw under warm sun; shadow = green-olive under violet sky
s = s.replace('''        gA = s.grassA; dry = gA * np.array([1.15, 1.0, 0.7]); green = gA * np.array([0.6, 1.0, 0.8])''',
'''        gA = s.grassA; dry = gA * np.array([1.15, 1.0, 0.7]); green = np.array([0.10, 0.20, 0.07]); olive = np.array([0.24, 0.26, 0.08])''')
s = s.replace('''        P["g_gap"] = tone(green * (sun * 0.03 + sky * 0.30))
        # grass shadow family (dark olive base / darker blade / near-black gap)
        P["g_dol"] = tone(gA * (sky * 0.95 + bnc * 0.3))
        P["g_dk"] = tone(gA * (sky * 0.45))
        P["g_blk"] = tone(gA * sky * 0.10)''', '''        P["g_gap"] = tone(green * (sun * 0.02 + sky * 0.25))
        # grass shadow family (dark olive base / darker blade / near-black gap)
        P["g_dol"] = tone(olive * (sky * 0.75 + bnc * 0.3))
        P["g_dk"] = tone(olive * (sky * 0.30))
        P["g_blk"] = tone(olive * sky * 0.05)''')
# rock: lit states lean on the sun (orange), shadows on the violet sky
s = s.replace('''        P["r_half"] = tone(rA * (sky * 1.05 + sun * 0.16))
        P["r_lit"] = tone(rA * (sky * 0.8 + sun * 0.62))
        P["r_rim"] = tone(rA * (sky * 0.8 + sun * 1.05))''', '''        P["r_half"] = tone(rA * (sky * 1.15 + sun * 0.12))
        P["r_lit"] = tone(rA * (sky * 0.5 + sun * 0.75))
        P["r_rim"] = tone(rA * (sky * 0.5 + sun * 1.2))''')
# sky ramp: evenly spaced along the elevation path (k-means wasted entries on near-duplicates)
s = s.replace('''        mat = obs["mat"]; skypx = obs["col"][mat == SKY]
        self.sky = kmeans_ramp(tone(np.concatenate([skypx, sk])), 8, s.seed)''', '''        self.sky = self.path_ramp(s, 8)''')
s = s.replace('''    @staticmethod
    def _lin(c):''', '''    @staticmethod
    def path_ramp(s, k):
        """sample the sky from zenith-ish (35 deg) down to the horizon at the view centre and toward
        the sun's side; pick k colours evenly spaced along the Lab path (distinct bands)."""
        fwd = s.basis()[0]; az0 = math.atan2(fwd[0], fwd[2])
        els = np.linspace(0.62, 0.0, 200)
        cols = []
        for daz in (-0.35, 0.0, 0.35):
            d = np.stack([np.sin(az0 + daz) * np.cos(els), np.sin(els), np.cos(az0 + daz) * np.cos(els)], -1)
            cols.append(tone(s.sky(d)))
        c = np.mean(cols, 0); lab = to_lab(c)
        seg = np.r_[0, np.cumsum(np.linalg.norm(np.diff(lab, axis=0), axis=1))]
        pick = [np.argmin(np.abs(seg - q)) for q in np.linspace(0, seg[-1], k)]
        out = c[pick]
        return out[np.argsort(to_lab(out)[:, 0])]

    @staticmethod
    def _lin(c):''')
open("tarn.py", "w").write(s)
EOF
OMP_NUM_THREADS=4 nice -n 10 python3 palette_card.py medium left 10m 0 out/palette_left.png | head -40

# output:
Traceback (most recent call last):
  File "~/work/pixelart-studies/pedagogy/observation/palette_card.py", line 15, in <module>
    card(sys.argv[1], sys.argv[2], sys.argv[3], int(sys.argv[4]), sys.argv[5])
  File "~/work/pixelart-studies/pedagogy/observation/palette_card.py", line 6, in card
    rgb, obsimg, pal, obs, sc = tarn.paint_scene(size, light, dist, seed, True)
                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "~/work/pixelart-studies/pedagogy/observation/tarn.py", line 764, in paint_scene
    pal = Palette(sc, obs)
          ^^^^^^^^^^^^^^^^
  File "~/work/pixelart-studies/pedagogy/observation/tarn.py", line 461, in __init__
    farpx = obs["col"][mat == FAR]
                       ^^^
NameError: name 'mat' is not defined. Did you mean: 'math'?
[This command modified 1 file you've previously read: ../pedagogy/observation/tarn.py. Call Read before editing.]

cd ~/work/pixelart-studies/pedagogy/observation && grep -n 'farpx = obs\["col"\]' tarn.py && sed -i '' 's/        farpx = obs\["col"\]\[mat == FAR\]/        mat = obs["mat"]; farpx = obs["col"][mat == FAR]/' tarn.py && OMP_NUM_THREADS=4 nice -n 10 python3 palette_card.py medium left 10m 0 out/palette_left.png | head -40

# output:
461:        farpx = obs["col"][mat == FAR]
g_crest    (232, 170, 83)  L*=74
g_tan      (201, 145, 72)  L*=64
g_ochre    (154, 110, 58)  L*=50
g_gap      (28, 35, 23)  L*=13
g_dol      (75, 68, 45)  L*=29
g_dk       (40, 38, 26)  L*=15
g_blk      (11, 10, 5)  L*=3
g_mid      (122, 90, 52)  L*=41
r_contact  (36, 30, 38)  L*=12
r_core     (73, 60, 71)  L*=27
r_shade    (120, 93, 94)  L*=42
r_half     (144, 116, 125)  L*=52
r_lit      (218, 166, 135)  L*=72
r_rim      (251, 194, 156)  L*=83
accent     (254, 189, 92)  L*=81
sky0       (172, 146, 180)  L*=64
sky1       (181, 151, 179)  L*=66
sky2       (190, 156, 178)  L*=68
sky3       (196, 160, 175)  L*=70
sky4       (202, 164, 171)  L*=71
sky5       (207, 167, 167)  L*=72
sky6       (212, 170, 162)  L*=73
sky7       (215, 173, 158)  L*=74
far0       (174, 139, 134)  L*=61
far1       (179, 142, 136)  L*=63
far2       (184, 151, 155)  L*=66
far3       (199, 162, 162)  L*=70
w0         (147, 120, 125)  L*=53
w1         (124, 102, 116)  L*=46
w2         (99, 82, 97)  L*=37
w3         (72, 60, 75)  L*=27

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("tarn.py").read()
s = s.replace("        col = col * 0.5 + hz * 0.5\n        return np.where(mnt[..., None], col, self.sky(d)), mnt, mnt & (ndl > 0.35)",
              "        col = col * 0.72 + hz * 0.28\n        return np.where(mnt[..., None], col, self.sky(d)), mnt, mnt & (ndl > 0.35)")
open("tarn.py", "w").write(s)
EOF
OMP_NUM_THREADS=4 nice -n 10 python3 tarn.py --out out/v2_b.png

# output:
colours used: 24 palette: 31

cd ~/work/pixelart-studies/pedagogy/observation && python3 -c "
from PIL import Image
im=Image.open('out/v2_b.png'); w,h=im.size
im.crop((420,150,780,380)).resize((720,460),Image.NEAREST).save('out/v2_b_zoom.png')"

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("tarn.py").read()
s = s.replace('LIGHTS = {"left": -78.0, "front": 168.0, "right": 78.0, "back": -14.0}', 'LIGHTS = {"left": -105.0, "front": 170.0, "right": 105.0, "back": -14.0}')
# boulder: dome taper + tilt + stronger weathering dents
s = s.replace('''        self.dents = [(norm(rng.normal(0, 1, 3)), rng.uniform(0.04, 0.09)) for _ in range(5)]''', '''        self.dents = [(norm(rng.normal(0, 1, 3)), rng.uniform(0.06, 0.16)) for _ in range(6)]
        self.taper = rng.uniform(0.18, 0.35)          # corestones weather to domes: narrower on top
        self.tilt = rng.uniform(-0.18, 0.18)''')
s = s.replace('''    def boulder_sdf(self, p):
        L = self.local(p); a = self.a''', '''    def boulder_sdf(self, p):
        L = self.local(p); a = self.a
        ct, st = math.cos(self.tilt), math.sin(self.tilt)
        L = np.stack([ct * L[..., 0] - st * L[..., 1], st * L[..., 0] + ct * L[..., 1], L[..., 2]], -1)
        tp = 1 - self.taper * np.clip(L[..., 1] / self.half[1], -1, 1)
        L = np.stack([L[..., 0] / tp, L[..., 1], L[..., 2] / tp], -1)''')
s = s.replace("            d = d + amp * a * np.exp(-np.sum((L - c) ** 2, -1) / (0.5 * a) ** 2)", "            d = d + amp * a * np.exp(-np.sum((L - c) ** 2, -1) / (0.6 * a) ** 2)")
s = s.replace("        return d\n\n    def scene_sdf", "        return d * 0.8\n\n    def scene_sdf")
# rock grain lower
s = s.replace("        v = v + 0.33 * min(1.0, scale) * g", "        v = v + 0.22 * min(1.0, scale) * g")
# water: ripple + wind lines
s = s.replace("        amp = math.radians(0.3)", "        amp = math.radians(0.45)")
s = s.replace("        for _ in range(int(len(ys_w) * 0.35) + 2):", "        for _ in range(int(len(ys_w) * 0.8) + 4):")
# more trees in clumps
s = s.replace("        xs_t = rng.uniform(-30, W + 30, int(W / 5 * self.tree_density))\n        keep = fbm2(xs_t * 0.02 + self.seed * 0.1, np.zeros_like(xs_t), self.seed + 61, 2) > -0.1",
              "        xs_t = rng.uniform(-30, W + 30, int(W / 2.5 * self.tree_density))\n        keep = fbm2(xs_t * 0.015 + self.seed * 0.1, np.zeros_like(xs_t), self.seed + 61, 2) > 0.05")
# far bank masses: lit where a slow noise 'faces the sun'; the waterline base darker
s = s.replace('''        # shading of the far bank: lit if the sun is not behind it
        fwd, right, up = self.basis()
        if self.back: mark[mark == 1] = 7''', '''        # far bank: tussock masses. lit where a slow noise field 'faces the sun', shadow elsewhere;
        # the lowest 1-2 rows (the bank's face at the waterline) are in shadow
        fwd, right, up = self.basis()
        yyb, xxb = np.mgrid[0:HH, 0:W]
        facing = fbm2(xxb * 0.09 + self.seed, yyb * 0.35, self.seed + 62, 3) + 0.25 * np.sign(-(self.sun @ right)) * np.sin(xxb * 0.15)
        bankm = mark == 1
        mark[bankm & (facing < (0.25 if not self.back else 0.9))] = 7
        for x in range(W):
            y0 = int(round(y_wl[x])) + OFF
            if 0 <= y0 < HH: mark[max(0, y0 - 1):y0 + 1, x] = np.where(mark[max(0, y0 - 1):y0 + 1, x] > 0, 7, 0)''')
# water: wider checker for mirrored sky
s = s.replace("        sky_pick = np.where(self.checker3(pos - np.floor(pos)), cand[i1], cand[i0])", "        ff = pos - np.floor(pos)\n        sky_pick = np.where(np.where(ff < 0.2, False, np.where(ff > 0.8, True, self.chk)), cand[i1], cand[i0])")
open("tarn.py", "w").write(s)
EOF
OMP_NUM_THREADS=4 nice -n 10 python3 tarn.py --out out/v2_c.png

# output:
colours used: 24 palette: 31

cd ~/work/pixelart-studies/pedagogy/observation && grep -n "def mountain_ridge" -A 30 tarn.py | head -45

# output:
255:    def mountain_ridge(self, az):
256-        r = 0.045 + 0.055 * (0.5 + 0.5 * fbm2(az * 3.0 + self.seed * 0.37, np.zeros_like(az) + 1.7, self.seed + 40, 5))
257-        return r + 0.03 * np.maximum(0, fbm2(az * 1.3 + 9.1, np.zeros_like(az), self.seed + 41, 3))
258-
259-    def far_layer(self, d):
260-        """sky + distant granite range (3 km, dusk air), by direction. -> linear rgb, mountain mask, lit mask"""
261-        az = np.arctan2(d[..., 0], d[..., 2]); el = np.arcsin(np.clip(d[..., 1], -1, 1))
262-        ridge = self.mountain_ridge(az); mnt = el < ridge
263-        def R(a, e):
264-            return (1 - np.abs(fbm2(a * 9 + 3.1, e * 14 + 1.3, self.seed + 43, 4))) * 0.6 + (ridge - e) * 3
265-        ea = 0.0015
266-        gx = (R(az + ea, el) - R(az - ea, el)) / (2 * ea) * 0.012
267-        gy = (R(az, el + ea) - R(az, el - ea)) / (2 * ea) * 0.012
268-        vd = norm(np.stack([d[..., 0], np.zeros_like(el), d[..., 2]], -1))
269-        side = np.stack([vd[..., 2], np.zeros_like(el), -vd[..., 0]], -1)
270-        n = norm(-vd + side * (-gx)[..., None] * 1.3 + np.array([0, 1, 0]) * (0.45 - 0.4 * gy)[..., None])
271-        ndl = np.clip(n @ self.sun, 0, 1) ** 0.7
272-        snow = (fbm2(az * 22, el * 30, self.seed + 44, 3) + 0.9 * (el - ridge + 0.04) / 0.04 > 0.55) & (n[..., 1] > 0.35)
273-        alb = np.where(snow[..., None], np.array([0.80, 0.78, 0.86]), np.array([0.34, 0.30, 0.32]))
274-        col = alb * (self.sunC * 0.55 * ndl[..., None] + self.skyC * 1.3 * (0.5 + 0.5 * n[..., 1:2]))
275-        hz = self.sky(norm(np.stack([d[..., 0], np.full_like(el, 0.02), d[..., 2]], -1)))
276-        col = col * 0.72 + hz * 0.28
277-        return np.where(mnt[..., None], col, self.sky(d)), mnt, mnt & (ndl > 0.35)
278-
279-    def mid_layer(self):
280-        """far shore bank + conifers as marks on an extended canvas (rows -OFF..H).
281-        keys: 1 bank lit, 7 bank shade, 2 tree dark, 3 tree lit edge, 4 tree mid"""
282-        OFF = 150; HH = H + OFF
283-        mark = np.zeros((HH, W), np.int8)
284-        rng = np.random.default_rng(self.seed + 99)
285-        zf = self.zfar; rays = self.rays()[0]

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("tarn.py").read()
start = s.index("    def mountain_ridge(self, az):")
end = s.index("    def mid_layer(self):")
new = '''    def peaks(self):
        """the range as layered pyramids (Ferrari's mountains are facets: each peak a lit flank and
        a shadow flank split at a leaning ridge line; flanks at ~45 deg and 2:1).
        rows: az, apex_el, slope_left, slope_right, ridge_lean, layer (0 far .. 2 near)"""
        if hasattr(self, "_peaks"): return self._peaks
        rng = np.random.default_rng(self.seed + 400)
        az0 = self.yaw; P = []
        for layer, n, el_rng in ((0, 6, (0.075, 0.12)), (1, 7, (0.05, 0.085)), (2, 8, (0.028, 0.055))):
            for _ in range(n):
                P.append((az0 + rng.uniform(-0.75, 0.75), rng.uniform(*el_rng), rng.uniform(0.55, 1.25),
                          rng.uniform(0.55, 1.25), rng.uniform(-0.5, 0.5), layer))
        self._peaks = np.array(P); return self._peaks

    def far_layer(self, d):
        """sky + distant granite range (dusk air), by direction -> linear rgb, mountain mask, lit mask"""
        az = np.arctan2(d[..., 0], d[..., 2]); el = np.arcsin(np.clip(d[..., 1], -1, 1))
        Pk = self.peaks()
        col = self.sky(d).copy(); mnt = np.zeros(az.shape, bool); lit = np.zeros(az.shape, bool)
        fwd, right, up = self.basis()
        sunx = self.sun @ right
        base_el = -0.01
        for layer in (0, 1, 2):                         # far to near: nearer layers occlude
            L = Pk[Pk[:, 5] == layer]
            best = np.full(az.shape, -np.inf); side = np.zeros(az.shape); snowline = np.zeros(az.shape)
            for pa, pe, sl, sr, lean, _ in L:
                dx = az - pa
                h = np.where(dx < 0, pe + sl * dx, pe - sr * dx)
                better = h > best
                ridge_x = pa + lean * (pe - el)            # the ridge line leans
                sd = np.where(az < ridge_x, -1.0, 1.0)
                best = np.where(better, h, best); side = np.where(better, sd, side)
                snowline = np.where(better, pe - 0.022 - 0.01 * layer, snowline)
            inside = (el < best) & (el > base_el)
            # flank normal: faces left or right, tilted up, toward the viewer
            vd = norm(np.stack([d[..., 0], np.zeros_like(el), d[..., 2]], -1))
            sidev = np.stack([vd[..., 2], np.zeros_like(el), -vd[..., 0]], -1)
            n = norm(-vd * 0.7 + sidev * side[..., None] * 0.9 + np.array([0, 1, 0]) * 0.55)
            ndl = np.clip(n @ self.sun, 0, 1)
            # snow: upper parts, ragged lower edge, more on shadow flanks (it survives there)
            rag = 0.006 * fbm2(az * 60, el * 60, self.seed + 44 + layer, 2)
            snow = (el > snowline + rag) & (fbm2(az * 25, el * 40, self.seed + 45, 2) > -0.35)
            alb = np.where(snow[..., None], np.array([0.78, 0.76, 0.86]), np.array([0.30, 0.26, 0.30]))
            c = alb * (self.sunC * 0.62 * ndl[..., None] + self.skyC * 1.25 * (0.55 + 0.45 * n[..., 1:2]))
            hz = self.sky(norm(np.stack([d[..., 0], np.full_like(el, 0.03), d[..., 2]], -1)))
            haze = (0.42, 0.3, 0.2)[layer]
            c = c * (1 - haze) + hz * haze
            col = np.where(inside[..., None], c, col); mnt |= inside
            lit = np.where(inside, ndl > 0.3, lit)
        return col, mnt, lit

'''
s = s[:start] + new + s[end:]
s = s.replace('''            rc[miss] = fc; rkey[miss] = np.where(midhit, mark[qy, qx], 0)''', '''            rc[miss] = fc; rkey[miss] = np.where(midhit, mark[qy, qx], 0)''')
# rock: brighter lit plateau (rough surface; painterly clarity)
s = s.replace("        lit = 3.75 + 1.25 * np.clip((lit_amt - 0.12) / 0.45, 0, 1) ** 0.7", "        lit = 3.8 + 1.3 * np.clip((lit_amt - 0.08) / 0.32, 0, 1) ** 0.6")
s = s.replace("        v = np.where(lit_amt > 0.12, np.maximum(lit, shd), shd)", "        v = np.where(lit_amt > 0.08, np.maximum(lit, shd), shd)")
s = s.replace("        for _ in range(int(len(ys_w) * 0.8) + 4):", "        for _ in range(int(len(ys_w) * 0.45) + 4):")
open("tarn.py", "w").write(s)
EOF
grep -n "wl \* math.radians" tarn.py

# output:
416:        nw = norm(nw + np.stack([np.zeros_like(wl), np.zeros_like(wl), -wl * math.radians(2.5)], -1))

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("tarn.py").read()
s = s.replace('''    R = np.zeros((H, W)); refl = {''', '''    wind = np.zeros((H, W), bool)
    R = np.zeros((H, W)); refl = {''')
s = s.replace('''        wl = wmask[yy, xx]''', '''        wl = wmask[yy, xx]; wind[:] = (wmask > 0) & water''')
s = s.replace('''    return dict(col=col, mat=mat, depth=depth, nrm=nrm, pos=pos, R=R, refl=refl, midm=midm,''', '''    return dict(col=col, mat=mat, depth=depth, nrm=nrm, pos=pos, R=R, refl=refl, midm=midm, wind=wind,''')
s = s.replace('''        out = np.where(thing >= 0, thing, sky_pick)
        self.img[m] = out[m]''', '''        out = np.where(thing >= 0, thing, sky_pick)
        # wind-lines are solid 1-px strokes of the lighter sky-in-water colour (never dithered)
        out = np.where(o["wind"], cand[np.clip(i1 + 1, 0, len(cand) - 1)], out)
        self.img[m] = out[m]''')
open("tarn.py", "w").write(s)
EOF
OMP_NUM_THREADS=4 nice -n 10 python3 tarn.py --out out/v2_d.png

# output:
colours used: 25 palette: 31

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("tarn.py").read()
s = s.replace('''            best = np.full(az.shape, -np.inf); side = np.zeros(az.shape); snowline = np.zeros(az.shape)
            for pa, pe, sl, sr, lean, _ in L:
                dx = az - pa
                h = np.where(dx < 0, pe + sl * dx, pe - sr * dx)
                better = h > best
                ridge_x = pa + lean * (pe - el)            # the ridge line leans
                sd = np.where(az < ridge_x, -1.0, 1.0)''', '''            best = np.full(az.shape, -np.inf); side = np.zeros(az.shape); snowline = np.zeros(az.shape)
            jag = 0.010 * fbm2(az * 45 + layer * 7, np.full_like(az, 0.3), self.seed + 46 + layer, 3)
            for k_, (pa, pe, sl, sr, lean, _) in enumerate(L):
                dx = az - pa
                h = np.where(dx < 0, pe + sl * dx, pe - sr * dx) + jag * np.clip(pe - np.abs(dx) * 0.5, 0, None) / pe
                better = h > best
                ridge_x = pa + lean * (pe - el)            # the ridge line leans
                sd = np.where(az < ridge_x, -1.0, 1.0)
                # secondary ridges: facets inside each flank that turn the other way
                u = (az - ridge_x) * 38 + fbm2(az * 20, el * 20, self.seed + 47 + k_, 2) * 1.2
                flip = (np.sin(u + k_) > 0.55) & (np.abs(az - ridge_x) > 0.012)
                sd = np.where(flip, -sd, sd)''')
s = s.replace("            haze = (0.42, 0.3, 0.2)[layer]", "            haze = (0.30, 0.2, 0.12)[layer]")
s = s.replace("        keep = fbm2(xs_t * 0.015 + self.seed * 0.1, np.zeros_like(xs_t), self.seed + 61, 2) > 0.05", "        keep = fbm2(xs_t * 0.015 + self.seed * 0.1, np.zeros_like(xs_t), self.seed + 61, 2) > -0.25")
open("tarn.py", "w").write(s)
EOF
OMP_NUM_THREADS=4 nice -n 10 python3 tarn.py --out out/v2_e.png

# output:
colours used: 25 palette: 31

"""
sheets.py -- parameter sheets for the tarn method.  Every cell is a 320x180 painting shown at 3x
nearest-neighbour.  Four processes x one thread each (the 4-thread budget).

  python sheets.py            -> out/sheet_size.png, sheet_light.png, sheet_distance.png, sheet_seed.png
  python sheets.py light      -> just one
"""
import os, sys
os.environ["OMP_NUM_THREADS"] = "1"; os.environ["OPENBLAS_NUM_THREADS"] = "1"; os.environ["MKL_NUM_THREADS"] = "1"
import numpy as np
from multiprocessing import Pool
from PIL import Image, ImageDraw

BASE = dict(size="medium", light="left", distance="10m", seed=0)
SWEEPS = {
    "size": ("size", ["small", "medium", "large"], [1, 2, 3], dict(distance="10m")),
    "light": ("light", ["left", "front", "right", "back"], [1, 2, 3], {}),
    "distance": ("distance", ["close", "10m", "40m"], [1, 2, 3], {}),
    "seed": ("seed", [11, 12, 13, 14], [0, 1, 2], {}),
}

def render(args):
    import tarn
    kw, key = args
    os.makedirs("out/cells", exist_ok=True)
    fn = "out/cells/%s_%s_%s_s%d.png" % (kw["size"], kw["light"], kw["distance"], kw["seed"])
    if not os.path.exists(fn):
        rgb = tarn.paint_scene(**kw)
        Image.fromarray(rgb).save(fn)
    return key, fn

def make(name):
    param, values, seeds, extra = SWEEPS[name]
    jobs = []
    for r, v in enumerate(values):
        for c, sd in enumerate(seeds):
            kw = dict(BASE); kw.update(extra); kw[param] = v
            if name == "seed":        # seed sheet: rows = seeds, columns = a few light directions
                kw["seed"] = v; kw["light"] = ["left", "right", "back"][c]
            else:
                kw["seed"] = sd
            jobs.append((kw, (r, c)))
    with Pool(4) as p:
        res = p.map(render, jobs)
    S = 3; cw, ch = 320 * S, 180 * S; pad = 14; lab = 30
    rows, cols = len(values), len(seeds)
    sheet = Image.new("RGB", (cols * (cw + pad) + 150, rows * (ch + pad) + lab), (236, 232, 226))
    d = ImageDraw.Draw(sheet)
    fixed = {k: v for k, v in dict(BASE, **extra).items() if k != param}
    title = f"sweep: {param}   (fixed: " + ", ".join(f"{k}={v}" for k, v in fixed.items() if not (name != 'seed' and k == 'seed')) + ")"
    if name == "seed": title = "sweep: seed (rows)   columns: light = left / right / back;  size=medium, distance=10m"
    d.text((8, 8), title, fill=(40, 20, 20))
    for (r, c), fn in res:
        im = Image.open(fn).convert("RGB")
        im = im.resize((cw, ch), Image.NEAREST)
        sheet.paste(im, (150 + c * (cw + pad), lab + r * (ch + pad)))
    for r, v in enumerate(values):
        d.text((8, lab + r * (ch + pad) + ch // 2), f"{param} = {v}", fill=(40, 20, 20))
    if name != "seed":
        for c, sd in enumerate(seeds):
            d.text((150 + c * (cw + pad) + 4, lab - 14), f"seed {sd}", fill=(40, 20, 20))
    sheet.save(f"out/sheet_{name}.png"); print("wrote", name)

if __name__ == "__main__":
    names = sys.argv[1:] or list(SWEEPS)
    for n in names: make(n)

cd ~/work/pixelart-studies/pedagogy/observation && (OMP_NUM_THREADS=2 nice -n 10 python3 tarn.py --size large --light back --distance close --seed 2 --out out/t_close_back.png & OMP_NUM_THREADS=2 nice -n 10 python3 tarn.py --size small --light front --distance 40m --seed 3 --out out/t_40_front.png & wait) 2>&1 | tail -5

# output:
colours used: 28 palette: 31
colours used: 20 palette: 31

cd ~/work/pixelart-studies/pedagogy/observation && python3 -c "
from PIL import Image
im=Image.open('out/t_40_front.png')
im.crop((480,110,720,250)).resize((960,560),Image.NEAREST).save('out/t_40_zoom.png')"

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/observation && grep -n "bfrom" tarn.py | head; grep -n "def ao" -A 5 tarn.py; grep -n "occ = np.clip(1 - (hgt" tarn.py

# output:
130:        self.bfrom = norm(np.array([-sh[0] * 0.6, -1.0, -sh[2] * 0.6]))   # direction bounce light travels FROM (below, far side)
370:        bnc = np.clip(n @ (-self.bfrom), 0, 1) * ao
374:        return col, dict(vis=vis, ao=ao, ndl=ndl, trans=trans, bnc=np.clip(n @ (-self.bfrom), 0, 1))
220:    def ao(self, p, n):
221-        occ = np.zeros(p.shape[:-1]); sc = 1.0; s = max(self.a, 0.8)
222-        for dd in (0.04, 0.1, 0.2, 0.35, 0.55):
223-            occ += (dd * s - self.scene_sdf(p + n * dd * s)) * sc; sc *= 0.7
224-        return np.clip(1 - 1.4 * occ / s, 0, 1)
225-
633:        occ = np.clip(1 - (hgt / (0.3 * sc.a + 1e-6)), 0, 1) * 0.8 + (1 - ao) * 1.2

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("tarn.py").read()
s = s.replace("        self.bfrom = norm(np.array([-sh[0] * 0.6, -1.0, -sh[2] * 0.6]))   # direction bounce light travels FROM (below, far side)",
              "        self.bto = norm(np.array([-sh[0] * 0.6, -1.0, -sh[2] * 0.6]))   # unit vector TOWARD the bounce source: below, away from the sun")
s = s.replace("        bnc = np.clip(n @ (-self.bfrom), 0, 1) * ao", "        bnc = np.clip(n @ self.bto, 0, 1) * ao")
s = s.replace("bnc=np.clip(n @ (-self.bfrom), 0, 1))", "bnc=np.clip(n @ self.bto, 0, 1))")
s = s.replace("        occ = np.zeros(p.shape[:-1]); sc = 1.0; s = max(self.a, 0.8)", "        occ = np.zeros(p.shape[:-1]); sc = 1.0; s = max(self.a, 0.3)")
s = s.replace("        occ = np.clip(1 - (hgt / (0.3 * sc.a + 1e-6)), 0, 1) * 0.8 + (1 - ao) * 1.2", "        occ = np.clip(1 - (hgt / (0.22 * sc.a + 1e-6)), 0, 1) * 0.8 + (1 - ao) * 0.6")
s = s.replace("        v = v + 0.22 * min(1.0, scale) * g", "        v = v + 0.12 * min(1.0, scale) * g")
# grass: broad lit/shadow zones; stipple only in the transition (Ferrari: families in zones)
s = s.replace('''        t = self.grass_light()
        lit = m & (t > rng.uniform(size=(H, W)))''', '''        t = self.grass_light()
        ts = smoothstep(0.3, 0.7, t)
        lit = m & (ts > rng.uniform(size=(H, W)))''')
# terrain: add bank-scale hummocks (3-4 m) so the near bank has masses
s = s.replace('''            t = fbm2(x * 0.8, z * 0.8, self.seed + 11, 3)''', '''            t = fbm2(x * 0.8, z * 0.8, self.seed + 11, 3) + 1.4 * fbm2(x * 0.28, z * 0.28, self.seed + 13, 2)''')
open("tarn.py", "w").write(s)
EOF
(OMP_NUM_THREADS=2 nice -n 10 python3 tarn.py --size large --light back --distance close --seed 2 --out out/t_close_back.png & OMP_NUM_THREADS=2 nice -n 10 python3 tarn.py --size small --light front --distance 40m --seed 3 --out out/t_40_front.png & wait) 2>&1 | tail -3

# output:
colours used: 28 palette: 31
colours used: 20 palette: 31

cd ~/work/pixelart-studies/pedagogy/observation && OMP_NUM_THREADS=4 nice -n 10 python3 -c "
import tarn, numpy as np
sc=tarn.Scene('large','back','close',2); o=tarn.observe(sc)
m=o['mat']==tarn.ROCK
print('rock px',m.sum())
for k in ('vis','ao','ndl','bnc','hgt'): print(k, np.percentile(o[k][m],[5,25,50,75,95]).round(2))
print('ny', np.percentile(o['nrm'][...,1][m],[5,25,50,75,95]).round(2))
print('bto', sc.bto, 'sun', sc.sun)
"

# output:
rock px 13909
vis [0.   0.   0.   0.   0.04]
ao [0.65 0.82 0.9  0.99 1.  ]
ndl [0. 0. 0. 0. 0.]
bnc [0.   0.   0.   0.12 0.29]
hgt [0.27 0.61 0.93 1.27 1.63]
ny [0.14 0.31 0.39 0.48 0.78]
bto [ 0.09478966 -0.85749293 -0.50568844] sun [-0.18367003  0.0784591   0.97985177]

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("tarn.py").read()
s = s.replace("self.bto = norm(np.array([-sh[0] * 0.6, -1.0, -sh[2] * 0.6]))", "self.bto = norm(np.array([-sh[0] * 0.85, -0.6, -sh[2] * 0.85]))")
s = s.replace("        shd = 2.0 + 1.0 * np.clip((bnc - 0.3) / 0.35, 0, 1)\n        shd = np.maximum(shd, 2.0 + 2.0 * np.clip((n[..., 1] - 0.45) / 0.4, 0, 1) * 0.95)   # sky-lit tops",
              "        shd = 2.0 + 1.0 * np.clip((bnc - 0.12) / 0.4, 0, 1)\n        shd = np.maximum(shd, 2.0 + 2.0 * np.clip((n[..., 1] - 0.45) / 0.4, 0, 1) * 0.95)   # sky-lit tops")
open("tarn.py", "w").write(s)
EOF
grep -n "shd = 2.0" tarn.py; OMP_NUM_THREADS=4 nice -n 10 python3 tarn.py --size large --light back --distance close --seed 2 --out out/t_close_back.png

# output:
630:        shd = 2.0 + 1.0 * np.clip((bnc - 0.12) / 0.4, 0, 1)
colours used: 28 palette: 31

cd ~/work/pixelart-studies/pedagogy/observation && rm -rf out/cells && nice -n 10 python3 sheets.py > out/sheets.log 2>&1; tail -5 out/sheets.log

# output:
Command running in background with ID: bgbk0e8dt. Output is being written to: (tmp) You will be notified when it completes. To check interim output, use Read on that file path.
Session cwd remains ~/work/pixelart-studies/moodboards; directory changes made by the backgrounded command do not apply to subsequent commands.

cd ~/work/pixelart-studies/pedagogy/observation && cat > compare_stats.py <<'EOF'
"""pixel statistics that describe 'how it is painted', for Ferrari's tarn and my cells:
 colours per 8x8 tile (Ferrari's grass: 3-4 locally), isolated-pixel fraction (salt-and-pepper),
 mean horizontal / vertical run length, and total colours."""
import sys, glob, numpy as np
from PIL import Image
def stats(a):
    a = a.astype(np.int32); key = a[..., 0] * 65536 + a[..., 1] * 256 + a[..., 2]
    H, W = key.shape
    tiles = [len(np.unique(key[y:y + 8, x:x + 8])) for y in range(0, H - 7, 8) for x in range(0, W - 7, 8)]
    c = key[1:-1, 1:-1]
    iso = (c != key[:-2, 1:-1]) & (c != key[2:, 1:-1]) & (c != key[1:-1, :-2]) & (c != key[1:-1, 2:])
    def runs(k):
        L = []
        for r in k:
            ch = np.nonzero(r[1:] != r[:-1])[0]; L += list(np.diff(np.r_[-1, ch, len(r) - 1]))
        return np.mean(L)
    return dict(colours=len(np.unique(key)), tile_cols=np.mean(tiles), isolated=iso.mean(), hrun=runs(key), vrun=runs(key.T))
if __name__ == "__main__":
    f = np.array(Image.open("ferrari/native.png").convert("RGB"))
    print("%-40s" % "ferrari (native 634x469)", {k: round(float(v), 3) for k, v in stats(f).items()})
    for fn in sorted(glob.glob(sys.argv[1] if len(sys.argv) > 1 else "out/cells/*.png"))[:40]:
        a = np.array(Image.open(fn).convert("RGB"))
        print("%-40s" % fn.split("/")[-1], {k: round(float(v), 3) for k, v in stats(a).items()})
EOF
sleep 1; ls out/cells 2>/dev/null | head

# output:
medium_left_10m_s1.png
small_left_10m_s1.png
small_left_10m_s2.png
small_left_10m_s3.png

cd ~/work/pixelart-studies/pedagogy/observation && python3 -c "
from PIL import Image
im=Image.open('out/cells/small_left_10m_s1.png'); im.resize((960,540),Image.NEAREST).save('out/peek.png')"

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/observation && for i in $(seq 1 55); do [ -f out/sheet_seed.png ] && break; sleep 10; done; cat out/sheets.log; ls out/cells | wc -l

# output:
wrote size
wrote light
wrote distance
wrote seed
      36

cd ~/work/pixelart-studies/pedagogy/observation && python3 -c "
from PIL import Image
for n in ['size','light','distance','seed']:
  im=Image.open(f'out/sheet_{n}.png'); w,h=im.size; im.resize((w*2//5,h*2//5),Image.LANCZOS).save(f'out/sheet_{n}_small.png'); print(n,w,h)"

# output:
size 3072 1692
light 3072 2246
distance 3072 1692
seed 3072 2246

cd ~/work/pixelart-studies/pedagogy/observation && grep -n "def grass_light" -A 6 tarn.py; grep -n "ndc = 0.22" tarn.py; grep -n "self.z1 =" tarn.py; grep -n "tree_density=0.5" tarn.py

# output:
667:    def grass_light(self):
668-        o = self.o
669-        t = np.clip(o["vis"] * (0.1 + 1.1 * o["ndl"]) / 0.75, 0, 1)
670-        t = np.maximum(t, np.clip(o["trans"] * 1.3, 0, 1))
671-        return t
672-
673-    def paint_grass(self):
108:        ndc = 0.22 + rng.uniform(-0.05, 0.05)
111:        self.z1 = max(3.0, 0.3 * self.D)                   # near bank lip
91:    def __init__(self, size="medium", light="left", distance="10m", seed=0, tree_density=0.5):

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("tarn.py").read()
s = s.replace('''        t = np.clip(o["vis"] * (0.1 + 1.1 * o["ndl"]) / 0.75, 0, 1)''', '''        # grass is a volume of near-vertical blades: where the sun reaches it at all it is lit
        # (r23: lit vs shadow grass is decided by cast shadows, not by the ground's tilt); the
        # tussock slope facing the sun adds to it
        t = np.clip(o["vis"] * (0.45 + 1.2 * o["ndl"]), 0, 1)''')
s = s.replace("        ndc = 0.22 + rng.uniform(-0.05, 0.05)", "        ndc = rng.uniform(0.12, 0.32)")
s = s.replace("        self.z1 = max(3.0, 0.3 * self.D)                   # near bank lip", "        self.z1 = 3.0 + 0.1 * self.D + rng.uniform(-0.3, 0.6)   # near bank lip")
s = s.replace('''def __init__(self, size="medium", light="left", distance="10m", seed=0, tree_density=0.5):''', '''def __init__(self, size="medium", light="left", distance="10m", seed=0, tree_density=None):''')
s = s.replace('''        self.tree_density = tree_density''', '''        self.tree_density = rng.uniform(0.3, 0.7) if tree_density is None else tree_density''')
# emergent sedge in the shallows (r19), painted after the water, before the bank grass
s = s.replace('''        self.paint_water()
        self.paint_rock()
        self.paint_grass()''', '''        self.paint_water()
        self.paint_sedge()
        self.paint_rock()
        self.paint_grass()''')
s = s.replace('''    # -- water (study C) -----------------------------------------------------------------------''', '''    # -- emergent sedge in the shallows (observed r19: blades standing out of the water near the
    #    lip, each with a darker, broken reflection hanging below its root) --------------------
    def paint_sedge(self):
        o = self.o; sc = self.sc; m = o["mat"] == WATER; rng = self.rng; I = self.I
        if not m.any(): return
        P = o["pos"]; bf = sc.bank_field(P[..., 0], P[..., 2])
        shallow = m & (bf > -0.9) & (bf < -0.08)
        clump = fbm2(P[..., 0] * 1.3, P[..., 2] * 1.3, sc.seed + 90, 2) > 0.25
        ys, xs = np.nonzero(shallow & clump & (rng.uniform(size=(H, W)) < 0.10))
        depth = o["depth"]; mat = o["mat"]; pix_ang = HFOV / W; img = self.img
        lit_side = not sc.back
        for y, x in zip(ys, xs):
            n = int(np.clip(0.45 / depth[y, x] / pix_ang * rng.uniform(0.5, 1.1), 2, 16))
            run = int(rng.choice([3, 4, 6, 0])); direc = -1 if rng.uniform() < 0.5 else 1
            body = I("g_dk"); tip = I("g_tan") if (lit_side and rng.uniform() < 0.55) else I("g_dol")
            xx = x; posr = 0
            for k in range(n):
                yy = y - k
                if yy < 0 or xx < 0 or xx >= W: break
                if depth[yy, xx] < depth[y, x] - 0.05: break
                img[yy, xx] = tip if k > n * 0.55 else body
                posr += 1
                if run and posr >= run: xx += direc; posr = 0
            # reflection: straight down, darker, broken by ripples
            for k in range(1, int(n * 0.8)):
                yy = y + k
                if yy >= H or not m[yy, x]: break
                if rng.uniform() < 0.75: img[yy, x] = I("g_blk") if k < n * 0.4 else I("g_dk")

    # -- water (study C) -----------------------------------------------------------------------''')
open("tarn.py", "w").write(s)
EOF
(OMP_NUM_THREADS=2 nice -n 10 python3 tarn.py --size medium --light left --distance 40m --seed 1 --out out/t_40_left.png & OMP_NUM_THREADS=2 nice -n 10 python3 tarn.py --size medium --light front --distance 10m --seed 2 --out out/t_10_front.png & wait) 2>&1 | tail -3

# output:
colours used: 24 palette: 31
colours used: 24 palette: 31

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("tarn.py").read()
old = '''    def shade(self, p, mat, n, vdir):
        vis = self.soft_shadow(p, n); ao = self.ao(p, n)'''
new = '''    def shade(self, p, mat, n, vdir):
        # grass: test the sun from the blade tops (~0.2 m up), not the soil -- low sun still
        # reaches the tops of the grass on the far side of a hummock (lit tops, dark hollows)
        lift = np.where(mat == 2, 0.0, 0.2)[..., None] * np.array([0, 1.0, 0])
        vis = self.soft_shadow(p + lift, n); ao = self.ao(p, n)'''
assert old in s
s = s.replace(old, new)
open("tarn.py", "w").write(s)
EOF
(OMP_NUM_THREADS=2 nice -n 10 python3 tarn.py --size medium --light left --distance 40m --seed 1 --out out/t_40_left.png & OMP_NUM_THREADS=2 nice -n 10 python3 tarn.py --size medium --light front --distance 10m --seed 2 --out out/t_10_front.png & wait) 2>&1 | tail -3

# output:
colours used: 24 palette: 31
colours used: 24 palette: 31

cd ~/work/pixelart-studies/pedagogy/observation && OMP_NUM_THREADS=4 nice -n 10 python3 -c "
import tarn, numpy as np
sc=tarn.Scene('medium','front','10m',2); o=tarn.observe(sc)
m=o['mat']==tarn.GRASS
for k in ('vis','ao','ndl','trans'): print(k, np.percentile(o[k][m],[5,25,50,75,95]).round(3))
print('sun',sc.sun)
p=o['pos'][m][:5]; print(p)
"

# output:
vis [0.23  0.246 0.258 0.265 0.274]
ao [0.72  0.726 0.731 0.741 0.791]
ndl [0.    0.    0.088 0.17  0.436]
trans [0.109 0.139 0.168 0.188 0.204]
sun [ 0.11440577  0.0784591  -0.990331  ]
[[ 9.25045878  0.29742765 15.93326033]
 [ 8.76913883  0.37427542 15.01026311]
 [ 8.40234212  0.3015117  15.22573928]
 [ 8.43057745  0.30571998 15.17693462]
 [ 8.45336982  0.31071969 15.11902484]]

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("tarn.py").read()
s = s.replace("            res = np.minimum(res, 10.0 * h / t)\n            t = t + np.clip(h, 0.04, 1.5)\n            if np.all((t > 50) | (res < 0.02)): break",
              "            res = np.minimum(res, 40.0 * h / t)\n            t = t + np.clip(h, 0.04, 1.5)\n            if np.all((t > 50) | (res < 0.02)): break")
s = s.replace("trans = np.where(rock, 0, np.clip(-(vdir @ self.sun), 0, 1) ** 3 * vis * 0.9)", "trans = np.where(rock, 0, np.clip(vdir @ self.sun, 0, 1) ** 3 * vis * 0.9)")
open("tarn.py", "w").write(s)
EOF
grep -n "40.0 \* h / t\|vdir @ self.sun" tarn.py; (OMP_NUM_THREADS=2 nice -n 10 python3 tarn.py --size medium --light left --distance 40m --seed 1 --out out/t_40_left.png & OMP_NUM_THREADS=2 nice -n 10 python3 tarn.py --size medium --light front --distance 10m --seed 2 --out out/t_10_front.png & wait) 2>&1 | tail -3

# output:
215:            res = np.minimum(res, 40.0 * h / t)
375:        trans = np.where(rock, 0, np.clip(vdir @ self.sun, 0, 1) ** 3 * vis * 0.9)
colours used: 27 palette: 31
colours used: 24 palette: 31

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("tarn.py").read()
s = s.replace("        lit = 3.8 + 1.3 * np.clip((lit_amt - 0.08) / 0.32, 0, 1) ** 0.6", "        lit = 3.8 + 1.3 * np.clip((lit_amt - 0.08) / 0.55, 0, 1) ** 0.75")
s = s.replace("        lift = np.where(mat == 2, 0.0, 0.2)[..., None] * np.array([0, 1.0, 0])", "        lift = np.where(mat == 2, 0.0, 0.12)[..., None] * np.array([0, 1.0, 0])")
s = s.replace('''        base = np.where(lit & (r > 0.84), I("g_tan"), base)''', '''        base = np.where(lit & (r > 0.91), I("g_tan"), base)''')
s = s.replace('''            gap = rng.uniform() < 0.3 and Lp >= 3''', '''            gap = rng.uniform() < 0.34 and Lp >= 3''')
s = s.replace('''                    c_body = I("g_tan") if rng.uniform() < 0.5 else I("g_ochre"); c_tip = I("g_tan")''', '''                    c_body = I("g_ochre") if rng.uniform() < 0.75 else I("g_mid"); c_tip = I("g_tan") if rng.uniform() < 0.7 else I("g_ochre")''')
s = s.replace("                img[yy, xx] = c_tip if k >= n * 0.45 else c_body", "                img[yy, xx] = c_tip if k >= n * 0.6 else c_body")
open("tarn.py", "w").write(s)
EOF
(OMP_NUM_THREADS=2 nice -n 10 python3 tarn.py --size medium --light left --distance 40m --seed 1 --out out/t_40_left.png & OMP_NUM_THREADS=2 nice -n 10 python3 tarn.py --size medium --light front --distance 10m --seed 2 --out out/t_10_front.png & wait) 2>&1 | tail -3

# output:
colours used: 27 palette: 31
colours used: 24 palette: 31

cd ~/work/pixelart-studies/pedagogy/observation && rm -rf out/cells && nice -n 10 python3 sheets.py > out/sheets.log 2>&1; cat out/sheets.log | tail -4; python3 -c "
from PIL import Image
for n in ['size','light','distance','seed']:
  im=Image.open(f'out/sheet_{n}.png'); w,h=im.size; im.resize((w*2//5,h*2//5),Image.LANCZOS).save(f'out/sheet_{n}_small.png')"

# output:
wrote size
wrote light
wrote distance
wrote seed

cd ~/work/pixelart-studies/pedagogy/observation && ls out/cells | head -40 && python3 -c "
from PIL import Image
im=Image.open('out/cells/medium_left_close_s1.png'); im.crop((100,40,260,140)).resize((960,600),Image.NEAREST).save('out/zoom_close.png')"

# output:
large_left_10m_s1.png
large_left_10m_s2.png
large_left_10m_s3.png
medium_back_10m_s1.png
medium_back_10m_s11.png
medium_back_10m_s12.png
medium_back_10m_s13.png
medium_back_10m_s14.png
medium_back_10m_s2.png
medium_back_10m_s3.png
medium_front_10m_s1.png
medium_front_10m_s2.png
medium_front_10m_s3.png
medium_left_10m_s1.png
medium_left_10m_s11.png
medium_left_10m_s12.png
medium_left_10m_s13.png
medium_left_10m_s14.png
medium_left_10m_s2.png
medium_left_10m_s3.png
medium_left_40m_s1.png
medium_left_40m_s2.png
medium_left_40m_s3.png
medium_left_close_s1.png
medium_left_close_s2.png
medium_left_close_s3.png
medium_right_10m_s1.png
medium_right_10m_s11.png
medium_right_10m_s12.png
medium_right_10m_s13.png
medium_right_10m_s14.png
medium_right_10m_s2.png
medium_right_10m_s3.png
small_left_10m_s1.png
small_left_10m_s2.png
small_left_10m_s3.png

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("tarn.py").read()
old = '''        z[rim] = 6
        # contact: lowest boulder pixel in each column touching grass -> darkest'''
new = '''        z[rim] = 6
        # surface texture: short vertical flecks (1x2, 1x3) of the neighbouring value, running down
        # the fall line -- granite grain / weathering flutes. Ferrari's rock planes are never one
        # flat colour; each carries flecks of the next value. Density grows with size on screen.
        if npx > 250:
            dens = 0.05 + 0.07 * min(1.0, scale)
            seeds_ = m & (self.rng.uniform(size=(H, W)) < dens) & (z >= 3) & (z <= 5)
            ys_, xs_ = np.nonzero(seeds_)
            for y_, x_ in zip(ys_, xs_):
                zz = z[y_, x_]; nz = zz - 1 if (zz == 5 or self.rng.uniform() < 0.6) else zz + 1
                for k in range(int(self.rng.integers(1, 4))):
                    if y_ + k < H and m[y_ + k, x_] and z[y_ + k, x_] == zz: z[y_ + k, x_] = nz
        # contact: lowest boulder pixel in each column touching grass -> darkest'''
assert old in s
s = s.replace(old, new)
open("tarn.py", "w").write(s)
EOF
OMP_NUM_THREADS=4 nice -n 10 python3 tarn.py --size medium --light left --distance close --seed 1 --out out/t_close_left.png && python3 -c "
from PIL import Image
im=Image.open('out/t_close_left.png'); im.crop((300,120,780,420)).resize((960,600),Image.NEAREST).save('out/zoom_close.png')"

# output:
colours used: 27 palette: 31

cd ~/work/pixelart-studies/pedagogy/observation && sed -i '' 's/            dens = 0.05 + 0.07 \* min(1.0, scale)/            dens = 0.03 + 0.045 * min(1.0, scale)/' tarn.py && grep -n "dens = 0.03" tarn.py && rm -rf out/cells && nice -n 10 python3 sheets.py > out/sheets.log 2>&1; tail -4 out/sheets.log; python3 -c "
from PIL import Image
for n in ['size','light','distance','seed']:
  im=Image.open(f'out/sheet_{n}.png'); w,h=im.size; im.resize((w*2//5,h*2//5),Image.LANCZOS).save(f'out/sheet_{n}_small.png')"

# output:
668:            dens = 0.03 + 0.045 * min(1.0, scale)
wrote size
wrote light
wrote distance
wrote seed

cd ~/work/pixelart-studies/pedagogy/observation && python3 - <<'EOF'
s = open("tarn.py").read()
old = '''        t = np.clip(o["vis"] * (0.45 + 1.2 * o["ndl"]), 0, 1)
        t = np.maximum(t, np.clip(o["trans"] * 1.3, 0, 1))
        return t'''
new = '''        t = np.clip(o["vis"] * (0.45 + 1.2 * o["ndl"]), 0, 1)
        # but we only see the lit side of a blade when the sun is not ahead of us: facing the sun,
        # the grass shows its shadowed side and only the tips glow (translucency, painted as tips)
        fwd = self.sc.basis()[0]; fh = np.array([fwd[0], 0, fwd[2]]); fh /= np.linalg.norm(fh)
        sh = np.array([self.sc.sun[0], 0, self.sc.sun[2]]); sh /= np.linalg.norm(sh)
        facing = np.clip(0.6 - 0.75 * float(fh @ sh), 0, 1)
        return t * facing'''
assert old in s; s = s.replace(old, new)
old2 = '''                if fam_lit:
                    c_body = I("g_ochre") if rng.uniform() < 0.75 else I("g_mid"); c_tip = I("g_tan") if rng.uniform() < 0.7 else I("g_ochre")
                    if t[y, x] > 0.85 and rng.uniform() < 0.4: c_tip = I("g_crest")
                else:
                    c_body = I("g_dk"); c_tip = I("g_dol")'''
new2 = '''                if fam_lit:
                    c_body = I("g_ochre") if rng.uniform() < 0.75 else I("g_mid"); c_tip = I("g_tan") if rng.uniform() < 0.7 else I("g_ochre")
                    if t[y, x] > 0.85 and rng.uniform() < 0.4: c_tip = I("g_crest")
                else:
                    c_body = I("g_dk"); c_tip = I("g_dol")
                    if o["trans"][y, x] > 0.25 and rng.uniform() < 0.7:      # back-lit: glowing tips
                        c_tip = I("g_crest") if rng.uniform() < 0.4 else I("g_tan")'''
assert old2 in s; s = s.replace(old2, new2)
s = s.replace("            jag = 0.010 * fbm2(az * 45 + layer * 7, np.full_like(az, 0.3), self.seed + 46 + layer, 3)",
              "            jag = 0.016 * fbm2(az * 40 + layer * 7, np.full_like(az, 0.3), self.seed + 46 + layer, 4)")
s = s.replace("        for layer, n, el_rng in ((0, 6, (0.075, 0.12)), (1, 7, (0.05, 0.085)), (2, 8, (0.028, 0.055))):",
              "        for layer, n, el_rng in ((0, 9, (0.07, 0.12)), (1, 10, (0.045, 0.085)), (2, 11, (0.025, 0.055))):")
open("tarn.py", "w").write(s)
EOF
OMP_NUM_THREADS=4 nice -n 10 python3 tarn.py --size medium --light back --distance 10m --seed 14 --out out/t_back14.png

# output:
colours used: 28 palette: 31

cd ~/work/pixelart-studies/pedagogy/observation && rm -rf out/cells && nice -n 10 python3 sheets.py > out/sheets.log 2>&1; tail -4 out/sheets.log; python3 -c "
from PIL import Image
for n in ['size','light','distance','seed']:
  im=Image.open(f'out/sheet_{n}.png'); w,h=im.size; im.resize((w*2//5,h*2//5),Image.LANCZOS).save(f'out/sheet_{n}_small.png')"

# output:
wrote size
wrote light
wrote distance
wrote seed

cd ~/work/pixelart-studies/pedagogy/observation && python3 compare_stats.py "out/cells/medium_*_10m_s1.png"; python3 compare_stats.py "out/cells/medium_left_*_s2.png" | tail -3; python3 -c "
from PIL import Image
f=Image.open('ferrari/native.png').convert('RGB').crop((150,230,470,410))
m=Image.open('out/cells/medium_left_10m_s2.png').convert('RGB')
out=Image.new('RGB',(320*3*2+12,180*3),'white')
out.paste(f.resize((960,540),Image.NEAREST),(0,0)); out.paste(m.resize((960,540),Image.NEAREST),(972,0)); out.save('out/compare_ferrari_vs_mine.png')"

# output:
ferrari (native 634x469)                 {'colours': 172.0, 'tile_cols': 4.686, 'isolated': 0.196, 'hrun': 1.728, 'vrun': 2.048}
medium_back_10m_s1.png                   {'colours': 28.0, 'tile_cols': 4.326, 'isolated': 0.197, 'hrun': 1.916, 'vrun': 2.075}
medium_front_10m_s1.png                  {'colours': 27.0, 'tile_cols': 4.734, 'isolated': 0.17, 'hrun': 2.0, 'vrun': 2.181}
medium_left_10m_s1.png                   {'colours': 27.0, 'tile_cols': 4.759, 'isolated': 0.17, 'hrun': 1.978, 'vrun': 2.206}
medium_right_10m_s1.png                  {'colours': 27.0, 'tile_cols': 4.569, 'isolated': 0.157, 'hrun': 2.057, 'vrun': 2.251}
medium_left_10m_s2.png                   {'colours': 27.0, 'tile_cols': 4.677, 'isolated': 0.185, 'hrun': 1.881, 'vrun': 2.128}
medium_left_40m_s2.png                   {'colours': 25.0, 'tile_cols': 5.144, 'isolated': 0.238, 'hrun': 1.661, 'vrun': 1.878}
medium_left_close_s2.png                 {'colours': 27.0, 'tile_cols': 4.52, 'isolated': 0.189, 'hrun': 1.934, 'vrun': 2.167}

# Observation first, then translation: a boulder at a tarn, at dusk

Everything here lives in `~/work/pixelart-studies/pedagogy/observation/`.

| what | where |
|---|---|
| reference photos (28, with credits) | `refs/r01..r28*.jpg`, `refs/credits.tsv` (candidates in `refs/cand*/`) |
| value block-ins of the photos | `studies/blockin_*.png` (made by `blockin.py`) |
| measured light profiles | `studies/measurements.png` (made by `studies_profiles.py`) |
| Ferrari at native size, and zoomed crops | `ferrari/native.png`, `ferrari/*.png`; contour stats in `ferrari_contours.py` |
| translation studies: photo, Ferrari, mine, at 8x | `studies/translate_{A..E}.png` (made by `translate_studies.py`, primitives in `pix.py`) |
| the method | `tarn.py` (the first, abandoned attempt is kept as `tarn_v1_first_attempt.py`) |
| parameter sheets | `out/sheet_size.png`, `sheet_light.png`, `sheet_distance.png`, `sheet_seed.png` (made by `sheets.py`) |
| pixel statistics, and my cell next to Ferrari | `compare_stats.py`, `out/compare_ferrari_vs_mine.png` |

Commands: `nice -n 10 python3 tarn.py --size large --light back --distance close --seed 3`
and `nice -n 10 python3 sheets.py` (4 worker processes, one thread each).

---

## 1. The photographs

Wikimedia Commons is poor for "boulder at a tarn at dusk" as one photo. I split the subject into
its parts and gathered each one separately. These are the ones I actually used:

- **Light wrapping granite, sun low from the left:** r01–r05 (Joshua Tree, public domain);
  r07–r09 (Monsanto granite at dusk under a violet sky).
- **A boulder's foot in grass, the contact:** r10 (boulder by Lochan na h-Earba, with an undercut
  at its foot), r13 (an erratic sitting in a lawn).
- **Boulders at still water, and their reflections:** r16, r18 (a stone in flat water), r19
  (Blea Tarn: a boulder at the lip of a grass bank, reflected, with sedge coming out of the water).
- **Grass banks and tussocks against water, and grass in low sun:** r20, r22, r23.
- **Dusk water carrying the sky:** r21, r24, r25 (Lake Cerknica, pink over violet).
- **Distance:** r11 and r12 (the same kind of boulder at 30–60 m on a moor).

## 2. What is actually there

Numbers are CIE L* sampled from the photos (`studies/measurements.png`, and point samples logged
in the session).

### Light on a rounded boulder (r02, r19, r10)

- **The lit side is a plateau, not a gradient.** Along a scanline in r02 the lit face holds at
  L*≈60–80 across most of its width. Rough granite scatters light broadly, so its lit side looks
  flatter than a Lambert sphere.
- **The terminator is a cliff.** L* drops from about 60 to 25 within a few percent of the
  boulder's width, and just past the drop there is a **core band** that is darker than the rest
  of the shadow side (terminator L*≈25, shadow side further round L*≈37 in r02).
- **The shadow side is lit by bounce and is warm.** Its far part picks up light again from the
  lit ground (r02: from L*≈25 back up to 37, and more orange). At dusk the sky is also a light:
  upward-facing planes in shadow turn violet and lighter.
- **Contact.** The darkest value in the whole boulder sits at the line where it meets the ground
  (r02 crevice L*≈33 against a lit face at 58; r19 contact L*≈31 against a lit top at 60). Where
  the rock overhangs (r10), the pocket underneath is the darkest thing in the picture.
- **The cast shadow** of a 4–5° sun is very long. Low grass inside it goes dark olive and loses
  its warm highlights, which makes it a different colour family, not just a darker version.

### Grass masses (r20, r22, r23)

- Grass is a **volume of near-vertical blades**. With low sun, what decides lit versus shadow
  grass is cast shadow, not the tilt of the ground: a whole tussock can be lit on a slope that
  faces away from the sun.
- Light collects on **crests**: the top edge of every mass and its sun-facing shoulder. The base
  and the body sink into shadow (r20 block-in: tussock tops at L*≈50–65, bodies at 18–30).
- **Texture has a direction and changes with depth.** I measured the ratio of horizontal to
  vertical gradient: in r22 it rises from 1.1 (isotropic) in the distance to 1.45 in the
  foreground. Near grass reads as vertical strokes. Far grass reads as stipple.
- **Facing the sun**, you see the shadowed side of each blade, with glowing tips from light
  shining through them.

### Where the bank meets the water, and reflections (r19, r25, r18)

- **Reflections are darker than what they reflect.** Sky mid band L*=86 against its reflection
  at 55; hill 19 against 12.5; boulder shadow side 28 against 15 (r19); stone 11 against 5 (r18).
  Water is a Fresnel mirror, and near the viewer it shows the dark water body.
- **Reflections show the underside.** You look down at the bank and the mirror looks up at it,
  so the reflection is shorter and made mostly of the shadowed faces.
- **At the far waterline there is a light line**, the water right at the edge reflecting sky at
  a grazing angle (a spike in the r25 profile). **Right under a near grass lip it is dark**
  (overhang shadow).
- **Still water is broken into horizontal streaks** by faint ripples and wind-lines, which
  reflect a slightly higher, lighter part of the sky.

### Distance (r11, r12; resampling in `measurements.png` panel D)

- A 2 m boulder at 40 m is about 6 px tall at this camera. At 10 px it still has light side,
  shadow side and contact. At 4 px it is two values and a dark base.
- Aerial perspective at dusk pushes far things toward the violet-pink of the horizon sky. The far
  treeline stays nearly black because it is backlit or in shadow.

### Value structure (`studies/blockin_*.png`)
The 2-value notan of every dusk photo is the same: **the sky and the water that mirrors it form
the light family; all land forms the dark family.** Inside the land, only sun-struck planes rise
into the middle values. This became the palette's first constraint.

## 3. How Ferrari translates these things

Measured on `ferrari/native.png`: the supplied PNG is his image at 2× pixel scale, so native
resolution is 634×469 with 172 colours.

- **Grass: one 3-colour family per lighting zone.** In the near-left lit grass, four colours make
  up 99% of the pixels: ochre base (48%), tan blades (32%), dark-green gaps (16%). In the
  shadowed near-right grass it is black (49%), dark olive (25%), darker olive (25%). The shadow
  zone is **a different family**, which matches the photos: cast-shadowed grass is not lit grass
  made darker.
- **Blades are 1-px lines** made of vertical runs averaging about 3 px, with horizontal runs of
  1.5 px (`crop_grass_tips_on_water.png`). Near the tips they lean in equal steps.
- **Crest bands.** Each lit mass has a 1–3 px band of its lightest tan directly under the top
  contour, and the lit colour is then stippled down into the shadow body with falling density
  (`treebase.png`, `island8.png`).
- **Contours resolve into clean runs** (`ferrari_contours.py`). Along the mountain ridge, 57% of
  run–step pairs are exactly 45° (1,1) or 2:1 (2,1), and consecutive runs repeat their length
  54% of the time. The left bank lip is 90% consistent. He holds a slope's step pattern until
  the form turns.
- **Rock is flat planes with a lit lip.** The sun-facing ridges of the mountain facets carry the
  lightest salmon as a 1–2 px edge. Planes are one colour, flecked with the neighbouring value.
- **Stones at the waterline** (`stones8.png`) are three or four flat values, the darkest as a line
  underneath. Their reflections are horizontal slabs one step darker.
- **Water and sky:** flat bands of adjacent ramp colours joined by 50% checkerboard strips.
  Reflections of things are horizontal runs, and light wind-lines cut across them.
- **Pixel statistics** (`compare_stats.py`): 4.7 colours per 8×8 tile, 20% isolated pixels,
  mean horizontal run 1.73 px, vertical run 2.05 px. The painting is dense with texture, but that
  texture sits inside a few large, clear shapes.

## 4. The translation studies (the step that made the method work)

My first program (`tarn_v1_first_attempt.py`) went straight from a physical render to palette
quantisation and blade scattering. It produced a smooth render that had been posterised, not a
painting (`out/t1.png`). After the critic's note, I went back and translated **one observed truth
at a time**, each shown beside its photo and beside Ferrari's nearest pixels at 8×:

- **D, light on a boulder** (`translate_D.png`). Painting each lighting zone as flat colour made
  cartoon cel-shading. The fix was a continuous ramp coordinate (1 contact, 2 core, 3 bounce
  shadow, 4 half/sky-lit top, 5 lit, 6 rim). The lit side and the shadow side get *separate
  ranges* with a jump between them, so dithering never crosses the terminator. Values dither only
  where they fall between colours, so planes stay flat, and the dither is clustered (2-px clumps),
  never salt-and-pepper. Added: a sun-side 1-px rim, a vertical weathering grain, a joint crack
  with a lit lip, and the darkest colour on the contact row.
- **A, the contact** (`translate_A.png`): the darkest line under the rock, a black undercut pocket
  on the shadow side, the cast shadow switching the grass to the shadow family, and tufts
  overlapping the rock's foot.
- **B, the lit top of a grass mass** (`translate_B.png`): contour through `clean_profile` (flat
  crest, 2:1 shoulders, 45° flanks), a crest band 3 px thick on the sun side thinning to 1 px,
  its lower edge notched, and the lit colour stippled downward. The first version drew a clean
  tan outline, which looked like a drawing, not grass.
- **C, the lip and its reflection** (`translate_C.png`): the reflection is mirrored and
  compressed, shifted one step darker, and resampled as 2–7 px horizontal runs. A light line
  marks the waterline at middle distance. A ragged edge fades the reflection into the sky-water.
  Wind-lines are solid 1-px strokes. Mirroring the bank's own dark lip line produced a doubled
  outline and had to be excluded.
- **E, near blades against water** (`translate_E.png`): each blade leans by runs that shorten
  toward the tip (5, 4, 3, 2, 1: a curve made only of clean steps). Gap strokes are short and
  vertical. Tan blades stand against the water.

The primitives these studies produced (`clean_profile`, `majority_clean`, clustered dither,
horizontal-run resampling, stroke blades) are what `tarn.py` uses.

## 5. The method (`tarn.py`)

**Stage 1, observe.** A small scene model at 320×180:

- a signed-distance granite corestone: a rounded box, tapered toward a dome, tilted, with broad
  weathering dents, optionally split by a joint, and sunk 22–36% into the bank;
- a bank heightfield with 3–4 m hummocks and 1 m tussocks;
- a near bank and a promontory lip, and the tarn out to a far shore 70–110 m away with conifers
  (mark-painted, heights in metres) and three layers of faceted peaks.

Light model: sun at 4.5°; sun colour warm orange; sky fill violet; bounce from lit grass,
arriving from below and away from the sun; soft shadows (grass visibility tested from the blade
tops); AO; blade translucency when back-lit. The water is a rippled Fresnel mirror that
ray-traces the scene again.

Output is a G-buffer: material, depth, normal, sun visibility, n·l, bounce, AO, height above
ground, what each water pixel reflects, and the wind-lines.

**Palette, 31 colours.** Every entry comes from the light model evaluated at a *canonical light
state*, so the palette is the observation, quantised deliberately:

- grass lit family: crest, tan, ochre, dark-green gap;
- grass shadow family: dark olive, darker olive, black; plus one mid tone for reflections;
- rock: contact, core, bounce shadow, sky-lit half, lit, rim;
- sky: 8 colours spaced evenly along the path from 35° down to the horizon;
- far: 4 colours, k-means of the mountains;
- water: 4 colours, the sky ramp darkened as Fresnel predicts;
- one accent (sun disk and glitter when back-lit, otherwise the hottest grass tip).

**Stage 2, translate.** Each material is painted with its study's vocabulary: sky bands with
checker strips; faceted mountains; mark-painted trees and far bank; water reflections as
horizontal runs one step darker, checker for mirrored sky, light and dark waterlines, solid
wind-lines; emergent sedge in the shallows (r19) with broken dark reflections; rock by ramp
coordinate with fall-line flecks, rim and contact. Grass is painted last: stippled family choice
from the light amount, crest bands on sun-facing tops, then 1-px blades far to near, depth-tested
so near tips overlap the water and the boulder's foot. Blade length is set by projecting 0.3 m
blades, which is how distance changes the grass from stroke to stipple, as observed.

**Parameters.** Size (1.1 / 1.9 / 2.9 m); light direction (sun azimuth −105°, 170°, +105°, −14°
relative to the view, so left and right are raking side-light); distance (5.5, 10, 40 m); seed
(boulder shape, dents, joint, sink depth, shoreline, bank position, tree density, peaks, ripples).

## 6. Honest comparison

**Against the photos, what carries over:**

- The dusk notan: sky and water light, land dark.
- The boulder's plateau-and-cliff light, with a core band, a warm bounce-lit shadow side, a
  sky-lit violet top, a sun-side rim and a black contact line (visible in the close row of
  `sheet_distance`).
- Reflections that are darker and show the underside. The back-lit row has the dark rock mass
  over a bright mirrored sky that r25 and r18 show.
- Lit versus shadow grass decided by cast shadows, and the view-dependent flip: facing the sun,
  the grass shows its shadowed side with glowing tips.
- Distance turning strokes into stipple, and the 40 m boulder shrinking to a few values, as in
  the resampling study.

**Against the photos, what is off:** the rock's surface is too clean at 10 m. Real granite at dusk
shows lichen mottling and a cooler, greyer hue than my salmon. The cast shadow of the boulder on
the grass is mostly hidden by the camera angle and rarely reads.

**Against Ferrari (`out/compare_ferrari_vs_mine.png`, same scale):**

- The micro-statistics now match closely: 4.3–4.8 colours per tile (his 4.7), 16–20% isolated
  pixels (his 20%), runs 1.9 × 2.1 px (his 1.7 × 2.0). Every cell uses 24–28 of 31 colours.
- **The biggest gap is structure, not texture.** His grass banks are big rounded masses, each
  split into a lit half and a shadow half with a crest band, and the whole picture is built from
  a few of those masses. My near grass is one even field, so the bottom third of every cell is
  texture with no shapes in it, and at 40 m this dominates the frame. The hummocks exist in my
  geometry, but at 4.5° sun and a 10° camera they barely change the lighting. Ferrari invents
  the masses. The next step is to paint the bank as designed masses: pick 2–4 mounds per cell,
  light them with the study-B recipe, and let the physical model decide only which side is lit.
- My water is a large, mostly flat violet area. His is full of the mirrored mountains and banks.
  My framing puts too much open water below the far shore and too little land around it.
- Contour cleaning is applied only to the far bank top and in the studies, not to the boulder
  silhouette or the grass masses in the full method.
- His palette is richer in the middle values, with more warm-to-violet steps in the land. Mine
  spends 8 entries on the sky, which is flatter than his.

**Were the sheets painted?** Yes at close range and at 10 m, especially the back-lit and raking
cells. The 40 m row is the weakest: it reads as a grass texture sample with a scene behind it.