The working thread

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

# output:
~/work/pixelart-studies/pedagogy/analysis/:
total 0
drwxr-xr-x  2 user  staff   64 Sep 25 18:02 .
drwxr-xr-x  7 user  staff  224 Sep 25 18:02 ..

~/work/pixelart-studies/pedagogy/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/shared && python3 -c "
from PIL import Image; import numpy as np
im=Image.open('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); print(len(c))
"; which python3; python3 -c "import scipy, sklearn, skimage; print('ok')"

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

cd ~/work/pixelart-studies/pedagogy/shared && nice -n 10 python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('ferrari_alpine_tarn_dusk.png').convert('RGB')).astype(int)
# horizontal run lengths
d=np.any(a[:,1:]!=a[:,:-1],axis=2)
runs=[]
for r in d[::7]:
    idx=np.flatnonzero(r); runs+=list(np.diff(idx))
print(np.bincount(runs)[:12])
d=np.any(a[1:]!=a[:-1],axis=2)
runs=[]
for r in d.T[::7]:
    idx=np.flatnonzero(r); runs+=list(np.diff(idx))
print(np.bincount(runs)[:12])
from collections import Counter
c=Counter(map(tuple,a.reshape(-1,3))); print(len(c)); print(c.most_common(10)); print(sorted(c.values())[:40])
"

# output:
[    0     0 35268     0  7235     0  3368     0  1296     0   621     0]
[    0     0 27053     0  5778     0  3112     0  1562     0   935     0]
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)]
[12, 24, 44, 48, 60, 72, 76, 88, 92, 100, 100, 104, 104, 112, 112, 116, 124, 132, 132, 132, 132, 136, 152, 156, 156, 164, 164, 168, 172, 176, 180, 184, 188, 192, 192, 192, 196, 200, 200, 208]

mkdir -p ~/work/pixelart-studies/pedagogy/analysis/{img,src,out} && cd ~/work/pixelart-studies/pedagogy/analysis && nice -n 10 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))
blk=np.all(a[...,:3]==0,axis=2); ys,xs=np.nonzero(blk); print(ys.min(),ys.max(),xs.min(),xs.max())
# phase check
for oy in (0,1):
  for ox in (0,1):
    s=a[oy::2,ox::2,:3]; 
    print(oy,ox, np.mean(np.any(a[oy:oy+2*((a.shape[0]-oy)//2):2, ox:ox+2*((a.shape[1]-ox)//2):2,:3]!=a[oy+1:oy+1+2*((a.shape[0]-oy-1)//2):2, ox:ox+2*((a.shape[1]-ox)//2):2,:3][:((a.shape[0]-oy)//2)] if False else 0)))
"


# output:
(array([255], dtype=uint8), array([1189384]))
0 937 0 1267
0 0 0.0
0 1 0.0
1 0 0.0
1 1 0.0

cd ~/work/pixelart-studies/pedagogy/analysis && nice -n 10 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)
H,W,_=a.shape
for oy in (0,1):
  for ox in (0,1):
    b=a[oy:,ox:]; h=(b.shape[0]//2)*2; w=(b.shape[1]//2)*2; b=b[:h,:w]
    m=(np.any(b[0::2,0::2]!=b[1::2,0::2],axis=2)|np.any(b[0::2,0::2]!=b[0::2,1::2],axis=2)|np.any(b[0::2,0::2]!=b[1::2,1::2],axis=2)).mean()
    print(oy,ox,m)
"


# output:
0 0 0.0
0 1 0.5779868430360048
1 0 0.4872671142387231
1 1 0.8133126746870822

cd ~/work/pixelart-studies/pedagogy/analysis && nice -n 10 python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('../shared/ferrari_alpine_tarn_dusk.png').convert('RGB'))
n=a[::2,::2]; Image.fromarray(n).save('img/00_native.png'); print(n.shape)
from collections import Counter
c=Counter(map(tuple,n.reshape(-1,3))); print(len(c))
import colorsys
rows=[]
for col,k in c.most_common():
    r,g,b=[x/255 for x in col]; L=0.2126*r**2.2+0.7152*g**2.2+0.0722*b**2.2
    h,l,s=colorsys.rgb_to_hls(r,g,b)
    rows.append((col,k,round(L**(1/2.2)*100),round(h*360),round(s*100)))
for r in rows[:60]: print(r)
"


# output:
(469, 634, 3)
172
((0, 0, 0), 57934, 0, 0, 0)
((136, 101, 50), 18310, 42, 36, 46)
((62, 59, 23), 15789, 23, 55, 46)
((196, 131, 70), 14037, 57, 29, 52)
((28, 31, 4), 13829, 12, 67, 77)
((207, 161, 186), 13065, 68, 327, 32)
((115, 92, 35), 11708, 37, 43, 53)
((46, 43, 32), 10248, 17, 47, 18)
((200, 165, 193), 8257, 69, 312, 24)
((66, 63, 42), 7501, 24, 52, 22)
((196, 134, 76), 6182, 58, 29, 50)
((213, 162, 179), 6111, 69, 340, 38)
((217, 162, 175), 6029, 69, 346, 42)
((25, 31, 4), 5991, 11, 73, 77)
((58, 55, 48), 5990, 22, 42, 9)
((224, 162, 175), 5612, 70, 347, 50)
((28, 31, 24), 5326, 12, 86, 13)
((106, 80, 40), 5133, 33, 36, 45)
((227, 162, 168), 4824, 70, 354, 54)
((235, 167, 165), 4319, 72, 2, 64)
((10, 34, 10), 3777, 12, 120, 55)
((235, 167, 161), 3633, 72, 5, 65)
((103, 84, 109), 3333, 35, 286, 13)
((68, 52, 74), 2764, 23, 284, 17)
((235, 170, 158), 2725, 73, 9, 66)
((87, 68, 43), 2717, 28, 34, 34)
((49, 39, 54), 2493, 17, 280, 16)
((28, 31, 20), 2340, 12, 76, 22)
((79, 60, 63), 2197, 25, 351, 14)
((239, 141, 114), 1874, 65, 13, 80)
((128, 85, 106), 1851, 38, 331, 20)
((68, 56, 74), 1663, 24, 280, 14)
((60, 63, 45), 1557, 24, 70, 17)
((178, 152, 188), 1508, 63, 283, 21)
((106, 80, 59), 1442, 33, 27, 28)
((236, 174, 155), 1388, 74, 14, 68)
((103, 80, 87), 1382, 34, 342, 13)
((173, 141, 165), 1252, 59, 315, 16)
((132, 93, 110), 1181, 41, 334, 17)
((194, 168, 186), 1116, 69, 318, 18)
((88, 72, 93), 825, 30, 286, 13)
((64, 48, 55), 812, 21, 334, 14)
((217, 166, 175), 790, 70, 349, 40)
((190, 164, 186), 781, 67, 309, 17)
((243, 175, 155), 773, 75, 14, 79)
((61, 48, 69), 723, 21, 277, 18)
((53, 40, 58), 679, 18, 283, 18)
((87, 68, 97), 666, 29, 279, 18)
((41, 32, 16), 664, 13, 38, 44)
((8, 11, 1), 654, 4, 78, 83)
((180, 144, 167), 651, 60, 322, 19)
((96, 80, 94), 647, 33, 308, 9)
((224, 192, 210), 632, 79, 326, 34)
((198, 152, 170), 630, 64, 337, 29)
((80, 64, 74), 604, 27, 322, 11)
((66, 48, 38), 589, 20, 21, 27)
((240, 178, 152), 580, 75, 18, 75)
((217, 159, 169), 572, 68, 350, 43)
((69, 51, 42), 563, 22, 20, 24)
((201, 154, 174), 563, 65, 334, 30)

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/util.py <<'EOF'
import numpy as np
from PIL import Image, ImageDraw, ImageFont
import os
HERE=os.path.dirname(os.path.abspath(__file__))
ROOT=os.path.dirname(HERE)
def load_ref():
    return np.array(Image.open(os.path.join(ROOT,'img','00_native.png')).convert('RGB'))
def up(a,s): return np.repeat(np.repeat(a,s,0),s,1)
def save(a,name,s=1):
    if a.dtype!=np.uint8: a=np.clip(a,0,255).astype(np.uint8)
    if a.ndim==2: a=np.stack([a]*3,-1)
    Image.fromarray(up(a,s)).save(os.path.join(ROOT,'img',name))
def srgb2lin(c):
    c=np.asarray(c,float)/255; return np.where(c<=0.04045,c/12.92,((c+0.055)/1.055)**2.4)
def lum(a):
    """relative luminance -> CIE L* (0..100)"""
    l=srgb2lin(a); Y=l[...,0]*0.2126+l[...,1]*0.7152+l[...,2]*0.0722
    return np.where(Y>0.008856,116*np.cbrt(Y)-16,903.3*Y)
def rgb2lab(a):
    l=srgb2lin(a)
    M=np.array([[0.4124,0.3576,0.1805],[0.2126,0.7152,0.0722],[0.0193,0.1192,0.9505]])
    xyz=l@M.T/np.array([0.95047,1.0,1.08883])
    f=np.where(xyz>0.008856,np.cbrt(xyz),7.787*xyz+16/116)
    L=116*f[...,1]-16; A=500*(f[...,0]-f[...,1]); B=200*(f[...,1]-f[...,2])
    return np.stack([L,A,B],-1)
def label(img,text,pos=(4,4),fill=(255,255,255),bg=(0,0,0)):
    im=Image.fromarray(img) if isinstance(img,np.ndarray) else img
    d=ImageDraw.Draw(im)
    try: f=ImageFont.truetype('/System/Library/Fonts/Menlo.ttc',14)
    except: f=ImageFont.load_default()
    bb=d.textbbox(pos,text,font=f); d.rectangle([bb[0]-2,bb[1]-2,bb[2]+2,bb[3]+2],fill=bg); d.text(pos,text,fill=fill,font=f)
    return np.array(im)
EOF
cat > src/crop.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
a=load_ref(); x,y,w,h,s,name=sys.argv[1:7]
x,y,w,h,s=map(int,(x,y,w,h,s)); save(a[y:y+h,x:x+w],name,s)
EOF
nice -n 10 python3 src/crop.py 0 240 200 110 5 c_grass_left.png; nice -n 10 python3 src/crop.py 330 380 200 90 5 c_grass_right.png

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && for args in "160 70 180 110 5 c_mountain.png" "0 0 120 240 3 c_tree_left.png" "150 250 250 150 4 c_water.png" "200 200 280 70 4 c_midbanks.png" "380 230 254 90 4 c_rightmid.png" "230 380 120 89 6 c_shore.png"; do nice -n 10 python3 src/crop.py $args; done

# output:
Exit code 1
Traceback (most recent call last):
  File "~/work/pixelart-studies/pedagogy/analysis/src/crop.py", line 2, in <module>
    a=load_ref(); x,y,w,h,s,name=sys.argv[1:7]
                  ^^^^^^^^^^^^^^
ValueError: not enough values to unpack (expected 6, got 1)
Traceback (most recent call last):
  File "~/work/pixelart-studies/pedagogy/analysis/src/crop.py", line 2, in <module>
    a=load_ref(); x,y,w,h,s,name=sys.argv[1:7]
                  ^^^^^^^^^^^^^^
ValueError: not enough values to unpack (expected 6, got 1)
Traceback (most recent call last):
  File "~/work/pixelart-studies/pedagogy/analysis/src/crop.py", line 2, in <module>
    a=load_ref(); x,y,w,h,s,name=sys.argv[1:7]
                  ^^^^^^^^^^^^^^
ValueError: not enough values to unpack (expected 6, got 1)
Traceback (most recent call last):
  File "~/work/pixelart-studies/pedagogy/analysis/src/crop.py", line 2, in <module>
    a=load_ref(); x,y,w,h,s,name=sys.argv[1:7]
                  ^^^^^^^^^^^^^^
ValueError: not enough values to unpack (expected 6, got 1)
Traceback (most recent call last):
  File "~/work/pixelart-studies/pedagogy/analysis/src/crop.py", line 2, in <module>
    a=load_ref(); x,y,w,h,s,name=sys.argv[1:7]
                  ^^^^^^^^^^^^^^
ValueError: not enough values to unpack (expected 6, got 1)
Traceback (most recent call last):
  File "~/work/pixelart-studies/pedagogy/analysis/src/crop.py", line 2, in <module>
    a=load_ref(); x,y,w,h,s,name=sys.argv[1:7]
                  ^^^^^^^^^^^^^^
ValueError: not enough values to unpack (expected 6, got 1)

cd ~/work/pixelart-studies/pedagogy/analysis && for args in "160 70 180 110 5 c_mountain.png" "0 0 120 240 3 c_tree_left.png" "150 250 250 150 4 c_water.png" "200 200 280 70 4 c_midbanks.png" "380 230 254 90 4 c_rightmid.png" "230 380 120 89 6 c_shore.png"; do nice -n 10 python3 src/crop.py ${=args}; done

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/grid.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
a=load_ref(); s=2; g=up(a,s).copy()
im=Image.fromarray(g); d=ImageDraw.Draw(im)
f=ImageFont.truetype('/System/Library/Fonts/Menlo.ttc',11)
for x in range(0,a.shape[1],20):
    d.line([(x*s,0),(x*s,g.shape[0])],fill=(0,255,255) if x%100==0 else (0,120,120),width=1)
    if x%40==0: d.text((x*s+2,2),str(x),fill=(255,255,0),font=f)
for y in range(0,a.shape[0],20):
    d.line([(0,y*s),(g.shape[1],y*s)],fill=(0,255,255) if y%100==0 else (0,120,120),width=1)
    d.text((2,y*s+2),str(y),fill=(255,255,0),font=f)
im.save('img/01_grid.png')
EOF
nice -n 10 python3 src/grid.py

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/seg_try.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
from scipy.ndimage import gaussian_filter
from sklearn.cluster import KMeans
a=load_ref(); lab=rgb2lab(a)
bl=np.stack([gaussian_filter(lab[...,i],3) for i in range(3)],-1)
H,W=a.shape[:2]; yy,xx=np.mgrid[0:H,0:W]
F=np.concatenate([bl.reshape(-1,3),(yy.reshape(-1,1)*0.12),(xx.reshape(-1,1)*0.03)],1)
km=KMeans(16,n_init=4,random_state=0).fit(F[::7]); lab_=km.predict(F).reshape(H,W)
rng=np.random.default_rng(1); cols=rng.integers(40,255,(16,3))
out=cols[lab_].astype(np.uint8)
im=Image.fromarray(up(out,2)); d=ImageDraw.Draw(im); f=ImageFont.truetype('/System/Library/Fonts/Menlo.ttc',16)
for k in range(16):
    ys,xs=np.nonzero(lab_==k); d.text((int(np.median(xs))*2,int(np.median(ys))*2),str(k),fill=(0,0,0),font=f)
im.save('img/tmp_kmeans.png'); np.save('out/km.npy',lab_)
EOF
nice -n 10 python3 src/seg_try.py

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && nice -n 10 python3 src/crop.py 120 200 420 140 3 c_midzone.png

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/planes.py <<'EOF'
"""Hand-traced planes of the reference (native 634x469 coords) + colour-based sky/tree split.
Output: out/planes.npy (int labels), img/02_planes.png"""
import sys; sys.path.insert(0,'src'); from util import *
a=load_ref(); H,W=a.shape[:2]; lab=rgb2lab(a); L=lab[...,0]
NAMES=['sky','mountain','far forest','framing trees','far banks','island','water','left meadow (mid)','left bank (fore)','right bank (fore)']
COLS=[(214,170,196),(150,110,160),(90,80,50),(40,40,20),(120,120,60),(180,160,70),(120,150,210),(230,180,90),(200,120,50),(60,70,30)]
def poly(pts):
    im=Image.new('L',(W,H),0); ImageDraw.Draw(im).polygon(pts,fill=1); return np.array(im)>0
mountain=poly([(150,135),(205,108),(250,100),(285,90),(307,66),(330,84),(355,95),(395,118),(470,128),(505,135),(505,235),(150,235)])
water=poly([(205,250),(560,250),(634,262),(634,285),(560,290),(520,300),(490,320),(450,345),(420,370),(390,395),(360,420),(345,448),(250,448),(235,420),(215,390),(190,360),(165,335),(140,318),(160,300),(205,288)])
island=poly([(257,285),(275,268),(310,258),(360,257),(400,265),(418,285),(400,298),(330,300),(270,296)])
leftmeadow=poly([(0,238),(60,240),(130,248),(205,258),(207,288),(160,300),(140,318),(0,318)])
leftfore=poly([(0,318),(140,318),(165,335),(190,360),(215,390),(235,420),(250,448),(262,469),(0,469)])
rightfore=poly([(634,285),(560,290),(520,300),(490,320),(450,345),(420,370),(390,395),(360,420),(345,448),(330,469),(634,469)])
farbanks=poly([(80,212),(200,215),(300,225),(420,222),(500,215),(634,215),(634,262),(560,250),(205,250),(205,258),(130,248),(60,240),(0,238),(0,225)])
framing=poly([(0,0),(175,0),(175,245),(0,245)])|poly([(490,0),(634,0),(634,235),(490,235)])
skyish=(L>50)&(lab[...,1]>3)&(lab[...,2]<30)   # pink/violet high value
yy,xx=np.mgrid[0:H,0:W]
lab_=np.full((H,W),2)                      # default far forest (upper middle)
lab_[framing]=3
lab_[mountain & ~framing]=1
# inside mountain zone, conifer colours stay forest: dark or yellow-ochre
coniferish=(L<35)|((lab[...,2]>25)&(lab[...,1]<25))
lab_[mountain & ~framing & coniferish]=2
lab_[(yy<245)&skyish&~mountain]=0
lab_[(yy<140)&skyish]=0
lab_[farbanks]=4; lab_[water]=6; lab_[island]=5
lab_[leftmeadow]=7; lab_[leftfore]=8; lab_[rightfore]=9
np.save('out/planes.npy',lab_)
C=np.array(COLS,np.uint8); out=C[lab_]
mix=(0.45*a+0.55*out).astype(np.uint8)
img=up(mix,2)
im=Image.fromarray(img); d=ImageDraw.Draw(im); f=ImageFont.truetype('/System/Library/Fonts/Menlo.ttc',15)
for i,n in enumerate(NAMES):
    d.rectangle([8,8+i*20,24,22+i*20],fill=COLS[i],outline=(0,0,0)); d.text((30,8+i*20),f'{i} {n}',fill=(255,255,255),font=f,stroke_width=2,stroke_fill=(0,0,0))
im.save('img/02_planes.png')
for i,n in enumerate(NAMES): print(i,n,(lab_==i).mean().round(3))
EOF
nice -n 10 python3 src/planes.py

# output:
0 sky 0.189
1 mountain 0.03
2 far forest 0.095
3 framing trees 0.157
4 far banks 0.066
5 island 0.018
6 water 0.16
7 left meadow (mid) 0.046
8 left bank (fore) 0.108
9 right bank (fore) 0.131

cd ~/work/pixelart-studies/pedagogy/analysis && sed -i '' 's/lab_\[(yy<140)&skyish\]=0/lab_[(yy<140)\&skyish\&~mountain]=0/; s/(360,420),(345,448),(250,448),(235,420)/(360,420),(345,448),(332,469),(262,469),(250,448),(235,420)/' src/planes.py && grep -n "yy<140\|332,469" src/planes.py && nice -n 10 python3 src/planes.py

# output:
10:water=poly([(205,250),(560,250),(634,262),(634,285),(560,290),(520,300),(490,320),(450,345),(420,370),(390,395),(360,420),(345,448),(332,469),(262,469),(250,448),(235,420),(215,390),(190,360),(165,335),(140,318),(160,300),(205,288)])
26:lab_[(yy<140)&skyish&~mountain]=0
0 sky 0.179
1 mountain 0.04
2 far forest 0.09
3 framing trees 0.157
4 far banks 0.066
5 island 0.018
6 water 0.165
7 left meadow (mid) 0.046
8 left bank (fore) 0.108
9 right bank (fore) 0.131

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/values.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
from scipy.ndimage import gaussian_filter
from sklearn.cluster import KMeans
import matplotlib; matplotlib.use('Agg'); import matplotlib.pyplot as plt
def analyse(a,planes,names,tag,prefix):
    L=lum(a); Lb=gaussian_filter(L,2.5)
    g=(L/100*255); gb=(Lb/100*255)
    save(np.concatenate([g,np.full((a.shape[0],6),255),gb],1),f'{prefix}_grey.png',2 if a.shape[1]>400 else 3)
    res={}
    rows=[]
    for k in (2,3,5):
        km=KMeans(k,n_init=6,random_state=0).fit(Lb.reshape(-1,1)[::5]); c=np.sort(km.cluster_centers_.ravel())
        th=(c[1:]+c[:-1])/2; q=np.digitize(Lb,th); lv=np.linspace(0,255,k) if k>2 else np.array([30,235])
        if k==3: lv=np.array([25,130,240])
        rows.append(lv[q]); res[k]=(th,c)
        np.save(f'out/{prefix}_notan{k}.npy',q)
    sep=np.full((a.shape[0],6),255)
    save(np.concatenate([rows[0],sep,rows[1],sep,rows[2]],1),f'{prefix}_notan.png',1 if a.shape[1]>400 else 2)
    # per-plane stats
    stats=[]
    for i,n in enumerate(names):
        m=planes==i
        if m.sum()<50: stats.append(None); continue
        stats.append((n,np.percentile(Lb[m],[5,25,50,75,95]),L[m].std(),m.mean()))
    fig,ax=plt.subplots(1,2,figsize=(13,4.6))
    data=[Lb[planes==i] for i in range(len(names)) if (planes==i).sum()>=50]
    nm=[n for i,n in enumerate(names) if (planes==i).sum()>=50]
    ax[0].boxplot(data,whis=(5,95),showfliers=False,vert=False); ax[0].set_yticks(range(1,len(nm)+1),nm); ax[0].set_xlabel('L* (squint-blurred)'); ax[0].set_xlim(0,100); ax[0].set_title(f'{tag}: value range per plane')
    for t in res[3][0]: ax[0].axvline(t,color='r',ls=':')
    ax[1].hist(L.ravel(),bins=100,range=(0,100),color='k',alpha=.5,label='pixel L*'); ax[1].hist(Lb.ravel(),bins=100,range=(0,100),color='r',alpha=.4,label='blurred L*'); ax[1].legend(); ax[1].set_title('value histogram (red dotted = 3-notan cuts)')
    for t in res[3][0]: ax[1].axvline(t,color='r',ls=':')
    plt.tight_layout(); plt.savefig(f'img/{prefix}_valueplanes.png',dpi=80); plt.close()
    # flat value plan: each plane filled with its median blurred L
    flat=np.zeros_like(L)
    for i in range(len(names)):
        m=planes==i
        if m.any(): flat[m]=np.median(Lb[m])
    save(flat/100*255,f'{prefix}_valueplan.png',1 if a.shape[1]>400 else 2)
    return res,stats
if __name__=='__main__':
    a=load_ref(); planes=np.load('out/planes.npy')
    from planes_names import NAMES
    res,stats=analyse(a,planes,NAMES,'Ferrari','03')
    for k,(th,c) in res.items(): print(k,'centers',c.round(1),'cuts',th.round(1))
    for s in stats:
        if s: print(f'{s[0]:20s} p5/25/50/75/95={s[1].round(0)} pixstd={s[2]:.1f} area={s[3]:.3f}')
EOF
echo "NAMES=['sky','mountain','far forest','framing trees','far banks','island','water','left meadow (mid)','left bank (fore)','right bank (fore)']" > src/planes_names.py
nice -n 10 python3 src/values.py

# output:
2 centers [19.6 59.9] cuts [39.7]
3 centers [16.3 41.5 69.8] cuts [28.9 55.6]
5 centers [10.8 20.5 35.4 48.7 70.6] cuts [15.6 27.9 42.  59.6]
sky                  p5/25/50/75/95=[45. 71. 71. 72. 75.] pixstd=1.6 area=0.179
mountain             p5/25/50/75/95=[17. 35. 48. 63. 72.] pixstd=16.3 area=0.040
far forest           p5/25/50/75/95=[ 9. 14. 20. 29. 44.] pixstd=17.2 area=0.090
framing trees        p5/25/50/75/95=[ 5. 10. 16. 21. 40.] pixstd=18.7 area=0.157
far banks            p5/25/50/75/95=[10. 14. 18. 21. 28.] pixstd=14.3 area=0.066
island               p5/25/50/75/95=[16. 21. 28. 40. 52.] pixstd=17.5 area=0.018
water                p5/25/50/75/95=[14. 19. 29. 50. 70.] pixstd=23.6 area=0.165
left meadow (mid)    p5/25/50/75/95=[22. 37. 42. 48. 55.] pixstd=19.1 area=0.046
left bank (fore)     p5/25/50/75/95=[28. 38. 43. 47. 51.] pixstd=17.7 area=0.108
right bank (fore)    p5/25/50/75/95=[ 4.  9. 14. 19. 22.] pixstd=10.7 area=0.131

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/light_probe.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
a=load_ref(); P=np.load('out/planes.npy'); lab=rgb2lab(a); L=lab[...,0]
sky=P==0
# sky gradient: by row and by column
for y in range(0,240,20):
    m=sky[y:y+10]; 
    if m.sum(): print('row',y,'L=%.1f a=%.1f b=%.1f'%tuple(lab[y:y+10][m].mean(0)))
H,W=L.shape
for x0 in range(0,W,80):
    m=sky[60:200,x0:x0+80]
    if m.sum()>100: print('col',x0,'L=%.1f a=%.1f b=%.1f'%tuple(lab[60:200,x0:x0+80][m].mean(0)))
# which side of dark are the warm lit pixels, per plane
for pi,name in [(3,'framing trees'),(2,'far forest'),(1,'mountain'),(4,'far banks'),(5,'island')]:
    m=P==pi; lit=m&(L>np.percentile(L[m],70)); dark=L<np.percentile(L[m],40)
    left=np.zeros_like(lit); right=np.zeros_like(lit); upn=np.zeros_like(lit); dn=np.zeros_like(lit)
    # for lit pixels, is the dark neighbour at distance 1..3 to the right (=> lit on left side of form)?
    r=l=u=d=0
    for k in (1,2,3):
        r+=(lit[:,:-k]&dark[:,k:]).sum(); l+=(lit[:,k:]&dark[:,:-k]).sum()
        d+=(lit[:-k]&dark[k:]).sum(); u+=(lit[k:]&dark[:-k]).sum()
    print(f'{name:14s} lit->dark: right {r} left {l} below {d} above {u}  => lit edge faces {"LEFT" if r>l else "RIGHT"}, {"UP" if d>u else "DOWN"}')
# water vs source brightness: reflected sky
w=P==6
print('water pixels L>55 mean', L[w&(L>55)].mean(), ' sky mean', L[sky].mean())
EOF
nice -n 10 python3 src/light_probe.py

# output:
row 0 L=71.5 a=18.5 b=-8.7
row 20 L=71.1 a=20.5 b=-6.8
row 40 L=71.8 a=21.7 b=-0.5
row 60 L=72.7 a=24.7 b=3.0
row 80 L=74.6 a=24.8 b=10.7
row 100 L=75.2 a=22.8 b=15.0
row 120 L=76.3 a=19.4 b=17.9
row 140 L=79.4 a=17.5 b=21.2
col 0 L=74.3 a=23.8 b=10.3
col 80 L=74.4 a=23.7 b=10.7
col 160 L=74.2 a=24.1 b=10.1
col 240 L=73.5 a=24.7 b=7.1
col 320 L=73.8 a=24.5 b=8.3
col 400 L=74.1 a=23.7 b=9.7
col 480 L=74.6 a=23.4 b=11.4
col 560 L=74.7 a=23.1 b=11.8
framing trees  lit->dark: right 0 left 0 below 0 above 0  => lit edge faces RIGHT, DOWN
far forest     lit->dark: right 0 left 0 below 0 above 0  => lit edge faces RIGHT, DOWN
mountain       lit->dark: right 1568 left 1358 below 2299 above 1377  => lit edge faces LEFT, UP
far banks      lit->dark: right 5357 left 5750 below 5467 above 6160  => lit edge faces RIGHT, DOWN
island         lit->dark: right 473 left 370 below 333 above 760  => lit edge faces LEFT, DOWN
water pixels L>55 mean 68.92653835582287  sky mean 72.57122258471404

cd ~/work/pixelart-studies/pedagogy/analysis && sed -i '' 's/dark=L<np.percentile(L\[m\],40)/dark=m\&(L<=np.percentile(L[m],40)+0.5)/' src/light_probe.py && nice -n 10 python3 src/light_probe.py | tail -6

# output:
framing trees  lit->dark: right 14994 left 18445 below 15746 above 15435  => lit edge faces RIGHT, UP
far forest     lit->dark: right 5969 left 8171 below 6423 above 6418  => lit edge faces RIGHT, UP
mountain       lit->dark: right 239 left 699 below 728 above 519  => lit edge faces RIGHT, UP
far banks      lit->dark: right 6353 left 6644 below 6470 above 6430  => lit edge faces RIGHT, UP
island         lit->dark: right 542 left 425 below 427 above 714  => lit edge faces LEFT, DOWN
water pixels L>55 mean 68.92653835582287  sky mean 72.57122258471404

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/lightmap.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
a=load_ref(); P=np.load('out/planes.npy'); lab=rgb2lab(a); L,A,B=lab[...,0],lab[...,1],lab[...,2]
# light classes: 0 deep shadow/black, 1 shadow (cool / dark), 2 half-light, 3 lit (warm), 4 highlight
cls=np.zeros(L.shape,int)
warm=(B>12)
cls[(L>=8)]=1
cls[(L>=30)&~warm]=2
cls[(L>=25)&warm]=3
cls[(L>=62)&warm]=4
cls[(L>=62)&~warm]=2   # lavender snow / sky in shade-light
C=np.array([(0,0,60),(60,60,160),(150,150,200),(250,170,40),(255,255,160)],np.uint8)
out=C[cls]; out[P==0]=(235,235,235)
img=up(out,2)
im=Image.fromarray(img); d=ImageDraw.Draw(im); f=ImageFont.truetype('/System/Library/Fonts/Menlo.ttc',15)
for i,t in enumerate(['core/black accents','shadow (dark, cool or olive)','cool light (lavender snow, sky refl.)','warm lit (sunlit ochre/salmon)','warm highlight']):
    d.rectangle([8,8+i*20,24,22+i*20],fill=tuple(C[i]),outline=(0,0,0)); d.text((30,8+i*20),t,fill=(0,0,0),font=f)
im.save('img/05_lightmap.png')
# magnified mountain + a tree
save(np.concatenate([up(a[70:200,200:400],3),up(out[70:200,200:400],3)],1),'05_light_mountain.png',1)
save(np.concatenate([up(a[20:200,30:130],3),up(out[20:200,30:130],3)],1),'05_light_tree.png',1)
EOF
nice -n 10 python3 src/lightmap.py

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/reflection.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
from scipy.ndimage import gaussian_filter
a=load_ref(); lab=rgb2lab(a); L=lab[...,0]; Lb=gaussian_filter(L,1.5)
# find mirror axis y0 (possibly half-integer) and vertical scale s: water row y maps to source row y0-(y-y0)*s
best=None
xs=slice(250,420)
for y0 in np.arange(225,262,0.5):
  for s in (0.8,0.85,0.9,0.95,1.0,1.05,1.1):
    ys=np.arange(300,400); src=np.round(y0-(ys-y0)*s).astype(int)
    if src.min()<0: continue
    e=np.mean(np.abs(Lb[ys][:,xs]-Lb[src][:,xs]))
    if best is None or e<best[0]: best=(e,y0,s)
print('best axis',best)
e,y0,s=best
ys=np.arange(300,400); src=np.round(y0-(ys-y0)*s).astype(int)
dL=Lb[ys][:,xs]-Lb[src][:,xs]
print('mean dL refl-src %.2f'%dL.mean())
for lo,hi in [(0,30),(30,55),(55,100)]:
    m=(Lb[src][:,xs]>=lo)&(Lb[src][:,xs]<hi); print(f' src L {lo}-{hi}: refl-src dL={dL[m].mean():.2f}  (n={m.sum()})')
labb=np.stack([gaussian_filter(lab[...,i],1.5) for i in range(3)],-1)
d=labb[ys][:,xs]-labb[src][:,xs]; print('mean dLab',d.reshape(-1,3).mean(0).round(2))
# side by side image: source (flipped) vs reflection
flip=a[src][:,250:420]; refl=a[ys][:,250:420]
save(np.concatenate([flip,np.full((100,4,3),255,np.uint8),refl],1),'06_reflection_compare.png',4)
EOF
nice -n 10 python3 src/reflection.py

# output:
best axis (9.748440918704885, 228.0, 1.0)
mean dL refl-src -8.15
 src L 0-30: refl-src dL=1.21  (n=2761)
 src L 30-55: refl-src dL=-4.46  (n=5216)
 src L 55-100: refl-src dL=-13.14  (n=9023)
mean dLab [-8.15 -5.1  -1.3 ]

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/form.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
from scipy.ndimage import gaussian_filter
from skimage import measure
a=load_ref(); P=np.load('out/planes.npy'); L=lum(a)
s=3; img=Image.fromarray(up((0.55*a+0.45*np.stack([L*2.55]*3,-1)).astype(np.uint8),s)); d=ImageDraw.Draw(img)
Lb=gaussian_filter(L,4); gy,gx=np.gradient(gaussian_filter(L,7))
cols={1:(255,120,255),4:(120,255,120),5:(255,255,0),7:(255,160,0),8:(255,80,0),9:(0,255,255),6:(160,160,255)}
for pi,c in cols.items():
    m=P==pi
    Lm=np.where(m,Lb,np.nan)
    # isophotes of the squinted value within the mass
    lv=np.nanpercentile(Lm,[20,40,60,80])
    for v in lv:
        for cn in measure.find_contours(np.nan_to_num(Lm,nan=-99),v):
            pts=[(p[1]*s,p[0]*s) for p in cn[::2]]
            if len(pts)>6: d.line(pts,fill=c,width=1)
    # brightness gradient arrows (points toward the lit side of the form)
    for y in range(8,a.shape[0],18):
        for x in range(8,a.shape[1],18):
            if m[y,x] and m[max(0,y-6):y+6,max(0,x-6):x+6].mean()>0.9:
                vx,vy=gx[y,x],gy[y,x]; n=np.hypot(vx,vy)
                if n<0.15: d.ellipse([x*s-2,y*s-2,x*s+2,y*s+2],outline=c); continue
                k=min(9,3+n*6)/n; x2,y2=x+vx*k,y+vy*k
                d.line([(x*s,y*s),(x2*s,y2*s)],fill=c,width=2); d.ellipse([x2*s-3,y2*s-3,x2*s+3,y2*s+3],fill=c)
img.save('img/07_form.png')
img.crop((180*s,190*s,634*s,330*s)).save('img/07_form_mid.png')
EOF
nice -n 10 python3 src/form.py

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/profiles.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
from scipy.ndimage import gaussian_filter, uniform_filter1d
import matplotlib; matplotlib.use('Agg'); import matplotlib.pyplot as plt
a=load_ref(); P=np.load('out/planes.npy'); L=lum(a)
Lh=uniform_filter1d(gaussian_filter(L,1.5),15,axis=1)  # average across 15 px horizontally
fig,ax=plt.subplots(1,4,figsize=(15,3.8))
specs=[('island x=340',340,255,302,5),('far hummock x=560',560,212,262,4),('left bank x=60',60,238,469,None),('right bank x=560',560,288,469,9)]
for axx,(t,x,y0,y1,pi) in zip(ax,specs):
    ys=np.arange(y0,y1); axx.plot(Lh[ys,x],ys,'k'); axx.invert_yaxis(); axx.set_title(t); axx.set_xlabel('L* (15px avg)'); axx.set_ylabel('y (row)')
    axx.set_xlim(0,70)
plt.tight_layout(); plt.savefig('img/07_profiles.png',dpi=80)
# horizontal profile along island top & right bank near water
for t,y,x0,x1 in [('island row 272',272,262,415),('left meadow row 270',270,0,200)]:
    print(t, np.round(Lh[y,x0:x1:15],0))
EOF
nice -n 10 python3 src/profiles.py

# output:
island row 272 [29. 26. 20. 16. 23. 39. 53. 54. 32. 19. 24.]
left meadow row 270 [53. 53. 52. 53. 52. 52. 51. 50. 49. 48. 45. 45. 40. 24.]

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/edges.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
from scipy.ndimage import gaussian_filter, gaussian_gradient_magnitude, binary_dilation, median_filter
def edge_analysis(a,prefix,scale):
    L=lum(a)
    # suppress dither: median 3x3 first (dither checker -> flat), then scale-space gradient
    Lm=median_filter(L,3)
    g1=gaussian_gradient_magnitude(Lm,1.0); g3=gaussian_gradient_magnitude(Lm,3.0)
    strong=g3>np.percentile(g3,80)
    hard=g1/(g3+1e-6)
    base=np.stack([L*2.0+40]*3,-1).clip(0,255)
    out=base.copy()
    H=strong&(hard>1.9); S=strong&(hard<=1.9)
    out[H]=(255,40,40); out[S]=(60,140,255)
    save(out.astype(np.uint8),f'{prefix}_edges.png',scale)
    return H.sum()/strong.sum(), g3, hard, strong
if __name__=='__main__':
    a=load_ref(); P=np.load('out/planes.npy')
    fr,g3,hard,strong=edge_analysis(a,'08',2)
    print('share of strong edges that are hard: %.2f'%fr)
    L=gaussian_filter(lum(a),2)
    from planes_names import NAMES
    # plane-boundary contrast: found vs lost
    res={}
    for i in range(10):
        for j in range(i+1,10):
            bi=binary_dilation(P==i,iterations=2)&(P==j)
            if bi.sum()<60: continue
            # value 4px inside each side
            mi=binary_dilation(P==j,iterations=4)&(P==i); mj=binary_dilation(P==i,iterations=4)&(P==j)
            d=abs(np.median(L[mi])-np.median(L[mj])); res[(i,j)]=d
            print(f'{NAMES[i]:18s}|{NAMES[j]:18s} dL={d:5.1f} hardfrac={(hard[bi&strong]>1.9).mean() if (bi&strong).any() else 0:.2f} len={bi.sum()}')
EOF
nice -n 10 python3 src/edges.py

# output:
share of strong edges that are hard: 0.52
sky               |mountain           dL=  5.1 hardfrac=0.34 len=408
sky               |far forest         dL= 34.2 hardfrac=0.63 len=1657
sky               |framing trees      dL= 36.4 hardfrac=0.66 len=8183
mountain          |far forest         dL= 18.6 hardfrac=0.57 len=9846
mountain          |framing trees      dL=  5.4 hardfrac=0.44 len=117
mountain          |far banks          dL=  1.1 hardfrac=0.58 len=71
far forest        |framing trees      dL=  2.5 hardfrac=0.48 len=312
far forest        |far banks          dL=  1.4 hardfrac=0.58 len=613
framing trees     |far banks          dL=  1.6 hardfrac=0.65 len=642
far banks         |water              dL=  0.3 hardfrac=0.33 len=870
far banks         |left meadow (mid)  dL=  4.1 hardfrac=0.64 len=413
island            |water              dL=  1.5 hardfrac=0.36 len=660
water             |left meadow (mid)  dL= 10.2 hardfrac=0.52 len=193
water             |left bank (fore)   dL=  0.2 hardfrac=0.57 len=321
water             |right bank (fore)  dL=  0.1 hardfrac=0.00 len=643
left meadow (mid) |left bank (fore)   dL=  0.8 hardfrac=0.90 len=283

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/edges.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
from scipy.ndimage import gaussian_filter, median_filter, map_coordinates, binary_dilation
from skimage.feature import canny
def edge_widths(a):
    L=lum(a); Lm=gaussian_filter(median_filter(L,3),0.7)
    E=canny(median_filter(L,3),sigma=2.0,low_threshold=3,high_threshold=6)
    gy,gx=np.gradient(gaussian_filter(Lm,2.0))
    ys,xs=np.nonzero(E); n=np.hypot(gx[ys,xs],gy[ys,xs])+1e-9; ux,uy=gx[ys,xs]/n,gy[ys,xs]/n
    t=np.linspace(-8,8,33)
    py=ys[:,None]+uy[:,None]*t[None]; px=xs[:,None]+ux[:,None]*t[None]
    prof=map_coordinates(Lm,[py,px],order=1,mode='nearest')
    lo=np.percentile(prof,10,axis=1); hi=np.percentile(prof,90,axis=1); amp=hi-lo
    p=(prof-lo[:,None])/(amp[:,None]+1e-9)
    # rise width: distance between where profile crosses .2 and .8 nearest centre
    w=np.zeros(len(ys))
    for i in range(len(ys)):
        c=16; q=p[i]
        a20=np.argmin(np.where(np.abs(np.arange(33)-c)<=16,np.abs(q-0.2),9)); a80=np.argmin(np.abs(q-0.8))
        w[i]=abs(t[a80]-t[a20])
    return ys,xs,w,amp,L
def draw(a,prefix,scale):
    ys,xs,w,amp,L=edge_widths(a)
    base=np.stack([L*1.6+60]*3,-1).clip(0,255)
    keep=amp>8
    out=base.copy()
    col=np.zeros((len(ys),3))
    col[w<=2.0]=(230,20,20); col[(w>2.0)&(w<=4.5)]=(250,200,0); col[w>4.5]=(30,120,255)
    out[ys[keep],xs[keep]]=col[keep]
    save(out.astype(np.uint8),f'{prefix}_edges.png',scale)
    return ys[keep],xs[keep],w[keep],amp[keep]
if __name__=='__main__':
    a=load_ref(); P=np.load('out/planes.npy')
    from planes_names import NAMES
    ys,xs,w,amp=draw(a,'08',2)
    print('edge px',len(w),'hard(<=2) %.2f mid %.2f soft(>4.5) %.2f'%((w<=2).mean(),((w>2)&(w<=4.5)).mean(),(w>4.5).mean()))
    for i,n in enumerate(NAMES):
        m=P[ys,xs]==i
        if m.sum()>30: print(f'{n:18s} n={m.sum():5d} hard {np.mean(w[m]<=2):.2f} soft {np.mean(w[m]>4.5):.2f} median amp {np.median(amp[m]):.1f}')
EOF
nice -n 10 python3 src/edges.py

# output:
edge px 42908 hard(<=2) 0.23 mid 0.24 soft(>4.5) 0.53
sky                n= 1468 hard 0.44 soft 0.33 median amp 66.4
mountain           n= 1866 hard 0.26 soft 0.50 median amp 36.7
far forest         n= 4778 hard 0.23 soft 0.54 median amp 27.9
framing trees      n= 8302 hard 0.25 soft 0.50 median amp 30.9
far banks          n= 2900 hard 0.24 soft 0.53 median amp 19.7
island             n=  723 hard 0.25 soft 0.53 median amp 20.3
water              n= 6827 hard 0.20 soft 0.55 median amp 22.8
left meadow (mid)  n= 2313 hard 0.24 soft 0.50 median amp 23.5
left bank (fore)   n= 6821 hard 0.20 soft 0.55 median amp 19.6
right bank (fore)  n= 6910 hard 0.20 soft 0.55 median amp 12.9

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
import re
s=open('src/edges.py').read()
s=s.replace("E=canny(median_filter(L,3),sigma=2.0,low_threshold=3,high_threshold=6)","E=canny(median_filter(L,3),sigma=SIG,low_threshold=2,high_threshold=4)")
s=s.replace("def edge_widths(a):","def edge_widths(a,SIG=3.5):")
s=s.replace("t=np.linspace(-8,8,33)","t=np.linspace(-8,8,33)")
s=s.replace("base=np.stack([L*1.6+60]*3,-1).clip(0,255)","base=(a*0.35+150).clip(0,255)")
open('src/edges.py','w').write(s)
EOF
nice -n 10 python3 src/edges.py

# output:
edge px 26663 hard(<=2) 0.23 mid 0.23 soft(>4.5) 0.53
sky                n= 1220 hard 0.50 soft 0.28 median amp 68.7
mountain           n= 1249 hard 0.28 soft 0.47 median amp 41.0
far forest         n= 2961 hard 0.22 soft 0.56 median amp 33.2
framing trees      n= 5272 hard 0.25 soft 0.52 median amp 35.8
far banks          n= 1884 hard 0.25 soft 0.55 median amp 22.8
island             n=  479 hard 0.26 soft 0.49 median amp 23.6
water              n= 4390 hard 0.21 soft 0.56 median amp 26.8
left meadow (mid)  n= 1219 hard 0.23 soft 0.52 median amp 24.8
left bank (fore)   n= 3958 hard 0.19 soft 0.58 median amp 20.3
right bank (fore)  n= 4031 hard 0.19 soft 0.57 median amp 13.5

cd ~/work/pixelart-studies/pedagogy/analysis && sed -i '' 's/low_threshold=2,high_threshold=4/low_threshold=4,high_threshold=8/; s/keep=amp>8/keep=amp>18/' src/edges.py && nice -n 10 python3 src/edges.py

# output:
edge px 17065 hard(<=2) 0.24 mid 0.22 soft(>4.5) 0.54
sky                n= 1216 hard 0.50 soft 0.29 median amp 68.8
mountain           n= 1164 hard 0.29 soft 0.46 median amp 41.9
far forest         n= 2434 hard 0.22 soft 0.56 median amp 37.2
framing trees      n= 4082 hard 0.25 soft 0.52 median amp 39.8
far banks          n= 1181 hard 0.25 soft 0.58 median amp 29.7
island             n=  299 hard 0.25 soft 0.49 median amp 27.7
water              n= 2840 hard 0.19 soft 0.58 median amp 34.5
left meadow (mid)  n=  899 hard 0.22 soft 0.56 median amp 28.5
left bank (fore)   n= 2397 hard 0.19 soft 0.61 median amp 25.8
right bank (fore)  n=  553 hard 0.11 soft 0.64 median amp 20.1

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/clusters.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
from scipy.ndimage import label as cclabel, find_objects
def colour_index(a):
    flat=a.reshape(-1,3); u,inv=np.unique(flat,axis=0,return_inverse=True); return inv.reshape(a.shape[:2]),u
def cluster_stats(a,mask):
    """connected same-colour runs (4-conn) inside mask: size, h, w, aspect (h/w), vertical fraction"""
    idx,u=colour_index(a)
    S=[];Hs=[];Ws=[];
    for c in np.unique(idx[mask]):
        m=(idx==c)&mask
        lab,n=cclabel(m)
        if n==0: continue
        sizes=np.bincount(lab.ravel())[1:]
        for sl,sz in zip(find_objects(lab),sizes):
            S.append(sz); Hs.append(sl[0].stop-sl[0].start); Ws.append(sl[1].stop-sl[1].start)
    S=np.array(S);Hs=np.array(Hs);Ws=np.array(Ws)
    return dict(n=len(S),size_med=np.median(S),size_mean=S.mean(),size_p90=np.percentile(S,90),
                single=(S==1).mean(),vert=np.mean(Hs>Ws),horiz=np.mean(Ws>Hs),aspect_med=np.median(Hs/Ws),
                h_p90=np.percentile(Hs,90), w_p90=np.percentile(Ws,90),
                colours=len(np.unique(idx[mask])), per100=len(S)/mask.sum()*100)
def run_lengths(a,mask,axis):
    """mean run length of identical colour along axis inside mask"""
    idx,_=colour_index(a); b=idx if axis==1 else idx.T; mk=mask if axis==1 else mask.T
    runs=[]
    for r,m in zip(b,mk):
        if m.sum()<4: continue
        v=r[m]; ch=np.flatnonzero(np.diff(v)!=0); pts=np.r_[-1,ch,len(v)-1]; runs+=list(np.diff(pts))
    return np.mean(runs)
if __name__=='__main__':
    a=load_ref(); P=np.load('out/planes.npy')
    from planes_names import NAMES
    import json; out={}
    for i,n in enumerate(NAMES):
        m=P==i; s=cluster_stats(a,m); s['runH']=run_lengths(a,m,1); s['runV']=run_lengths(a,m,0)
        out[n]={k:float(v) for k,v in s.items()}
        print(f"{n:18s} cols={s['colours']:3.0f} clusters/100px={s['per100']:5.1f} size med={s['size_med']:.0f} mean={s['size_mean']:5.1f} p90={s['size_p90']:4.0f} single={s['single']:.2f} vert={s['vert']:.2f} horiz={s['horiz']:.2f} runH={s['runH']:.2f} runV={s['runV']:.2f}")
    json.dump(out,open('out/ref_cluster_stats.json','w'),indent=1)
EOF
nice -n 10 python3 src/clusters.py

# output:
sky                cols= 21 clusters/100px= 33.4 size med=1 mean=  3.0 p90=   1 single=0.97 vert=0.00 horiz=0.01 runH=1.99 runV=1.94
mountain           cols= 24 clusters/100px= 30.5 size med=1 mean=  3.3 p90=   5 single=0.72 vert=0.09 horiz=0.13 runH=2.36 runV=2.27
far forest         cols= 22 clusters/100px= 26.1 size med=1 mean=  3.8 p90=   6 single=0.65 vert=0.14 horiz=0.13 runH=2.00 runV=2.10
framing trees      cols= 23 clusters/100px= 19.3 size med=1 mean=  5.2 p90=   6 single=0.64 vert=0.19 horiz=0.09 runH=2.14 runV=2.42
far banks          cols= 47 clusters/100px= 28.3 size med=1 mean=  3.5 p90=   4 single=0.76 vert=0.08 horiz=0.09 runH=1.84 runV=1.80
island             cols= 48 clusters/100px= 34.9 size med=1 mean=  2.9 p90=   3 single=0.80 vert=0.06 horiz=0.10 runH=1.72 runV=1.64
water              cols=166 clusters/100px= 42.8 size med=1 mean=  2.3 p90=   4 single=0.75 vert=0.09 horiz=0.11 runH=1.50 runV=1.49
left meadow (mid)  cols= 43 clusters/100px= 22.4 size med=1 mean=  4.5 p90=   5 single=0.61 vert=0.23 horiz=0.10 runH=1.77 runV=2.23
left bank (fore)   cols= 50 clusters/100px= 16.2 size med=2 mean=  6.2 p90=  11 single=0.39 vert=0.57 horiz=0.02 runH=1.51 runV=3.24
right bank (fore)  cols= 42 clusters/100px= 17.9 size med=2 mean=  5.6 p90=   8 single=0.41 vert=0.52 horiz=0.04 runH=1.56 runV=3.10

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/atlas.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
from collections import Counter
def atlas(a,wins,name,s=7,sz=32):
    tiles=[]
    for title,(x,y) in wins:
        w=a[y:y+sz,x:x+sz]
        cnt=Counter(map(tuple,w.reshape(-1,3))).most_common(3)
        row=[up(w,s)]
        for col,_ in cnt:   # isolate each of the 3 dominant colours
            m=np.all(w==col,axis=2); t=np.full_like(w,128); t[m]=col; t[~m]=(40,40,40) if np.mean(col)>90 else (200,200,200)
            row.append(up(t,s//2+1)[:sz*s//2+sz//2*0+ sz*(s//2+1)][:,:])
        # compose: big tile + 3 small isolation tiles stacked
        big=row[0]; smalls=[r[:sz*(s//2+1),:sz*(s//2+1)] for r in row[1:]]
        colh=big.shape[0]; sw=smalls[0].shape[1]
        side=np.full((colh,sw,3),255,np.uint8); yy=0
        for sm in smalls:
            h=min(sm.shape[0],colh-yy); side[yy:yy+h]=sm[:h]; yy+=h+2
            if yy>=colh: break
        t=np.concatenate([big,np.full((colh,3,3),255,np.uint8),side],1)
        t=np.concatenate([np.full((22,t.shape[1],3),255,np.uint8),t],0)
        t=label(t,title,(2,3),fill=(0,0,0),bg=(255,255,255))
        tiles.append(t)
    W=max(t.shape[1] for t in tiles); rows=[]
    for i in range(0,len(tiles),3):
        r=tiles[i:i+3]; r=[np.pad(t,((0,0),(0,W-t.shape[1]+6),(0,0)),constant_values=255) for t in r]
        while len(r)<3: r.append(np.full_like(r[0],255))
        rows.append(np.concatenate(r,1))
    Image.fromarray(np.concatenate(rows,0)).save(f'img/{name}')
if __name__=='__main__':
    a=load_ref()
    wins=[('fore grass, lit (left)',(40,400)),('fore grass, shade (right)',(560,400)),('mid meadow, lit',(60,262)),
          ('far bank / hummock',(520,228)),('island top (rim light)',(340,258)),('conifer, near',(40,120)),
          ('conifer edge vs sky',(95,60)),('mountain rock + light',(215,110)),('snow, shade/light',(318,120)),
          ('water: sky reflection',(300,370)),('water: tree reflection',(290,310)),('shore stones',(250,405))]
    atlas(a,wins,'09_cluster_atlas.png')
EOF
nice -n 10 python3 src/atlas.py

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/palette.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
import matplotlib; matplotlib.use('Agg'); import matplotlib.pyplot as plt
from planes_names import NAMES
a=load_ref(); P=np.load('out/planes.npy')
flat=a.reshape(-1,3); u,inv,cnt=np.unique(flat,axis=0,return_inverse=True,return_counts=True); inv=inv.ravel()
pl=P.ravel()
M=np.zeros((len(u),10))
np.add.at(M,(inv,pl),1)
lab=rgb2lab(u.astype(float)); L=lab[:,0]; hue=np.degrees(np.arctan2(lab[:,2],lab[:,1]))%360; C=np.hypot(lab[:,1],lab[:,2])
# material groups (merge planes)
groups={'sky':[0],'mountain (rock+snow)':[1],'conifers':[2,3],'grass lit (left)':[7,8],'grass shade / banks':[4,9],'island':[5],'water-only':[6]}
home=np.argmax(M,1)
own={}
for g,ps in groups.items():
    share=M[:,ps].sum(1)/M.sum(1)
    if g=='water-only': sel=(M[:,6]/M.sum(1)>0.9)
    else: sel=(share>0.45)&(M[:,6]/M.sum(1)<=0.9)
    own[g]=np.flatnonzero(sel)
# assign each colour to a single group (highest share excl water), ignore duplicates
assigned={}
for i in range(len(u)):
    best=None
    for g,ps in groups.items():
        if g=='water-only': continue
        s=M[i,ps].sum()
        if best is None or s>best[1]: best=(g,s)
    if M[i,6]/M[i].sum()>0.9: best=('water-only',0)
    assigned.setdefault(best[0],[]).append(i)
sw=18; rows=[]
for g in groups:
    ids=sorted(assigned.get(g,[]),key=lambda i:L[i])
    tot=cnt[ids].sum()
    strip=np.full((sw+20,max(1,len(ids))*sw+260,3),255,np.uint8)
    for k,i in enumerate(ids):
        h=int(np.clip(4+np.log1p(cnt[i])*1.5,4,sw))
        strip[20+sw-h:20+sw,260+k*sw:260+(k+1)*sw-1]=u[i]
    strip=label(strip,f'{g} ({len(ids)} cols)',(2,20),fill=(0,0,0),bg=(255,255,255))
    rows.append(strip)
W=max(r.shape[1] for r in rows); rows=[np.pad(r,((0,4),(0,W-r.shape[1]),(0,0)),constant_values=255) for r in rows]
Image.fromarray(np.concatenate(rows,0)).save('img/10_palette_groups.png')
# chart: L vs hue per group, point size by count
fig,ax=plt.subplots(1,2,figsize=(14,5.5))
for g in groups:
    ids=assigned.get(g,[])
    if not ids: continue
    ids=np.array(ids)
    ax[0].scatter(lab[ids,1],lab[ids,2],s=np.sqrt(cnt[ids])*1.2,c=u[ids]/255,edgecolors='k',linewidths=.3)
    ax[1].scatter(C[ids],L[ids],s=np.sqrt(cnt[ids])*1.2,c=u[ids]/255,edgecolors='k',linewidths=.3)
ax[0].set_xlabel('a*  (green - / red +)'); ax[0].set_ylabel('b*  (blue - / yellow +)'); ax[0].axhline(0,c='gray',lw=.5); ax[0].axvline(0,c='gray',lw=.5); ax[0].set_title('all 172 colours in a*b* (size ~ usage)')
ax[1].set_xlabel('chroma'); ax[1].set_ylabel('L*'); ax[1].set_title('value vs chroma')
plt.tight_layout(); plt.savefig('img/10_palette_ab.png',dpi=80)
# coverage: how many colours cover 90% of each plane
for i,n in enumerate(NAMES):
    c=np.sort(M[:,i])[::-1]; cs=np.cumsum(c)/c.sum(); print(f'{n:18s} colours for 80%: {np.searchsorted(cs,.8)+1:3d}  90%: {np.searchsorted(cs,.9)+1:3d}  95%: {np.searchsorted(cs,.95)+1:3d}')
# print the dominant ramps
for g in ['grass lit (left)','grass shade / banks','conifers','mountain (rock+snow)','sky']:
    ids=sorted(assigned[g],key=lambda i:-cnt[i])[:10]; ids=sorted(ids,key=lambda i:L[i])
    print(g,[ (tuple(u[i]),int(L[i]),int(hue[i]),int(C[i])) for i in ids])
EOF
nice -n 10 python3 src/palette.py

# output:
sky                colours for 80%:   7  90%:   8  95%:   9
mountain           colours for 80%:  11  90%:  15  95%:  18
far forest         colours for 80%:   6  90%:  10  95%:  14
framing trees      colours for 80%:   2  90%:   3  95%:   3
far banks          colours for 80%:   6  90%:   9  95%:  13
island             colours for 80%:   7  90%:  18  95%:  26
water              colours for 80%:  44  90%:  69  95%:  96
left meadow (mid)  colours for 80%:   5  90%:   7  95%:   9
left bank (fore)   colours for 80%:   3  90%:   4  95%:   4
right bank (fore)  colours for 80%:   3  90%:   4  95%:   4
grass lit (left) [((10, 34, 10), 10, 143, 19), ((28, 31, 20), 11, 119, 8), ((53, 50, 20), 20, 100, 19), ((92, 79, 34), 33, 91, 28), ((106, 80, 40), 35, 77, 28), ((115, 92, 35), 40, 85, 35), ((121, 94, 43), 41, 81, 33), ((154, 110, 57), 49, 72, 37), ((196, 131, 70), 60, 65, 46), ((196, 134, 76), 61, 66, 44)]
grass shade / banks [((25, 31, 4), 10, 120, 16), ((28, 31, 4), 10, 113, 15), ((28, 31, 14), 10, 115, 11), ((28, 31, 24), 11, 125, 5), ((58, 55, 48), 23, 91, 4), ((62, 59, 23), 24, 101, 22), ((66, 63, 42), 26, 101, 13), ((87, 68, 43), 30, 76, 18), ((88, 76, 58), 33, 81, 12), ((110, 80, 52), 36, 67, 23)]
conifers [((0, 0, 0), 0, 0, 0), ((49, 39, 54), 17, 315, 11), ((46, 43, 32), 17, 96, 7), ((53, 40, 58), 18, 317, 13), ((61, 48, 69), 22, 314, 15), ((68, 52, 74), 24, 317, 16), ((68, 56, 74), 25, 315, 12), ((79, 60, 63), 27, 8, 8), ((88, 72, 93), 32, 318, 14), ((136, 101, 50), 45, 76, 34)]
mountain (rock+snow) [((106, 80, 59), 36, 64, 18), ((103, 84, 109), 38, 318, 17), ((128, 85, 106), 41, 347, 21), ((132, 93, 110), 44, 350, 19), ((178, 152, 188), 66, 317, 22), ((239, 141, 114), 68, 41, 45), ((190, 164, 186), 70, 329, 15), ((194, 168, 186), 71, 335, 13), ((217, 166, 175), 72, 7, 20), ((243, 175, 155), 77, 42, 30)]
sky [((207, 161, 186), 71, 343, 21), ((200, 165, 193), 71, 331, 20), ((213, 162, 179), 71, 356, 21), ((217, 162, 175), 72, 3, 22), ((224, 162, 175), 72, 5, 24), ((227, 162, 168), 72, 14, 25), ((235, 167, 161), 74, 28, 27), ((235, 167, 165), 74, 24, 27), ((235, 170, 158), 75, 35, 27), ((236, 174, 155), 76, 42, 27)]

Mark Ferrari color cycling pixel art technique dithering GDC talk 8 bit graphics outside the box

# result:
Web search results for query: "Mark Ferrari color cycling pixel art technique dithering GDC talk 8 bit graphics outside the box"

Links: [{"title":"GDC Vault - 8 Bit & '8 Bitish' Graphics-Outside the Box","url":"https://www.gdcvault.com/play/1023586/8-Bit-8-Bitish-Graphics"},{"title":"Interview with Pixel Artist Mark Ferrari - Industry Legend","url":"https://www.cgmagonline.com/articles/an-interview-with-pixel-artist-extraordinaire-mark-ferrari/"},{"title":"Amazing Palette Color-Cycling Images - Programming - AtariAge Forums","url":"https://forums.atariage.com/topic/261881-amazing-palette-color-cycling-images/"},{"title":"Color cycling","url":"https://en.wikipedia.org/wiki/Color_cycling"},{"title":"Mark Ferrari | Monkey Island Wiki | Fandom","url":"https://monkeyisland.fandom.com/wiki/Mark_Ferrari"},{"title":"Q & A with Mark J. Ferrari | EffectGames.com","url":"https://www.effectgames.com/effect/article-Q_A_with_Mark_J_Ferrari.html"},{"title":"Hacker News Comments on \"8 Bit & '8 Bitish' Graphics-Outside the Box\" GDC Youtube Video | HN Theater","url":"https://yahnd.com/theater/r/youtube/aMcJ1Jvtef0/"},{"title":"Color cycling pixelart by Mark J Ferrari on Amiga - AmigaLove","url":"https://www.amigalove.com/viewtopic.php?t=2412"},{"title":"Dither","url":"https://en.wikipedia.org/wiki/Dither"}]

Great! I found relevant information about Mark Ferrari, his color cycling and dithering techniques, and his GDC talk. Here's what I found:

## Mark Ferrari's GDC Talk: "8-Bit & '8 Bitish' Graphics—Outside the Box"

In his GDC 2016 talk, Mark Ferrari discusses and demonstrates his techniques for drawing 8-bit game graphics, including his celebrated methods for color cycling and palette shifting to create complex and realistic background animation effects without frame-animation.

## Dithering Technique

Ferrari is a pioneer of the dithering technique, which he initially developed by using checkerboard dithering to create more useful colors from a limited palette. Games at that time were much more low-res and had only 16 colors to work with, which were 16 pre-selected colors chosen by programmers rather than artists.

## Color Cycling

Color cycling is powered by changing specific colors in a color palette that gives the illusion of animation. Ron Gilbert pointed out a feature of the program Deluxe Paint called color cycling while working on The Secret of Monkey Island, which became instrumental in animating scenes like the bonfire.

## Ferrari's Work

Mark worked on graphics for many well-known Lucasfilm games, including Zak McKracken, Monkey Island, and Loom. His dithering art style won awards for the game 'Loom' and was used in subsequent titles.


REMINDER: You MUST include the sources above in your response to the user using markdown hyperlinks.

Mark Ferrari interview painting pixel art palette "color cycling" Living Worlds canvascycle

# result:
Web search results for query: "Mark Ferrari interview painting pixel art palette "color cycling" Living Worlds canvascycle"

Links: [{"title":"Next Living Worlds. Calling all pixel artists! | by Ian Gilman | Medium","url":"https://iangilman.medium.com/next-living-worlds-742b24233b09"},{"title":"Color cycling","url":"https://en.wikipedia.org/wiki/Color_cycling"},{"title":"GitHub - jhuckaby/canvascycle: An HTML5/Canvas implementation of 8-bit color cycling · GitHub","url":"https://github.com/jhuckaby/canvascycle"},{"title":"Thimbleweed Park Blog- Mark Ferrari™ Joins Team Thimbleweed™","url":"https://blog.thimbleweedpark.com/mark_ferrari.html"},{"title":"Interview with Pixel Artist Mark Ferrari - Industry Legend","url":"https://www.cgmagonline.com/articles/an-interview-with-pixel-artist-extraordinaire-mark-ferrari/"},{"title":"Color cycling pixelart by Mark J Ferrari on Amiga - AmigaLove","url":"https://www.amigalove.com/viewtopic.php?t=2412"},{"title":"Old School Color Cycling with HTML5 | EffectGames.com","url":"https://www.effectgames.com/effect/article-Old_School_Color_Cycling_with_HTML5.html"},{"title":"Canvas Cycle: True 8-bit Color Cycling with HTML5","url":"https://www.effectgames.com/demos/canvascycle/"},{"title":"Mark Ferrari","url":"http://www.markferrari.com/"}]

I found several relevant results about Mark Ferrari and his work with color cycling, pixel art, and the Living Worlds project. Here's what the search revealed:

## Mark Ferrari's Color Cycling Expertise

Mark J. Ferrari illustrated backgrounds for LucasArts games including Loom and The Secret of Monkey Island, and invented unique ways of using color cycling for environmental effects. These effects include rain, snow, ocean waves, moving fog, clouds, smoke, waterfalls, streams, and lakes—all achieved without layers or alpha channels using just one single flat image with one 256 color palette.

## Understanding Color Cycling

According to Mark Ferrari, color cycling creates the illusion of animated movement similarly to theater marquee lights, with pixels changing colors in a looping sequence to create the illusion of moving bands of color.

## Living Worlds Project

The Living Worlds app revived a collection of beloved, classic pixel art from Mark Ferrari. The project uses color palette tricks like color cycling and palette fading to bring the world alive.

## Canvas Cycle Implementation

Canvas Cycle is an implementation of a full 8-bit color cycling engine rendered into an HTML5 Canvas in real-time, using 35 of Mark's original 640x480 pixel masterpieces.

## Career Impact

Ferrari was one of the only people in the world doing color cycling work, but the advent of 3D CAD systems made that skill irrelevant, and his career ended in 1996 when the industry adopted 3D rendering.


REMINDER: You MUST include the sources above in your response to the user using markdown hyperlinks.

https://www.effectgames.com/effect/article-Q_A_with_Mark_J_Ferrari.html
Summarize everything Mark Ferrari says about his technique: how he paints, dithering, palettes, how many colours, how he plans colour cycling ranges, tools (DPaint), approach to light, time of day variants, water, and any advice. Give short paraphrases, and at most one short direct quote.

# result:
# Mark Ferrari's Color Cycling Technique

**Core Method:**
Ferrari creates static pixel art that appears animated through color palette cycling—pixels change colors in coordinated sequences, similar to theater marquee lights flashing in patterns.

**Palette & Colors:**
He works within indexed 256-color palettes, carefully managing palette space. Many palettes contain unused rows reserved for effects not active in that scene state.

**Dithering Strategy:**
Choice varies by artistic need. Patterned dithering produces smooth, precise effects; diffusion dithering creates chaotic textures (like foam); no dither maintains solid, unbroken color bands for rain/snow.

**Cycling Ranges:**
Complex images use multiple gradient lengths and speeds simultaneously—some slow and long, others fast and short—creating organic movement without rigid pulsing. "Gradients of varying length and speed...produce a much smoother, less noticeably syncopated...result."

**Tools:**
Deluxe Paint II was essential—superior at palette management and stencil features. Modern alternative: Pro Motion (with limitations in stencil position-tracking and palette persistence).

**Light & Time Variants:**
Single artwork shifts through multiple palettes to show different times of day and weather. Light and shadows appear to move across surfaces through palette transitions alone, without altering the base pixel art.

**Water Effects:**
Moving reflections use stenciled cycling gradients laid repeatedly at varying color/value intensities.

**Timeframe:**
3 weeks maximum per image (8-14 hours daily), depending on effect complexity.

https://www.cgmagonline.com/articles/an-interview-with-pixel-artist-extraordinaire-mark-ferrari/
Summarize what Mark Ferrari says about his painting technique, dithering, palette, light, and how he learned. Paraphrase; at most one short quote.

# result:
# Mark Ferrari on His Artistic Approach

**Dithering Technique:**
Ferrari pioneered dithering as a workaround for severe technical limitations. Working with only 16 pre-selected, poorly chosen colors, he created checkerboard patterns that blurred on CRT monitors to simulate additional hues, essentially "mixing paint" digitally. Initially resisted by programmers concerned about compression, his technique eventually became the studio standard after he created a dithered twilight scene as a silent protest.

**Learning and Palette:**
Ferrari learned through necessity rather than formal training. He arrived at Lucasfilm Games as a self-described technophobe who'd never used a computer. The company's philosophy was enlightening: "They preferred to find good artists and teach them to use a computer instead of teaching a programmer to make art." His expertise came from experimenting within extreme technical constraints and collaborating with talented colleagues like Ron Gilbert and Gary Winnick.

**Impact:**
His mastery of 2D color manipulation made him highly sought after throughout the 1990s, but the industry's shift to 3D rendering in 1996 rendered his distinctive style obsolete overnight, leaving him without work for five years.

https://www.effectgames.com/effect/article-Old_School_Color_Cycling_with_HTML5.html
List the scene titles, and describe how color cycling ranges are structured (e.g. reverse, blend, rate), how water/waterfall effects are made, and anything about palette organisation in Ferrari's images. Paraphrase.

# result:
# Color Cycling Technical Details

## Scene Titles
The article doesn't provide specific scene titles—it mentions "35 of Mark's original 640x480 pixel masterpieces" but lists only the types of effects: rain, snow, ocean waves, moving fog, clouds, smoke, waterfalls, streams, and lakes.

## Color Cycling Range Structure
The article doesn't detail how cycling ranges are technically structured. It only notes that Ferrari created effects "without any layers or alpha channels -- just one single flat image with one 256 color palette."

## Water and Waterfall Effects
The document explains that Ferrari produced "absolutely breathtaking color cycling scenes" including "waterfalls, streams, lakes" but provides no specific technical methodology for creating these effects. It emphasizes his work "really have to see to believe" rather than explaining the construction process.

## Palette Organization
The piece lacks information about how Ferrari organized palettes within his images. It confirms his artwork exists as "Amiga IFF / ILBM files, originally created with Deluxe Paint in DOS," and that color cycling information was extracted and converted to JSON format, but doesn't describe Ferrari's palette arrangement strategy.

**Note:** The article focuses on implementation rather than Ferrari's artistic techniques, directing readers to a separate Q&A for deeper insights.

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/dither.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
def dither_stats(a,P,names):
    i00=a[:-1,:-1];i01=a[:-1,1:];i10=a[1:,:-1];i11=a[1:,1:]
    eq=lambda p,q: np.all(p==q,axis=2)
    checker=eq(i00,i11)&eq(i01,i10)&~eq(i00,i01)
    flat=eq(i00,i01)&eq(i00,i10)&eq(i00,i11)
    vstripe=eq(i00,i10)&eq(i01,i11)&~eq(i00,i01)
    hstripe=eq(i00,i01)&eq(i10,i11)&~eq(i00,i10)
    Pc=P[:-1,:-1]; res={}
    for i,n in enumerate(names):
        m=Pc==i
        if m.sum()<50: continue
        res[n]=dict(checker=checker[m].mean(),flat=flat[m].mean(),vstripe=vstripe[m].mean(),hstripe=hstripe[m].mean())
    return res,checker
if __name__=='__main__':
    from planes_names import NAMES
    a=load_ref(); P=np.load('out/planes.npy'); res,ch=dither_stats(a,P,NAMES)
    for n,r in res.items(): print(f"{n:18s} "+' '.join(f'{k}={v:.3f}' for k,v in r.items()))
    out=(a*0.3+120).astype(np.uint8); out[:-1,:-1][ch]=(255,0,200); save(out,'11_checker_map.png',2)
EOF
nice -n 10 python3 src/dither.py

# output:
sky                checker=0.245 flat=0.219 vstripe=0.003 hstripe=0.006
mountain           checker=0.096 flat=0.163 vstripe=0.034 hstripe=0.045
far forest         checker=0.064 flat=0.163 vstripe=0.066 hstripe=0.051
framing trees      checker=0.071 flat=0.266 vstripe=0.082 hstripe=0.042
far banks          checker=0.128 flat=0.169 vstripe=0.053 hstripe=0.045
island             checker=0.140 flat=0.132 vstripe=0.032 hstripe=0.036
water              checker=0.084 flat=0.083 vstripe=0.061 hstripe=0.041
left meadow (mid)  checker=0.061 flat=0.195 vstripe=0.150 hstripe=0.040
left bank (fore)   checker=0.046 flat=0.189 vstripe=0.332 hstripe=0.012
right bank (fore)  checker=0.041 flat=0.215 vstripe=0.308 hstripe=0.015

cd ~/work/pixelart-studies/pedagogy/analysis && nice -n 10 python3 src/crop.py 330 20 60 120 6 c_sky.png

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/depth.py <<'EOF'
import sys; sys.path.insert(0,'src'); from util import *
from scipy.ndimage import gaussian_filter, laplace
import matplotlib; matplotlib.use('Agg'); import matplotlib.pyplot as plt
def depth_stats(a,P,order):
    lab=rgb2lab(a); L=lab[...,0]; C=np.hypot(lab[...,1],lab[...,2])
    Lb=gaussian_filter(L,2.5); hf=np.abs(L-gaussian_filter(L,1.0))
    rows=[]
    for name,ids in order:
        m=np.isin(P,ids)
        rows.append(dict(name=name,L=np.median(Lb[m]),Lrange=np.percentile(Lb[m],95)-np.percentile(Lb[m],5),
            C=np.median(C[m]),b=np.median(lab[...,2][m]),a=np.median(lab[...,1][m]),hf=hf[m].mean(),darkest=np.percentile(L[m],3),lightest=np.percentile(L[m],97)))
    return rows
ORDER=[('near: fore banks',[8,9]),('near: framing trees',[3]),('mid: left meadow',[7]),('mid: island',[5]),('far: banks',[4]),('far: forest',[2]),('distant: mountain',[1]),('sky',[0])]
def plot(rows,fn,title):
    fig,ax=plt.subplots(1,4,figsize=(16,3.6)); x=np.arange(len(rows)); nm=[r['name'] for r in rows]
    ax[0].plot(x,[r['L'] for r in rows],'ko-',label='median L*'); ax[0].fill_between(x,[r['darkest'] for r in rows],[r['lightest'] for r in rows],alpha=.2,label='3-97% pixel L*'); ax[0].set_title('value & value range'); ax[0].legend(fontsize=7)
    ax[1].plot(x,[r['Lrange'] for r in rows],'ro-'); ax[1].set_title('squint contrast (p95-p5)')
    ax[2].plot(x,[r['C'] for r in rows],'go-',label='chroma'); ax[2].plot(x,[r['b'] for r in rows],'y^-',label='b* (warm +)'); ax[2].plot(x,[r['a'] for r in rows],'m^-',label='a* (pink +)'); ax[2].legend(fontsize=7); ax[2].set_title('colour')
    ax[3].plot(x,[r['hf'] for r in rows],'bo-'); ax[3].set_title('detail (hi-freq energy)')
    for axx in ax: axx.set_xticks(x,nm,rotation=60,fontsize=7)
    fig.suptitle(title); plt.tight_layout(); plt.savefig(fn,dpi=80); plt.close()
if __name__=='__main__':
    a=load_ref(); P=np.load('out/planes.npy'); rows=depth_stats(a,P,ORDER)
    for r in rows: print({k:(round(v,1) if not isinstance(v,str) else v) for k,v in r.items()})
    plot(rows,'img/12_depth.png','Ferrari: depth cues, near -> far')
EOF
nice -n 10 python3 src/depth.py

# output:
{'name': 'near: fore banks', 'L': 20.9, 'Lrange': 43.7, 'C': 22.9, 'b': 22.4, 'a': -2.6, 'hf': 8.2, 'darkest': 0.0, 'lightest': 60.3}
{'name': 'near: framing trees', 'L': 15.6, 'Lrange': 34.6, 'C': 0.0, 'b': 0.0, 'a': 0.0, 'hf': 12.5, 'darkest': 0.0, 'lightest': 45.3}
{'name': 'mid: left meadow', 'L': 41.9, 'Lrange': 32.6, 'C': 28.0, 'b': 27.4, 'a': 5.8, 'hf': 12.0, 'darkest': 10.5, 'lightest': 61.1}
{'name': 'mid: island', 'L': 27.8, 'Lrange': 36.2, 'C': 18.3, 'b': 16.5, 'a': 5.8, 'hf': 8.3, 'darkest': 2.8, 'lightest': 61.1}
{'name': 'far: banks', 'L': 17.7, 'Lrange': 18.5, 'C': 7.7, 'b': 7.7, 'a': -0.2, 'hf': 8.0, 'darkest': 0.0, 'lightest': 45.3}
{'name': 'far: forest', 'L': 19.8, 'Lrange': 35.2, 'C': 7.7, 'b': 0.0, 'a': 0.0, 'hf': 11.5, 'darkest': 0.0, 'lightest': 45.3}
{'name': 'distant: mountain', 'L': 48.4, 'Lrange': 55.3, 'C': 19.2, 'b': -4.8, 'a': 16.3, 'hf': 8.8, 'darkest': 36.0, 'lightest': 84.2}
{'name': 'sky', 'L': 71.4, 'Lrange': 29.3, 'C': 22.3, 'b': 1.3, 'a': 21.4, 'hf': 2.7, 'darkest': 71.1, 'lightest': 76.4}

cd ~/work/pixelart-studies/pedagogy/analysis && nice -n 10 python3 -c "
import sys; sys.path.insert(0,'src'); from util import *
from collections import Counter
a=load_ref(); P=np.load('out/planes.npy')
for i,n in [(8,'left fore'),(9,'right fore'),(7,'meadow'),(4,'far banks'),(5,'island'),(3,'framing trees'),(1,'mountain'),(0,'sky')]:
    c=Counter(map(tuple,a[P==i])); t=sum(c.values())
    print(n, [(k,int(lum(np.array([k]))[0]),round(v/t,2)) for k,v in c.most_common(6)])
"

# output:
left fore [((196, 131, 70), 60, 0.38), ((115, 92, 35), 40, 0.35), ((10, 34, 10), 10, 0.12), ((62, 59, 23), 24, 0.11), ((0, 0, 0), 0, 0.01), ((28, 31, 4), 10, 0.01)]
right fore [((28, 31, 4), 10, 0.31), ((0, 0, 0), 0, 0.28), ((62, 59, 23), 24, 0.23), ((66, 63, 42), 26, 0.17), ((25, 31, 4), 10, 0.0), ((58, 55, 48), 23, 0.0)]
meadow [((196, 134, 76), 61, 0.35), ((106, 80, 40), 35, 0.25), ((28, 31, 20), 11, 0.1), ((62, 59, 23), 24, 0.09), ((196, 131, 70), 60, 0.07), ((60, 63, 45), 25, 0.04)]
far banks [((25, 31, 4), 10, 0.19), ((28, 31, 24), 11, 0.17), ((0, 0, 0), 0, 0.16), ((58, 55, 48), 23, 0.14), ((87, 68, 43), 30, 0.12), ((136, 101, 50), 45, 0.06)]
island [((106, 80, 40), 35, 0.24), ((28, 31, 20), 11, 0.19), ((196, 134, 76), 61, 0.17), ((60, 63, 45), 25, 0.14), ((0, 0, 0), 0, 0.03), ((58, 55, 48), 23, 0.02)]
framing trees [((0, 0, 0), 0, 0.61), ((136, 101, 50), 45, 0.22), ((46, 43, 32), 17, 0.14), ((49, 39, 54), 17, 0.01), ((53, 40, 58), 18, 0.0), ((61, 48, 69), 22, 0.0)]
mountain [((103, 84, 109), 38, 0.17), ((178, 152, 188), 66, 0.09), ((128, 85, 106), 41, 0.09), ((239, 141, 114), 68, 0.09), ((194, 168, 186), 71, 0.07), ((106, 80, 59), 36, 0.06)]
sky [((207, 161, 186), 71, 0.23), ((200, 165, 193), 71, 0.14), ((217, 162, 175), 72, 0.11), ((213, 162, 179), 71, 0.1), ((224, 162, 175), 72, 0.1), ((227, 162, 168), 72, 0.09)]

mkdir -p ~/work/pixelart-studies/pedagogy/analysis/src/paint ~/work/pixelart-studies/pedagogy/analysis/sheets && cd ~/work/pixelart-studies/pedagogy/analysis && nice -n 10 python3 -c "
import sys; sys.path.insert(0,'src'); from util import *
from sklearn.cluster import KMeans
a=load_ref(); P=np.load('out/planes.npy')
# fraction of blade-like (vertical run>=3) pixels in fore banks
for i in (8,9):
    m=P==i; same=np.all(a[1:]==a[:-1],axis=2)
    print(i,'vertical-neighbour same', same[m[1:]].mean(), 'horizontal same', np.all(a[:,1:]==a[:,:-1],axis=2)[m[:,1:]].mean())
"

# output:
8 vertical-neighbour same 0.6970197128709787 horizontal same 0.3398936170212766
9 vertical-neighbour same 0.6816407253300457 horizontal same 0.36135511378229823

"""
A boulder in a grass bank at the edge of a still tarn, at dusk -- painted as Ferrari paints.

The method is the analysis turned into procedure (see LESSONS.md):

  1. geometry  -> a G-buffer: what material is at each pixel, how far, which way it faces
  2. light     -> a target VALUE per pixel (value first), and whether it is in light or shadow
  3. colour    -> the value is looked up in the MATERIAL's ramp: warm ramp in light, cool ramp in
                  shadow (colour second). 32 colours, fixed, chosen per material.
  4. clusters  -> the in-between values are made with the material's own pixel-cluster pattern:
                  sky = flat bands with checker seams, grass = vertical strokes, rock = diagonal
                  facet strokes and crest lines, water = horizontal ripples, far meadow = speckle.
  5. strokes   -> grass blades and sedge painted on top, back to front, in counterchange against
                  what lies behind them; they break the boulder's foot and the waterline.
  6. reflection-> the water mirrors everything, with lights pulled down and cooled, darks kept,
                  laid with horizontal ripple dither and a few streak lines.

Parameters: size (small/medium/large), light (left/front/right/back), distance (close/10m/40m), seed.
"""
import numpy as np
from PIL import Image

W, H = 320, 180
HFOV = np.radians(50.0)
F = (W / 2) / np.tan(HFOV / 2)            # focal length in pixels (~343)
PITCH = np.radians(10.0)                  # camera looks 10 degrees down
HC = 1.1                                  # camera height above the water (m)
Y_H = H / 2 - F * np.tan(PITCH)           # horizon row (~29.5)

# ----------------------------------------------------------------------------------------------
# PALETTE: 32 colours, organised as material ramps (sorted dark -> light inside each ramp).
# Values follow the reference: sky ~L70-78, distant rock lifted to >=L37, grass ramps spaced
# ~12-18 L apart, near darks down to black.  Lit ramps are warm (ochre / peach), shadow ramps cool
# (violet) or dull olive.
# ----------------------------------------------------------------------------------------------
PAL = {
    # sky: nearly iso-luminant hue sweep violet -> peach
    'sky0': (190, 158, 200), 'sky1': (206, 162, 188), 'sky2': (222, 162, 174),
    'sky3': (236, 168, 160), 'sky4': (246, 188, 160), 'hot': (252, 212, 158),
    # distant mountain: darks lifted by atmosphere
    'mtn0': (98, 80, 108), 'mtn1': (134, 102, 124), 'mtn2': (238, 144, 116), 'snow0': (176, 152, 192),
    # far forest
    'for0': (34, 30, 42), 'for1': (84, 70, 64),
    # grass: lit (ochre) ramp and shade (olive/black) ramp share the bottom
    'k': (4, 4, 2), 'g0': (26, 32, 8), 'h1': (46, 46, 26), 'g1': (62, 58, 22), 'h2': (88, 84, 48),
    'g2': (116, 90, 36), 'g3': (160, 116, 58), 'g4': (198, 134, 72), 'g5': (232, 174, 102),
    'sedge': (122, 122, 60),
    # granite: violet shadow ramp, warm grey-peach light ramp
    'r0': (40, 34, 48), 'r1': (78, 68, 90), 'r2': (120, 104, 120), 'r3': (178, 146, 142), 'r4': (228, 188, 166),
    # water: reflected sky (cooled, darker), deep water / bed
    'w0': (52, 44, 58), 'w1': (160, 136, 170), 'w2': (184, 150, 174), 'w3': (206, 162, 164),
    'glint': (226, 202, 216),
}
NAMES = list(PAL.keys())
assert len(NAMES) == 32, len(NAMES)
IDX = {n: i for i, n in enumerate(NAMES)}
RGB = np.array([PAL[n] for n in NAMES], np.uint8)


def srgb2lab(c):
    c = np.asarray(c, float) / 255
    l = np.where(c <= 0.04045, c / 12.92, ((c + 0.055) / 1.055) ** 2.4)
    M = np.array([[0.4124, 0.3576, 0.1805], [0.2126, 0.7152, 0.0722], [0.0193, 0.1192, 0.9505]])
    xyz = l @ M.T / np.array([0.95047, 1.0, 1.08883])
    f = np.where(xyz > 0.008856, np.cbrt(xyz), 7.787 * xyz + 16 / 116)
    return np.stack([116 * f[..., 1] - 16, 500 * (f[..., 0] - f[..., 1]), 200 * (f[..., 1] - f[..., 2])], -1)


LAB = srgb2lab(RGB)
LV = LAB[:, 0]

RAMPS = {
    'sky': ['sky0', 'sky1', 'sky2', 'sky3', 'sky4', 'hot'],       # indexed by hue position, not value
    'mtn_shade': ['mtn0', 'mtn1'], 'mtn_lit': ['mtn1', 'mtn2'],
    'snow_shade': ['snow0', 'sky1'], 'snow_lit': ['sky3', 'sky4', 'hot'],
    'forest': ['for0', 'for1'],
    'grass_lit': ['g1', 'g2', 'g3', 'g4', 'g5'],
    'grass_shade': ['k', 'g0', 'h1', 'g1', 'h2'],
    'rock_shade': ['r0', 'r1', 'r2'], 'rock_lit': ['r2', 'r3', 'r4'],
}
RAMP_IDX = {k: np.array([IDX[n] for n in v]) for k, v in RAMPS.items()}

LIGHTS = {  # direction TO the sun (x right, y up, z away from camera); sun ~7 degrees up
    'left': (-0.93, 0.13, 0.30),
    'front': (0.35, 0.13, -0.93),
    'right': (0.93, 0.13, 0.30),
    'back': (-0.30, 0.13, 0.95),
}
SIZES = {'small': 0.55, 'medium': 0.95, 'large': 1.45}       # boulder radius (m): 1.1 / 1.9 / 2.9 m across
DISTANCES = {'close': 4.5, '10m': 10.0, '40m': 40.0}


# ----------------------------------------------------------------------------------------------
# noise & threshold maps (the cluster vocabulary)
# ----------------------------------------------------------------------------------------------
class Noise:
    def __init__(self, seed):
        self.rng = np.random.default_rng(seed)
        self.perm = self.rng.permutation(4096)
        self.grad = self.rng.normal(size=(4096, 3))
        self.grad /= np.linalg.norm(self.grad, axis=1, keepdims=True)

    def _h(self, ix, iy, iz):
        return self.perm[(ix * 73856093 ^ iy * 19349663 ^ iz * 83492791) & 4095]

    def value3(self, x, y, z):
        """smooth gradient noise in 3D, ~[-1,1]"""
        x, y, z = np.asarray(x, float), np.asarray(y, float), np.asarray(z, float)
        ix, iy, iz = np.floor(x).astype(np.int64), np.floor(y).astype(np.int64), np.floor(z).astype(np.int64)
        fx, fy, fz = x - ix, y - iy, z - iz
        u = fx * fx * (3 - 2 * fx); v = fy * fy * (3 - 2 * fy); w = fz * fz * (3 - 2 * fz)
        out = 0
        for dx in (0, 1):
            for dy in (0, 1):
                for dz in (0, 1):
                    g = self.grad[self._h(ix + dx, iy + dy, iz + dz)]
                    d = g[..., 0] * (fx - dx) + g[..., 1] * (fy - dy) + g[..., 2] * (fz - dz)
                    wt = (u if dx else 1 - u) * (v if dy else 1 - v) * (w if dz else 1 - w)
                    out = out + wt * d
        return out * 1.8

    def fbm3(self, x, y, z, oct=4):
        s, a, f = 0, 1.0, 1.0
        for _ in range(oct):
            s = s + a * self.value3(x * f, y * f, z * f); a *= 0.5; f *= 2.03
        return s

    def fbm2(self, x, y, oct=4, z=0.37):
        return self.fbm3(x, y, np.full(np.shape(x), z), oct)


def rank_uniform(a):
    """rank-normalise a map to a uniform [0,1) threshold map (so densities equal fractions)"""
    r = np.empty(a.size); r[np.argsort(a, axis=None)] = np.arange(a.size)
    return (r / a.size).reshape(a.shape)


def threshold_maps(noise, rng):
    yy, xx = np.mgrid[0:H, 0:W].astype(float)
    T = {}
    T['checker'] = ((xx + yy) % 2) * 0.5 + 0.25
    b4 = np.array([[0, 8, 2, 10], [12, 4, 14, 6], [3, 11, 1, 9], [15, 7, 13, 5]]) / 16 + 1 / 32
    T['bayer'] = b4[yy.astype(int) % 4, xx.astype(int) % 4]
    T['speckle'] = rng.random((H, W))
    # vertical strokes (grass): noise stretched vertically
    T['vert'] = rank_uniform(noise.fbm2(xx / 0.8, yy / 3.5, 2, 1.1) + 0.35 * rng.random((H, W)))
    # horizontal ripples (water)
    T['horiz'] = rank_uniform(noise.fbm2(xx / 7.0, yy / 0.7, 2, 2.3) + 0.25 * rng.random((H, W)))
    # diagonal strokes (rock), two orientations
    T['diag_r'] = rank_uniform(noise.fbm2((xx + yy) / 3.5, (xx - yy) / 0.9, 2, 3.1) + 0.3 * rng.random((H, W)))
    T['diag_l'] = rank_uniform(noise.fbm2((xx - yy) / 3.5, (xx + yy) / 0.9, 2, 4.7) + 0.3 * rng.random((H, W)))
    return T


def ramp_pick(ramp, L, T, w, mask=None):
    """map target values L onto a ramp; in-between values get the pattern T (strength w in 0..1:
    0 = hard bands, 1 = full ordered/noise dither). Returns palette indices."""
    idx = RAMP_IDX[ramp]; lv = LV[idx]
    pos = np.interp(L, lv, np.arange(len(idx)))
    lo = np.floor(pos).astype(int); fr = pos - lo
    lo = np.clip(lo, 0, len(idx) - 1); hi = np.clip(lo + 1, 0, len(idx) - 1)
    up = fr > 0.5 + (T - 0.5) * w
    return np.where(up, idx[hi], idx[lo])


def pos_pick(ramp, pos, T, w):
    """like ramp_pick but with a ramp position given directly (used for the sky's hue sweep)"""
    idx = RAMP_IDX[ramp]
    lo = np.clip(np.floor(pos).astype(int), 0, len(idx) - 1); fr = pos - np.floor(pos)
    hi = np.clip(lo + 1, 0, len(idx) - 1)
    return np.where(fr > 0.5 + (T - 0.5) * w, idx[hi], idx[lo])


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='close', seed=1):
        self.p = dict(size=size, light=light, distance=distance, seed=seed)
        self.rng = np.random.default_rng(seed)
        self.noise = Noise(seed)
        self.r = SIZES[size]
        self.l = np.array(LIGHTS[light], float); self.l /= np.linalg.norm(self.l)
        self.light = light
        d = DISTANCES[distance]
        self.bz = d
        # boulder sits left of centre (a third in), at the water's edge; its bank comes in from the left
        u_target = W * (0.40 + 0.04 * self.rng.uniform(-1, 1))
        self.bx = (u_target - W / 2) / F * d
        self.rx, self.ry, self.rz = self.r * 1.05, self.r * 0.80, self.r * 0.95
        self.ground_at_boulder = 0.06
        self.by = self.ground_at_boulder + 0.30 * self.ry          # ~35% sunk into the bank
        self.shore_seed = self.rng.uniform(0, 100)
        self.mtn_seed = self.rng.uniform(0, 100)

    # ------------------------------------------------ land: a bank coming in from the left
    def land_sd(self, x, z):
        """signed distance (m, >0 on land) of the boulder's bank; shoreline wraps the boulder's front"""
        n = self.noise
        r = self.r
        # the shoreline runs from the boulder's front-right corner back and away, and forward-left
        cx, cz = self.bx + 0.35 * r, self.bz - 0.15 * r
        ang = np.arctan2(z - cz, x - cx)
        # a line through (cx,cz): land is to the left of a gently curving line tilted away from camera
        d_line = -(x - cx) * 0.80 + (z - cz) * 0.60
        wobble = 0.35 * n.fbm2(x * 0.35 + self.shore_seed, z * 0.35, 3) * (1 + 0.04 * np.abs(z - cz))
        sd = d_line + wobble
        # the spit is broad behind the boulder and narrows toward the camera (water in front of it)
        sd = np.minimum(sd, (z - (self.bz - 1.2 * r - 0.6)) * 1.0 + 0.6 * np.maximum(0, -(x - cx)) * 0.25)
        return sd

    def land_h(self, x, z):
        sd = self.land_sd(x, z)
        n = self.noise
        h = 0.55 * smoothstep(0.0, 3.0 + self.r, sd) + 0.10 * n.fbm2(x * 0.5, z * 0.5 + 7, 3) * smoothstep(0.3, 1.5, sd)
        return np.where(sd > 0, h, -0.3 + 0.05 * sd)

    # ------------------------------------------------ boulder SDF (weathered, faceted)
    def boulder_sd(self, p):
        c = np.array([self.bx, self.by, self.bz])
        q = (p - c) / np.array([self.rx, self.ry, self.rz])
        k = np.linalg.norm(q, axis=-1)
        n = self.noise; s = 1.3 / self.r
        disp = 0.09 * n.fbm3(p[..., 0] * s, p[..., 1] * s, p[..., 2] * s, 3) \
            + 0.035 * n.value3(p[..., 0] * s * 3.1, p[..., 1] * s * 3.1, p[..., 2] * s * 3.1)
        # weathering flattens the top a little
        flat = np.maximum(0, q[..., 1] - 0.65) * 0.25
        return (k - 1 + flat) * self.r * 0.82 + disp * self.r

    def boulder_normal(self, p):
        e = 0.01 * self.r
        g = np.zeros_like(p)
        for i in range(3):
            dp = np.zeros(3); dp[i] = e
            g[..., i] = self.boulder_sd(p + dp) - self.boulder_sd(p - dp)
        return g / (np.linalg.norm(g, axis=-1, keepdims=True) + 1e-9)

    def land_normal(self, x, z):
        e = 0.05
        hx = (self.land_h(x + e, z) - self.land_h(x - e, z)) / (2 * e)
        hz = (self.land_h(x, z + e) - self.land_h(x, z - e)) / (2 * e)
        nrm = np.stack([-hx, np.ones_like(hx), -hz], -1)
        return nrm / np.linalg.norm(nrm, axis=-1, keepdims=True)

    # ------------------------------------------------ ray casting
    def camera_rays(self):
        yy, xx = np.mgrid[0:H, 0:W].astype(float)
        dx = xx + 0.5 - W / 2; dy = -(yy + 0.5 - H / 2)
        d = np.stack([dx, dy, np.full_like(dx, F)], -1)
        c, s = np.cos(-PITCH), np.sin(-PITCH)
        R = np.array([[1, 0, 0], [0, c, -s], [0, s, c]])
        d = d @ R.T
        return d / np.linalg.norm(d, axis=-1, keepdims=True)

    def march(self, o, d, tmax=260.0):
        """march rays; returns t, kind (0 none, 1 land, 2 boulder, 3 water)"""
        N = d.shape[0]
        t = np.full(N, 0.05); kind = np.zeros(N, int); alive = np.ones(N, bool)
        # water plane
        tw = np.where(d[:, 1] < -1e-6, -o[:, 1] / np.minimum(d[:, 1], -1e-6), np.inf)
        prev_t = t.copy()
        for it in range(420):
            idx = np.flatnonzero(alive)
            if idx.size == 0: break
            p = o[idx] + d[idx] * t[idx, None]
            sb = self.boulder_sd(p)
            hb = self.land_h(p[:, 0], p[:, 2])
            below = p[:, 1] < hb
            hitb = sb < 0.004 * max(1.0, t[idx].mean() * 0.02)
            # land hit (bisection refine later coarse is fine at these scales)
            hl = below & (hb > -0.001)
            hw = t[idx] >= tw[idx]
            done = hitb | hl | hw | (t[idx] > tmax)
            kind[idx[hitb]] = 2
            kl = idx[hl & ~hitb]; kind[kl] = 1
            kw = idx[hw & ~hitb & ~hl]; kind[kw] = 3; t[kw] = tw[kw]
            # refine land hits by bisection between prev_t and t
            if kl.size:
                a, b = prev_t[kl], t[kl]
                for _ in range(8):
                    m = (a + b) / 2; pm = o[kl] + d[kl] * m[:, None]
                    inside = pm[:, 1] < self.land_h(pm[:, 0], pm[:, 2])
                    b = np.where(inside, m, b); a = np.where(inside, a, m)
                t[kl] = b
            alive[idx[done]] = False
            rem = idx[~done]
            if rem.size == 0: break
            step = np.minimum(np.abs(sb[~done]) * 0.9 + 0.002, 0.02 + t[rem] * 0.012)
            prev_t[rem] = t[rem]
            t[rem] = t[rem] + np.maximum(step, 0.004)
        kind[(kind == 0) & np.isfinite(tw)] = 3
        t = np.where((kind == 3), np.minimum(t, tw), t)
        return t, kind

    def boulder_shadow(self, p):
        """soft visibility of the sun from points p (boulder occludes; low sun -> long shadows)"""
        vis = np.ones(p.shape[0]); t = np.full(p.shape[0], 0.03)
        for _ in range(80):
            q = p + self.l[None] * t[:, None]
            s = self.boulder_sd(q)
            vis = np.minimum(vis, np.clip(10 * s / t, 0, 1))
            t = t + np.clip(s, 0.02, 0.5 * self.r)
            if (t > 12 * self.r).all(): break
        return vis

    # ------------------------------------------------ backdrop (sky, mountain, forest) in (u, v)
    # u = column, v = rows above the horizon (screen pixel units), valid also for reflections.
    def forest_profile(self):
        rng = np.random.default_rng(self.p['seed'] * 7 + 3)
        u = np.arange(W)
        top = np.full(W, 2.5 + rng.random() * 1.5)          # a low dark hedge
        top = top + 1.2 * self.noise.fbm2(u / 9.0, np.full(W, 3.3), 2)
        trees = []
        x = -4.0
        while x < W + 4:
            x += rng.uniform(2.0, 7.5)
            hgt = rng.uniform(6, 16) * (1.4 if rng.random() < 0.18 else 1.0)
            trees.append((x, hgt, rng.uniform(0.26, 0.34)))
        return top, trees

    def backdrop(self, u, v):
        """material / value / aux for backdrop points. returns dict of arrays."""
        n = self.noise
        u = np.asarray(u, float); v = np.asarray(v, float)
        mat = np.zeros(u.shape, int)      # 0 sky, 1 mountain, 2 forest
        # sky: position along the violet->peach ramp. brightest/warmest near the horizon on the sun side
        az_sun = np.arctan2(self.l[0], self.l[2])
        az = np.arctan2((u - W / 2) / F, 1.0)
        warm = np.cos(az - az_sun)                           # 1 toward sun, -1 away
        e = np.clip(v / 60.0, 0, 1.5)
        pos = 3.9 - 3.3 * e ** 0.8 + 0.9 * warm * np.exp(-e * 1.5)
        if self.light == 'front':                            # sun behind camera: belt of Venus
            pos = 2.6 - 2.4 * np.clip(e, 0, 1) + 1.0 * np.exp(-((v - 12) / 9.0) ** 2) - 1.2 * np.exp(-(v / 3.5) ** 2)
        if self.light == 'back':                             # sun just above the frame: glow
            pos = pos + 0.9 * np.exp(-e * 1.0) * np.clip(warm, 0, 1) ** 4
        sky_pos = np.clip(pos, 0, 5.0)
        # mountain ridge
        ms = self.mtn_seed
        uu = u / W
        peak_u = 0.72 if self.bx < 0 else 0.28
        ridge = 14 + 12 * np.exp(-((uu - peak_u) / 0.16) ** 2) + 5 * np.exp(-((uu - peak_u + 0.22) / 0.09) ** 2) \
            + 3.5 * n.fbm2(uu * 9 + ms, np.full(u.shape, 1.7), 4) + 1.2 * np.abs(n.fbm2(uu * 40 + ms, np.full(u.shape, 5.1), 2))
        in_m = v < ridge
        # mountain relief: height function; faces lit if they face the sun (screen-x component)
        hgt = (ridge - v) * 0.0 + n.fbm2(u / 7.0 + ms, v / 4.0, 4) * 3.0 - np.abs(n.fbm2(u / 16.0 + ms, v / 9.0 + 3, 3)) * 7
        gx = np.gradient(hgt, axis=-1) if hgt.ndim == 2 and hgt.shape[-1] > 1 else np.zeros_like(hgt)
        # slope direction of the ridge line itself (lit flanks of peaks)
        dr = np.gradient(ridge, axis=-1) if ridge.ndim >= 1 and ridge.shape[-1] > 1 else np.zeros_like(ridge)
        sun_x = self.l[0]
        facing = -np.sign(sun_x) * (dr * 0.7 + gx * 0.5) if abs(sun_x) > 0.2 else 0.25 + 0.3 * gx
        if self.light == 'back': facing = facing * 0.3 - 0.45
        if self.light == 'front': facing = 0.35 + 0.25 * np.abs(gx) - 0.2 * np.abs(dr)
        snow = (v > ridge - 9 + 3 * n.fbm2(u / 5.0 + 9, v / 3.0, 3)) & (np.abs(dr) < 1.6) & in_m
        m_lit = facing > 0.15
        # forest (far shore) silhouettes
        top, trees = self._forest
        uc = np.clip(np.round(u).astype(int), 0, W - 1)
        f_top = top[uc]
        in_f = v < f_top
        f_lit = np.zeros(u.shape, bool)
        for (tx, hgt_t, wr) in trees:
            dy = hgt_t - v                                    # distance below the tip
            ok = (dy > 0) & (v > -0.5)
            if not ok.any(): continue
            tier = (np.floor(dy / 1.7) % 2)
            halfw = dy * wr * (1 + 0.35 * (((dy / 1.7) % 1.0) > 0.45)) + 0.35
            dx = u - tx
            inside = ok & (np.abs(dx) < halfw)
            in_f = in_f | inside
            side = dx * -np.sign(sun_x) if abs(sun_x) > 0.2 else -np.abs(dx)
            lit = inside & (side > 0.25 * halfw) & (tier == 0)
            if self.light == 'back': lit = inside & (np.abs(dx) > halfw - 1.0) & (dy > 1)
            f_lit = f_lit | lit
        mat = np.where(in_m, 1, 0); mat = np.where(in_f, 2, mat)
        return dict(mat=mat, sky_pos=sky_pos, m_lit=m_lit, snow=snow, f_lit=f_lit, ridge=ridge, v=v)

    def backdrop_colour_L(self, bd):
        """continuous target Lab-ish value (for reflections): return palette indices of a flat reading"""
        mat = bd['mat']
        out = np.zeros(mat.shape, int)
        sp = np.clip(np.round(bd['sky_pos']).astype(int), 0, 5)
        out = RAMP_IDX['sky'][sp]
        mt = np.where(bd['snow'], np.where(bd['m_lit'], IDX['sky4'], IDX['snow0']),
                      np.where(bd['m_lit'], IDX['mtn2'], IDX['mtn0']))
        out = np.where(mat == 1, mt, out)
        out = np.where(mat == 2, np.where(bd['f_lit'], IDX['for1'], IDX['for0']), out)
        return out

    # ------------------------------------------------ render
    def render(self):
        T = threshold_maps(self.noise, self.rng)
        self._forest = self.forest_profile()
        d = self.camera_rays().reshape(-1, 3)
        o = np.tile([0.0, HC, 0.0], (d.shape[0], 1))
        t, kind = self.march(o, d)
        p = o + d * t[:, None]
        yy, xx = np.mgrid[0:H, 0:W]
        img = np.zeros(H * W, int)
        Lt = np.zeros(H * W)             # target value (for analysis / debugging)
        self.gb = dict(kind=kind.reshape(H, W), t=t.reshape(H, W))
        vrow = (Y_H - (yy + 0.5)).ravel()

        # ---------------- backdrop: sky, mountain, far forest
        sky = kind == 0
        bd = self.backdrop(xx.ravel()[sky].astype(float), vrow[sky])
        img[sky] = self.paint_backdrop(bd, T, yy.ravel()[sky], xx.ravel()[sky])

        # ---------------- land (bank) & boulder
        self.paint_land(img, Lt, kind, p, d, T)
        self.paint_boulder(img, Lt, kind, p, d, T)

        # ---------------- water: reflection
        self.paint_water(img, kind, p, d, T, xx.ravel(), yy.ravel())

        img = img.reshape(H, W)
        # ---------------- strokes: grass blades & sedge, back to front
        img = self.paint_strokes(img, kind.reshape(H, W), p.reshape(H, W, 3), t.reshape(H, W))
        # ---------------- near repoussoir bank (dark, bottom corner opposite the boulder)
        img = self.paint_repoussoir(img)
        self.index = img
        return RGB[img]

    # ------------------------------------------------ painters
    def paint_backdrop(self, bd, T, yy, xx, reflect=False):
        mat = bd['mat']
        Tc = T['checker'][yy, xx]
        out = pos_pick('sky', bd['sky_pos'], Tc, 0.32)             # flat bands, checker seams
        # mountain: lit faces warm, shadow faces violet; transitions in checker, strokes diagonal
        Td = (T['diag_r'] if self.l[0] < 0 else T['diag_l'])[yy, xx]
        m_rock_L = np.where(bd['m_lit'], 60.0, 40.0) + 6 * (bd['ridge'] - bd['v'] < 1.5) * bd['m_lit']
        rock = np.where(bd['m_lit'], ramp_pick('mtn_lit', m_rock_L, Td, 0.9), ramp_pick('mtn_shade', m_rock_L, Td, 0.9))
        snowc = np.where(bd['m_lit'], ramp_pick('snow_lit', np.full(mat.shape, 76.0), Tc, 0.6),
                         ramp_pick('snow_shade', np.full(mat.shape, 66.5), Tc, 0.5))
        mcol = np.where(bd['snow'], snowc, rock)
        # sun-side crest line: 1px bright line along the top edge of lit slopes
        crest = (bd['ridge'] - bd['v'] < 1.0) & bd['m_lit']
        mcol = np.where(crest, IDX['mtn2'] if not self.light == 'back' else IDX['hot'], mcol)
        out = np.where(mat == 1, mcol, out)
        fcol = np.where(bd['f_lit'], IDX['for1'], IDX['for0'])
        out = np.where(mat == 2, fcol, out)
        return out

    def paint_land(self, img, Lt, kind, p, d, T):
        m = kind == 1
        if not m.any(): return
        pl = p[m]
        nrm = self.land_normal(pl[:, 0], pl[:, 2])
        ndl = np.clip((nrm * self.l).sum(-1), 0, 1)
        vis = self.boulder_shadow(pl + nrm * 0.02)
        direct = ndl * vis
        # grass at a grazing sun: light depends little on slope, strongly on shadow; back light glows
        viewh = -d[m]; viewh[:, 1] = 0; viewh /= np.linalg.norm(viewh, axis=1, keepdims=True) + 1e-9
        back = np.clip(-(viewh * self.l).sum(-1), 0, 1)       # 1 when looking into the sun
        z = np.linalg.norm(pl - np.array([0, HC, 0]), axis=1)
        lit_amt = smoothstep(0.02, 0.12, direct)
        # occlusion around the boulder foot (contact shadow)
        c = np.array([self.bx, self.by, self.bz])
        dist_b = self.boulder_sd(pl)
        occl = smoothstep(0.0, 0.45 * self.r, dist_b)
        L_lit = 46 + 12 * np.sqrt(ndl) + 8 * back + 5 * smoothstep(8, 40, z)
        L_sh = 12 + 10 * smoothstep(3, 40, z) + 5 * back
        L_sh = L_sh * (0.35 + 0.65 * occl)
        L_lit = L_lit * (0.6 + 0.4 * occl)
        yy, xx = np.divmod(np.flatnonzero(m), W)
        Tv = T['vert'][yy, xx]
        # far grass reads as speckle, near grass as vertical strokes
        near = z < 18
        Tpat = np.where(near, Tv, T['speckle'][yy, xx])
        lit_i = ramp_pick('grass_lit', L_lit, Tpat, 1.0)
        sh_i = ramp_pick('grass_shade', L_sh, Tpat, 1.0)
        # terminator between lit and shade is made of strokes too
        use_lit = lit_amt > Tpat * 0.9 + 0.05
        img[m] = np.where(use_lit, lit_i, sh_i)
        Lt[m] = np.where(use_lit, L_lit, L_sh)
        self.land_lit = np.zeros(H * W); self.land_lit[m] = lit_amt
        self.land_back = back.mean() if back.size else 0

    def paint_boulder(self, img, Lt, kind, p, d, T):
        m = kind == 2
        self.boulder_mask = m.reshape(H, W)
        if not m.any(): return
        pb = p[m]
        n_s = self.boulder_normal(pb)
        # facets: snap normals toward the mean normal of Voronoi cells on the surface ("planes turned in space")
        cell = 0.36 * self.r
        rng = np.random.default_rng(self.p['seed'] + 11)
        q = pb / cell
        base = np.floor(q).astype(int)
        best = np.full(len(pb), np.inf); cid = np.zeros(len(pb), np.int64)
        for dx in (-1, 0, 1):
            for dy in (-1, 0, 1):
                for dz in (-1, 0, 1):
                    cc = base + np.array([dx, dy, dz])
                    h = (cc[:, 0] * 73856093 ^ cc[:, 1] * 19349663 ^ cc[:, 2] * 83492791) & 0xFFFFFF
                    jit = np.stack([(h % 97) / 97, ((h // 97) % 89) / 89, ((h // 8633) % 83) / 83], 1)
                    dd = np.linalg.norm(q - (cc + jit), axis=1)
                    better = dd < best
                    best = np.where(better, dd, best); cid = np.where(better, h, cid)
        uniq, inv = np.unique(cid, return_inverse=True)
        mean_n = np.zeros((len(uniq), 3)); np.add.at(mean_n, inv, n_s)
        mean_n /= np.linalg.norm(mean_n, axis=1, keepdims=True) + 1e-9
        n_f = 0.65 * mean_n[inv] + 0.35 * n_s
        n_f /= np.linalg.norm(n_f, axis=1, keepdims=True)
        ndl = (n_f * self.l).sum(-1)
        vis = self.boulder_shadow(pb + n_s * 0.03)
        direct = np.clip(ndl, 0, 1) * vis
        sky_amb = 0.5 + 0.5 * n_f[:, 1]
        bounce = np.clip(-n_f[:, 1], 0, 1)
        hg = pb[:, 1] - self.land_h(pb[:, 0], pb[:, 2]).clip(0, None)
        occl = smoothstep(0.0, 0.35 * self.r, hg)
        L_lit = 52 + 32 * direct ** 0.7
        core = np.exp(-((ndl + 0.05) / 0.2) ** 2)
        L_sh = (16 + 12 * sky_amb + 7 * bounce - 9 * core) * (0.45 + 0.55 * occl)
        lit = direct > 0.06
        yy, xx = np.divmod(np.flatnonzero(m), W)
        # stroke direction on rock follows the facet's slope in screen space
        Td = np.where(n_f[:, 0] * n_f[:, 1] > 0, T['diag_l'][yy, xx], T['diag_r'][yy, xx])
        Tc = T['checker'][yy, xx]
        Tm = np.where(self.r * F / self.bz > 25, Td, Tc)
        li = ramp_pick('rock_lit', L_lit, Tm, 0.85)
        si = ramp_pick('rock_shade', L_sh, Tm, 0.85)
        col = np.where(lit, li, si)
        # facet crest lines: where the facet id changes and this side is the lit one -> r4 line; creases -> r0
        cid_img = np.full(H * W, -1, np.int64); cid_img[m] = cid
        ndl_img = np.full(H * W, -9.0); ndl_img[m] = ndl
        cimg = cid_img.reshape(H, W); nimg = ndl_img.reshape(H, W)
        edge = np.zeros((H, W), bool); brighter = np.zeros((H, W), bool)
        for sy, sx in ((0, 1), (1, 0), (0, -1), (-1, 0)):
            c2 = np.roll(np.roll(cimg, sy, 0), sx, 1); n2 = np.roll(np.roll(nimg, sy, 0), sx, 1)
            e = (c2 != cimg) & (c2 >= 0) & (cimg >= 0)
            edge |= e; brighter |= e & (nimg > n2 + 0.12)
        ed = edge.ravel()[m]; br = brighter.ravel()[m]
        big = self.r * F / self.bz > 14                       # detail only when the boulder is big enough
        rr = self.rng.random(len(col))
        if big:
            col = np.where(br & lit & (rr < 0.75), IDX['r4'], col)
            col = np.where(ed & ~br & ~lit & (rr < 0.45), IDX['r0'], col)
            # granite speckle: dark specks in light, light specks in shade
            col = np.where(lit & (rr > 0.965), IDX['r2'], col)
            col = np.where(~lit & (rr > 0.985) & (L_sh > 22), IDX['r2'], col)
        # sunlit rim on the silhouette when back-lit
        if self.light == 'back':
            sil = self.boulder_mask & ~(np.roll(self.boulder_mask, 1, 0) & np.roll(self.boulder_mask, 1, 1) & np.roll(self.boulder_mask, -1, 1))
            s = sil.ravel()[m] & (n_f[:, 1] > -0.1)
            col = np.where(s, IDX['r4'], col)
        img[m] = col
        Lt[m] = np.where(lit, L_lit, L_sh)
        self.b_lit = np.zeros(H * W, bool); self.b_lit[m] = lit

    def paint_water(self, img, kind, p, d, T, xx, yy):
        m = kind == 3
        if not m.any(): return
        pw = p[m]; dw = d[m].copy()
        dr = dw * np.array([1, -1, 1])
        o = pw + dr * 0.01
        t2, k2 = self.march(o, dr, tmax=200)
        p2 = o + dr * t2[:, None]
        src = np.zeros(len(pw), int)
        # reflected backdrop: the column stays, the elevation mirrors
        e = np.arcsin(np.clip(dr[:, 1], -1, 1))
        v_up = F * (np.tan(e + PITCH) - np.tan(PITCH))
        sky = k2 == 0
        if sky.any():
            bd = self.backdrop(xx[m][sky].astype(float), v_up[sky])
            src[sky] = self.backdrop_colour_L(bd)
            self._refl_skypos = bd['sky_pos']
        # reflected boulder & land: re-shade with the same light, flat reading
        for kk in (1, 2):
            s = k2 == kk
            if not s.any(): continue
            pp = p2[s]
            if kk == 1:
                nrm = self.land_normal(pp[:, 0], pp[:, 2]); ndl = np.clip((nrm * self.l).sum(-1), 0, 1)
                vis = self.boulder_shadow(pp + nrm * 0.02); lit = ndl * vis > 0.05
                src[s] = np.where(lit, IDX['g3'], IDX['g0'])
            else:
                nrm = self.boulder_normal(pp); ndl = (nrm * self.l).sum(-1)
                vis = self.boulder_shadow(pp + nrm * 0.03)
                lit = np.clip(ndl, 0, 1) * vis > 0.06
                hg = pp[:, 1] - self.ground_at_boulder
                src[s] = np.where(lit, np.where(ndl > 0.45, IDX['r4'], IDX['r3']), np.where(hg < 0.25 * self.r, IDX['r0'], IDX['r1']))
        # reflection transform measured on the reference: lights -13 L, mids -4.5, darks ~+1; cooler (a* -5)
        lab = LAB[src].copy()
        L = lab[:, 0]
        lab[:, 0] = L - 0.30 * np.maximum(0, L - 25) + 1.0 * (L < 25)
        lab[:, 1] -= 4.0
        # Fresnel: nearer water (steeper look) shows more of the dark water body
        dep = np.arcsin(np.clip(-dw[:, 1], 0, 1))
        kref = np.clip(1.0 - 1.9 * dep, 0.5, 0.97)
        lab = lab * kref[:, None] + LAB[IDX['w0']][None] * (1 - kref[:, None])
        # quantise onto the palette with horizontal ripple dither between the two nearest colours
        allowed = np.array([IDX[n] for n in ['k', 'for0', 'w0', 'r0', 'r1', 'mtn0', 'mtn1', 'r2', 'h1', 'g0', 'g1', 'g2', 'g3',
                                             'w1', 'w2', 'w3', 'sky1', 'sky2', 'r3', 'mtn2', 'snow0']])
        dd = np.linalg.norm(lab[:, None, :] - LAB[allowed][None], axis=-1)
        o2 = np.argsort(dd, axis=1)
        c1, c2 = allowed[o2[:, 0]], allowed[o2[:, 1]]
        d1, d2 = dd[np.arange(len(dd)), o2[:, 0]], dd[np.arange(len(dd)), o2[:, 1]]
        frac = d1 / (d1 + d2 + 1e-9)                           # 0 = exactly c1, 0.5 = halfway
        Th = T['horiz'][yy[m], xx[m]]; Tc = T['checker'][yy[m], xx[m]]
        Tr = np.where(LAB[c1][:, 0] > 55, Tc, Th)              # light water: checker, dark: horizontal
        col = np.where(frac > 0.5 + (Tr - 0.5) * 0.9, c2, c1)
        # streak lines: sparse horizontal 1px lines, denser toward the far shore
        r = self.rng.random(len(col))
        rowseed = np.random.default_rng(self.p['seed'] + 5).random(H)
        vrow = yy[m]
        streak_row = rowseed[vrow] < 0.28 * np.exp(-(vrow - Y_H) / 60)
        seg = (np.sin(xx[m] * 0.21 + rowseed[vrow] * 40) + 0.6 * np.sin(xx[m] * 0.07 + rowseed[vrow] * 11)) > 0.9
        light_src = LAB[col][:, 0] > 50
        col = np.where(streak_row & seg & ~light_src, IDX['w1'], col)
        col = np.where(streak_row & seg & light_src & (r < 0.8), IDX['w0'] if False else IDX['glint'], col)
        img[m] = col

    def paint_strokes(self, img, kind, p, t):
        """grass blades & sedge, back to front, in counterchange with what lies behind"""
        rng = np.random.default_rng(self.p['seed'] + 101)
        out = img.copy()
        land = kind == 1
        ys, xs = np.nonzero(land)
        if len(ys) == 0: return out
        z = t[ys, xs]
        pl = p[ys, xs]
        # blade world height: short turf; sedge near the boulder foot and at the waterline
        db = self.boulder_sd(pl)
        sd = self.land_sd(pl[:, 0], pl[:, 2])
        near_b = np.exp(-np.maximum(db, 0) / (0.45 * self.r))
        near_w = np.exp(-np.maximum(sd, 0) / 0.5)
        hb = 0.07 + 0.45 * np.maximum(near_b, 0.7 * near_w) * self.r ** 0.3
        Lpx = F * hb / z
        dens = np.clip(0.10 + 0.5 * np.maximum(near_b, near_w), 0, 0.8) * (Lpx >= 1.5)
        spawn = rng.random(len(ys)) < dens
        order = np.argsort(ys[spawn], kind='stable')           # back (top) to front (bottom)
        bys, bxs, bL = ys[spawn][order], xs[spawn][order], Lpx[spawn][order]
        lit_here = self.land_lit.reshape(H, W)[bys, bxs] > 0.5
        lean_field = self.noise.fbm2(bxs / 23.0, bys / 17.0, 2, 9.1) * 0.55
        LVimg = LV
        sun_side = -np.sign(self.l[0]) if abs(self.l[0]) > 0.2 else 0
        for i in range(len(bys)):
            y0, x0 = bys[i], bxs[i]
            L = int(np.clip(round(bL[i] * rng.uniform(0.55, 1.25)), 1, 26))
            ang = lean_field[i] + rng.normal(0, 0.18)
            curl = rng.normal(0, 0.035)
            x = float(x0); y = y0
            bg = out[y0, x0]
            blit = lit_here[i]
            for k in range(L):
                yy = y - k
                if yy < 0: break
                xi = int(round(x))
                if not (0 <= xi < W): break
                behind = LVimg[out[yy, xi]]
                tip = k >= L - max(1, L // 4)
                # counterchange: dark blade over light, light blade over dark
                if behind > 42:
                    c = IDX['g2'] if (blit and rng.random() < 0.55) else IDX['g0']
                    if kind[yy, xi] == 2 or kind[yy, xi] == 0 or kind[yy, xi] == 3:
                        c = IDX['g0'] if behind > 55 else IDX['h1']
                else:
                    if blit:
                        c = IDX['g4'] if tip else IDX['g2']
                        if self.light == 'back' and tip: c = IDX['g5']
                    else:
                        c = IDX['h2'] if tip else (IDX['g1'] if behind > 16 else IDX['h1'])
                        if kind[yy, xi] != 1: c = IDX['sedge'] if tip else IDX['g1']
                out[yy, xi] = c
                ang += curl
                x += np.tan(np.clip(ang, -1.1, 1.1))
            # reflection of blades rooted at the waterline
            if near_w[spawn][order][i] > 0.6 and L >= 3:
                x = float(x0)
                for k in range(1, L):
                    yy = y0 + k
                    if yy >= H: break
                    xi = int(round(x + (x - x0) * 0))
                    if 0 <= xi < W and kind[yy, xi] == 3:
                        out[yy, xi] = IDX['for0'] if LVimg[out[yy, xi]] > 30 else IDX['g1']
        return out

    def paint_repoussoir(self, img):
        """dark near bank in the corner opposite the boulder, grass silhouettes against the water"""
        rng = np.random.default_rng(self.p['seed'] + 202)
        out = img.copy()
        right = self.bx < 0
        xs = np.arange(W)
        xr = (xs if right else (W - 1 - xs)) / W        # 0 at the far side .. 1 at the corner
        edge = H - (np.clip(xr - 0.62, 0, None) * 150) - 4 * self.noise.fbm2(xs / 13.0, np.full(W, 8.8), 2)
        edge = edge.astype(float)
        yy, xx = np.mgrid[0:H, 0:W]
        m = yy >= edge[None, :]
        # base: black & dark olive in vertical strokes (shade bank, like Ferrari's right bank)
        T = rank_uniform(self.noise.fbm2(xx / 0.8, yy / 3.2, 2, 5.5) + 0.4 * rng.random((H, W)))
        depth = (yy - edge[None, :]) / 20.0
        L = 20 - 12 * np.clip(depth, 0, 1) + 6 * (T > 0.8)
        base = ramp_pick('grass_shade', L, T, 1.0)
        out[m] = base[m]
        # blades rising out of the top edge, silhouetted against water
        lit_side = (self.l[0] > 0.2) == right or self.light == 'front'
        for x0 in range(W):
            if not (edge[x0] < H): continue
            nb = rng.poisson(0.9)
            for _ in range(nb):
                y0 = int(edge[x0] + rng.uniform(0, 6))
                L = int(rng.uniform(4, 16))
                ang = rng.normal(0.25 if right else -0.25, 0.3); curl = rng.normal(0, 0.05)
                x = float(x0)
                for k in range(L):
                    y = y0 - k; xi = int(round(x))
                    if y < 0 or not (0 <= xi < W): break
                    tip = k > L * 0.7
                    out[y, xi] = (IDX['g3'] if (lit_side and tip) else IDX['g1']) if rng.random() < 0.9 else IDX['h2']
                    ang += curl; x += np.tan(np.clip(ang, -1, 1))
        return out


def paint(size='medium', light='left', distance='close', seed=1, return_scene=False):
    s = Scene(size, light, distance, seed)
    rgb = s.render()
    return (rgb, s) if return_scene else rgb


if __name__ == '__main__':
    import sys
    rgb = paint()
    Image.fromarray(np.repeat(np.repeat(rgb, 3, 0), 3, 1)).save(sys.argv[1] if len(sys.argv) > 1 else 'test.png')

cd ~/work/pixelart-studies/pedagogy/analysis && time OMP_NUM_THREADS=4 OPENBLAS_NUM_THREADS=4 nice -n 10 python3 src/paint/ferrari_method.py out/test.png 2>&1 | tail -20

# output:
Traceback (most recent call last):
  File "~/work/pixelart-studies/pedagogy/analysis/src/paint/ferrari_method.py", line 725, in <module>
    rgb = paint()
          ^^^^^^^
  File "~/work/pixelart-studies/pedagogy/analysis/src/paint/ferrari_method.py", line 719, in paint
    rgb = s.render()
          ^^^^^^^^^^
  File "~/work/pixelart-studies/pedagogy/analysis/src/paint/ferrari_method.py", line 422, in render
    img = self.paint_repoussoir(img)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "~/work/pixelart-studies/pedagogy/analysis/src/paint/ferrari_method.py", line 712, in paint_repoussoir
    out[y, xi] = (IDX['g3'] if (lit_side and tip) else IDX['g1']) if rng.random() < 0.9 else IDX['h2']
    ~~~^^^^^^^
IndexError: index 183 is out of bounds for axis 0 with size 180
OMP_NUM_THREADS=4 OPENBLAS_NUM_THREADS=4 nice -n 10 python3  out/test.png 2>&  27.84s user 5.65s system 100% cpu 33.219 total
tail -20  0.00s user 0.00s system 0% cpu 33.219 total

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
old_start=s.index("        # mountain ridge\n")
old_end=s.index("        snow = (v > ridge")
new='''        # mountain ridge (functions of u so derivatives are exact even for scattered samples)
        ridge = self.ridge(u)
        dr = self.ridge(u + 0.5) - self.ridge(u - 0.5)
        in_m = v < ridge
        gx = self.relief(u + 0.5, v) - self.relief(u - 0.5, v)
        sun_x = self.l[0]
        if self.light == 'back':
            facing = -0.5 + 0.0 * gx
        elif self.light == 'front':
            facing = 0.35 + 0.25 * np.abs(gx) - 0.25 * np.abs(dr)
        else:
            facing = -np.sign(sun_x) * (dr * 0.8 + gx * 0.6)
'''
s=s[:old_start]+new+s[old_end:]
s=s.replace('''    def backdrop(self, u, v):''','''    def ridge(self, u):
        n = self.noise; ms = self.mtn_seed; uu = np.asarray(u, float) / W
        peak_u = 0.72 if self.bx < 0 else 0.28
        return 14 + 12 * np.exp(-((uu - peak_u) / 0.16) ** 2) + 5 * np.exp(-((uu - peak_u + 0.22) / 0.09) ** 2) \\
            + 3.5 * n.fbm2(uu * 9 + ms, np.full(uu.shape, 1.7), 4) + 1.2 * np.abs(n.fbm2(uu * 40 + ms, np.full(uu.shape, 5.1), 2))

    def relief(self, u, v):
        n = self.noise; ms = self.mtn_seed
        return n.fbm2(u / 7.0 + ms, v / 4.0, 4) * 3.0 - np.abs(n.fbm2(u / 16.0 + ms, v / 9.0 + 3, 3)) * 7

    def backdrop(self, u, v):''')
s=s.replace("                    if y < 0 or not (0 <= xi < W): break","                    if y < 0 or not (0 <= xi < W): break\n                    if y >= H: continue")
open(f,'w').write(s)
EOF
grep -n "ms = self.mtn_seed$\|uu = u / W\|peak_u" src/paint/ferrari_method.py | head; time nice -n 10 python3 src/paint/ferrari_method.py out/test.png 2>&1 | tail -5

# output:
326:        peak_u = 0.72 if self.bx < 0 else 0.28
327:        return 14 + 12 * np.exp(-((uu - peak_u) / 0.16) ** 2) + 5 * np.exp(-((uu - peak_u + 0.22) / 0.09) ** 2) \
331:        n = self.noise; ms = self.mtn_seed
nice -n 10 python3 src/paint/ferrari_method.py out/test.png 2>&1  27.85s user 8.45s system 103% cpu 35.218 total
tail -5  0.00s user 0.00s system 0% cpu 35.218 total

cd ~/work/pixelart-studies/pedagogy/analysis && sed -i '' 's/c, s = np.cos(-PITCH), np.sin(-PITCH)/c, s = np.cos(PITCH), np.sin(PITCH)/' src/paint/ferrari_method.py && time nice -n 10 python3 src/paint/ferrari_method.py out/test.png 2>&1 | tail -5

# output:
nice -n 10 python3 src/paint/ferrari_method.py out/test.png 2>&1  26.61s user 7.98s system 103% cpu 33.379 total
tail -5  0.00s user 0.00s system 0% cpu 33.379 total

cd ~/work/pixelart-studies/pedagogy/analysis && grep -n "def land_sd" -A 22 src/paint/ferrari_method.py | head -30

# output:
200:    def land_sd(self, x, z):
201-        """signed distance (m, >0 on land) of the boulder's bank; shoreline wraps the boulder's front"""
202-        n = self.noise
203-        r = self.r
204-        # the shoreline runs from the boulder's front-right corner back and away, and forward-left
205-        cx, cz = self.bx + 0.35 * r, self.bz - 0.15 * r
206-        ang = np.arctan2(z - cz, x - cx)
207-        # a line through (cx,cz): land is to the left of a gently curving line tilted away from camera
208-        d_line = -(x - cx) * 0.80 + (z - cz) * 0.60
209-        wobble = 0.35 * n.fbm2(x * 0.35 + self.shore_seed, z * 0.35, 3) * (1 + 0.04 * np.abs(z - cz))
210-        sd = d_line + wobble
211-        # the spit is broad behind the boulder and narrows toward the camera (water in front of it)
212-        sd = np.minimum(sd, (z - (self.bz - 1.2 * r - 0.6)) * 1.0 + 0.6 * np.maximum(0, -(x - cx)) * 0.25)
213-        return sd
214-
215-    def land_h(self, x, z):
216-        sd = self.land_sd(x, z)
217-        n = self.noise
218-        h = 0.55 * smoothstep(0.0, 3.0 + self.r, sd) + 0.10 * n.fbm2(x * 0.5, z * 0.5 + 7, 3) * smoothstep(0.3, 1.5, sd)
219-        return np.where(sd > 0, h, -0.3 + 0.05 * sd)
220-
221-    # ------------------------------------------------ boulder SDF (weathered, faceted)
222-    def boulder_sd(self, p):

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
a=s.index("    def land_sd(self, x, z):"); b=s.index("    def land_h(self, x, z):")
s=s[:a]+'''    def land_sd(self, x, z):
        """signed distance (m, >0 on land): a promontory coming in from the left, its shoreline
        wrapping the boulder's front-right so the boulder stands at the water's edge"""
        n = self.noise; r = self.r; d = self.bz
        A = 1.8 * r + 0.12 * d + 1.2; B = 1.2 * r + 0.07 * d + 0.9
        pfx, pfz = self.bx + 0.45 * r, self.bz - 0.30 * r
        cx, cz = pfx - 0.77 * A, pfz + 0.64 * B
        e1 = (1 - np.sqrt(((x - cx) / A) ** 2 + ((z - cz) / B) ** 2)) * min(A, B)
        e2 = (1 - np.sqrt(((x - (cx - 1.3 * A)) / (1.6 * A)) ** 2 + ((z - (cz + 0.1 * B)) / (0.95 * B)) ** 2)) * min(A, B)
        sd = np.maximum(e1, e2)
        wob = 0.22 * (1 + 0.03 * d) * n.fbm2(x * 0.45 + self.shore_seed, z * 0.45, 3)
        return sd + wob

'''+s[b:]
open(f,'w').write(s)
EOF
echo ok

# output:
ok

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
s=s.replace("'grass_lit': ['g1', 'g2', 'g3', 'g4', 'g5'],","'grass_lit': ['g0', 'g1', 'g2', 'g3', 'g4', 'g5'],")
a=s.index("    def paint_land(self, img, Lt, kind, p, d, T):"); b=s.index("    def paint_boulder(")
s=s[:a]+'''    def paint_land(self, img, Lt, kind, p, d, T):
        m = kind == 1
        self.land_lit = np.zeros(H * W)
        if not m.any(): return
        pl = p[m]
        # light is judged on the LARGE form (smoothed normal): light and shade in big connected masses
        e = 0.45
        hx = (self.land_h(pl[:, 0] + e, pl[:, 2]) - self.land_h(pl[:, 0] - e, pl[:, 2])) / (2 * e)
        hz = (self.land_h(pl[:, 0], pl[:, 2] + e) - self.land_h(pl[:, 0], pl[:, 2] - e)) / (2 * e)
        nrm = np.stack([-hx, np.ones_like(hx), -hz], -1); nrm /= np.linalg.norm(nrm, axis=1, keepdims=True)
        ndl = (nrm * self.l).sum(-1)
        vis = self.boulder_shadow(pl + np.array([0, 0.03, 0]))
        lit_amt = smoothstep(-0.06, 0.08, ndl) * smoothstep(0.35, 0.8, vis)
        viewh = -d[m].copy(); viewh[:, 1] = 0; viewh /= np.linalg.norm(viewh, axis=1, keepdims=True) + 1e-9
        back = np.clip(-(viewh * self.l).sum(-1), 0, 1)       # 1 when looking into the sun
        z = np.linalg.norm(pl - np.array([0, HC, 0]), axis=1)
        occl = smoothstep(0.0, 0.5 * self.r, self.boulder_sd(pl))
        far = smoothstep(6, 45, z)
        # value plan: lit grass mid-light, brightening as the plane recedes; shade grass near-black
        L_lit = (43 + 9 * np.sqrt(np.clip(ndl, 0, 1)) + 7 * back + 7 * far) * (0.55 + 0.45 * occl)
        L_sh = (10 + 9 * far + 4 * back) * (0.3 + 0.7 * occl)
        yy, xx = np.divmod(np.flatnonzero(m), W)
        near = smoothstep(30, 12, z)
        Tv = T['vert'][yy, xx]; Ts = T['speckle'][yy, xx]
        Ttex = np.where(near > 0.5, Tv, Ts)
        # texture spread: near grass spans base / mid stroke / dark gap (Ferrari: 60/40/24/10),
        # the spread shrinks with distance until grass is a two-colour speckle
        amp = 5 + 17 * near
        Lli = L_lit + amp * (Ttex * 2 - 1) * np.where(Ttex < 0.12, 1.6, 1.0)
        Lsh = L_sh + (0.6 * amp) * (Ttex * 2 - 1)
        Tq = T['checker'][yy, xx]
        lit_i = ramp_pick('grass_lit', Lli, Tq, 0.3)
        sh_i = ramp_pick('grass_shade', Lsh, Tq, 0.3)
        use_lit = lit_amt > T['vert'][yy, xx] * 0.8 + 0.1       # terminator made of strokes too
        img[m] = np.where(use_lit, lit_i, sh_i)
        Lt[m] = np.where(use_lit, L_lit, L_sh)
        self.land_lit[m] = lit_amt

'''+s[b:]
open(f,'w').write(s)
EOF
echo ok

# output:
ok
[This command modified 1 file you've previously read: ../pedagogy/analysis/src/paint/ferrari_method.py. Call Read before editing.]

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[("n_f = 0.65 * mean_n[inv] + 0.35 * n_s","n_f = 0.85 * mean_n[inv] + 0.15 * n_s"),
("L_lit = 52 + 32 * direct ** 0.7","L_lit = 49 + 31 * direct"),
("        Tm = np.where(self.r * F / self.bz > 25, Td, Tc)\n        li = ramp_pick('rock_lit', L_lit, Tm, 0.85)\n        si = ramp_pick('rock_shade', L_sh, Tm, 0.85)",
 "        Tm = np.where(self.r * F / self.bz > 25, 0.5 * Td + 0.5 * Tc, Tc)\n        li = ramp_pick('rock_lit', L_lit, Tm, 0.55)\n        si = ramp_pick('rock_shade', L_sh, Tm, 0.55)"),
("col = np.where(lit & (rr > 0.965), IDX['r2'], col)","col = np.where(lit & (rr > 0.985), IDX['r2'], col)"),
("col = np.where(~lit & (rr > 0.985) & (L_sh > 22), IDX['r2'], col)","col = np.where(~lit & (rr > 0.993) & (L_sh > 24), IDX['r2'], col)"),
("kref = np.clip(1.0 - 1.9 * dep, 0.5, 0.97)","kref = np.clip(1.0 - 0.9 * dep, 0.62, 0.97)"),
]
for a,b in rep:
    assert a in s, a; s=s.replace(a,b)
open(f,'w').write(s)
EOF
time nice -n 10 python3 src/paint/ferrari_method.py out/test.png 2>&1 | tail -3

# output:
nice -n 10 python3 src/paint/ferrari_method.py out/test.png 2>&1  30.02s user 9.23s system 104% cpu 37.590 total
tail -3  0.00s user 0.00s system 0% cpu 37.589 total

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[("A = 1.8 * r + 0.12 * d + 1.2; B = 1.2 * r + 0.07 * d + 0.9","A = 2.6 * r + 0.15 * d + 2.0; B = 1.7 * r + 0.10 * d + 1.6"),
("pfx, pfz = self.bx + 0.45 * r, self.bz - 0.30 * r\n        cx, cz = pfx - 0.77 * A, pfz + 0.64 * B","pfx, pfz = self.bx + 0.55 * r, self.bz - 0.55 * r\n        cx, cz = pfx - 0.57 * A, pfz + 0.82 * B"),
("'left': (-0.93, 0.13, 0.30),","'left': (-0.97, 0.13, 0.02),"),
("'right': (0.93, 0.13, 0.30),","'right': (0.97, 0.13, 0.02),"),
("L_sh = (16 + 12 * sky_amb + 7 * bounce - 9 * core) * (0.45 + 0.55 * occl)","L_sh = (13 + 21 * sky_amb ** 1.5 + 8 * bounce - 10 * core) * (0.45 + 0.55 * occl)"),
("kref = np.clip(1.0 - 0.9 * dep, 0.62, 0.97)","kref = np.clip(1.0 - 0.5 * dep, 0.80, 0.97)"),
]
for a,b in rep:
    assert a in s, a; s=s.replace(a,b)
# blade reflections shorter & broken
a="""            if near_w[spawn][order][i] > 0.6 and L >= 3:
                x = float(x0)
                for k in range(1, L):"""
b="""            if near_w[spawn][order][i] > 0.6 and L >= 3:
                x = float(x0)
                for k in range(1, int(L * 0.6)):
                    if rng.random() < 0.3: continue"""
assert a in s; s=s.replace(a,b)
# streaks: subtle, far water only
a="""        streak_row = rowseed[vrow] < 0.28 * np.exp(-(vrow - Y_H) / 60)"""
b="""        streak_row = rowseed[vrow] < 0.22 * np.exp(-(vrow - Y_H) / 25)"""
assert a in s; s=s.replace(a,b)
s=s.replace("""        col = np.where(streak_row & seg & ~light_src, IDX['w1'], col)
        col = np.where(streak_row & seg & light_src & (r < 0.8), IDX['w0'] if False else IDX['glint'], col)""",
"""        col = np.where(streak_row & seg & ~light_src & (r < 0.85), IDX['mtn0'], col)
        col = np.where(streak_row & seg & light_src & (r < 0.85), IDX['w3'], col)""")
open(f,'w').write(s)
EOF
time nice -n 10 python3 src/paint/ferrari_method.py out/test.png 2>&1 | tail -3

# output:
nice -n 10 python3 src/paint/ferrari_method.py out/test.png 2>&1  26.50s user 6.93s system 108% cpu 30.778 total
tail -3  0.00s user 0.00s system 0% cpu 30.777 total

cd ~/work/pixelart-studies/pedagogy/analysis && grep -n "near_w = \|hb = 0.07\|dens = \|n_f = 0.85\|ndl = (n_f\|sky_amb = \|bounce = np.clip\|def land_h" -A0 src/paint/ferrari_method.py; sed -n '/def land_h/,/return np.where/p' src/paint/ferrari_method.py

# output:
213:    def land_h(self, x, z):
512:        n_f = 0.85 * mean_n[inv] + 0.15 * n_s
514:        ndl = (n_f * self.l).sum(-1)
517:        sky_amb = 0.5 + 0.5 * n_f[:, 1]
518:        bounce = np.clip(-n_f[:, 1], 0, 1)
636:        near_w = np.exp(-np.maximum(sd, 0) / 0.5)
637:        hb = 0.07 + 0.45 * np.maximum(near_b, 0.7 * near_w) * self.r ** 0.3
639:        dens = np.clip(0.10 + 0.5 * np.maximum(near_b, near_w), 0, 0.8) * (Lpx >= 1.5)
    def land_h(self, x, z):
        sd = self.land_sd(x, z)
        n = self.noise
        h = 0.55 * smoothstep(0.0, 3.0 + self.r, sd) + 0.10 * n.fbm2(x * 0.5, z * 0.5 + 7, 3) * smoothstep(0.3, 1.5, sd)
        return np.where(sd > 0, h, -0.3 + 0.05 * sd)

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[
("""        h = 0.55 * smoothstep(0.0, 3.0 + self.r, sd) + 0.10 * n.fbm2(x * 0.5, z * 0.5 + 7, 3) * smoothstep(0.3, 1.5, sd)
        return np.where(sd > 0, h, -0.3 + 0.05 * sd)""",
"""        r = self.r; d = self.bz
        A = 2.6 * r + 0.15 * d + 2.0; B = 1.7 * r + 0.10 * d + 1.6
        # a rounded hummock behind-left of the boulder (Ferrari's mounds: a lit rim, a dark face)
        mx, mz = self.bx - 0.9 * A, self.bz + 0.9 * B
        mound = (0.45 + 0.35 * r) * np.exp(-(((x - mx) / (0.75 * A)) ** 2 + ((z - mz) / (0.8 * B)) ** 2))
        h = 0.30 * smoothstep(0.0, 2.0 + r, sd) + mound * smoothstep(0.0, 1.0, sd) \\
            + 0.06 * n.fbm2(x * 0.5, z * 0.5 + 7, 3) * smoothstep(0.3, 1.5, sd)
        return np.where(sd > 0, h, -0.3 + 0.05 * sd)"""),
("""        n_f = 0.85 * mean_n[inv] + 0.15 * n_s""","""        n_f = 0.55 * mean_n[inv] + 0.45 * n_s"""),
("""        sky_amb = 0.5 + 0.5 * n_f[:, 1]
        bounce = np.clip(-n_f[:, 1], 0, 1)""","""        sky_amb = 0.5 + 0.5 * n_s[:, 1]            # ambient judged on the smooth form: no blotches
        bounce = np.clip(-n_s[:, 1], 0, 1) + 0.35 * np.clip(-(n_s * self.l)[..., 0] * 0, 0, 1)"""),
("""        near_w = np.exp(-np.maximum(sd, 0) / 0.5)""","""        clump = smoothstep(0.1, 0.6, self.noise.fbm2(pl[:, 0] * 0.9 + 3, pl[:, 2] * 0.9, 2))
        near_w = np.exp(-np.maximum(sd, 0) / 0.4) * clump"""),
]
for a,b in rep:
    assert a in s, a; s=s.replace(a,b)
open(f,'w').write(s)
EOF
time nice -n 10 python3 src/paint/ferrari_method.py out/test.png 2>&1 | tail -3

# output:
nice -n 10 python3 src/paint/ferrari_method.py out/test.png 2>&1  25.91s user 7.77s system 105% cpu 31.898 total
tail -3  0.00s user 0.00s system 0% cpu 31.898 total

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/paint/debug_gb.py <<'EOF'
import sys; sys.path.insert(0,'src/paint'); import ferrari_method as fm
import numpy as np
from PIL import Image
s=fm.Scene(*sys.argv[1:4], int(sys.argv[4]) if len(sys.argv)>4 else 1)
fm_paint=s.paint_boulder
store={}
def pb(img,Lt,kind,p,d,T):
    fm_paint(img,Lt,kind,p,d,T); store['Lt']=Lt.copy(); store['kind']=kind.copy()
s.paint_boulder=pb
rgb=s.render()
Lt=store['Lt'].reshape(fm.H,fm.W); k=store['kind'].reshape(fm.H,fm.W)
g=np.clip(Lt*2.55,0,255).astype(np.uint8); g[k==0]=128; g[k==3]=60
out=np.concatenate([np.stack([g]*3,-1),rgb],1)
Image.fromarray(np.repeat(np.repeat(out,2,0),2,1)).save('out/debug_gb.png')
EOF
nice -n 10 python3 src/paint/debug_gb.py medium left close 1

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[("disp = 0.09 * n.fbm3","disp = 0.055 * n.fbm3"),
("L_lit = 49 + 31 * direct","L_lit = 42 + 38 * direct ** 0.85"),
]
for a,b in rep:
    assert a in s, a; s=s.replace(a,b)
open(f,'w').write(s)
EOF
nice -n 10 python3 src/paint/debug_gb.py medium left close 1

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/paint/sheets.py <<'EOF'
"""Render parameter sweep sheets. Cells are 320x180 native, shown 3x nearest-neighbour."""
import sys, os
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import numpy as np
from PIL import Image, ImageDraw, ImageFont
from multiprocessing import Pool
import ferrari_method as fm
ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
OUT = os.path.join(ROOT, 'sheets'); CELLS = os.path.join(OUT, 'cells')
os.makedirs(CELLS, exist_ok=True)
BASE = dict(size='medium', light='left', distance='10m', seed=1)

def key(p): return f"{p['size']}_{p['light']}_{p['distance']}_s{p['seed']}"

def render(p):
    fn = os.path.join(CELLS, key(p) + '.png')
    if not os.path.exists(fn) or os.environ.get('FORCE'):
        rgb, s = fm.paint(**p, return_scene=True)
        Image.fromarray(rgb).save(fn)
        np.save(fn.replace('.png', '_idx.npy'), s.index)
    return fn

def sheet(name, cells, cols, scale=3, title=''):
    fnt = ImageFont.truetype('/System/Library/Fonts/Menlo.ttc', 22)
    tiles = []
    for p, lab in cells:
        im = Image.open(os.path.join(CELLS, key(p) + '.png'))
        im = im.resize((fm.W * scale, fm.H * scale), Image.NEAREST)
        canvas = Image.new('RGB', (im.width, im.height + 34), (250, 248, 244))
        canvas.paste(im, (0, 34)); ImageDraw.Draw(canvas).text((6, 5), lab, fill=(20, 20, 20), font=fnt)
        tiles.append(canvas)
    rows = (len(tiles) + cols - 1) // cols; tw, th = tiles[0].size; g = 12
    S = Image.new('RGB', (cols * tw + (cols + 1) * g, rows * th + (rows + 1) * g + 46), (250, 248, 244))
    ImageDraw.Draw(S).text((g, 10), title, fill=(0, 0, 0), font=fnt)
    for i, t in enumerate(tiles):
        S.paste(t, (g + (i % cols) * (tw + g), 46 + g + (i // cols) * (th + g)))
    S.save(os.path.join(OUT, name))

def plan():
    sw = {}
    sw['sheet_size.png'] = ([dict(BASE, size=v) for v in ('small', 'medium', 'large')], 'size', 3)
    sw['sheet_light.png'] = ([dict(BASE, light=v) for v in ('left', 'front', 'right', 'back')], 'light', 2)
    sw['sheet_distance.png'] = ([dict(BASE, distance=v) for v in ('close', '10m', '40m')], 'distance', 3)
    sw['sheet_seed.png'] = ([dict(BASE, seed=v) for v in (1, 2, 3, 4, 5, 6)], 'seed', 3)
    sw['sheet_light_x_distance.png'] = ([dict(BASE, light=l, distance=d) for d in ('close', '10m', '40m') for l in ('left', 'front', 'right', 'back')], None, 4)
    return sw

if __name__ == '__main__':
    only = sys.argv[1:]
    sw = plan()
    if only: sw = {k: v for k, v in sw.items() if any(o in k for o in only)}
    todo = []
    for k, (ps, _, _) in sw.items():
        for p in ps:
            if p not in todo: todo.append(p)
    with Pool(4) as pool:
        pool.map(render, todo)
    for k, (ps, var, cols) in sw.items():
        cells = [(p, f"{var} = {p[var]}" if var else f"{p['light']} / {p['distance']}") for p in ps]
        sheet(k, cells, cols, title=f"{k[:-4]}   (base: medium, left, 10 m, seed 1; 320x180 native, 32 colours, 3x)")
    print('done', len(todo), 'cells')
EOF
time FORCE=1 OMP_NUM_THREADS=1 nice -n 10 python3 src/paint/sheets.py light distance 2>&1 | tail -3

# output:
Command did not complete within its 120s timeout and was moved to the background (ID: bwnhj0xmv). 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.

sleep 100; cat (tmp) ls ~/work/pixelart-studies/pedagogy/analysis/sheets/

# output:
<tool_use_error>Blocked: sleep 100 followed by: cat (tmp) ls ~/work/pixelart-studies/pedagogy/analysis/sheets/. 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/analysis && grep -n "img\[sky\] = self.paint_backdrop\|img = self.paint_repoussoir(img)\|self.index = img\|out\[m\] = base\[m\]\|def paint_repoussoir" src/paint/ferrari_method.py

# output:
419:        img[sky] = self.paint_backdrop(bd, T, yy.ravel()[sky], xx.ravel()[sky])
432:        img = self.paint_repoussoir(img)
433:        self.index = img
696:    def paint_repoussoir(self, img):
712:        out[m] = base[m]

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
s=s.replace("""        img[sky] = self.paint_backdrop(bd, T, yy.ravel()[sky], xx.ravel()[sky])""","""        img[sky] = self.paint_backdrop(bd, T, yy.ravel()[sky], xx.ravel()[sky])
        # plane labels for self-analysis: 0 sky 1 mountain 2 forest 3 water 4 bank 5 boulder 6 near bank
        pl_ = np.zeros(H * W, int); pl_[sky] = bd['mat']
        pl_[kind == 3] = 3; pl_[kind == 1] = 4; pl_[kind == 2] = 5
        self.planes = pl_.reshape(H, W)""")
s=s.replace("""        out[m] = base[m]""","""        out[m] = base[m]
        self.planes = np.where(m, 6, self.planes)""")
open(f,'w').write(s)
EOF
echo ok

# output:
ok

cd ~/work/pixelart-studies/pedagogy/analysis && sed -i '' "s|        np.save(fn.replace('.png', '_idx.npy'), s.index)|        np.save(fn.replace('.png', '_idx.npy'), s.index); np.save(fn.replace('.png', '_planes.npy'), s.planes)|" src/paint/sheets.py && grep -n "_planes" src/paint/sheets.py

# output:
20:        np.save(fn.replace('.png', '_idx.npy'), s.index); np.save(fn.replace('.png', '_planes.npy'), s.planes)

cd ~/work/pixelart-studies/pedagogy/analysis && grep -n "def land_sd" -A 14 src/paint/ferrari_method.py | tail -4; grep -n "vis = self.boulder_shadow(pl + np.array" -A 3 src/paint/ferrari_method.py; grep -n "lab\[:, 0\] = L - 0.30\|lab = lab \* kref\|kref = np.clip\|img = self.paint_repoussoir" src/paint/ferrari_method.py

# output:
211-        return sd + wob
212-
213-    def land_h(self, x, z):
214-        sd = self.land_sd(x, z)
471:        vis = self.boulder_shadow(pl + np.array([0, 0.03, 0]))
472-        lit_amt = smoothstep(-0.06, 0.08, ndl) * smoothstep(0.35, 0.8, vis)
473-        viewh = -d[m].copy(); viewh[:, 1] = 0; viewh /= np.linalg.norm(viewh, axis=1, keepdims=True) + 1e-9
474-        back = np.clip(-(viewh * self.l).sum(-1), 0, 1)       # 1 when looking into the sun
436:        img = self.paint_repoussoir(img)
605:        lab[:, 0] = L - 0.30 * np.maximum(0, L - 25) + 1.0 * (L < 25)
609:        kref = np.clip(1.0 - 0.5 * dep, 0.80, 0.97)
610:        lab = lab * kref[:, None] + LAB[IDX['w0']][None] * (1 - kref[:, None])

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[
("""        wob = 0.22 * (1 + 0.03 * d) * n.fbm2(x * 0.45 + self.shore_seed, z * 0.45, 3)
        return sd + wob""",
"""        wob = 0.22 * (1 + 0.03 * d) * n.fbm2(x * 0.45 + self.shore_seed, z * 0.45, 3)
        return np.maximum(sd + wob, self.near_sd(x, z))

    def near_sd(self, x, z):
        \"\"\"the camera's own bank: a V opening onto the water (Ferrari's two foreground banks)\"\"\"
        s = 1.0 if self.bx < 0 else -1.0                  # +1: boulder on the left
        xb = x * s                                         # >0 = side away from the boulder
        zn = 2.25 + 1.0 * np.maximum(0, -xb) ** 1.25 + 2.6 * np.maximum(0, xb - 0.1) ** 1.35
        zn = zn + 0.12 * self.noise.fbm2(x * 1.7 + 50, z * 1.7, 3)
        return zn - z"""),
("""        lit_amt = smoothstep(-0.06, 0.08, ndl) * smoothstep(0.35, 0.8, vis)""",
"""        lit_amt = smoothstep(-0.06, 0.08, ndl) * smoothstep(0.35, 0.8, vis)
        # Ferrari's device: the near bank on the side away from the sun lies in the shadow of
        # off-frame trees -> a dark repoussoir; with back light the whole foreground is in shade
        nearb = self.near_sd(pl[:, 0], pl[:, 2]) > -0.05
        sx = self.l[0]
        if self.light == 'back':
            off = nearb
        elif abs(sx) > 0.2:
            edge = 0.15 * pl[:, 2] + 0.25 * self.noise.fbm2(pl[:, 0] * 2 + 9, pl[:, 2] * 2, 2)
            off = nearb & ((pl[:, 0] * np.sign(sx)) < -edge)
        else:
            off = np.zeros(len(pl), bool)
        lit_amt = np.where(off, 0.0, lit_amt)"""),
("""        lab[:, 0] = L - 0.30 * np.maximum(0, L - 25) + 1.0 * (L < 25)""",
"""        # (calibrated: reflected sky ~4 L darker than sky, top lights ~13 darker, darks unchanged)
        lab[:, 0] = L - 0.6 * np.maximum(0, L - 68) - 0.06 * np.maximum(0, L - 30) + 1.0 * (L < 25)"""),
("""        kref = np.clip(1.0 - 0.5 * dep, 0.80, 0.97)""","""        kref = np.clip(1.0 - 0.3 * dep, 0.88, 0.99)"""),
("""        img = self.paint_repoussoir(img)""","""        # (the screen-space repoussoir is replaced by the 3D near bank)"""),
]
for a,b in rep:
    assert a in s, a; s=s.replace(a,b)
open(f,'w').write(s)
EOF
nice -n 10 python3 src/paint/debug_gb.py medium left 10m 1

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/contours.py <<'EOF'
"""Pixel-geometry of contours: how silhouettes resolve into runs (flat, 45deg, 2:1 ...)."""
import sys; sys.path.insert(0,'src'); from util import *
from collections import Counter
def profile_runs(top):
    """top: y per column (int). Returns list of (run_len_x, step_y) segments: a horizontal run then a step."""
    segs=[]; run=1
    for i in range(1,len(top)):
        dy=int(top[i]-top[i-1])
        if dy==0: run+=1
        else: segs.append((run,dy)); run=1
    segs.append((run,0)); return segs
def classify(segs):
    c=Counter()
    for run,dy in segs:
        a=abs(dy)
        if dy==0: continue
        if run==1 and a==1: c['45deg (1:1)']+=1
        elif run==2 and a==1: c['2:1 (shallow)']+=1
        elif run==1 and a==2: c['1:2 (steep)']+=1
        elif run>=3 and a==1: c['long flat run then 1 step']+=1
        elif run==1 and a>=3: c['vertical drop >=3']+=1
        else: c['other']+=1
    tot=sum(c.values()); return {k:round(v/tot,3) for k,v in c.most_common()},tot
def top_profile(mask,x0,x1):
    out=[]
    for x in range(x0,x1):
        ys=np.flatnonzero(mask[:,x]); out.append(ys[0] if len(ys) else -1)
    return np.array(out)
if __name__=='__main__':
    a=load_ref(); P=np.load('out/planes.npy')
    nonsky=P!=0
    for name,(x0,x1) in {'mountain crest':(205,300),'mountain right shoulder':(318,405),'tree line (left group)':(0,160)}.items():
        t=top_profile(nonsky,x0,x1); segs=profile_runs(t); cl,n=classify(segs)
        print(name,n,cl)
        print('   runs(x) hist', Counter([r for r,d in segs]).most_common(8))
    # bottoms: island meeting water; find bottom boundary of island colour mass
    lab=rgb2lab(a)
    EOF
nice -n 10 python3 src/contours.py

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
s=open('src/contours.py').read()
i=s.index("    # bottoms:"); s=s[:i]
open('src/contours.py','w').write(s)
EOF
nice -n 10 python3 src/contours.py

# output:
mountain crest 34 {'long flat run then 1 step': 0.529, '45deg (1:1)': 0.412, '2:1 (shallow)': 0.029, '1:2 (steep)': 0.029}
   runs(x) hist [(1, 16), (4, 6), (3, 5), (5, 4), (6, 3), (2, 1)]
mountain right shoulder 58 {'45deg (1:1)': 0.431, '2:1 (shallow)': 0.293, 'vertical drop >=3': 0.138, '1:2 (steep)': 0.069, 'long flat run then 1 step': 0.052, 'other': 0.017}
   runs(x) hist [(1, 38), (2, 18), (5, 2), (3, 1)]
tree line (left group) 107 {'vertical drop >=3': 0.458, '45deg (1:1)': 0.178, 'other': 0.131, '2:1 (shallow)': 0.121, '1:2 (steep)': 0.103, 'long flat run then 1 step': 0.009}
   runs(x) hist [(1, 80), (2, 22), (3, 4), (6, 1), (18, 1)]

cd ~/work/pixelart-studies/pedagogy/analysis && nice -n 10 python3 src/crop.py 255 270 170 40 6 c_island_bottom.png && nice -n 10 python3 src/crop.py 400 230 150 35 6 c_hummock_base.png && nice -n 10 python3 src/crop.py 245 400 100 35 8 c_stones.png

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[
("""        lit_amt = smoothstep(-0.06, 0.08, ndl) * smoothstep(0.35, 0.8, vis)
""","""        # grass blades stand upright: they catch a grazing sun whatever the ground's slope, unless
        # the ground turns well away from it or something casts a shadow
        lit_amt = smoothstep(-0.32, -0.12, ndl) * smoothstep(0.35, 0.8, vis)
"""),
("""        zn = zn + 0.12 * self.noise.fbm2(x * 1.7 + 50, z * 1.7, 3)""","""        zn = np.minimum(zn, 7.5) + 0.12 * self.noise.fbm2(x * 1.7 + 50, z * 1.7, 3)"""),
("L_lit = 42 + 38 * direct ** 0.85","L_lit = 40 + 40 * direct ** 1.3"),
]
for a,b in rep:
    assert a in s, a; s=s.replace(a,b)
open(f,'w').write(s)
EOF
echo ok

# output:
ok

"""Pixel geometry: contours resolved into short straight runs with clean steps.

Measured on the reference (src/contours.py): Ferrari's mountain crest is 41% 1:1 steps and 53% flat
runs of 3-6 px then a single step; the right shoulder is 43% 1:1 and 29% 2:1.  Silhouettes are
straight segments with CONSISTENT step ratios, not noise.  These helpers impose the same grammar
on procedurally generated shapes: simplify the contour to a polygon, snap every edge to one of the
clean pixel slopes, solve for vertex positions that keep the shape, and re-rasterise.
"""
import numpy as np
from PIL import Image, ImageDraw
from skimage import measure
from scipy.ndimage import distance_transform_edt

# clean slopes as (dx, dy) directions: flat, 3:1, 2:1, 1:1, 1:2, 1:3, vertical (both signs)
_BASE = [(1, 0), (3, 1), (2, 1), (1, 1), (1, 2), (1, 3), (0, 1)]
DIRS = []
for dx, dy in _BASE:
    for sx, sy in ((1, 1), (1, -1), (-1, 1), (-1, -1)):
        v = (dx * sx, dy * sy)
        if v not in DIRS: DIRS.append(v)
DIRS = np.array(DIRS, float)
UDIRS = DIRS / np.linalg.norm(DIRS, axis=1, keepdims=True)


def snap_polygon(P, prefer_flat=0.0):
    """P: (n,2) closed polygon (x,y). Returns a polygon whose edges all have clean slopes."""
    n = len(P)
    E = np.roll(P, -1, 0) - P
    L = np.linalg.norm(E, axis=1) + 1e-9
    U = E / L[:, None]
    cos = U @ UDIRS.T
    # a little bias toward flat runs (ground contacts, crests read level)
    cos = cos + prefer_flat * (np.abs(UDIRS[:, 1]) < 1e-6)[None]
    D = UDIRS[np.argmax(cos, 1)]
    # unknowns: v0 (2) + t_i (n); vertex i = v0 + sum_{j<i} t_j D_j
    A = np.zeros((2 * n + 2, 2 + n)); b = np.zeros(2 * n + 2)
    for i in range(n):
        A[2 * i, 0] = 1; A[2 * i + 1, 1] = 1
        for j in range(i):
            A[2 * i, 2 + j] = D[j, 0]; A[2 * i + 1, 2 + j] = D[j, 1]
        b[2 * i] = P[i, 0]; b[2 * i + 1] = P[i, 1]
    w = 30.0                                             # closure
    A[2 * n, 2:] = w * D[:, 0]; A[2 * n + 1, 2:] = w * D[:, 1]
    sol, *_ = np.linalg.lstsq(A, b, rcond=None)
    v0, t = sol[:2], sol[2:]
    V = [v0]
    for j in range(n - 1):
        V.append(V[-1] + t[j] * D[j])
    return np.array(V)


def clean_mask(mask, tol=1.1, min_area=6, prefer_flat=0.0):
    """re-rasterise a binary mask with clean-slope straight edges"""
    H, W = mask.shape
    pad = np.pad(mask.astype(float), 1)
    out = Image.new('L', (W, H), 0); d = ImageDraw.Draw(out)
    holes = []
    for c in measure.find_contours(pad, 0.5):
        c = c[:, ::-1] - 1                                # (x, y)
        if len(c) < 8: continue
        area = 0.5 * np.abs(np.dot(c[:, 0], np.roll(c[:, 1], 1)) - np.dot(c[:, 1], np.roll(c[:, 0], 1)))
        if area < min_area: continue
        poly = measure.approximate_polygon(c, tolerance=tol)[:-1]
        if len(poly) < 3: continue
        sp = snap_polygon(poly, prefer_flat)
        # orientation decides fill or hole: sample the original mask at the contour's interior side
        inside = measure.points_in_poly(np.argwhere(mask)[:, ::-1] + 0.0, c).mean() if False else None
        xy = [tuple(p) for p in np.round(sp + 0.0).astype(int)]
        cy, cx = np.round(c.mean(0)[::-1]).astype(int)
        signed = np.sum((np.roll(c[:, 0], -1) - c[:, 0]) * (np.roll(c[:, 1], -1) + c[:, 1]))
        (holes if signed > 0 else [None]).append(xy) if False else None
        rr = measure.grid_points_in_poly((H, W), c[:, ::-1])
        frac = mask[rr].mean() if rr.any() else 1
        if frac > 0.5: d.polygon(xy, fill=1)
        else: holes.append(xy)
    for xy in holes: d.polygon(xy, fill=0)
    return np.array(out) > 0


def refill(img, old, new, fallback=None):
    """pixels gained take the nearest old-inside colour; pixels lost take the nearest outside colour"""
    out = img.copy()
    gain = new & ~old; lose = old & ~new
    if gain.any():
        _, (iy, ix) = distance_transform_edt(~old, return_indices=True)
        out[gain] = img[iy[gain], ix[gain]]
    if lose.any():
        src = fallback if fallback is not None else img
        _, (iy, ix) = distance_transform_edt(old, return_indices=True)
        out[lose] = src[iy[lose], ix[lose]]
    return out


def polyline_profile(f, u0, u1, knots, rng, jitter=0.35):
    """sample f at knots, then join them with clean-slope segments (for ridges / crests).
    Returns y per integer column u in [u0, u1)."""
    us = np.linspace(u0, u1, knots)
    us[1:-1] += rng.uniform(-jitter, jitter, knots - 2) * (us[1] - us[0])
    ys = f(us)
    P = [(us[0], ys[0])]
    for i in range(1, len(us)):
        dx, dy = us[i] - P[-1][0], ys[i] - P[-1][1]
        # snap slope to the clean set (x must advance)
        cand = [(1, 0), (3, 1), (2, 1), (1, 1), (1, 2), (1, 3), (1, 5)]
        best = min(cand, key=lambda c: abs(np.arctan2(abs(dy), dx) - np.arctan2(c[1], c[0])))
        slope = np.sign(dy) * best[1] / best[0]
        P.append((us[i], P[-1][1] + slope * dx))
    P = np.array(P)
    u = np.arange(int(u0), int(u1))
    y = np.interp(u, P[:, 0], P[:, 1])
    return u, np.floor(y + 0.5)

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/pixelgeo.py'
s=open(f).read()
a=s.index("        # orientation decides fill or hole"); b=s.index("        rr = measure.grid_points_in_poly")
s=s[:a]+"        xy = [tuple(p) for p in np.round(sp).astype(int)]\n"+s[b:]
open(f,'w').write(s)
EOF
cd src/paint && nice -n 10 python3 -c "
import numpy as np, pixelgeo as pg
from PIL import Image
yy,xx=np.mgrid[0:60,0:80]
rng=np.random.default_rng(0)
m=((xx-40)**2/30**2+(yy-32)**2/20**2+0.15*rng.random((60,80)))<1
n=pg.clean_mask(m,1.1)
out=np.concatenate([m,np.zeros((60,2),bool),n],1)
Image.fromarray((np.repeat(np.repeat(out,6,0),6,1)*255).astype(np.uint8)).save('../../out/test_clean.png')
"

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && sed -n '/    def render(self):/,/        return RGB\[img\]/p' src/paint/ferrari_method.py

# output:
def render(self):
        T = threshold_maps(self.noise, self.rng)
        self._forest = self.forest_profile()
        d = self.camera_rays().reshape(-1, 3)
        o = np.tile([0.0, HC, 0.0], (d.shape[0], 1))
        t, kind = self.march(o, d)
        p = o + d * t[:, None]
        yy, xx = np.mgrid[0:H, 0:W]
        img = np.zeros(H * W, int)
        Lt = np.zeros(H * W)             # target value (for analysis / debugging)
        self.gb = dict(kind=kind.reshape(H, W), t=t.reshape(H, W))
        vrow = (Y_H - (yy + 0.5)).ravel()

        # ---------------- backdrop: sky, mountain, far forest
        sky = kind == 0
        bd = self.backdrop(xx.ravel()[sky].astype(float), vrow[sky])
        img[sky] = self.paint_backdrop(bd, T, yy.ravel()[sky], xx.ravel()[sky])
        # plane labels for self-analysis: 0 sky 1 mountain 2 forest 3 water 4 bank 5 boulder 6 near bank
        pl_ = np.zeros(H * W, int); pl_[sky] = bd['mat']
        pl_[kind == 3] = 3; pl_[kind == 1] = 4; pl_[kind == 2] = 5
        self.planes = pl_.reshape(H, W)

        # ---------------- land (bank) & boulder
        self.paint_land(img, Lt, kind, p, d, T)
        self.paint_boulder(img, Lt, kind, p, d, T)

        # ---------------- water: reflection
        self.paint_water(img, kind, p, d, T, xx.ravel(), yy.ravel())

        img = img.reshape(H, W)
        # ---------------- strokes: grass blades & sedge, back to front
        img = self.paint_strokes(img, kind.reshape(H, W), p.reshape(H, W, 3), t.reshape(H, W))
        # ---------------- near repoussoir bank (dark, bottom corner opposite the boulder)
        # (the screen-space repoussoir is replaced by the 3D near bank)
        self.index = img
        return RGB[img]

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[
("import numpy as np\nfrom PIL import Image\n","import numpy as np\nfrom PIL import Image\nimport pixelgeo as pg\n"),
("""    def ridge(self, u):
        n = self.noise""","""    def ridge(self, u):
        \"\"\"the mountain's crest, built of straight clean-slope segments (Ferrari's crest grammar)\"\"\"
        if not hasattr(self, '_ridge_pl'):
            rng = np.random.default_rng(self.p['seed'] + 17)
            uu, yy = pg.polyline_profile(self.ridge_raw, -12, W + 12, int(W / 8), rng)
            self._ridge_pl = (uu, yy)
        uu, yy = self._ridge_pl
        return np.interp(np.asarray(u, float), uu, yy)

    def ridge_raw(self, u):
        n = self.noise"""),
("""        img = img.reshape(H, W)
        # ---------------- strokes: grass blades & sedge, back to front
        img = self.paint_strokes(img, kind.reshape(H, W), p.reshape(H, W, 3), t.reshape(H, W))""",
"""        img = img.reshape(H, W); kind2 = kind.reshape(H, W).copy()
        # ---------------- pixel geometry: silhouettes as clean straight runs, flat bottoms, dark lips
        img, kind2 = self.pixel_geometry(img, kind2, p.reshape(H, W, 3))
        # ---------------- strokes: grass blades & sedge, back to front
        img = self.paint_strokes(img, kind2, p.reshape(H, W, 3), t.reshape(H, W))"""),
("""        self.index = img
        return RGB[img]""","""        pl2 = self.planes.copy()
        pl2[(kind2 == 1)] = 4; pl2[kind2 == 2] = 5
        pp = p.reshape(H, W, 3)
        near = (kind2 == 1) & (self.near_sd(pp[..., 0], pp[..., 2]) > -0.05)
        pl2[near] = 6
        self.planes = pl2
        self.index = img
        return RGB[img]

    def pixel_geometry(self, img, kind, p):
        # boulder silhouette -> clean-slope polygon, with a bias to a flat bottom where it meets water
        bm = kind == 2
        if bm.sum() > 20:
            nb = pg.clean_mask(bm, 1.0, prefer_flat=0.12)
            img = pg.refill(img, bm, nb); kind = pg.refill(kind, bm, nb)
            kind[nb] = 2
        # boulder reflection gets the same grammar
        rb = self.refl_boulder
        if rb.sum() > 20:
            nr = pg.clean_mask(rb, 1.0, prefer_flat=0.12) & (kind == 3)
            img = pg.refill(img, rb, nr)
        # land silhouettes (bank tops against water / forest)
        lm = kind == 1
        if lm.sum() > 20:
            nl = pg.clean_mask(lm, 1.3, min_area=10, prefer_flat=0.08) & (kind != 2)
            img = pg.refill(img, lm, nl); k2 = pg.refill(kind, lm, nl); k2[nl] = 1; kind = k2
        # dark lip: the first water row under a bank or the boulder is a dark contact line (flat base)
        below_b = np.zeros_like(bm); below_b[1:] = (kind[:-1] == 2) & (kind[1:] == 3)
        below_l = np.zeros_like(bm); below_l[1:] = (kind[:-1] == 1) & (kind[1:] == 3)
        img[below_b] = IDX['r0']
        img[below_l] = IDX['g0']
        return img, kind"""),
]
for a,b in rep:
    assert a in s, a[:60]; s=s.replace(a,b)
# store boulder reflection mask in paint_water
a="""        # reflected boulder & land: re-shade with the same light, flat reading"""
b="""        self.refl_boulder = np.zeros((H, W), bool)
        wi = np.flatnonzero(m)
        self.refl_boulder.ravel()[wi[k2 == 2]] = True
        # reflected boulder & land: re-shade with the same light, flat reading"""
assert a in s; s=s.replace(a,b)
s=s.replace("""        m = kind == 3
        if not m.any(): return
        pw = p[m]; dw = d[m].copy()""","""        m = kind == 3
        self.refl_boulder = np.zeros((H, W), bool)
        if not m.any(): return
        pw = p[m]; dw = d[m].copy()""")
open(f,'w').write(s)
EOF
cd src/paint && time nice -n 10 python3 debug_gb.py medium left 10m 1 && echo ok

# output:
Exit code 1
Traceback (most recent call last):
  File "~/work/pixelart-studies/pedagogy/analysis/src/paint/debug_gb.py", line 14, in <module>
    Image.fromarray(np.repeat(np.repeat(out,2,0),2,1)).save('out/debug_gb.png')
  File "~/miniconda3/lib/python3.12/site-packages/PIL/Image.py", line 2591, in save
    fp = builtins.open(filename, "w+b")
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
FileNotFoundError: [Errno 2] No such file or directory: 'out/debug_gb.png'
nice -n 10 python3 debug_gb.py medium left 10m 1  38.96s user 11.65s system 103% cpu 48.938 total

cd ~/work/pixelart-studies/pedagogy/analysis && sed -i '' "s|'out/debug_gb.png'|os.path.join(os.path.dirname(os.path.abspath(__file__)),'..','..','out','debug_gb.png')|; s|^import numpy as np$|import numpy as np, os|" src/paint/debug_gb.py && sed -i '' "s|sys.path.insert(0,'src/paint')|sys.path.insert(0,os.path.dirname(os.path.abspath(__file__)))|; s|^import sys; |import sys, os; |" src/paint/debug_gb.py && head -3 src/paint/debug_gb.py && nice -n 10 python3 src/paint/debug_gb.py medium left 10m 1

# output:
import sys, os; sys.path.insert(0,os.path.dirname(os.path.abspath(__file__))); import ferrari_method as fm
import numpy as np, os
from PIL import Image

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
a=s.index("    def near_sd(self, x, z):"); b=s.index("    def land_h(self, x, z):")
s=s[:a]+'''    def near_sd(self, x, z):
        """the camera's own bank: a V opening onto the water (Ferrari's two foreground banks).
        Its edge is designed in the PICTURE (a composition line), then lifted onto the ground."""
        c, sn = np.cos(PITCH), np.sin(PITCH)
        yc = -HC * c + z * sn * -1 * -1 if False else None
        # camera coordinates of the ground point (x, 0, z)
        cy = -HC * c - z * sn * -1 if False else None
        # rotate world->camera (inverse pitch)
        Yw, Zw = -HC, z
        yc = Yw * c + Zw * sn
        zc = -Yw * sn + Zw * c
        zc = np.maximum(zc, 0.1)
        u = W / 2 + F * x / zc
        yscr = H / 2 - F * yc / zc
        s_ = 1.0 if self.bx < 0 else -1.0
        uu = u if s_ > 0 else (W - u)                      # uu: boulder side on the left
        n = self.noise
        wob = 5.0 * n.fbm2(uu / 23.0 + 40, np.full(np.shape(uu), 2.2), 3)
        e_left = H * 0.66 + (uu / (0.30 * W)) * (H * 0.40)           # low bank on the boulder side
        e_right = H + 4 - ((uu - 0.56 * W) / (0.44 * W)) * (H * 0.58)  # rising dark bank opposite
        edge = np.minimum(np.maximum(e_left, e_right), H + 6) + wob
        return (yscr - edge) * zc / F

'''+s[b:]
open(f,'w').write(s)
EOF
nice -n 10 python3 src/paint/debug_gb.py medium left 10m 1

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
s=s.replace("        edge = np.minimum(np.maximum(e_left, e_right), H + 6) + wob","        edge = np.minimum(np.minimum(e_left, e_right), H + 6) + wob")
for junk in ["        yc = -HC * c + z * sn * -1 * -1 if False else None\n","        # camera coordinates of the ground point (x, 0, z)\n        cy = -HC * c - z * sn * -1 if False else None\n"]:
    s=s.replace(junk,"" if 'cy' not in junk else "        # camera coordinates of the ground point (x, 0, z)\n")
open(f,'w').write(s)
EOF
grep -n "if False" src/paint/ferrari_method.py; nice -n 10 python3 src/paint/debug_gb.py medium left 10m 1

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && sed -n '/    def ridge_raw(self, u):/,/        return dict(mat=mat/p' src/paint/ferrari_method.py

# output:
def ridge_raw(self, u):
        n = self.noise; ms = self.mtn_seed; uu = np.asarray(u, float) / W
        peak_u = 0.72 if self.bx < 0 else 0.28
        return 14 + 12 * np.exp(-((uu - peak_u) / 0.16) ** 2) + 5 * np.exp(-((uu - peak_u + 0.22) / 0.09) ** 2) \
            + 3.5 * n.fbm2(uu * 9 + ms, np.full(uu.shape, 1.7), 4) + 1.2 * np.abs(n.fbm2(uu * 40 + ms, np.full(uu.shape, 5.1), 2))

    def relief(self, u, v):
        n = self.noise; ms = self.mtn_seed
        return n.fbm2(u / 7.0 + ms, v / 4.0, 4) * 3.0 - np.abs(n.fbm2(u / 16.0 + ms, v / 9.0 + 3, 3)) * 7

    def backdrop(self, u, v):
        """material / value / aux for backdrop points. returns dict of arrays."""
        n = self.noise
        u = np.asarray(u, float); v = np.asarray(v, float)
        mat = np.zeros(u.shape, int)      # 0 sky, 1 mountain, 2 forest
        # sky: position along the violet->peach ramp. brightest/warmest near the horizon on the sun side
        az_sun = np.arctan2(self.l[0], self.l[2])
        az = np.arctan2((u - W / 2) / F, 1.0)
        warm = np.cos(az - az_sun)                           # 1 toward sun, -1 away
        e = np.clip(v / 60.0, 0, 1.5)
        pos = 3.9 - 3.3 * e ** 0.8 + 0.9 * warm * np.exp(-e * 1.5)
        if self.light == 'front':                            # sun behind camera: belt of Venus
            pos = 2.6 - 2.4 * np.clip(e, 0, 1) + 1.0 * np.exp(-((v - 12) / 9.0) ** 2) - 1.2 * np.exp(-(v / 3.5) ** 2)
        if self.light == 'back':                             # sun just above the frame: glow
            pos = pos + 0.9 * np.exp(-e * 1.0) * np.clip(warm, 0, 1) ** 4
        sky_pos = np.clip(pos, 0, 5.0)
        # mountain ridge (functions of u so derivatives are exact even for scattered samples)
        ridge = self.ridge(u)
        dr = self.ridge(u + 0.5) - self.ridge(u - 0.5)
        in_m = v < ridge
        gx = self.relief(u + 0.5, v) - self.relief(u - 0.5, v)
        sun_x = self.l[0]
        if self.light == 'back':
            facing = -0.5 + 0.0 * gx
        elif self.light == 'front':
            facing = 0.35 + 0.25 * np.abs(gx) - 0.25 * np.abs(dr)
        else:
            facing = -np.sign(sun_x) * (dr * 0.8 + gx * 0.6)
        snow = (v > ridge - 9 + 3 * n.fbm2(u / 5.0 + 9, v / 3.0, 3)) & (np.abs(dr) < 1.6) & in_m
        m_lit = facing > 0.15
        # forest (far shore) silhouettes
        top, trees = self._forest
        uc = np.clip(np.round(u).astype(int), 0, W - 1)
        f_top = top[uc]
        in_f = v < f_top
        f_lit = np.zeros(u.shape, bool)
        for (tx, hgt_t, wr) in trees:
            dy = hgt_t - v                                    # distance below the tip
            ok = (dy > 0) & (v > -0.5)
            if not ok.any(): continue
            tier = (np.floor(dy / 1.7) % 2)
            halfw = dy * wr * (1 + 0.35 * (((dy / 1.7) % 1.0) > 0.45)) + 0.35
            dx = u - tx
            inside = ok & (np.abs(dx) < halfw)
            in_f = in_f | inside
            side = dx * -np.sign(sun_x

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
a=s.index("    def ridge_raw(self, u):"); b=s.index("    def backdrop(self, u, v):")
s=s[:a]+'''    def ridge_raw(self, u):
        """a big peak, deliberately taller than the frame: the frame crops it, the water shows it whole"""
        n = self.noise; ms = self.mtn_seed; uu = np.asarray(u, float) / W
        pu = 0.70 if self.bx < 0 else 0.30
        pu2 = pu - 0.26 if pu > 0.5 else pu + 0.26
        return 13 + 52 * np.maximum(0, 1 - np.abs(uu - pu) / 0.25) ** 1.25 \\
            + 24 * np.maximum(0, 1 - np.abs(uu - pu2) / 0.13) ** 1.1 \\
            + 3.0 * n.fbm2(uu * 8 + ms, np.full(uu.shape, 1.7), 3)

    def relief(self, u, v):
        """depth-relief of the mountain face: big flanks either side of the peak + ridged spurs"""
        n = self.noise; ms = self.mtn_seed
        pu = (0.70 if self.bx < 0 else 0.30) * W
        spurs = 1 - np.abs(n.fbm2((u + 0.6 * v) / 13.0 + ms, (v - 0.3 * u) / 9.0, 3))
        spurs2 = 1 - np.abs(n.fbm2((u - 0.7 * v) / 6.0 + ms, v / 5.0 + 4, 2))
        return -0.35 * np.abs(u - pu) + 7 * spurs + 2.5 * spurs2

    def mountain_light(self, u, v):
        e = 0.7
        hu = (self.relief(u + e, v) - self.relief(u - e, v)) / (2 * e)
        hv = (self.relief(u, v + e) - self.relief(u, v - e)) / (2 * e)
        nrm = np.stack([-hu, 0.55 - 0.5 * hv, np.ones_like(hu)], -1)
        nrm /= np.linalg.norm(nrm, axis=-1, keepdims=True)
        lm = np.array([self.l[0], self.l[1] + 0.12, -self.l[2]]); lm /= np.linalg.norm(lm)
        return (nrm * lm).sum(-1), nrm

'''+s[b:]
a=s.index("        gx = self.relief(u + 0.5, v) - self.relief(u - 0.5, v)"); b=s.index("        m_lit = facing > 0.15")
s=s[:a]+'''        ndl_m, nrm_m = self.mountain_light(u, v)
        if self.light == 'back':
            facing = ndl_m - 0.25              # mostly silhouette; only crests catch light
        else:
            facing = ndl_m
        snow = in_m & (v > 17 + 7 * n.fbm2(u / 9.0 + 9, v / 5.0, 3)) & (nrm_m[..., 1] > 0.18 + 0.2 * n.fbm2(u / 4.0, v / 3.0 + 2, 2))
'''+s[b:]
s=s.replace("        m_lit = facing > 0.15","        m_lit = facing > 0.12")
open(f,'w').write(s)
EOF
nice -n 10 python3 src/paint/debug_gb.py medium left 10m 1

# output:
Exit code 1
Traceback (most recent call last):
  File "~/work/pixelart-studies/pedagogy/analysis/src/paint/debug_gb.py", line 10, in <module>
    rgb=s.render()
        ^^^^^^^^^^
  File "~/work/pixelart-studies/pedagogy/analysis/src/paint/ferrari_method.py", line 462, in render
    bd = self.backdrop(xx.ravel()[sky].astype(float), vrow[sky])
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "~/work/pixelart-studies/pedagogy/analysis/src/paint/ferrari_method.py", line 427, in backdrop
    side = dx * -np.sign(sun_x) if abs(sun_x) > 0.2 else -np.abs(dx)
                                       ^^^^^
NameError: name 'sun_x' is not defined

cd ~/work/pixelart-studies/pedagogy/analysis && sed -i '' 's/        ndl_m, nrm_m = self.mountain_light(u, v)/        sun_x = self.l[0]\n        ndl_m, nrm_m = self.mountain_light(u, v)/' src/paint/ferrari_method.py && nice -n 10 python3 src/paint/debug_gb.py medium left 10m 1

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && sed -n '/    def paint_strokes/,/        return out/p' src/paint/ferrari_method.py

# output:
def paint_strokes(self, img, kind, p, t):
        """grass blades & sedge, back to front, in counterchange with what lies behind"""
        rng = np.random.default_rng(self.p['seed'] + 101)
        out = img.copy()
        land = kind == 1
        ys, xs = np.nonzero(land)
        if len(ys) == 0: return out
        z = t[ys, xs]
        pl = p[ys, xs]
        # blade world height: short turf; sedge near the boulder foot and at the waterline
        db = self.boulder_sd(pl)
        sd = self.land_sd(pl[:, 0], pl[:, 2])
        near_b = np.exp(-np.maximum(db, 0) / (0.45 * self.r))
        clump = smoothstep(0.1, 0.6, self.noise.fbm2(pl[:, 0] * 0.9 + 3, pl[:, 2] * 0.9, 2))
        near_w = np.exp(-np.maximum(sd, 0) / 0.4) * clump
        hb = 0.07 + 0.45 * np.maximum(near_b, 0.7 * near_w) * self.r ** 0.3
        Lpx = F * hb / z
        dens = np.clip(0.10 + 0.5 * np.maximum(near_b, near_w), 0, 0.8) * (Lpx >= 1.5)
        spawn = rng.random(len(ys)) < dens
        order = np.argsort(ys[spawn], kind='stable')           # back (top) to front (bottom)
        bys, bxs, bL = ys[spawn][order], xs[spawn][order], Lpx[spawn][order]
        lit_here = self.land_lit.reshape(H, W)[bys, bxs] > 0.5
        lean_field = self.noise.fbm2(bxs / 23.0, bys / 17.0, 2, 9.1) * 0.55
        LVimg = LV
        sun_side = -np.sign(self.l[0]) if abs(self.l[0]) > 0.2 else 0
        for i in range(len(bys)):
            y0, x0 = bys[i], bxs[i]
            L = int(np.clip(round(bL[i] * rng.uniform(0.55, 1.25)), 1, 26))
            ang = lean_field[i] + rng.normal(0, 0.18)
            curl = rng.normal(0, 0.035)
            x = float(x0); y = y0
            bg = out[y0, x0]
            blit = lit_here[i]
            for k in range(L):
                yy = y - k
                if yy < 0: break
                xi = int(round(x))
                if not (0 <= xi < W): break
                behind = LVimg[out[yy, xi]]
                tip = k >= L - max(1, L // 4)
                # counterchange: dark blade over light, light blade over dark
                if behind > 42:
                    c = IDX['g2'] if (blit and rng.random() < 0.55) else IDX['g0']
                    if kind[yy, xi] == 2 or kind[yy, xi] == 0 or kind[yy, xi] == 3:
                        c = IDX['g0'] if behind > 55 else IDX['h1']
                else:
                    if blit:
                        c = IDX['g4'] if tip else IDX['g2']
                        if self.light == 'back' and tip: c = IDX['g5']
                    else:
                        c = IDX['h2'] if tip else (IDX['g1'] if behind > 16 else IDX['h1'])
                        if kind[yy, xi] != 1: c = IDX['sedge'] if tip else IDX['g1']
                out[yy, xi] = c
                ang += curl
                x += np.tan(np.clip(ang, -1.1, 1.1))
            # reflection of blades rooted at the waterline
            if near_w[spawn][order][i] > 0.6 and L >= 3:
                x = float(x0)
                for k in range(1, int(L * 0.6)):

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
a=s.index("        lit_here = self.land_lit.reshape(H, W)[bys, bxs] > 0.5"); b=s.index("        return out\n", a)
s=s[:a]+'''        lit_here = self.land_lit.reshape(H, W)[bys, bxs] > 0.5
        wline = near_w[spawn][order]
        lean_field = self.noise.fbm2(bxs / 23.0, bys / 17.0, 2, 9.1)
        sun_dx = -1 if self.l[0] < -0.2 else (1 if self.l[0] > 0.2 else 0)   # screen side the sun is on
        # blade = straight runs with clean steps: a lower segment at one slope, the tip at a shallower
        # one (the arc of a sedge leaf), slopes from the pixel-clean set (dx per dy)
        SLOPES = [0.0, 1 / 3, 1 / 2, 1.0]
        for i in range(len(bys)):
            y0, x0 = bys[i], bxs[i]
            L = int(np.clip(round(bL[i] * rng.uniform(0.55, 1.25)), 1, 26))
            lean = lean_field[i] * 1.6 + rng.normal(0, 0.45)
            sgn = 1 if lean >= 0 else -1
            k0 = int(np.clip(abs(lean) * 2.2, 0, 3))
            k1 = min(3, k0 + (1 if (L > 5 and rng.random() < 0.6) else 0))
            split = int(L * rng.uniform(0.45, 0.75))
            blit = lit_here[i]
            x = float(x0); acc = 0.0
            pts = []
            for k in range(L):
                yy = y0 - k
                if yy < 0: break
                sl = SLOPES[k0] if k < split else SLOPES[k1]
                acc += sl
                if acc >= 1.0 - 1e-9:
                    x += sgn * np.floor(acc + 1e-9); acc -= np.floor(acc + 1e-9)
                xi = int(x)
                if not (0 <= xi < W): break
                pts.append((yy, xi, k))
            for (yy, xi, k) in pts:
                behind = LV[out[yy, xi]]
                tipf = k / max(1, L - 1)
                over_other = kind[yy, xi] != 1                      # blade crossing boulder / water / sky
                # impressionistic contrast inside the stroke: every blade carries two values
                if behind > 42:                                     # on light: a dark blade...
                    c = IDX['g0'] if (over_other or not blit or rng.random() < 0.6) else IDX['g2']
                    out[yy, xi] = c
                    if blit and sun_dx and 0 <= xi + sun_dx < W and not over_other and tipf > 0.3:
                        out[yy, xi + sun_dx] = IDX['g4'] if self.light != 'back' else IDX['g5']   # ...with its lit edge
                else:                                               # on dark: a light blade, lighter at the tip
                    if blit:
                        c = IDX['g2'] if tipf < 0.4 else (IDX['g3'] if tipf < 0.75 else IDX['g4'])
                        if self.light == 'back' and tipf > 0.7: c = IDX['g5']
                    else:
                        c = IDX['h1'] if tipf < 0.35 else (IDX['g1'] if tipf < 0.7 else IDX['h2'])
                        if over_other: c = IDX['g1'] if tipf < 0.6 else IDX['sedge']
                    out[yy, xi] = c
                    if sun_dx and blit and 0 <= xi - sun_dx < W and tipf > 0.2 and not over_other:
                        out[yy, xi - sun_dx] = IDX['g0']                # its shadow side
            # reflection of blades rooted at the waterline: short, dark, broken
            if wline[i] > 0.6 and L >= 3:
                for (yy, xi, k) in pts[:max(1, int(len(pts) * 0.55))]:
                    ry = y0 + (y0 - yy) + 1
                    if ry < H and kind[ry, xi] == 3 and rng.random() > 0.25:
                        out[ry, xi] = IDX['for0'] if LV[out[ry, xi]] > 30 else IDX['g1']
'''+s[b:]
open(f,'w').write(s)
EOF
nice -n 10 python3 src/paint/debug_gb.py medium left 10m 1

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && nice -n 10 python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('out/debug_gb.png'))[:, 640:]  # painted half at 2x
a=a[::2,::2]
Image.fromarray(np.repeat(np.repeat(a[40:180, 0:200],5,0),5,1)).save('out/zoom_a.png')
Image.fromarray(np.repeat(np.repeat(a[20:110, 120:320],5,0),5,1)).save('out/zoom_b.png')
"

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && FORCE=1 OMP_NUM_THREADS=1 nice -n 10 python3 src/paint/sheets.py > out/sheets.log 2>&1

# output:
Command running in background with ID: b4wyuyyls. 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.

"""Apply the SAME analyses used on Ferrari to painted cells, and compare side by side.
usage: python src/check_sheets.py <cell_key> [<cell_key> ...]   (keys as in sheets/cells/*.png)"""
import sys, os, json
sys.path.insert(0, 'src')
from util import *
from scipy.ndimage import gaussian_filter
from collections import Counter
import matplotlib; matplotlib.use('Agg'); import matplotlib.pyplot as plt
from clusters import cluster_stats, run_lengths
from dither import dither_stats
from values import analyse
from depth import depth_stats, plot as depth_plot
from planes_names import NAMES as FNAMES

CELLS = 'sheets/cells'
MY = ['sky', 'mountain', 'far forest', 'water', 'bank (boulder side)', 'boulder', 'near bank lit', 'near bank shade']
# correspondences: my plane -> Ferrari plane ids
CORR = {'sky': [0], 'mountain': [1], 'far forest': [2], 'water': [6], 'bank (boulder side)': [7, 5],
        'boulder': [1], 'near bank lit': [8], 'near bank shade': [9]}


def load_cell(key):
    a = np.array(Image.open(f'{CELLS}/{key}.png').convert('RGB'))
    pl = np.load(f'{CELLS}/{key}_planes.npy')
    # split the near bank into its lit and shaded masses by squinted value
    Lb = gaussian_filter(lum(a), 3)
    p2 = pl.copy()
    near = pl == 6
    p2[near & (Lb < 24)] = 7
    return a, p2


def stats_table(a, P, names, corr_ref=None):
    rows = {}
    lab = rgb2lab(a); L = lab[..., 0]
    same_v = np.all(a[1:] == a[:-1], axis=2); same_h = np.all(a[:, 1:] == a[:, :-1], axis=2)
    ds, _ = dither_stats(a, P, names)
    for i, n in enumerate(names):
        m = P == i
        if m.sum() < 80: continue
        cs = cluster_stats(a, m)
        c = Counter(map(tuple, a[m])); tot = sum(c.values())
        cum = np.cumsum(sorted(c.values(), reverse=True)) / tot
        rows[n] = dict(area=float(m.mean()), L_med=float(np.median(gaussian_filter(L, 2.5)[m])),
                       L_p5=float(np.percentile(L[m], 5)), L_p95=float(np.percentile(L[m], 95)),
                       colours_90=int(np.searchsorted(cum, 0.9) + 1), vsame=float(same_v[m[1:]].mean()),
                       hsame=float(same_h[m[:, 1:]].mean()), cluster_med=float(cs['size_med']),
                       cluster_mean=float(cs['size_mean']), single=float(cs['single']),
                       checker=float(ds.get(n, {}).get('checker', 0)), chroma=float(np.median(np.hypot(lab[..., 1], lab[..., 2])[m])),
                       b=float(np.median(lab[..., 2][m])))
    return rows


if __name__ == '__main__':
    keys = sys.argv[1:]
    ref = load_ref(); Pref = np.load('out/planes.npy')
    R = stats_table(ref, Pref, FNAMES)
    allrows = {'ferrari': R}
    for key in keys:
        a, P = load_cell(key)
        res, _ = analyse(a, P, MY, key, f'chk_{key}')
        M = stats_table(a, P, MY)
        allrows[key] = M
        rows = depth_stats(a, P, [('near bank', [6, 7]), ('bank (boulder side)', [4]), ('boulder', [5]),
                                  ('far forest', [2]), ('mountain', [1]), ('sky', [0])])
        depth_plot(rows, f'img/chk_{key}_depth.png', f'{key}: depth cues, near -> far')
        # side-by-side notan / grey with Ferrari (reference scaled to the same height)
        for kind in ('notan', 'grey'):
            mine = np.array(Image.open(f'img/chk_{key}_{kind}.png').convert('RGB'))
            theirs = np.array(Image.open(f'img/03_{kind}.png').convert('RGB'))
            h = min(mine.shape[0], theirs.shape[0])
            th = np.array(Image.fromarray(theirs).resize((int(theirs.shape[1] * h / theirs.shape[0]), h), Image.NEAREST))
            mi = np.array(Image.fromarray(mine).resize((int(mine.shape[1] * h / mine.shape[0]), h), Image.NEAREST))
            Image.fromarray(np.concatenate([th, np.full((h, 10, 3), 255, np.uint8), mi], 0 if kind == 'notan' else 1)).save(f'img/chk_{key}_{kind}_vs.png')
    json.dump(allrows, open('out/check_stats.json', 'w'), indent=1)
    # print comparison of corresponding planes
    for key in keys:
        print('=' * 20, key)
        for n, ids in CORR.items():
            if n not in allrows[key]: continue
            m = allrows[key][n]; f = allrows['ferrari'][FNAMES[ids[0]]]
            print(f'{n:20s} vs {FNAMES[ids[0]]:18s}| ' + ' '.join(f'{k}={m[k]:.2f}/{f[k]:.2f}' for k in ('L_med', 'L_p5', 'L_p95', 'colours_90', 'vsame', 'hsame', 'cluster_mean', 'single', 'checker', 'b')))

# Learning to paint like Mark Ferrari: a study of *Alpine Tarn at Dusk*

Everything below comes from programs in `src/`, and every figure is in `img/`. I looked at each
figure myself before writing about it. The reference arrived as a 1268×938 PNG. It is an exact 2×
nearest-neighbour upscale (every 2×2 block is one colour, with no phase error), so the native
picture is **634×469 in 172 colours** (`img/00_native.png`). All measurements below are made on
the native pixels.

Contents

1. Analysis, drawn: planes, values, light, form, edges, clusters, palette, depth, pixel geometry
2. What it means: Ferrari's method, as a painter would teach it
3. The method: `src/paint/ferrari_method.py`, parameters and sheets
4. Checking my sheets with the same analyses, one by one
5. What I would do next

---

## 1. The analysis

### 1.1 Planes and big masses (`img/02_planes.png`)

I traced ten planes by hand, using polygons for the ground and colour tests to split sky from tree
and rock. Share of the picture:

| plane | area | | plane | area |
|---|---|---|---|---|
| sky | 17.9% | | water | 16.5% |
| mountain | 4.0% | | left meadow (mid) | 4.6% |
| far forest | 9.0% | | left bank (fore) | 10.8% |
| framing trees | 15.7% | | right bank (fore) | 13.1% |
| far banks / hummocks | 6.6% | | island | 1.8% |

The composition is a **V of foreground banks opening onto water**. The lit left bank drops from the
middle-left down to the bottom centre, and the shadowed right bank rises diagonally from the bottom
centre to the right edge. The water sits in the V. Above it a band of low hummocks carries the far
shore, then a dark forest band, a small peak and a large sky. Tall framing conifers on both sides
close the rectangle. The peak, the only warm-and-cool jewel, sits almost dead centre, in a notch
the conifers leave open. Its reflection lies exactly under it, inside the V, so the V points the
eye at the mirrored peak.

### 1.2 Value structure (`img/03_grey.png`, `img/03_notan.png`, `img/03_valueplanes.png`, `img/03_valueplan.png`)

The grey version uses CIE L\*. Beside it is a squint version (Gaussian σ=2.5 px), because dithering
means individual pixels lie about the value a region reads as.

* **Two-value notan** (cut at L\*≈40): light = sky + snowfield + the reflected sky in the water +
  the lit left bank. Dark = every tree, the far banks and the whole right bank. It reads as an
  hourglass. A light field at the top pours through the notch around the peak into a light field
  at the bottom (water plus the left bank), pinched by two dark masses of trees and banks.
* **Three-value notan**, with k-means centres at L\* **16 / 42 / 70**. Every plane stays inside one
  or two of the three groups (squint median, then the 5–95% spread):

| plane | median | 5–95% | group |
|---|---|---|---|
| sky | 71 | 45–75 (the spread is only the tree edges) | light |
| mountain | 48 | 17–72 | all three: the one place that uses the full range |
| far forest | 20 | 9–44 | dark |
| framing trees | 16 | 5–40 | dark |
| far banks | 18 | 10–28 | dark |
| island | 28 | 16–52 | dark, with a mid rim |
| water | 29 | 14–70 | mirrors whatever is above it |
| left meadow (mid) | 42 | 22–55 | middle |
| left bank (fore) | 43 | 28–51 | middle |
| right bank (fore) | 14 | 4–22 | dark |

* **Nothing is white.** The lightest sizeable mass is the sky at L\* 71–79. The only pixels above 80
  are a few lit snow and alpenglow crest pixels on the peak, so **the peak carries the value
  extreme**. The darks go all the way to pure black (0,0,0), which is 19% of all pixels. Every one
  of them is in the trees and the near banks.
* **The ordering follows Carlson's angle theory of landscape values.** The sky is the source and the
  lightest (71). Flat planes are next, taking the most skylight: the lit meadow and the water
  reflecting the sky (42–70). Slanted planes come after them: the mountain and the mound faces.
  Uprights are darkest: the trees (16–20). The right bank breaks the rule only because it is in
  cast shadow.

### 1.3 Light (`img/05_lightmap.png`, `img/05_light_mountain.png`, `img/05_light_tree.png`, `img/07_profiles.png`)

I classed every pixel as deep shadow, shadow, cool light, warm lit or warm highlight, using value
plus warmth (b\*>12).

* **The sun is low, on the left and slightly behind the scene.** The evidence: the lit faces of
  the peak are the ones facing left, with a 1-px salmon line running along the left side of each
  crest (`05_light_mountain`). The conifers' ochre highlights sit on the upper-left of each branch
  tier. The far hummocks and the island are **rim-lit on top, with dark faces toward us** (the
  island's value profile peaks just under its crest at L\* 52 and falls to 27 at its base).
* **The sky has no sun in it.** Across the frame the sky is flat (L\* 73.5–74.7 in every column).
  Top to bottom it is an almost **iso-luminant hue sweep**: violet at the top (b\* −8.7, L\* 71.5)
  to peach at the horizon (b\* +21, L\* 79). **In this palette, colour changes and value does not.**
* **Warm light, cool shade, with a hard rule per material.** Sunlit ochre grass sits against black
  and olive shadow. Salmon and peach lit rock sits against violet shadow rock. Peach lit snow sits
  against lavender shadow snow. Shade gets its colour from the sky (violet) or from the local
  colour (olive), never from the sun.
* **Cast shadows from things outside the frame organise the ground.** The whole right foreground
  bank lies in shadow, and so do the island's left half and the far-left hummock's face. There is
  nothing in the frame to cast these shadows. They are compositional (a repoussoir), and they are
  justified by the forest off-frame.
* **Ground planes brighten as they recede.** The left bank goes from L\* ~30–45 at the bottom to 53
  at its far edge, and the right bank from 5 to 20 (`07_profiles`). Two things are behind this: the
  sheen of grass seen at a grazing angle toward the light, and deliberate darkening of the frame's
  bottom and corners (a vignette that funnels the eye inward).

### 1.4 Form (`img/07_form.png`, `img/07_form_mid.png`, `img/07_profiles.png`)

The overlay draws isophotes of the squint value inside each mass, with arrows pointing up the
brightness gradient (toward the lit side).

* **Hummocks and the island are lozenges.** A domed top, a flat bottom, ends tapered to points. The
  light sits in a band just below the crest, then value falls off down the front toward a dark
  base. A thin dark accent sits on top of the crest where the rim meets the darker things behind.
  The bottoms meet the water in a dead-level line (1.9).
* **The peak is planes, not gradients.** Each facet is one value, lit or shade, and the facets are
  separated by crisp edges or by 1–3 px checker strips. Snow is **large flat shapes** with jagged,
  hard-edged rock outcrops cut into them.
* **The banks are tilted planes.** They are not modelled at all. They are one value mass with
  texture, graded only by distance.
* **The trees are silhouettes plus flecks.** A black spire; horizontal, drooping branch spurs
  1 px thick; ochre flecks on the sun side of each tier.

### 1.5 Edges (`img/08_edges.png`)

I found mass edges on a median-filtered (de-dithered) image with Canny at σ=3.5, then measured the
20→80% rise width along each edge's normal. Red = hard (≤2 px), yellow = mid, blue = soft (>4.5 px).

* **The hard, found edges are silhouettes against the sky**: the conifers (50% of sky edges are
  hard, median contrast 69 L), the crest of the peak, and the bottom edge of the reflected mountain
  against the reflected sky.
* **The soft edges are all interior modelling.** Rock facets inside the mountain, the tree
  interiors, and the way the grass meets the grass (58–64% of bank edges are soft).
* **Lost edges** (next-to-no contrast between neighbouring planes, measured as ΔL across the
  boundary):
  * the far banks against their own reflections (ΔL 0.3), so the far shoreline is only a thin line;
  * the right bank against the water, where dark grass silhouettes break the line;
  * the mountain's right shoulder melting into the sky (ΔL 5 over the whole boundary);
  * framing trees against the far forest (ΔL 2.5).

  Ferrari lets the dark masses merge into one another and keeps the found edges for dark against
  light.

### 1.6 Cluster shapes (`img/09_cluster_atlas.png`, `img/11_checker_map.png`, magnified crops `img/c_*.png`)

Each atlas tile is a 32×32 window at 7×, with its three dominant colours isolated beside it.

| material | cluster vocabulary | measured |
|---|---|---|
| **near grass, lit** | 1-px vertical strokes 3–10 px tall. Mid-brown strokes and black-green gaps on a lit ochre base | **4 colours cover 90%**: base L60 38%, mid stroke L40 35%, olive L24 11%, gap L10 12%. Vertical neighbour same colour 70%, horizontal 34% |
| **near grass, shade** | *Negative painting*: olive strokes 1 px wide, curved and diagonal, on black | 4 colours cover 90%: black and near-black 59%, olive 40% |
| **mid meadow** | the strokes shrink to 1×2 ticks, then to irregular speckle. Speckle density *is* the value gradient | 7 colours cover 90% |
| **far banks** | near-uniform random dither of 2–3 close dark values: texture without strokes | |
| **island top** | lit band with a serrated, 1-px grass-tip top edge; value falls off through dither density | 14% checker |
| **conifer** | black mass, 1–3 px ochre flecks along drooping diagonal branch lines, sky holes | **3 colours cover 95%**: black 61%, ochre 22%, dark 14% |
| **conifer edge** | stair-stepped horizontal spurs, alternating left and right, longer lower down | |
| **mountain rock** | diagonal strokes along the fall line, 1-px crest lines, checker between violets | 15 colours for 90% |
| **snow** | flat areas; crisp jagged outcrops | |
| **sky** | **flat bands 6–10 rows tall, joined by 1–3 rows of checkerboard** | 8 colours cover 90%. 24.5% of 2×2 blocks are checkers |
| **water, sky reflection** | horizontal rows of checker; 1-px horizontal ripple lines | |
| **water, tree reflection** | broken speckle; ochre fragments | 44 colours cover 80%: the water holds every colour in the picture |
| **shore stones** | flat horizontal lozenges: light top row, mid body, dark bottom row, 45° ends | |

Two rules sit above the table. **Every material has a stroke direction**: grass is vertical,
conifer branches horizontal and drooping, rock diagonal along the slope, water horizontal. And
**the texture scale shrinks with distance** (strokes, then ticks, then speckle, then flat). The
colour count per plane is inverted from what you might expect. The nearest, most-textured planes
use **3–4 colours**. Complexity in colour lives only where the picture needs *light*: the peak
(15 colours) and the water (44).

### 1.7 Palette (`img/10_palette_groups.png`, `img/10_palette_ab.png`)

I assigned every colour to the material where it is used most:

* **The sky** (11 colours): L\* 71–76, hue sweeping violet 331° to peach 42°. It is an iso-luminant
  ramp.
* **The mountain** (17): a violet shadow ramp (L 36–44) plus salmon and peach lights (L 68–77), and
  lavender snow.
* **Conifers** (18): black, 5–6 dark violets that stand for distance, one ochre highlight (136,101,50).
* **Lit grass** (17): black-green, olive, then brown to ochre (196,131,70). The two dominant ochres
  differ by only (0,3,6).
* **Shade grass** (16): black-green through dull olive, with low chroma.
* **Water-only** (76): darkened and cooled copies of everything, mostly mauves.

In a\*b\* space the palette has **two hue families**. Sun colours are yellow-ochre and orange with
b\* +15..+45. Sky and air colours are violet-pink with b\* −15..+20. Dark olives are the only green
(a\*<0), and they are low in value. **Chroma peaks at mid values (L 40–70) and collapses in the
darks**: the most saturated colours are the lit ochre, the salmon crest and the peach glow, which
are exactly where the sun lands.

### 1.8 Depth (`img/12_depth.png`)

| plane (near → far) | squint L | darkest (p3) | chroma | b\* |
|---|---|---|---|---|
| near banks | 21 | **0** | 23 | +22 |
| framing trees | 16 | **0** | — | — |
| left meadow | 42 | 10 | 28 | +27 |
| island | 28 | 3 | 18 | +17 |
| far banks | 18 | 0 | 8 | +8 |
| far forest | 20 | 0 | 8 | 0 |
| **mountain** | 48 | **36** | 19 | **−5** (a\* +16) |
| sky | 71 | 71 | 22 | +1 |

Depth is made by, in order of strength:

1. **Overlap.** Seven layers stacked, with the V banks overlapping the water.
2. **The black point rises with distance.** Black up to the far forest, then a jump to L\* 36 for
   the peak: atmosphere is modelled as *lifted darks* more than as lowered lights.
3. **Hue.** Yellow-ochre near, grey-olive in the middle, violet-pink far.
4. **Texture scale.** Strokes, ticks, speckle, flat.
5. **Chroma** falls in the middle distance.

### 1.9 Pixel geometry: runs, steps and the bottoms of masses (`src/contours.py`, `img/c_island_bottom.png`, `img/c_hummock_base.png`, `img/c_stones.png`)

I ran this pass after a note from David (the critic): the medium favours short straight runs and
clean 45° and 2:1 steps. I measured how Ferrari's silhouettes break into runs:

| contour | 1:1 steps | 2:1 | flat run of 3–6 then one step | drop of ≥3 |
|---|---|---|---|---|
| mountain crest (left) | 41% | 3% | **53%** | 0 |
| mountain right shoulder | 43% | 29% | 5% | 14% |
| conifer line | 18% | 12% | 1% | 46% (the vertical spires) |

**The crest has no noise.** It is straight segments, each with one consistent step pattern: a run
of 1:1 steps, then a run of 4-4-4 flats, then 2:1. The magnified bottoms show a second rule:
**masses meet level ground or water in a dead-flat horizontal run**, with a 1-px darker contact
line and horizontal streaks right at the join. The island is a lozenge on a flat base. The shore
stones have flat tops and bottoms, 45° ends, and **light top row, dark bottom row: two values in a
single stroke.** Hummock flanks cross the ground in clean 2:1 diagonals.

---

## 2. What it means: the method as a painter would teach it

**Plan the picture in three values, then keep each mass inside its group.** Ferrari's picture works
in squint: light sky pouring down into light water and a lit bank, clamped by two dark masses.
Every plane stays in one value group (1.2). That is why an image of 172 colours and a million
dither pixels reads instantly. The texture is huge, but it is *confined* to a value band.

**Value is the structure. Colour is temperature and distance.** The sky is one value in eleven
colours. The lit grass is four values in four colours. When he needs to show light he spends hue
and chroma (warm) against cool, lower-chroma shade. When he needs to show distance he lifts the
black point and turns violet.

**Contrast is impressionistic and happens inside the stroke.** The strongest contrasts are not
between masses. They are inside each small mark:

* a grass blade is a light stroke with a black gap beside it;
* a conifer tier is an ochre fleck on black;
* a crest is a salmon line on violet;
* a stone is a light top row on a dark bottom row.

Across the picture, the mass values are held close. Up close, every stroke carries its own
light-dark pair. So the picture is calm at a distance and vibrant up close, like an
Impressionist's broken colour.

**The strokes are the material.** Grass is vertical strokes, water is horizontal rows, rock is
diagonal fall lines, conifers are horizontal drooping spurs. Direction alone tells you what a
thing is, before colour does. Texture shrinks with distance, so the stroke grammar itself is
perspective.

**Spend detail and colour where the light is.** The foreground is 3–4 colours of heavy texture.
The water and the peak get all the colours, because that is where light happens.

**Use the medium's own geometry.** Silhouettes are straight runs with regular steps. Ground
contacts are flat. The pixel grid is embraced as a drawing language, not hidden, so shapes look
*designed* rather than sampled.

**Find edges against the light, lose them in the dark.** Silhouettes against sky and water are
hard. Dark meets dark with no line at all. The eye is led by where edges are found.

**Organise light with shadows from outside the frame**, and **darken the corners**. The dark right
bank and the lit left bank are not physics. They are the composition's framing, and they are
plausible because of the forest.

**Reflections: exact mirror, compressed range.** The mirror axis is the far shoreline (row 228, at
scale 1.00). The reflected sky is ~4 L\* darker than the sky, the brightest lights drop by ~13 L\*,
and darks stay put (+1). Colours shift slightly cooler (a\* −5). Horizontal checker and streak
lines say *water* without ever breaking the mirror. Here too is the colour-cycling legacy. In his
256-colour scenes Ferrari reserved palette rows for cycling gradients (water, rain, fog), laid
them with stencils, and ran several gradient lengths and speeds at once so the motion never pulses
in step (Q&A with Mark J. Ferrari, EffectGames; his GDC 2016 talk *8 Bit & '8 Bitish'
Graphics — Outside the Box*). The horizontal streaks in this tarn are exactly the kind of rows he
would cycle. He dithered patterned where he wanted precision (the sky seams and the water
checkers) and diffusion or chaotic where he wanted texture (the grass and foam) (same source).

tail -3 ~/work/pixelart-studies/pedagogy/analysis/out/sheets.log; ls ~/work/pixelart-studies/pedagogy/analysis/sheets/cells | wc -l

# output:
33

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
a="""        img, kind2 = self.pixel_geometry(img, kind2, p.reshape(H, W, 3))"""
b="""        img, kind2 = self.pixel_geometry(img, kind2, p.reshape(H, W, 3))
        img = self.paint_stones(img, kind2, p.reshape(H, W, 3), t.reshape(H, W))"""
assert a in s; s=s.replace(a,b)
a="""    def paint_strokes(self, img, kind, p, t):"""
b='''    def paint_stones(self, img, kind, p, t):
        """a few stones in the shallows: flat lozenges, light top row / mid body / dark bottom row,
        45-degree ends, a dark reflection line under them (Ferrari's shore stones)"""
        rng = np.random.default_rng(self.p['seed'] + 303)
        out = img.copy()
        ys, xs = np.nonzero(kind == 3)
        if len(ys) == 0: return out
        pw = p[ys, xs]
        sd = self.land_sd(pw[:, 0], pw[:, 2])
        z = t[ys, xs]
        ok = (sd > -0.9) & (sd < -0.15) & (z < 30)
        cand = np.flatnonzero(ok)
        if len(cand) == 0: return out
        n = min(len(cand) // 60 + 1, 7)
        for j in rng.choice(cand, n, replace=False):
            y, x, zz = ys[j], xs[j], z[j]
            w = int(np.clip(F * rng.uniform(0.18, 0.45) / zz, 3, 14)); h = max(1, int(round(w / rng.uniform(3.0, 4.5))))
            for r in range(h + 1):
                inset = 1 if (r == 0 or r == h) and w > 3 else 0
                col = IDX['r2'] if r == 0 else (IDX['r0'] if r == h else IDX['r1'])
                yy = y - h + r
                for xx in range(x - w // 2 + inset, x + w // 2 + 1 - inset):
                    if 0 <= yy < H and 0 <= xx < W and kind[yy, xx] == 3:
                        out[yy, xx] = col
            yy = y + 1
            for xx in range(x - w // 2 + 1, x + w // 2):
                if 0 <= yy < H and 0 <= xx < W and kind[yy, xx] == 3 and rng.random() < 0.8:
                    out[yy, xx] = IDX['w0']
        return out

    def paint_strokes(self, img, kind, p, t):'''
assert a in s; s=s.replace(a,b)
open(f,'w').write(s)
EOF
echo ok

# output:
ok

until grep -qE "done|Error|Traceback" ~/work/pixelart-studies/pedagogy/analysis/out/sheets.log; do sleep 5; done; cat ~/work/pixelart-studies/pedagogy/analysis/out/sheets.log | tail -3

# output:
done 19 cells

cd ~/work/pixelart-studies/pedagogy/analysis && nice -n 10 python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('sheets/cells/medium_left_10m_s1.png'))
Image.fromarray(np.repeat(np.repeat(a[100:180, 180:320],6,0),6,1)).save('out/zoom_c.png')
Image.fromarray(np.repeat(np.repeat(a,3,0),3,1)).save('out/cell3x.png')
"

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && grep -n "e_left = \|e_right = \|'front': (0.35\|lit = direct > 0.06\|col = np.where(lit & (rr > 0.985)\|col = np.where(~lit & (rr > 0.993)\|spurs = 1 - \|spurs2 = 1 -\|return -0.35 \* np.abs\|def forest_profile" src/paint/ferrari_method.py; sed -n '/    def forest_profile/,/        return top, trees/p' src/paint/ferrari_method.py

# output:
85:    'front': (0.35, 0.13, -0.93),
230:        e_left = H * 0.66 + (uu / (0.30 * W)) * (H * 0.40)           # low bank on the boulder side
231:        e_right = H + 4 - ((uu - 0.56 * W) / (0.44 * W)) * (H * 0.58)  # rising dark bank opposite
337:    def forest_profile(self):
372:        spurs = 1 - np.abs(n.fbm2((u + 0.6 * v) / 13.0 + ms, (v - 0.3 * u) / 9.0, 3))
373:        spurs2 = 1 - np.abs(n.fbm2((u - 0.7 * v) / 6.0 + ms, v / 5.0 + 4, 2))
374:        return -0.35 * np.abs(u - pu) + 7 * spurs + 2.5 * spurs2
626:        lit = direct > 0.06
651:            col = np.where(lit & (rr > 0.985), IDX['r2'], col)
652:            col = np.where(~lit & (rr > 0.993) & (L_sh > 24), IDX['r2'], col)
    def forest_profile(self):
        rng = np.random.default_rng(self.p['seed'] * 7 + 3)
        u = np.arange(W)
        top = np.full(W, 2.5 + rng.random() * 1.5)          # a low dark hedge
        top = top + 1.2 * self.noise.fbm2(u / 9.0, np.full(W, 3.3), 2)
        trees = []
        x = -4.0
        while x < W + 4:
            x += rng.uniform(2.0, 7.5)
            hgt = rng.uniform(6, 16) * (1.4 if rng.random() < 0.18 else 1.0)
            trees.append((x, hgt, rng.uniform(0.26, 0.34)))
        return top, trees

cd ~/work/pixelart-studies/pedagogy/analysis && sed -n 600,660p src/paint/ferrari_method.py

# output:
base = np.floor(q).astype(int)
        best = np.full(len(pb), np.inf); cid = np.zeros(len(pb), np.int64)
        for dx in (-1, 0, 1):
            for dy in (-1, 0, 1):
                for dz in (-1, 0, 1):
                    cc = base + np.array([dx, dy, dz])
                    h = (cc[:, 0] * 73856093 ^ cc[:, 1] * 19349663 ^ cc[:, 2] * 83492791) & 0xFFFFFF
                    jit = np.stack([(h % 97) / 97, ((h // 97) % 89) / 89, ((h // 8633) % 83) / 83], 1)
                    dd = np.linalg.norm(q - (cc + jit), axis=1)
                    better = dd < best
                    best = np.where(better, dd, best); cid = np.where(better, h, cid)
        uniq, inv = np.unique(cid, return_inverse=True)
        mean_n = np.zeros((len(uniq), 3)); np.add.at(mean_n, inv, n_s)
        mean_n /= np.linalg.norm(mean_n, axis=1, keepdims=True) + 1e-9
        n_f = 0.55 * mean_n[inv] + 0.45 * n_s
        n_f /= np.linalg.norm(n_f, axis=1, keepdims=True)
        ndl = (n_f * self.l).sum(-1)
        vis = self.boulder_shadow(pb + n_s * 0.03)
        direct = np.clip(ndl, 0, 1) * vis
        sky_amb = 0.5 + 0.5 * n_s[:, 1]            # ambient judged on the smooth form: no blotches
        bounce = np.clip(-n_s[:, 1], 0, 1) + 0.35 * np.clip(-(n_s * self.l)[..., 0] * 0, 0, 1)
        hg = pb[:, 1] - self.land_h(pb[:, 0], pb[:, 2]).clip(0, None)
        occl = smoothstep(0.0, 0.35 * self.r, hg)
        L_lit = 40 + 40 * direct ** 1.3
        core = np.exp(-((ndl + 0.05) / 0.2) ** 2)
        L_sh = (13 + 21 * sky_amb ** 1.5 + 8 * bounce - 10 * core) * (0.45 + 0.55 * occl)
        lit = direct > 0.06
        yy, xx = np.divmod(np.flatnonzero(m), W)
        # stroke direction on rock follows the facet's slope in screen space
        Td = np.where(n_f[:, 0] * n_f[:, 1] > 0, T['diag_l'][yy, xx], T['diag_r'][yy, xx])
        Tc = T['checker'][yy, xx]
        Tm = np.where(self.r * F / self.bz > 25, 0.5 * Td + 0.5 * Tc, Tc)
        li = ramp_pick('rock_lit', L_lit, Tm, 0.55)
        si = ramp_pick('rock_shade', L_sh, Tm, 0.55)
        col = np.where(lit, li, si)
        # facet crest lines: where the facet id changes and this side is the lit one -> r4 line; creases -> r0
        cid_img = np.full(H * W, -1, np.int64); cid_img[m] = cid
        ndl_img = np.full(H * W, -9.0); ndl_img[m] = ndl
        cimg = cid_img.reshape(H, W); nimg = ndl_img.reshape(H, W)
        edge = np.zeros((H, W), bool); brighter = np.zeros((H, W), bool)
        for sy, sx in ((0, 1), (1, 0), (0, -1), (-1, 0)):
            c2 = np.roll(np.roll(cimg, sy, 0), sx, 1); n2 = np.roll(np.roll(nimg, sy, 0), sx, 1)
            e = (c2 != cimg) & (c2 >= 0) & (cimg >= 0)
            edge |= e; brighter |= e & (nimg > n2 + 0.12)
        ed = edge.ravel()[m]; br = brighter.ravel()[m]
        big = self.r * F / self.bz > 14                       # detail only when the boulder is big enough
        rr = self.rng.random(len(col))
        if big:
            col = np.where(br & lit & (rr < 0.75), IDX['r4'], col

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
a=s.index("        ndl = (n_f * self.l).sum(-1)\n        vis = self.boulder_shadow(pb + n_s * 0.03)")
b=s.index("        yy, xx = np.divmod(np.flatnonzero(m), W)\n        # stroke direction on rock")
s=s[:a]+'''        # the terminator follows the smooth form (one clean shadow shape); facets only nudge values
        ndl = 0.6 * (n_s * self.l).sum(-1) + 0.4 * (n_f * self.l).sum(-1)
        vis = self.boulder_shadow(pb + n_s * 0.03)
        tt = np.where(vis > 0.5, ndl, np.minimum(ndl, -0.2))
        view = -d[m]
        facing_v = np.abs((n_s * view).sum(-1))                 # 1 facing us, 0 at the silhouette
        sky_amb = 0.5 + 0.5 * n_s[:, 1]
        hg = pb[:, 1] - self.land_h(pb[:, 0], pb[:, 2]).clip(0, None)
        occl = smoothstep(0.0, 0.35 * self.r, hg)
        # value zones as a painter plans them: highlight / light / half-tone | core / shadow / reflected
        L_lit = (44 + 34 * smoothstep(0.05, 0.85, tt)) * (0.82 + 0.18 * facing_v)
        core = np.exp(-((tt + 0.02) / 0.12) ** 2)
        L_sh = (26 + 12 * (sky_amb - 0.5) * 2 - 13 * core) * (0.5 + 0.5 * occl)
        lit = tt > 0.05
        direct = np.clip(tt, 0, 1)
'''+s[b:]
rep=[("        Tm = np.where(self.r * F / self.bz > 25, 0.5 * Td + 0.5 * Tc, Tc)\n        li = ramp_pick('rock_lit', L_lit, Tm, 0.55)\n        si = ramp_pick('rock_shade', L_sh, Tm, 0.55)",
      "        Tm = np.where(self.r * F / self.bz > 25, 0.35 * Td + 0.65 * Tc, Tc)\n        li = ramp_pick('rock_lit', L_lit, Tm, 0.45)\n        si = ramp_pick('rock_shade', L_sh, Tm, 0.45)"),
("""            col = np.where(br & lit & (rr < 0.75), IDX['r4'], col)
            col = np.where(ed & ~br & ~lit & (rr < 0.45), IDX['r0'], col)
            # granite speckle: dark specks in light, light specks in shade
            col = np.where(lit & (rr > 0.985), IDX['r2'], col)
            col = np.where(~lit & (rr > 0.993) & (L_sh > 24), IDX['r2'], col)""",
"""            # a facet edge: light line on the sun-facing side, dark crease line opposite
            col = np.where(br & lit & (tt > 0.25) & (rr < 0.7), IDX['r4'], col)
            col = np.where(ed & ~br & lit & (tt < 0.5) & (rr < 0.35), IDX['r2'], col)
            col = np.where(ed & ~br & ~lit & (rr < 0.4), IDX['r0'], col)"""),
("    'front': (0.35, 0.13, -0.93),","    'front': (-0.38, 0.13, -0.92),"),
("        e_left = H * 0.66 + (uu / (0.30 * W)) * (H * 0.40)           # low bank on the boulder side\n        e_right = H + 4 - ((uu - 0.56 * W) / (0.44 * W)) * (H * 0.58)  # rising dark bank opposite",
 "        k = {'close': 0.55, '10m': 0.85, '40m': 1.0}[self.p['distance']]   # more foreground when far\n        e_left = H * (1 - 0.40 * k) + (uu / ((0.12 + 0.30 * k) * W)) * (H * 0.40 * k)   # bank on the boulder side\n        e_right = H + 4 - ((uu - (1 - 0.50 * k) * W) / (0.50 * k * W)) * (H * 0.66 * k)  # rising bank opposite"),
("        spurs = 1 - np.abs(n.fbm2((u + 0.6 * v) / 13.0 + ms, (v - 0.3 * u) / 9.0, 3))\n        spurs2 = 1 - np.abs(n.fbm2((u - 0.7 * v) / 6.0 + ms, v / 5.0 + 4, 2))\n        return -0.35 * np.abs(u - pu) + 7 * spurs + 2.5 * spurs2",
 "        spurs = 1 - np.abs(n.fbm2((u + 0.6 * v) / 22.0 + ms, (v - 0.3 * u) / 15.0, 2))\n        spurs2 = 1 - np.abs(n.fbm2((u - 0.7 * v) / 10.0 + ms, v / 8.0 + 4, 2))\n        return -0.35 * np.abs(u - pu) + 9 * spurs + 2.5 * spurs2"),
]
for a_,b_ in rep:
    assert a_ in s, a_[:70]; s=s.replace(a_,b_)
# forest variety: groves and gaps
a=s.index("        trees = []\n        x = -4.0"); b=s.index("        return top, trees")
s=s[:a]+'''        trees = []
        x = -4.0
        grove = rng.uniform(0.6, 1.4)
        while x < W + 4:
            if rng.random() < 0.10:                      # a gap in the forest
                x += rng.uniform(8, 22); grove = rng.uniform(0.6, 1.5)
            x += rng.uniform(1.5, 6.0)
            hgt = rng.uniform(5, 15) * grove * (1.6 if rng.random() < 0.12 else 1.0)
            trees.append((x, hgt, rng.uniform(0.24, 0.34)))
'''+s[b:]
open(f,'w').write(s)
EOF
nice -n 10 python3 src/paint/debug_gb.py medium front close 1 && cp out/debug_gb.png out/dbg_front_close.png && nice -n 10 python3 src/paint/debug_gb.py medium left 40m 1

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
a="""        pw = p[ys, xs]
        sd = self.land_sd(pw[:, 0], pw[:, 2])
        z = t[ys, xs]
        ok = (sd > -0.9) & (sd < -0.15) & (z < 30)"""
b="""        from scipy.ndimage import distance_transform_edt
        dist = distance_transform_edt(kind != 1)             # screen distance to the nearest bank pixel
        z = t[ys, xs]
        dd = dist[ys, xs]
        ok = (dd > 2) & (dd < 3 + 60 / np.maximum(z, 1)) & (z < 30)"""
assert a in s; s=s.replace(a,b)
open(f,'w').write(s)
EOF
FORCE=1 OMP_NUM_THREADS=1 nice -n 10 python3 src/paint/sheets.py > out/sheets.log 2>&1; tail -1 out/sheets.log

# output:
done 19 cells

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[("        tt = np.where(vis > 0.5, ndl, np.minimum(ndl, -0.2))","        tt = ndl                                       # (no self-shadowing: the form's terminator is enough)"),
("        vis = self.boulder_shadow(pb + n_s * 0.03)\n        tt","        tt"),
("            edge |= e; brighter |= e & (nimg > n2 + 0.12)","            edge |= e & (np.abs(nimg - n2) > 0.10); brighter |= e & (nimg > n2 + 0.15)"),
("            col = np.where(ed & ~br & ~lit & (rr < 0.4), IDX['r0'], col)","            col = np.where(ed & ~br & ~lit & (rr < 0.25), IDX['r0'], col)"),
("        n = min(len(cand) // 60 + 1, 7)","        n = min(len(cand) // 150 + 1, 4)"),
]
for a,b in rep:
    assert a in s, a[:60]; s=s.replace(a,b)
open(f,'w').write(s)
EOF
grep -n "vis = self.boulder_shadow(pb" src/paint/ferrari_method.py; FORCE=1 OMP_NUM_THREADS=1 nice -n 10 python3 src/paint/sheets.py > out/sheets.log 2>&1; tail -1 out/sheets.log

# output:
done 19 cells

cd ~/work/pixelart-studies/pedagogy/analysis && nice -n 10 python3 src/check_sheets.py medium_left_10m_s1 medium_back_close_s1 2>&1 | tail -20

# output:
Traceback (most recent call last):
  File "~/work/pixelart-studies/pedagogy/analysis/src/check_sheets.py", line 74, in <module>
    Image.fromarray(np.concatenate([th, np.full((h, 10, 3), 255, np.uint8), mi], 0 if kind == 'notan' else 1)).save(f'img/chk_{key}_{kind}_vs.png')
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ValueError: all the input array dimensions except for the concatenation axis must match exactly, but along dimension 1, the array at index 0 has size 1469 and the array at index 1 has size 10

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/check_sheets.py'
s=open(f).read()
a=s.index("            h = min(mine.shape[0], theirs.shape[0])"); b=s.index("    json.dump")
s=s[:a]+'''            if kind == 'notan':
                w = min(mine.shape[1], theirs.shape[1])
                th = np.array(Image.fromarray(theirs).resize((w, int(theirs.shape[0] * w / theirs.shape[1])), Image.NEAREST))
                mi = np.array(Image.fromarray(mine).resize((w, int(mine.shape[0] * w / mine.shape[1])), Image.NEAREST))
                out = np.concatenate([th, np.full((10, w, 3), 255, np.uint8), mi], 0)
            else:
                h = min(mine.shape[0], theirs.shape[0])
                th = np.array(Image.fromarray(theirs).resize((int(theirs.shape[1] * h / theirs.shape[0]), h), Image.NEAREST))
                mi = np.array(Image.fromarray(mine).resize((int(mine.shape[1] * h / mine.shape[0]), h), Image.NEAREST))
                out = np.concatenate([th, np.full((h, 10, 3), 255, np.uint8), mi], 1)
            Image.fromarray(out).save(f'img/chk_{key}_{kind}_vs.png')
'''+s[b:]
open(f,'w').write(s)
EOF
nice -n 10 python3 src/check_sheets.py medium_left_10m_s1 medium_back_close_s1 2>&1 | tail -20

# output:
==================== medium_left_10m_s1
sky                  vs sky               | L_med=72.73/71.40 L_p5=72.51/71.08 L_p95=75.06/75.38 colours_90=2.00/8.00 vsame=0.82/0.47 hsame=0.81/0.47 cluster_mean=8.40/2.99 single=0.98/0.97 checker=0.11/0.25 b=2.59/1.26
mountain             vs mountain          | L_med=56.82/48.44 L_p5=36.77/36.21 L_p95=75.06/77.33 colours_90=5.00/15.00 vsame=0.48/0.42 hsame=0.53/0.45 cluster_mean=4.29/3.28 single=0.58/0.72 checker=0.06/0.10 b=-7.29/-4.75
far forest           vs far forest        | L_med=21.46/19.81 L_p5=12.19/0.00 L_p95=30.96/45.32 colours_90=2.00/10.00 vsame=0.60/0.46 hsame=0.71/0.45 cluster_mean=12.06/3.83 single=0.39/0.65 checker=0.01/0.06 b=-7.36/0.00
water                vs water             | L_med=62.75/28.96 L_p5=11.07/0.00 L_p95=70.62/72.02 colours_90=10.00/69.00 vsame=0.28/0.33 hsame=0.32/0.33 cluster_mean=1.63/2.34 single=0.94/0.75 checker=0.50/0.08 b=-14.56/1.77
bank (boulder side)  vs left meadow (mid) | L_med=40.05/41.92 L_p5=11.07/10.52 L_p95=61.24/61.05 colours_90=6.00/7.00 vsame=0.39/0.56 hsame=0.26/0.44 cluster_mean=2.30/4.46 single=0.60/0.61 checker=0.04/0.06 b=34.34/27.43
boulder              vs mountain          | L_med=33.79/48.44 L_p5=11.07/36.21 L_p95=63.32/77.33 colours_90=5.00/15.00 vsame=0.75/0.42 hsame=0.71/0.45 cluster_mean=10.55/3.28 single=0.61/0.72 checker=0.03/0.10 b=-6.58/-4.75
near bank lit        vs left bank (fore)  | L_med=33.68/43.42 L_p5=11.07/10.78 L_p95=61.24/60.26 colours_90=6.00/4.00 vsame=0.47/0.70 hsame=0.27/0.34 cluster_mean=2.71/6.15 single=0.59/0.39 checker=0.04/0.05 b=22.61/35.29
near bank shade      vs right bank (fore) | L_med=18.85/14.17 L_p5=1.06/0.00 L_p95=35.26/26.39 colours_90=5.00/4.00 vsame=0.44/0.68 hsame=0.23/0.36 cluster_mean=2.48/5.57 single=0.52/0.41 checker=0.03/0.04 b=13.03/14.34
==================== medium_back_close_s1
sky                  vs sky               | L_med=75.32/71.40 L_p5=75.06/71.08 L_p95=80.79/75.38 colours_90=2.00/8.00 vsame=0.87/0.47 hsame=0.86/0.47 cluster_mean=14.57/2.99 single=0.96/0.97 checker=0.06/0.25 b=14.12/1.26
mountain             vs mountain          | L_med=46.53/48.44 L_p5=36.77/36.21 L_p95=66.13/77.33 colours_90=3.00/15.00 vsame=0.58/0.42 hsame=0.63/0.45 cluster_mean=6.20/3.28 single=0.64/0.72 checker=0.06/0.10 b=-13.32/-4.75
far forest           vs far forest        | L_med=22.82/19.81 L_p5=12.19/0.00 L_p95=30.96/45.32 colours_90=2.00/10.00 vsame=0.56/0.46 hsame=0.45/0.45 cluster_mean=4.55/3.83 single=0.46/0.65 checker=0.08/0.06 b=-7.36/0.00
water                vs water             | L_med=33.66/28.96 L_p5=12.19/0.00 L_p95=70.62/72.02 colours_90=11.00/69.00 vsame=0.38/0.33 hsame=0.49/0.33 cluster_mean=2.50/2.34 single=0.86/0.75 checker=0.27/0.08 b=-11.49/1.77
bank (boulder side)  vs left meadow (mid) | L_med=38.76/41.92 L_p5=11.07/10.52 L_p95=75.07/61.05 colours_90=7.00/7.00 vsame=0.54/0.56 hsame=0.39/0.44 cluster_mean=3.26/4.46 single=0.61/0.61 checker=0.05/0.06 b=21.59/27.43
boulder              vs mounta

cd ~/work/pixelart-studies/pedagogy/analysis && grep -n "T\['vert'\] = \|L_lit = (43\|Tr = np.where(LAB\[c1\]\|fcol = np.where(bd\['f_lit'\]\|def boulder_sd\|kind\[idx\[hitb\]\] = 2\|sb = self.boulder_sd(p)\|hitb = sb <" src/paint/ferrari_method.py

# output:
146:    T['vert'] = rank_uniform(noise.fbm2(xx / 0.8, yy / 3.5, 2, 1.1) + 0.35 * rng.random((H, W)))
249:    def boulder_sd(self, p):
296:            sb = self.boulder_sd(p)
299:            hitb = sb < 0.004 * max(1.0, t[idx].mean() * 0.02)
304:            kind[idx[hitb]] = 2
538:        fcol = np.where(bd['f_lit'], IDX['for1'], IDX['for0'])
575:        L_lit = (43 + 9 * np.sqrt(np.clip(ndl, 0, 1)) + 7 * back + 7 * far) * (0.55 + 0.45 * occl)
723:        Tr = np.where(LAB[c1][:, 0] > 55, Tc, Th)              # light water: checker, dark: horizontal

cd ~/work/pixelart-studies/pedagogy/analysis && sed -n 285,335p src/paint/ferrari_method.py

# output:
def march(self, o, d, tmax=260.0):
        """march rays; returns t, kind (0 none, 1 land, 2 boulder, 3 water)"""
        N = d.shape[0]
        t = np.full(N, 0.05); kind = np.zeros(N, int); alive = np.ones(N, bool)
        # water plane
        tw = np.where(d[:, 1] < -1e-6, -o[:, 1] / np.minimum(d[:, 1], -1e-6), np.inf)
        prev_t = t.copy()
        for it in range(420):
            idx = np.flatnonzero(alive)
            if idx.size == 0: break
            p = o[idx] + d[idx] * t[idx, None]
            sb = self.boulder_sd(p)
            hb = self.land_h(p[:, 0], p[:, 2])
            below = p[:, 1] < hb
            hitb = sb < 0.004 * max(1.0, t[idx].mean() * 0.02)
            # land hit (bisection refine later coarse is fine at these scales)
            hl = below & (hb > -0.001)
            hw = t[idx] >= tw[idx]
            done = hitb | hl | hw | (t[idx] > tmax)
            kind[idx[hitb]] = 2
            kl = idx[hl & ~hitb]; kind[kl] = 1
            kw = idx[hw & ~hitb & ~hl]; kind[kw] = 3; t[kw] = tw[kw]
            # refine land hits by bisection between prev_t and t
            if kl.size:
                a, b = prev_t[kl], t[kl]
                for _ in range(8):
                    m = (a + b) / 2; pm = o[kl] + d[kl] * m[:, None]
                    inside = pm[:, 1] < self.land_h(pm[:, 0], pm[:, 2])
                    b = np.where(inside, m, b); a = np.where(inside, a, m)
                t[kl] = b
            alive[idx[done]] = False
            rem = idx[~done]
            if rem.size == 0: break
            step = np.minimum(np.abs(sb[~done]) * 0.9 + 0.002, 0.02 + t[rem] * 0.012)
            prev_t[rem] = t[rem]
            t[rem] = t[rem] + np.maximum(step, 0.004)
        kind[(kind == 0) & np.isfinite(tw)] = 3
        t = np.where((kind == 3), np.minimum(t, tw), t)
        return t, kind

    def boulder_shadow(self, p):
        """soft visibility of the sun from points p (boulder occludes; low sun -> long shadows)"""
        vis = np.ones(p.shape[0]); t = np.full(p.shape[0], 0.03)
        for _ in range(80):
            q = p + self.l[None] * t[:, None]
            s = self.boulder_sd(q)
            vis = np.minimum(vis, np.clip(10 * s / t, 0, 1))
            t = t + np.clip(s, 0.02, 0.5 * self.r)
            if (t > 12 * self.r).all(): break
        return vis

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
# tree setup in __init__
a="""        self.shore_seed = self.rng.uniform(0, 100)"""
b="""        self.shore_seed = self.rng.uniform(0, 100)
        # a grove of conifers on the boulder's bank, behind it: tall dark verticals the frame crops and
        # the water shows whole (Ferrari's framing trees; they put the darks into the water)
        grng = np.random.default_rng(seed + 29)
        r = self.r; d = self.bz
        A = 2.6 * r + 0.15 * d + 2.0; B = 1.7 * r + 0.10 * d + 1.6
        self.trees = []
        for k in range(grng.integers(3, 6)):
            tz = self.bz + 0.8 * B + grng.uniform(0.2, 1.4) * B + 2.0
            tx = self.bx - grng.uniform(0.45, 1.7) * A - 1.0
            h = grng.uniform(11, 19)
            self.trees.append((tx, tz, h, h * grng.uniform(0.17, 0.22)))
        self.tree_top = max(t_[2] for t_ in self.trees) + 2"""
assert a in s; s=s.replace(a,b)
# tree SDF
a="""    def boulder_normal(self, p):"""
b='''    def tree_sd(self, p, with_id=False):
        """conifers: tiered cones (drooping branch tiers, spiky spurs) on short trunks"""
        best = np.full(p.shape[:-1], 1e9); tid = np.full(p.shape[:-1], -1)
        for i, (tx, tz, h, rb) in enumerate(self.trees):
            y0 = self.land_h(np.array([tx]), np.array([tz]))[0].clip(0, None) - 0.2
            dx = p[..., 0] - tx; dz = p[..., 2] - tz
            rr = np.sqrt(dx * dx + dz * dz)
            yy = p[..., 1] - y0
            fr = np.clip(yy / h, 0, 1)
            tier_len = 1.1 + 0.05 * h
            tier = ((h - yy) / tier_len) % 1.0                    # 0 at a tier's top, 1 at its drooping skirt
            ang = np.arctan2(dz, dx)
            spur = 0.75 + 0.45 * np.abs(np.sin(ang * 3.5 + yy * 1.7 + i))
            R = rb * (1 - fr) * (0.55 + 0.6 * tier) * spur * (yy > 1.2)
            dcone = (rr - R) * 0.45
            dcone = np.where(yy > h, np.hypot(rr, yy - h), dcone)
            dcone = np.where(yy < 0, np.maximum(dcone, -yy), dcone)
            trunk = np.maximum(rr - 0.18, np.maximum(-yy, yy - 2.0))
            dd = np.minimum(dcone, trunk)
            better = dd < best
            best = np.where(better, dd, best); tid = np.where(better, i, tid)
        return (best, tid) if with_id else best

    def boulder_normal(self, p):'''
assert a in s; s=s.replace(a,b)
# march integration
rep=[("""            sb = self.boulder_sd(p)
            hb = self.land_h(p[:, 0], p[:, 2])""","""            sb = self.boulder_sd(p)
            st = self.tree_sd(p)
            hb = self.land_h(p[:, 0], p[:, 2])"""),
("""            hw = t[idx] >= tw[idx]
            done = hitb | hl | hw | (t[idx] > tmax)
            kind[idx[hitb]] = 2""","""            hw = t[idx] >= tw[idx]
            hitt = (st < 0.01 * max(1.0, t[idx].mean() * 0.03)) & ~hitb
            gone = (d[idx, 1] > 0) & (p[:, 1] > self.tree_top)
            done = hitb | hitt | hl | hw | (t[idx] > tmax) | gone
            kind[idx[hitb]] = 2
            kind[idx[hitt & ~hl]] = 4"""),
("""            step = np.minimum(np.abs(sb[~done]) * 0.9 + 0.002, 0.02 + t[rem] * 0.012)""","""            step = np.minimum(np.minimum(np.abs(sb[~done]), np.abs(st[~done])) * 0.9 + 0.002, 0.02 + t[rem] * 0.012)"""),
("""        for it in range(420):""","""        for it in range(700):"""),
("""            kl = idx[hl & ~hitb]; kind[kl] = 1""","""            kl = idx[hl & ~hitb & ~hitt]; kind[kl] = 1"""),
("""            kw = idx[hw & ~hitb & ~hl]; kind[kw] = 3; t[kw] = tw[kw]""","""            kw = idx[hw & ~hitb & ~hl & ~hitt]; kind[kw] = 3; t[kw] = tw[kw]"""),
]
for a_,b_ in rep:
    assert a_ in s, a_[:60]; s=s.replace(a_,b_)
open(f,'w').write(s)
EOF
echo ok

# output:
ok

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
a="""        self.paint_boulder(img, Lt, kind, p, d, T)
"""
b="""        self.paint_boulder(img, Lt, kind, p, d, T)
        self.paint_trees(img, kind, p, d, T)
"""
assert a in s; s=s.replace(a,b)
a="""    def paint_boulder(self, img, Lt, kind, p, d, T):"""
b='''    def tree_look(self, pt, T_rand, yscr, u):
        """palette index for conifer points: black mass, ochre flecks on the sun side of each
        drooping tier (the reference: black 61%, ochre 22%, dark 14% -- 3 colours)"""
        _, tid = self.tree_sd(pt, with_id=True)
        tr = np.array(self.trees)[np.clip(tid, 0, None)]
        tx, tz, h, rb = tr[:, 0], tr[:, 1], tr[:, 2], tr[:, 3]
        dx = pt[:, 0] - tx; dz = pt[:, 2] - tz
        rr = np.sqrt(dx ** 2 + dz ** 2) + 1e-6
        nrm = np.stack([dx / rr, np.full_like(rr, 0.45), dz / rr], 1); nrm /= np.linalg.norm(nrm, axis=1, keepdims=True)
        ls = (nrm * self.l).sum(1)
        zc = np.maximum(pt[:, 2], 0.5)
        u_t = W / 2 + F * tx / zc
        tier_px = np.maximum(2.0, F * (1.1 + 0.05 * h) / zc)
        stripe = ((yscr - 0.55 * np.abs(u - u_t)) / tier_px) % 1.0
        col = np.where(T_rand < 0.16, IDX['for0'], IDX['k'])
        fleck = (ls > 0.05) & (stripe < 0.42) & (T_rand > 0.25)
        if self.light == 'back':
            fleck = (ls > 0.55) & (stripe < 0.3) & (T_rand > 0.5)
        col = np.where(fleck, IDX['g2'], col)
        col = np.where(fleck & (ls > 0.55) & (T_rand > 0.8), IDX['g3'], col)
        return col

    def paint_trees(self, img, kind, p, d, T):
        m = kind == 4
        self.tree_mask = m.reshape(H, W)
        if not m.any(): return
        yy, xx = np.divmod(np.flatnonzero(m), W)
        col = self.tree_look(p[m], T['speckle'][yy, xx], yy.astype(float), xx.astype(float))
        img[m] = col
        if self.light == 'back':                 # rim light on the silhouette against the glowing sky
            tm = self.tree_mask
            edge = tm & ~(np.roll(tm, 1, 0) & np.roll(tm, 1, 1) & np.roll(tm, -1, 1) & np.roll(tm, -1, 0))
            e = edge.ravel()[m]
            img[m] = np.where(e & (T['speckle'][yy, xx] > 0.35), IDX['g4'], img[m])

    def paint_boulder(self, img, Lt, kind, p, d, T):'''
assert a in s; s=s.replace(a,b)
# reflections of trees
a="""        # reflected boulder & land: re-shade with the same light, flat reading
        for kk in (1, 2):"""
b="""        st_ = k2 == 4
        if st_.any():
            src[st_] = self.tree_look(p2[st_], self.rng.random(st_.sum()), yy[m][st_].astype(float), xx[m][st_].astype(float))
        # reflected boulder & land: re-shade with the same light, flat reading
        for kk in (1, 2):"""
assert a in s; s=s.replace(a,b)
# planes label
a="""        pl_[kind == 3] = 3; pl_[kind == 1] = 4; pl_[kind == 2] = 5"""
b="""        pl_[kind == 3] = 3; pl_[kind == 1] = 4; pl_[kind == 2] = 5; pl_[kind == 4] = 8"""
assert a in s; s=s.replace(a,b)
open(f,'w').write(s)
EOF
sed -i '' "s/MY = \['sky', 'mountain', 'far forest', 'water', 'bank (boulder side)', 'boulder', 'near bank lit', 'near bank shade'\]/MY = ['sky', 'mountain', 'far forest', 'water', 'bank (boulder side)', 'boulder', 'near bank lit', 'near bank shade', 'grove']/; s/'boulder': \[1\], 'near bank lit': \[8\], 'near bank shade': \[9\]}/'boulder': [1], 'near bank lit': [8], 'near bank shade': [9], 'grove': [3]}/" src/check_sheets.py
time nice -n 10 python3 src/paint/debug_gb.py medium left 10m 1

# output:
nice -n 10 python3 src/paint/debug_gb.py medium left 10m 1  35.65s user 10.66s system 105% cpu 43.991 total
[This command modified 2 files you've previously read: ../pedagogy/analysis/src/check_sheets.py, ../pedagogy/analysis/src/paint/ferrari_method.py. Call Read before editing.]

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
a=s.index("        self.trees = []\n        for k in range(grng.integers(3, 6)):"); b=s.index("        self.tree_top =")
s=s[:a]+'''        self.trees = []
        n_t = int(grng.integers(3, 6))
        xs_ = self.bx - A * (0.5 + np.sort(grng.uniform(0, 1.3, n_t))) - 1.0
        for tx in xs_:
            h = grng.uniform(10, 19)
            tz = self.bz + 1.4 * B + grng.uniform(0.0, 1.5) * B + 2.0
            if any(abs(tx - t_[0]) < 0.35 * h * 0.28 and abs(tz - t_[1]) < 4 for t_ in self.trees):
                tx -= 0.3 * h * 0.28
            self.trees.append((tx, tz, h, h * grng.uniform(0.11, 0.15)))
'''+s[b:]
s=s.replace("            R = rb * (1 - fr) * (0.55 + 0.6 * tier) * spur * (yy > 1.2)","            R = rb * (1 - fr) * (0.35 + 0.9 * tier ** 1.5) * spur * (yy > 1.2)")
open(f,'w').write(s)
EOF
nice -n 10 python3 src/paint/debug_gb.py medium left 10m 1

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[("            spur = 0.75 + 0.45 * np.abs(np.sin(ang * 3.5 + yy * 1.7 + i))",
"            tj = np.floor((h - yy) / tier_len)\n            spur = 0.55 + 0.55 * np.abs(self.noise.value3(np.cos(ang) * 1.8 + tj * 3.1, np.sin(ang) * 1.8, i * 7.3 + tj)) + 0.15 * np.sin(ang * 9 + tj * 2)"),
("""        stripe = ((yscr - 0.55 * np.abs(u - u_t)) / tier_px) % 1.0
        col = np.where(T_rand < 0.16, IDX['for0'], IDX['k'])
        fleck = (ls > 0.05) & (stripe < 0.42) & (T_rand > 0.25)""",
"""        yy = pt[:, 1] - self.land_h(tx, tz).clip(0, None)
        tier = ((h - yy) / (1.1 + 0.05 * h)) % 1.0
        stripe = ((yscr - 0.55 * np.abs(u - u_t)) / tier_px) % 1.0
        col = np.where(T_rand < 0.16, IDX['for0'], IDX['k'])
        fleck = (ls > 0.12) & ((tier > 0.5) | (stripe < 0.3)) & (T_rand > 0.35 + 0.4 * (1 - ls))"""),
]
for a_,b_ in rep:
    assert a_ in s, a_[:60]; s=s.replace(a_,b_)
open(f,'w').write(s)
EOF
nice -n 10 python3 src/paint/debug_gb.py medium left 10m 1

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && nice -n 10 python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('out/debug_gb.png'))[:, 640:][::2,::2]
Image.fromarray(np.repeat(np.repeat(a,3,0),3,1)).save('out/cell3x.png')
"

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[("'r3': (178, 146, 142), 'r4': (228, 188, 166)","'r3': (190, 148, 130), 'r4': (236, 192, 160)"),
("        snow = in_m & (v > 17 + 7 * n.fbm2(u / 9.0 + 9, v / 5.0, 3)) & (nrm_m[..., 1] > 0.18 + 0.2 * n.fbm2(u / 4.0, v / 3.0 + 2, 2))",
 "        snow = in_m & (v > 17 + 8 * n.fbm2(u / 18.0 + 9, v / 9.0, 2)) & (nrm_m[..., 1] > 0.2 + 0.2 * n.fbm2(u / 11.0, v / 7.0 + 2, 2))"),
("        spurs2 = 1 - np.abs(n.fbm2((u - 0.7 * v) / 10.0 + ms, v / 8.0 + 4, 2))\n        return -0.35 * np.abs(u - pu) + 9 * spurs + 2.5 * spurs2",
 "        spurs2 = 1 - np.abs(n.fbm2((u - 0.7 * v) / 10.0 + ms, v / 8.0 + 4, 2))\n        return -0.35 * np.abs(u - pu) + 9 * spurs + 1.2 * spurs2"),
("            k0 = int(np.clip(abs(lean) * 2.2, 0, 3))\n            k1 = min(3, k0 + (1 if (L > 5 and rng.random() < 0.6) else 0))",
 "            k0 = int(np.clip(abs(lean) * 1.6, 0, 2))\n            k1 = min(3, k0 + (1 if (L > 5 and rng.random() < 0.6) else 0))"),
]
for a_,b_ in rep:
    assert a_ in s, a_[:60]; s=s.replace(a_,b_)
open(f,'w').write(s)
EOF
echo ok

# output:
ok

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[("    T['vert'] = rank_uniform(noise.fbm2(xx / 0.8, yy / 3.5, 2, 1.1) + 0.35 * rng.random((H, W)))",
      "    T['vert'] = rank_uniform(noise.fbm2(xx / 0.7, yy / 6.0, 2, 1.1) + 0.18 * rng.random((H, W)))"),
("        L_lit = (43 + 9 * np.sqrt(np.clip(ndl, 0, 1)) + 7 * back + 7 * far) * (0.55 + 0.45 * occl)",
 "        L_lit = (48 + 8 * np.sqrt(np.clip(ndl, 0, 1)) + 6 * back + 6 * far) * (0.55 + 0.45 * occl)"),
("        fcol = np.where(bd['f_lit'], IDX['for1'], IDX['for0'])",
 "        fcol = np.where(bd['f_lit'], np.where(T['speckle'][yy, xx] > 0.45, IDX['g2'], IDX['for1']),\n                        np.where(T['speckle'][yy, xx] > 0.6, IDX['k'], IDX['for0']))"),
("        Tr = np.where(LAB[c1][:, 0] > 55, Tc, Th)              # light water: checker, dark: horizontal",
 "        Tr = np.where((LAB[c1][:, 0] > 55) & (np.abs(frac - 0.5) < 0.12), Tc, Th)   # horizontal ripples; checker only mid-blend"),
]
for a_,b_ in rep:
    assert a_ in s, a_[:60]; s=s.replace(a_,b_)
open(f,'w').write(s)
EOF
FORCE=1 OMP_NUM_THREADS=1 nice -n 10 python3 src/paint/sheets.py > out/sheets.log 2>&1; tail -1 out/sheets.log

# output:
done 19 cells

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[("        ndl = 0.6 * (n_s * self.l).sum(-1) + 0.4 * (n_f * self.l).sum(-1)",
      "        ndl_s = (n_s * self.l).sum(-1)\n        ndl = 0.75 * ndl_s + 0.25 * (n_f * self.l).sum(-1)"),
("        lit = tt > 0.05\n","        lit = ndl_s > 0.04                           # one clean terminator from the smooth form\n"),
("        core = np.exp(-((tt + 0.02) / 0.12) ** 2)","        core = np.exp(-((ndl_s + 0.02) / 0.12) ** 2)"),
("            tz = self.bz + 1.4 * B + grng.uniform(0.0, 1.5) * B + 2.0","            tz = self.bz + 1.4 * B + grng.uniform(0.0, 1.5) * B + 9.0"),
("            tier_len = 1.1 + 0.05 * h","            tier_len = 0.8 + 0.07 * np.clip(yy, 0, None)"),
("        tier = ((h - yy) / (1.1 + 0.05 * h)) % 1.0","        tier = ((h - yy) / (0.8 + 0.07 * np.clip(yy, 0, None))) % 1.0"),
("        tier_px = np.maximum(2.0, F * (1.1 + 0.05 * h) / zc)","        tier_px = np.maximum(2.0, F * (0.8 + 0.07 * np.clip(pt[:, 1], 0, None)) / zc)"),
]
for a_,b_ in rep:
    assert a_ in s, a_[:60]; s=s.replace(a_,b_)
open(f,'w').write(s)
EOF
nice -n 10 python3 src/paint/debug_gb.py medium right close 1 && nice -n 10 python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('~/work/pixelart-studies/pedagogy/analysis/out/debug_gb.png'))[:, 640:][::2,::2]
Image.fromarray(np.repeat(np.repeat(a,3,0),3,1)).save('~/work/pixelart-studies/pedagogy/analysis/out/cell3x.png')"

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && grep -n "n_s = self.boulder_normal(pb)" src/paint/ferrari_method.py && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
a="        n_s = self.boulder_normal(pb)\n"
b="""        n_s = self.boulder_normal(pb)
        # the big form: the undisplaced ellipsoid's normal carries the light/shade plan; the weathered
        # surface only adds facets and strokes (a painter simplifies the form before modelling it)
        ax = np.array([self.rx, self.ry, self.rz])
        q_ = (pb - np.array([self.bx, self.by, self.bz])) / ax ** 2
        n_e = q_ / np.linalg.norm(q_, axis=1, keepdims=True)
        n_s = 0.7 * n_e + 0.3 * n_s
        n_s /= np.linalg.norm(n_s, axis=1, keepdims=True)
"""
assert a in s; s=s.replace(a,b,1)
open(f,'w').write(s)
EOF
nice -n 10 python3 src/paint/debug_gb.py medium right close 1 && nice -n 10 python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('~/work/pixelart-studies/pedagogy/analysis/out/debug_gb.png'))[:, 640:][::2,::2]
Image.fromarray(np.repeat(np.repeat(a,3,0),3,1)).save('~/work/pixelart-studies/pedagogy/analysis/out/cell3x.png')"

# output:
681:        n_s = self.boulder_normal(pb)

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[("        disp = 0.055 * n.fbm3(p[..., 0] * s, p[..., 1] * s, p[..., 2] * s, 3) \\",
      "        disp = 0.13 * n.fbm3(p[..., 0] * s * 0.55, p[..., 1] * s * 0.55, p[..., 2] * s * 0.55, 2) \\\n            + 0.04 * n.fbm3(p[..., 0] * s, p[..., 1] * s, p[..., 2] * s, 3) \\"),
("        n_s = 0.7 * n_e + 0.3 * n_s\n","        n_s = 0.45 * n_e + 0.55 * n_s\n"),
("_BASE = [(1, 0), (3, 1), (2, 1), (1, 1), (1, 2), (1, 3), (0, 1)]","_BASE = [(1, 0), (5, 1), (4, 1), (3, 1), (2, 1), (1, 1), (1, 2), (1, 3), (1, 4), (0, 1)]"),
]
for a_,b_ in rep:
    if a_ in s: s=s.replace(a_,b_)
    else:
        g='src/paint/pixelgeo.py'; t=open(g).read(); assert a_ in t, a_[:50]; open(g,'w').write(t.replace(a_,b_))
open(f,'w').write(s)
EOF
nice -n 10 python3 src/paint/debug_gb.py medium right close 1 && nice -n 10 python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('~/work/pixelart-studies/pedagogy/analysis/out/debug_gb.png'))[:, 640:][::2,::2]
Image.fromarray(np.repeat(np.repeat(a,3,0),3,1)).save('~/work/pixelart-studies/pedagogy/analysis/out/cell3x.png')"

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && sed -i '' 's/            nb = pg.clean_mask(bm, 1.0, prefer_flat=0.12)/            nb = pg.clean_mask(bm, 0.9, prefer_flat=0.04)/' src/paint/ferrari_method.py && FORCE=1 OMP_NUM_THREADS=1 nice -n 10 python3 src/paint/sheets.py > out/sheets.log 2>&1; tail -1 out/sheets.log; nice -n 10 python3 src/check_sheets.py medium_left_10m_s1 medium_left_close_s1 medium_back_10m_s1 medium_left_40m_s1 2>&1 | tail -40

# output:
done 19 cells
==================== medium_left_10m_s1
sky                  vs sky               | L_med=71.04/71.40 L_p5=72.51/71.08 L_p95=75.06/75.38 colours_90=2.00/8.00 vsame=0.76/0.47 hsame=0.80/0.47 cluster_mean=7.63/2.99 single=0.93/0.97 checker=0.10/0.25 b=2.59/1.26
mountain             vs mountain          | L_med=57.26/48.44 L_p5=36.77/36.21 L_p95=75.06/77.33 colours_90=5.00/15.00 vsame=0.52/0.42 hsame=0.57/0.45 cluster_mean=4.84/3.28 single=0.56/0.72 checker=0.06/0.10 b=-7.29/-4.75
far forest           vs far forest        | L_med=19.35/19.81 L_p5=1.06/0.00 L_p95=39.84/45.32 colours_90=3.00/10.00 vsame=0.31/0.46 hsame=0.35/0.45 cluster_mean=2.43/3.83 single=0.58/0.65 checker=0.04/0.06 b=0.76/0.00
water                vs water             | L_med=60.77/28.96 L_p5=1.06/0.00 L_p95=70.62/72.02 colours_90=12.00/69.00 vsame=0.35/0.33 hsame=0.47/0.33 cluster_mean=2.39/2.34 single=0.86/0.75 checker=0.30/0.08 b=-13.32/1.77
bank (boulder side)  vs left meadow (mid) | L_med=42.27/41.92 L_p5=11.07/10.52 L_p95=75.07/61.05 colours_90=7.00/7.00 vsame=0.43/0.56 hsame=0.25/0.44 cluster_mean=2.42/4.46 single=0.56/0.61 checker=0.03/0.06 b=34.34/27.43
boulder              vs mountain          | L_med=31.23/48.44 L_p5=11.07/36.21 L_p95=64.75/77.33 colours_90=5.00/15.00 vsame=0.83/0.42 hsame=0.76/0.45 cluster_mean=12.95/3.28 single=0.60/0.72 checker=0.02/0.10 b=-7.36/-4.75
near bank lit        vs left bank (fore)  | L_med=34.79/43.42 L_p5=11.07/10.78 L_p95=61.24/60.26 colours_90=6.00/4.00 vsame=0.51/0.70 hsame=0.27/0.34 cluster_mean=2.95/6.15 single=0.53/0.39 checker=0.04/0.05 b=22.61/35.29
near bank shade      vs right bank (fore) | L_med=18.31/14.17 L_p5=1.06/0.00 L_p95=35.26/26.39 colours_90=5.00/4.00 vsame=0.53/0.68 hsame=0.23/0.36 cluster_mean=2.92/5.57 single=0.43/0.41 checker=0.02/0.04 b=13.03/14.34
grove                vs framing trees     | L_med=10.80/15.57 L_p5=1.06/0.00 L_p95=39.84/45.32 colours_90=3.00/3.00 vsame=0.54/0.56 hsame=0.62/0.52 cluster_mean=5.44/5.17 single=0.63/0.64 checker=0.03/0.07 b=0.76/0.00
==================== medium_left_close_s1
sky                  vs sky               | L_med=66.99/71.40 L_p5=72.51/71.08 L_p95=75.06/75.38 colours_90=2.00/8.00 vsame=0.69/0.47 hsame=0.74/0.47 cluster_mean=5.82/2.99 single=0.90/0.97 checker=0.12/0.25 b=2.59/1.26
mountain             vs mountain          | L_med=57.67/48.44 L_p5=36.77/36.21 L_p95=75.06/77.33 colours_90=5.00/15.00 vsame=0.53/0.42 hsame=0.57/0.45 cluster_mean=4.90/3.28 single=0.57/0.72 checker=0.06/0.10 b=-7.29/-4.75
far forest           vs far forest        | L_med=18.92/19.81 L_p5=1.06/0.00 L_p95=39.84/45.32 colours_90=3.00/10.00 vsame=0.30/0.46 hsame=0.36/0.45 cluster_mean=2.46/3.83 single=0.59/0.65 checker=0.05/0.06 b=0.76/0.00
water                vs water             | L_med=45.99/28.96 L_p5=12.19/0.00 L_p95=70.62/72.02 colours_90=12.00/69.00 vsame=0.42/0.33 hsame=0.57/0.33 cluster_mean=3.41/2.34 single=0.79/0.75 checker=0.17/0.08 b=-7.72/1.77
bank (boulder side)  vs left m

cd ~/work/pixelart-studies/pedagogy/analysis && sed -n '/        near = smoothstep(30, 12, z)/,/        img\[m\] = np.where(use_lit, lit_i, sh_i)/p' src/paint/ferrari_method.py

# output:
near = smoothstep(30, 12, z)
        Tv = T['vert'][yy, xx]; Ts = T['speckle'][yy, xx]
        Ttex = np.where(near > 0.5, Tv, Ts)
        # texture spread: near grass spans base / mid stroke / dark gap (Ferrari: 60/40/24/10),
        # the spread shrinks with distance until grass is a two-colour speckle
        amp = 5 + 17 * near
        Lli = L_lit + amp * (Ttex * 2 - 1) * np.where(Ttex < 0.12, 1.6, 1.0)
        Lsh = L_sh + (0.6 * amp) * (Ttex * 2 - 1)
        Tq = T['checker'][yy, xx]
        lit_i = ramp_pick('grass_lit', Lli, Tq, 0.3)
        sh_i = ramp_pick('grass_shade', Lsh, Tq, 0.3)
        use_lit = lit_amt > T['vert'][yy, xx] * 0.8 + 0.1       # terminator made of strokes too
        img[m] = np.where(use_lit, lit_i, sh_i)

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
a=s.index("        # texture spread: near grass spans base / mid stroke / dark gap"); b=s.index("        use_lit = lit_amt > T['vert'][yy, xx] * 0.8 + 0.1")
s=s[:a]+'''        # NEAR grass: Ferrari's measured recipe, a base colour broken by strokes in fixed proportions
        # (lit: base L60 38% / mid stroke L40 35% / olive L24 11% / gap L10 12%;
        #  shade: black 28% / black-green 31% / olive 40%). The stroke threshold map is vertical, so the
        # proportions come out as vertical 1-px strokes; the plane's value shifts the thresholds.
        sh_l = np.clip((L_lit - 50) / 40, -0.3, 0.3)
        c_lit = np.select([Tv < 0.12 - sh_l * 0.3, Tv < 0.23 - sh_l * 0.4, Tv < 0.58 - sh_l],
                          [IDX['g0'], IDX['g1'], IDX['g2']], np.where(L_lit > 57, IDX['g4'], IDX['g3']))
        sh_s = np.clip((L_sh - 12) / 30, -0.3, 0.3)
        c_sh = np.select([Tv < 0.28 - sh_s, Tv < 0.60 - sh_s], [IDX['k'], IDX['g0']],
                         np.where(Tv > 0.9 - sh_s * 0.5, IDX['h2'], IDX['g1']))
        # FAR grass: the spread shrinks to a two-colour speckle around the plane's value
        amp = 6
        Tq = T['checker'][yy, xx]
        far_lit = ramp_pick('grass_lit', L_lit + amp * (Ts * 2 - 1), Tq, 0.3)
        far_sh = ramp_pick('grass_shade', L_sh + amp * (Ts * 2 - 1), Tq, 0.3)
        nearm = near > T['speckle'][yy, xx] * 0.6 + 0.2
        lit_i = np.where(nearm, c_lit, far_lit)
        sh_i = np.where(nearm, c_sh, far_sh)
'''+s[b:]
rep=[("        lit_amt = smoothstep(-0.32, -0.12, ndl) * smoothstep(0.35, 0.8, vis)","        lit_amt = smoothstep(-0.5, -0.3, ndl) * smoothstep(0.35, 0.8, vis)"),
("    T['horiz'] = rank_uniform(noise.fbm2(xx / 7.0, yy / 0.7, 2, 2.3) + 0.25 * rng.random((H, W)))","    T['horiz'] = rank_uniform(noise.fbm2(xx / 8.0, yy / 1.1, 2, 2.3) + 0.10 * rng.random((H, W)))"),
("        for k in range(grng.integers(3, 6)):","        for k in range(grng.integers(5, 9)):"),
("        n_t = int(grng.integers(3, 6))\n        xs_ = self.bx - A * (0.5 + np.sort(grng.uniform(0, 1.3, n_t))) - 1.0",
 "        n_t = int(grng.integers(5, 9))\n        xs_ = self.bx - A * (0.4 + np.sort(grng.uniform(0, 2.0, n_t))) - 1.0"),
]
for a_,b_ in rep:
    if a_ in s: s=s.replace(a_,b_)
    else: print('skip', a_[:50])
open(f,'w').write(s)
EOF
grep -n "fcol = np.where(bd\['f_lit'\]" -A1 src/paint/ferrari_method.py; grep -n "li = ramp_pick('rock_lit', L_lit, Tm, 0.45)" src/paint/ferrari_method.py

# output:
skip         for k in range(grng.integers(3, 6)):
583:        fcol = np.where(bd['f_lit'], np.where(T['speckle'][yy, xx] > 0.45, IDX['g2'], IDX['for1']),
584-                        np.where(T['speckle'][yy, xx] > 0.6, IDX['k'], IDX['for0']))
740:        li = ramp_pick('rock_lit', L_lit, Tm, 0.45)
[This command modified 1 file you've previously read: ../pedagogy/analysis/src/paint/ferrari_method.py. Call Read before editing.]

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[("""        fcol = np.where(bd['f_lit'], np.where(T['speckle'][yy, xx] > 0.45, IDX['g2'], IDX['for1']),
                        np.where(T['speckle'][yy, xx] > 0.6, IDX['k'], IDX['for0']))""",
"""        Tf = T['horiz'][yy, xx]                       # forest texture in horizontal tier strokes
        fcol = np.where(bd['f_lit'], np.where(Tf > 0.45, IDX['g2'], IDX['for1']),
                        np.where(Tf > 0.62, IDX['k'], IDX['for0']))"""),
("        li = ramp_pick('rock_lit', L_lit, Tm, 0.45)\n        si = ramp_pick('rock_shade', L_sh, Tm, 0.45)",
 "        # rock texture: a value spread laid in diagonal fall-line strokes (Ferrari's mountain rock)\n        spread = 7.0 * (Td * 2 - 1) * (self.r * F / self.bz > 25)\n        li = ramp_pick('rock_lit', L_lit + spread, Tm, 0.45)\n        si = ramp_pick('rock_shade', L_sh + 0.8 * spread, Tm, 0.45)"),
]
for a_,b_ in rep:
    assert a_ in s, a_[:50]; s=s.replace(a_,b_)
open(f,'w').write(s)
EOF
FORCE=1 OMP_NUM_THREADS=1 nice -n 10 python3 src/paint/sheets.py > out/sheets.log 2>&1; tail -1 out/sheets.log; nice -n 10 python3 src/check_sheets.py medium_left_10m_s1 medium_left_close_s1 medium_back_10m_s1 medium_left_40m_s1 2>&1 | grep -E "=====|near bank|boulder  |water|far forest|grove"

# output:
done 19 cells
==================== medium_left_10m_s1
far forest           vs far forest        | L_med=19.48/19.81 L_p5=1.06/0.00 L_p95=39.84/45.32 colours_90=4.00/10.00 vsame=0.30/0.46 hsame=0.62/0.45 cluster_mean=4.34/3.83 single=0.43/0.65 checker=0.01/0.06 b=0.76/0.00
water                vs water             | L_med=60.74/28.96 L_p5=1.06/0.00 L_p95=70.62/72.02 colours_90=12.00/69.00 vsame=0.36/0.33 hsame=0.48/0.33 cluster_mean=2.46/2.34 single=0.86/0.75 checker=0.30/0.08 b=-13.32/1.77
boulder              vs mountain          | L_med=31.54/48.44 L_p5=11.07/36.21 L_p95=64.75/77.33 colours_90=5.00/15.00 vsame=0.76/0.42 hsame=0.69/0.45 cluster_mean=8.58/3.28 single=0.62/0.72 checker=0.04/0.10 b=-6.58/-4.75
near bank lit        vs left bank (fore)  | L_med=34.26/43.42 L_p5=11.07/10.78 L_p95=61.24/60.26 colours_90=6.00/4.00 vsame=0.53/0.70 hsame=0.30/0.34 cluster_mean=3.30/6.15 single=0.52/0.39 checker=0.03/0.05 b=22.61/35.29
near bank shade      vs right bank (fore) | L_med=19.16/14.17 L_p5=1.06/0.00 L_p95=35.26/26.39 colours_90=5.00/4.00 vsame=0.51/0.68 hsame=0.22/0.36 cluster_mean=2.74/5.57 single=0.44/0.41 checker=0.02/0.04 b=13.03/14.34
grove                vs framing trees     | L_med=8.21/15.57 L_p5=1.06/0.00 L_p95=39.84/45.32 colours_90=2.00/3.00 vsame=0.58/0.56 hsame=0.64/0.52 cluster_mean=5.71/5.17 single=0.68/0.64 checker=0.03/0.07 b=0.76/0.00
==================== medium_left_close_s1
far forest           vs far forest        | L_med=19.30/19.81 L_p5=1.06/0.00 L_p95=39.84/45.32 colours_90=3.00/10.00 vsame=0.30/0.46 hsame=0.62/0.45 cluster_mean=4.42/3.83 single=0.42/0.65 checker=0.01/0.06 b=-7.36/0.00
water                vs water             | L_med=45.55/28.96 L_p5=12.19/0.00 L_p95=70.62/72.02 colours_90=13.00/69.00 vsame=0.43/0.33 hsame=0.58/0.33 cluster_mean=3.54/2.34 single=0.78/0.75 checker=0.17/0.08 b=-7.72/1.77
boulder              vs mountain          | L_med=30.62/48.44 L_p5=11.07/36.21 L_p95=64.75/77.33 colours_90=5.00/15.00 vsame=0.79/0.42 hsame=0.77/0.45 cluster_mean=11.08/3.28 single=0.71/0.72 checker=0.04/0.10 b=-8.18/-4.75
near bank lit        vs left bank (fore)  | L_med=32.80/43.42 L_p5=11.07/10.78 L_p95=61.24/60.26 colours_90=6.00/4.00 vsame=0.58/0.70 hsame=0.36/0.34 cluster_mean=4.00/6.15 single=0.53/0.39 checker=0.04/0.05 b=22.61/35.29
near bank shade      vs right bank (fore) | L_med=18.65/14.17 L_p5=1.06/0.00 L_p95=35.26/26.39 colours_90=5.00/4.00 vsame=0.59/0.68 hsame=0.27/0.36 cluster_mean=3.17/5.57 single=0.41/0.41 checker=0.02/0.04 b=13.03/14.34
grove                vs framing trees     | L_med=9.34/15.57 L_p5=1.06/0.00 L_p95=39.84/45.32 colours_90=2.00/3.00 vsame=0.59/0.56 hsame=0.65/0.52 cluster_mean=5.99/5.17 single=0.68/0.64 checker=0.03/0.07 b=0.76/0.00
==================== medium_back_10m_s1
far forest           vs far forest        | L_med=22.92/19.81 L_p5=1.06/0.00 L_p95=39.84/45.32 colours_90=4.00/10.00 vsame=0.29/0.46 hsame=0.39/0.45 cluster_mean=2.42/3.83 single=0.53/0.65 checker=0.03/0.06 b=0.76/0.

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[("        dens = np.clip(0.10 + 0.5 * np.maximum(near_b, near_w), 0, 0.8) * (Lpx >= 1.5)",
      "        # turf blades cover ~25% of the ground whatever their projected length; sedge is denser\n        dens = np.clip(0.25 / np.maximum(Lpx, 1) + 0.5 * np.maximum(near_b, near_w), 0, 0.8) * (Lpx >= 1.5)"),
("                    c = IDX['g0'] if (over_other or not blit or rng.random() < 0.6) else IDX['g2']",
 "                    c = IDX['g0'] if (over_other or not blit or rng.random() < 0.35) else IDX['g2']"),
("                        c = IDX['h1'] if tipf < 0.35 else (IDX['g1'] if tipf < 0.7 else IDX['h2'])",
 "                        c = IDX['g0'] if tipf < 0.3 else (IDX['h1'] if tipf < 0.6 else IDX['g1'])"),
]
for a_,b_ in rep:
    assert a_ in s, a_[:50]; s=s.replace(a_,b_)
open(f,'w').write(s)
EOF
cd src/paint && python3 -c "
import sys; sys.argv=['x','medium_left_10m_s1']
import sheets, os
os.environ['FORCE']='1'
sheets.render(dict(size='medium',light='left',distance='10m',seed=1))
" && cd ../.. && nice -n 10 python3 src/check_sheets.py medium_left_10m_s1 2>&1 | grep -E "near bank"

# output:
near bank lit        vs left bank (fore)  | L_med=38.40/43.42 L_p5=11.07/10.78 L_p95=61.24/60.26 colours_90=5.00/4.00 vsame=0.53/0.70 hsame=0.27/0.34 cluster_mean=3.25/6.15 single=0.47/0.39 checker=0.03/0.05 b=34.34/35.29
near bank shade      vs right bank (fore) | L_med=15.42/14.17 L_p5=1.06/0.00 L_p95=24.03/26.39 colours_90=4.00/4.00 vsame=0.61/0.68 hsame=0.33/0.36 cluster_mean=4.38/5.57 single=0.39/0.41 checker=0.03/0.04 b=13.03/14.34

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[("    T['vert'] = rank_uniform(noise.fbm2(xx / 0.7, yy / 6.0, 2, 1.1) + 0.18 * rng.random((H, W)))",
      "    T['vert'] = rank_uniform(noise.fbm2(xx / 0.6, yy / 9.0, 2, 1.1) + 0.05 * rng.random((H, W)))"),
("[IDX['g0'], IDX['g1'], IDX['g2']], np.where(L_lit > 57, IDX['g4'], IDX['g3']))","[IDX['g0'], IDX['g1'], IDX['g2']], np.where(L_lit > 50, IDX['g4'], IDX['g3']))"),
]
for a_,b_ in rep:
    assert a_ in s, a_[:50]; s=s.replace(a_,b_)
open(f,'w').write(s)
EOF
cd src/paint && FORCE=1 python3 -c "
import sheets
sheets.render(dict(size='medium',light='left',distance='10m',seed=1))
" && cd ../.. && nice -n 10 python3 src/check_sheets.py medium_left_10m_s1 2>&1 | grep -E "near bank"

# output:
near bank lit        vs left bank (fore)  | L_med=39.28/43.42 L_p5=11.07/10.78 L_p95=61.24/60.26 colours_90=5.00/4.00 vsame=0.60/0.70 hsame=0.27/0.34 cluster_mean=3.81/6.15 single=0.43/0.39 checker=0.03/0.05 b=34.34/35.29
near bank shade      vs right bank (fore) | L_med=15.78/14.17 L_p5=1.06/0.00 L_p95=24.03/26.39 colours_90=4.00/4.00 vsame=0.68/0.68 hsame=0.34/0.36 cluster_mean=5.76/5.57 single=0.35/0.41 checker=0.02/0.04 b=13.03/14.34

cd ~/work/pixelart-studies/pedagogy/analysis && nice -n 10 python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('sheets/cells/medium_left_10m_s1.png'))
Image.fromarray(np.repeat(np.repeat(a,3,0),3,1)).save('out/cell3x.png')
ref=np.array(Image.open('img/00_native.png'))
z=np.concatenate([np.repeat(np.repeat(a[110:180,0:110],6,0),6,1), np.repeat(np.repeat(ref[330:400,0:110],6,0),6,1)],1)
Image.fromarray(z).save('out/cmp_grass.png')
"

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && FORCE=1 OMP_NUM_THREADS=1 nice -n 10 python3 src/paint/sheets.py > out/sheets.log 2>&1; tail -1 out/sheets.log

# output:
done 19 cells

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[("        sd = np.maximum(e1, e2)\n","        sd = np.maximum(e1, e2) - 1.5 * np.maximum(0, x - (pfx + 0.6 * r))   # no spit beyond the boulder\n"),
("        flat = np.maximum(0, q[..., 1] - 0.65) * 0.25","        flat = np.maximum(0, q[..., 1] - 0.8) * 0.12"),
]
for a_,b_ in rep:
    assert a_ in s, a_[:50]; s=s.replace(a_,b_)
open(f,'w').write(s)
EOF
FORCE=1 OMP_NUM_THREADS=1 nice -n 10 python3 src/paint/sheets.py > out/sheets.log 2>&1; tail -1 out/sheets.log

# output:
done 19 cells

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[("        lit = ndl_s > 0.04                           # one clean terminator from the smooth form\n",
      "        n_t = 0.7 * n_e + 0.3 * n_s; n_t /= np.linalg.norm(n_t, axis=1, keepdims=True)\n        lit = (n_t * self.l).sum(-1) > 0.04          # one clean terminator from the big form\n"),
("        n = min(len(cand) // 150 + 1, 4)","        n = int(rng.integers(1, 3))"),
]
for a_,b_ in rep:
    assert a_ in s, a_[:50]; s=s.replace(a_,b_)
open(f,'w').write(s)
EOF
FORCE=1 OMP_NUM_THREADS=1 nice -n 10 python3 src/paint/sheets.py > out/sheets.log 2>&1; tail -1 out/sheets.log

# output:
done 19 cells

cd ~/work/pixelart-studies/pedagogy/analysis && ls sheets/cells/*.png | sed 's|sheets/cells/||; s|\.png||' | tr '\n' ' ' > out/cellkeys.txt; nice -n 10 python3 src/check_sheets.py $(cat out/cellkeys.txt) > out/check_all.txt 2>&1; tail -3 out/check_all.txt; nice -n 10 python3 - <<'EOF'
import json, numpy as np
d=json.load(open('out/check_stats.json'))
F=d.pop('ferrari')
CORR={'sky':'sky','mountain':'mountain','far forest':'far forest','water':'water','bank (boulder side)':'left meadow (mid)','boulder':'mountain','near bank lit':'left bank (fore)','near bank shade':'right bank (fore)','grove':'framing trees'}
keys=['L_med','L_p5','L_p95','colours_90','vsame','hsame','cluster_mean','single','checker','b']
print(f"{'plane':20s} {'Ferrari plane':18s} "+' '.join(f'{k:>13s}' for k in keys))
rows=[]
for n,fn in CORR.items():
    vals=[c[n] for c in d.values() if n in c]
    if not vals: continue
    m={k:np.median([v[k] for v in vals]) for k in keys}
    lo={k:np.percentile([v[k] for v in vals],10) for k in keys}; hi={k:np.percentile([v[k] for v in vals],90) for k in keys}
    print(f"{n:20s} {fn:18s} "+' '.join(f"{m[k]:6.2f}/{F[fn][k]:6.2f}" for k in keys), f"(n={len(vals)})")
    rows.append((n,fn,m,lo,hi,len(vals)))
json.dump([(n,fn,m,lo,hi,c) for n,fn,m,lo,hi,c in rows],open('out/check_summary.json','w'),indent=1)
EOF

# output:
near bank lit        vs left bank (fore)  | L_med=39.14/43.42 L_p5=11.07/10.78 L_p95=61.24/60.26 colours_90=4.00/4.00 vsame=0.58/0.70 hsame=0.26/0.34 cluster_mean=3.50/6.15 single=0.45/0.39 checker=0.03/0.05 b=34.34/35.29
near bank shade      vs right bank (fore) | L_med=15.51/14.17 L_p5=1.06/0.00 L_p95=24.03/26.39 colours_90=4.00/4.00 vsame=0.67/0.68 hsame=0.31/0.36 cluster_mean=5.37/5.57 single=0.33/0.41 checker=0.02/0.04 b=13.03/14.34
grove                vs framing trees     | L_med=7.77/15.57 L_p5=1.06/0.00 L_p95=39.84/45.32 colours_90=2.00/3.00 vsame=0.62/0.56 hsame=0.67/0.52 cluster_mean=6.61/5.17 single=0.69/0.64 checker=0.03/0.07 b=0.76/0.00
plane                Ferrari plane              L_med          L_p5         L_p95    colours_90         vsame         hsame  cluster_mean        single       checker             b
sky                  sky                 71.09/ 71.40  72.51/ 71.08  75.06/ 75.38   2.00/  8.00   0.76/  0.47   0.78/  0.47   7.81/  2.99   0.92/  0.97   0.09/  0.25   2.59/  1.26 (n=19)
mountain             mountain            57.08/ 48.44  36.77/ 36.21  75.06/ 77.33   5.00/ 15.00   0.55/  0.42   0.58/  0.45   5.13/  3.28   0.57/  0.72   0.06/  0.10  -7.29/ -4.75 (n=19)
far forest           far forest          19.96/ 19.81   1.06/  0.00  39.84/ 45.32   4.00/ 10.00   0.30/  0.46   0.62/  0.45   4.41/  3.83   0.42/  0.65   0.01/  0.06   0.76/  0.00 (n=19)
water                water               60.85/ 28.96  11.07/  0.00  70.62/ 72.02  12.00/ 69.00   0.37/  0.33   0.50/  0.33   2.51/  2.34   0.86/  0.75   0.29/  0.08 -11.49/  1.77 (n=19)
bank (boulder side)  left meadow (mid)   40.45/ 41.92  11.07/ 10.52  61.24/ 61.05   5.00/  7.00   0.51/  0.56   0.31/  0.44   3.17/  4.46   0.55/  0.61   0.04/  0.06  34.34/ 27.43 (n=19)
boulder              mountain            32.17/ 48.44  14.45/ 36.21  64.75/ 77.33   4.00/ 15.00   0.77/  0.42   0.74/  0.45  10.86/  3.28   0.68/  0.72   0.04/  0.10  -8.18/ -4.75 (n=19)
near bank lit        left bank (fore)    38.97/ 43.42  11.07/ 10.78  61.24/ 60.26   4.00/  4.00   0.58/  0.70   0.27/  0.34   3.51/  6.15   0.46/  0.39   0.03/  0.05  34.34/ 35.29 (n=19)
near bank shade      right bank (fore)   15.56/ 14.17   1.06/  0.00  24.03/ 26.39   4.00/  4.00   0.67/  0.68   0.32/  0.36   5.30/  5.57   0.34/  0.41   0.02/  0.04  13.03/ 14.34 (n=19)
grove                framing trees       11.03/ 15.57   1.06/  0.00  39.84/ 45.32   2.00/  3.00   0.54/  0.56   0.63/  0.52   5.13/  5.17   0.67/  0.64   0.03/  0.07   0.76/  0.00 (n=19)

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
# right-side far bank with a second grove
a="""        self.tree_top = max(t_[2] for t_ in self.trees) + 2"""
b="""        # a second wooded bank on the far right: dark masses on both sides, light in the middle
        # (the reference's hourglass notan: sky pouring into the water between two dark masses)
        s_ = 1.0 if self.bx < 0 else -1.0
        self.rz = max(28.0, 1.4 * d + 16.0)
        self.rxc = s_ * 0.36 * self.rz
        self.rA, self.rB = 0.30 * self.rz, 0.22 * self.rz
        for k in range(int(grng.integers(4, 8))):
            tx = self.rxc + s_ * grng.uniform(-0.45, 0.9) * self.rA
            tz = self.rz + grng.uniform(-0.2, 0.7) * self.rB
            h = grng.uniform(13, 24)
            self.trees.append((tx, tz, h, h * grng.uniform(0.11, 0.15)))
        self.tree_top = max(t_[2] for t_ in self.trees) + 2"""
assert a in s; s=s.replace(a,b)
a="""        return np.maximum(sd + wob, self.near_sd(x, z))"""
b="""        e3 = (1 - np.sqrt(((x - self.rxc) / self.rA) ** 2 + ((z - self.rz) / self.rB) ** 2)) * min(self.rA, self.rB) * 0.5
        e3 = e3 + 0.4 * n.fbm2(x * 0.2 + 70, z * 0.2, 3)
        return np.maximum(np.maximum(sd + wob, self.near_sd(x, z)), e3)"""
assert a in s; s=s.replace(a,b)
open(f,'w').write(s)
EOF
grep -n "self.rz\b\|self.rz =" src/paint/ferrari_method.py | head; grep -n "self.rx, self.ry, self.rz" src/paint/ferrari_method.py

# output:
194:        self.rx, self.ry, self.rz = self.r * 1.05, self.r * 0.80, self.r * 0.95
215:        self.rz = max(28.0, 1.4 * d + 16.0)
216:        self.rxc = s_ * 0.36 * self.rz
217:        self.rA, self.rB = 0.30 * self.rz, 0.22 * self.rz
220:            tz = self.rz + grng.uniform(-0.2, 0.7) * self.rB
238:        e3 = (1 - np.sqrt(((x - self.rxc) / self.rA) ** 2 + ((z - self.rz) / self.rB) ** 2)) * min(self.rA, self.rB) * 0.5
279:        q = (p - c) / np.array([self.rx, self.ry, self.rz])
709:        ax = np.array([self.rx, self.ry, self.rz])
194:        self.rx, self.ry, self.rz = self.r * 1.05, self.r * 0.80, self.r * 0.95
279:        q = (p - c) / np.array([self.rx, self.ry, self.rz])
709:        ax = np.array([self.rx, self.ry, self.rz])

cd ~/work/pixelart-studies/pedagogy/analysis && sed -i '' '215,240s/self\.rz\b/self.rbz/g' src/paint/ferrari_method.py && sed -i '' 's/self.rbz = max(28.0/self.rbz = max(28.0/' src/paint/ferrari_method.py && sed -n '213,222p;236,240p' src/paint/ferrari_method.py && nice -n 10 python3 src/paint/debug_gb.py medium left 10m 1 && nice -n 10 python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('~/work/pixelart-studies/pedagogy/analysis/out/debug_gb.png'))[:, 640:][::2,::2]
Image.fromarray(np.repeat(np.repeat(a,3,0),3,1)).save('~/work/pixelart-studies/pedagogy/analysis/out/cell3x.png')"

# output:
# (the reference's hourglass notan: sky pouring into the water between two dark masses)
        s_ = 1.0 if self.bx < 0 else -1.0
        self.rz = max(28.0, 1.4 * d + 16.0)
        self.rxc = s_ * 0.36 * self.rz
        self.rA, self.rB = 0.30 * self.rz, 0.22 * self.rz
        for k in range(int(grng.integers(4, 8))):
            tx = self.rxc + s_ * grng.uniform(-0.45, 0.9) * self.rA
            tz = self.rz + grng.uniform(-0.2, 0.7) * self.rB
            h = grng.uniform(13, 24)
            self.trees.append((tx, tz, h, h * grng.uniform(0.11, 0.15)))
        sd = np.maximum(e1, e2) - 1.5 * np.maximum(0, x - (pfx + 0.6 * r))   # no spit beyond the boulder
        wob = 0.22 * (1 + 0.03 * d) * n.fbm2(x * 0.45 + self.shore_seed, z * 0.45, 3)
        e3 = (1 - np.sqrt(((x - self.rxc) / self.rA) ** 2 + ((z - self.rz) / self.rB) ** 2)) * min(self.rA, self.rB) * 0.5
        e3 = e3 + 0.4 * n.fbm2(x * 0.2 + 70, z * 0.2, 3)
        return np.maximum(np.maximum(sd + wob, self.near_sd(x, z)), e3)

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
for a,b in [("self.rz = max(28.0","self.rbz = max(28.0"),("0.36 * self.rz\n","0.36 * self.rbz\n"),("0.30 * self.rz, 0.22 * self.rz","0.30 * self.rbz, 0.22 * self.rbz"),
            ("tz = self.rz + grng","tz = self.rbz + grng"),("((z - self.rz) / self.rB)","((z - self.rbz) / self.rB)")]:
    assert a in s, a; s=s.replace(a,b)
open(f,'w').write(s)
EOF
grep -c "self.rbz" src/paint/ferrari_method.py; nice -n 10 python3 src/paint/debug_gb.py medium left 10m 1 && nice -n 10 python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('~/work/pixelart-studies/pedagogy/analysis/out/debug_gb.png'))[:, 640:][::2,::2]
Image.fromarray(np.repeat(np.repeat(a,3,0),3,1)).save('~/work/pixelart-studies/pedagogy/analysis/out/cell3x.png')"

# output:
5

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'
s=open(f).read()
rep=[("self.rbz = max(28.0, 1.4 * d + 16.0)","self.rbz = max(45.0, 1.3 * d + 32.0)"),
("self.rxc = s_ * 0.36 * self.rbz","self.rxc = s_ * 0.44 * self.rbz"),
("self.rA, self.rB = 0.30 * self.rbz, 0.22 * self.rbz","self.rA, self.rB = 0.26 * self.rbz, 0.18 * self.rbz"),
("            tx = self.rxc + s_ * grng.uniform(-0.45, 0.9) * self.rA","            tx = self.rxc + s_ * grng.uniform(-0.25, 0.9) * self.rA"),
("""        e3 = (1 - np.sqrt(((x - self.rxc) / self.rA) ** 2 + ((z - self.rbz) / self.rB) ** 2)) * min(self.rA, self.rB) * 0.5
        e3 = e3 + 0.4 * n.fbm2(x * 0.2 + 70, z * 0.2, 3)
        return np.maximum(np.maximum(sd + wob, self.near_sd(x, z)), e3)""",
"""        return np.maximum(np.maximum(sd + wob, self.near_sd(x, z)), self.right_sd(x, z))

    def right_sd(self, x, z):
        e3 = (1 - np.sqrt(((x - self.rxc) / self.rA) ** 2 + ((z - self.rbz) / self.rB) ** 2)) * min(self.rA, self.rB) * 0.5
        return e3 + 0.4 * self.noise.fbm2(x * 0.2 + 70, z * 0.2, 3)"""),
("""        h = 0.30 * smoothstep(0.0, 2.0 + r, sd) + mound * smoothstep(0.0, 1.0, sd) \\""",
"""        # the far right bank rises into a hummock (lit rim, dark face -- the reference's far mounds)
        h = 0.30 * smoothstep(0.0, 2.0 + r, sd) + mound * smoothstep(0.0, 1.0, sd) \\
            + 2.2 * smoothstep(0.0, 6.0, self.right_sd(x, z)) \\"""),
("        pu = 0.70 if self.bx < 0 else 0.30\n        pu2","        pu = 0.60 if self.bx < 0 else 0.40\n        pu2"),
("        pu = (0.70 if self.bx < 0 else 0.30) * W","        pu = (0.60 if self.bx < 0 else 0.40) * W"),
]
for a_,b_ in rep:
    assert a_ in s, a_[:50]; s=s.replace(a_,b_)
open(f,'w').write(s)
EOF
nice -n 10 python3 src/paint/debug_gb.py medium left 10m 1 && nice -n 10 python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('~/work/pixelart-studies/pedagogy/analysis/out/debug_gb.png'))[:, 640:][::2,::2]
Image.fromarray(np.repeat(np.repeat(a,3,0),3,1)).save('~/work/pixelart-studies/pedagogy/analysis/out/cell3x.png')"

# output:
(Bash completed with no output)

cd ~/work/pixelart-studies/pedagogy/analysis && FORCE=1 OMP_NUM_THREADS=1 nice -n 10 python3 src/paint/sheets.py > out/sheets.log 2>&1; tail -1 out/sheets.log; nice -n 10 python3 src/check_sheets.py $(cat out/cellkeys.txt) > out/check_all.txt 2>&1; nice -n 10 python3 - <<'EOF'
import json, numpy as np
d=json.load(open('out/check_stats.json'))
F=d.pop('ferrari')
CORR={'sky':'sky','mountain':'mountain','far forest':'far forest','water':'water','bank (boulder side)':'left meadow (mid)','boulder':'mountain','near bank lit':'left bank (fore)','near bank shade':'right bank (fore)','grove':'framing trees'}
keys=['area','L_med','L_p5','L_p95','colours_90','vsame','hsame','cluster_mean','single','checker','b']
rows=[]
for n,fn in CORR.items():
    vals=[c[n] for c in d.values() if n in c]
    m={k:float(np.median([v[k] for v in vals])) for k in keys}
    print(f"{n:20s} {fn:18s} "+' '.join(f"{k}={m[k]:.2f}/{F[fn][k]:.2f}" for k in keys), f"(n={len(vals)})")
    rows.append(dict(plane=n,ref=fn,mine=m,ferrari={k:F[fn][k] for k in keys},n=len(vals)))
json.dump(rows,open('out/check_summary.json','w'),indent=1)
EOF

# output:
Command did not complete within its 600s timeout and was moved to the background (ID: bgsbr3kuk). 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/analysis && cat >> LESSONS.md <<'EOF'

---

## 3. The method (`src/paint/ferrari_method.py`, `src/paint/pixelgeo.py`, `src/paint/sheets.py`)

`paint(size, light, distance, seed)` returns a 320×180 image in a fixed 32-colour palette, and
`python src/paint/sheets.py` writes the sheets to `sheets/`. Every cell is also saved at native
size in `sheets/cells/`, with its palette-index map and plane map, so the cells can be analysed.
Parameters:

* `size`: small, medium or large. The boulder radius is 0.55, 0.95 or 1.45 m (1.1 / 1.9 / 2.9 m
  across).
* `light`: left, front, right or back. The sun stays about 7° up. Front means the sun is behind the
  viewer and slightly left, so the form still turns.
* `distance`: close, 10m or 40m. Close is 4.5 m.
* `seed`: varies the shoreline, boulder weathering, trees, mountain, blades and stones.

The camera is 1.1 m above the water, looking 10° down, with a 50° horizontal field of view. So the
horizon sits at row 29.5 and the frame's top edge is only 4.5° above horizontal. That drove a
design decision taken straight from the analysis. **Everything tall (the peak and the conifers) is
taller than the frame. The frame crops it, and the water shows it whole.** In the reference the
reflected peak is the thing the V of banks points to. Here the reflected peak and the reflected
conifers fill the water.

### The pipeline, with the analysis finding behind each step

1. **Geometry, as a G-buffer.** I ray-march:
   * a weathered, lumpy ellipsoid for the boulder, about 35% sunk;
   * a heightfield of banks: the boulder's promontory, whose shoreline wraps the boulder's
     front-right so its reflection hangs straight below it, a hummock behind it, and a far-right
     hummock;
   * tiered-cone conifers;
   * the water plane.

   The mountain, sky and far forest are a backdrop, defined in picture coordinates (column, rows
   above the horizon) so the reflection can sample them at the mirrored elevation.

   *Found in 1.1:* the V of foreground banks. The near bank is designed **in the picture plane** as
   two composition lines, then lifted onto the ground. A low lit bank sits on the boulder side and
   a bank rises diagonally, dark, on the other side. The V opens wider when the camera is farther
   away, so the foreground is never empty.
2. **Value first.** Each material computes a target L\*, and the scale is taken from the
   reference's value groups:
   * sky 71–79;
   * peak darks lifted to ≥37;
   * lit grass about 48–60 and shade grass 10–20;
   * boulder: light 44–78, core shadow down to 13;
   * water = the source value, compressed (1.2, 2).
3. **Colour second.** The value is looked up in the material's ramp: a warm ramp in light and a
   cool ramp in shade. There is never a nearest-colour search over the whole palette. The one
   exception is the water, which can reflect anything, so it may use a 21-colour subset.
4. **Clusters.** In-between values are laid with the material's own threshold map (1.6):
   * **sky**: flat bands with checker seams (`w=0.32`);
   * **near grass**: Ferrari's measured recipe, **base 38% / mid stroke 35% / olive 11% / gap 12%**
     in light and **black 28% / black-green 31% / olive 40%** in shade, thresholded on a
     vertically stretched noise so the proportions come out as vertical 1-px strokes;
   * **far grass**: a two-colour speckle;
   * **rock**: a value spread along diagonal fall lines, with checker between value zones;
   * **water**: horizontal ripple noise, with checker only in the middle of a blend;
   * **conifers**: black and violet-black with ochre flecks on the sun side of each drooping tier
     (black, ochre, dark: 3 colours).
5. **The boulder's light plan.** It is painted as a painter plans it:
   * one clean terminator from the *big* form (the undisplaced ellipsoid's normal);
   * zones of highlight, light and half-tone on the lit side;
   * core, shadow and sky-lit top on the shadow side;
   * a one-step darkening where the lit form turns away from us;
   * facets, with a light line on the sun side of a facet edge and a dark crease on the other.

   The lumps only move values inside zones.
6. **Pixel geometry.** From 1.9 and David's note. The boulder silhouette, its reflection and the
   bank silhouettes are simplified to polygons. Every edge is snapped to a clean pixel slope (flat,
   5:1 … 1:1 … 1:4, vertical), a least-squares solve finds vertex positions that keep the shape
   closed, and the result is re-rasterised. The mountain crest is a polyline of clean-slope
   segments. **Every mass that meets water gets a flat, 1-px dark contact line**, and the boulder
   gets a flat bottom. The stones in the shallows are flat lozenges with a light top row, mid body,
   dark bottom row and 45° ends.
7. **Strokes: impressionistic contrast inside the stroke.** Grass blades are straight runs with
   clean steps: a lower segment at one slope and the tip at a shallower one. They are painted back
   to front in counterchange:
   * on light ground, a dark blade **with its lit edge beside it**;
   * on dark ground, a light blade that gets lighter toward the tip, **with a dark shadow side**.

   Sedge rises around the boulder's foot and along the waterline, where it breaks the lost edge
   between boulder and bank. The blades at the waterline get short, broken dark reflections.
8. **Reflection.** An exact mirror (the ray is reflected in the water plane and traced again,
   including the boulder, banks and conifers). The calibrated transform: the sky loses ~4 L\*, top
   lights lose ~13, darks stay put, and a\* drops 4. Water reflects slightly less toward the frame
   bottom. There are sparse 1-px streak lines, denser toward the far shore: the rows Ferrari would
   colour-cycle.
9. **Light direction.** It changes more than shading. Each direction carries a scene decision
   taken from the reference:
   * the sky's warm side follows the sun;
   * front light gives a **Belt of Venus** (the pink band above the violet Earth-shadow);
   * back light gives a glow above the frame, rim-lit boulder, trees and blade tips, a silhouetted
   peak, and a whole foreground in shade;
   * side light puts the far side of the near V in the shadow of off-frame trees (the reference's
     dark right bank);
   * grass counts as lit whenever the sun reaches it, because blades stand upright and catch a
     grazing sun whatever the slope of the ground.

### The palette (32 colours, chosen per material)

| ramp | colours |
|---|---|
| sky (iso-luminant hue sweep) | sky0 violet, sky1, sky2 pink, sky3 salmon, sky4 peach, hot |
| distant rock (lifted darks) | mtn0 L37 violet, mtn1, mtn2 alpenglow salmon, snow0 lavender |
| far forest | for0 violet-black, for1 |
| grass, lit (warm) | g0 L11 black-green, g1 L24 olive, g2 L40 brown, g3 L51, g4 L60 ochre, g5 L73 back-lit tip |
| grass, shade | k black, g0, h1, g1, h2 olive; sedge (greener) |
| granite | r0 core L15, r1 shadow violet-grey, r2 half-tone mauve, r3 warm light, r4 peach highlight |
| water | w0 bed/deep, w1, w2, w3 (reflected sky, cooled), glint |
EOF
echo ok

# output:
ok
[This command modified 1 file you've previously read: ../pedagogy/analysis/LESSONS.md. Call Read before editing.]

until grep -q "n=19" (tmp) 2>/dev/null || grep -q Traceback (tmp) do sleep 10; done; cat (tmp)

# output:
done 19 cells
sky                  sky                area=0.01/0.18 L_med=64.86/71.40 L_p5=72.51/71.08 L_p95=75.06/75.38 colours_90=2.00/8.00 vsame=0.70/0.47 hsame=0.79/0.47 cluster_mean=7.19/2.99 single=0.89/0.97 checker=0.08/0.25 b=2.59/1.26 (n=19)
mountain             mountain           area=0.07/0.04 L_med=56.61/48.44 L_p5=36.77/36.21 L_p95=75.06/77.33 colours_90=5.00/15.00 vsame=0.55/0.42 hsame=0.59/0.45 cluster_mean=5.26/3.28 single=0.56/0.72 checker=0.05/0.10 b=-7.29/-4.75 (n=19)
far forest           far forest         area=0.02/0.09 L_med=20.55/19.81 L_p5=1.06/0.00 L_p95=39.84/45.32 colours_90=4.00/10.00 vsame=0.31/0.46 hsame=0.62/0.45 cluster_mean=4.11/3.83 single=0.44/0.65 checker=0.01/0.06 b=0.76/0.00 (n=19)
water                water              area=0.54/0.17 L_med=58.96/28.96 L_p5=1.06/0.00 L_p95=70.62/72.02 colours_90=12.00/69.00 vsame=0.37/0.33 hsame=0.49/0.33 cluster_mean=2.54/2.34 single=0.86/0.75 checker=0.27/0.08 b=-8.18/1.77 (n=19)
bank (boulder side)  left meadow (mid)  area=0.10/0.05 L_med=40.34/41.92 L_p5=11.07/10.52 L_p95=61.24/61.05 colours_90=6.00/7.00 vsame=0.55/0.56 hsame=0.38/0.44 cluster_mean=3.62/4.46 single=0.52/0.61 checker=0.03/0.06 b=34.34/27.43 (n=19)
boulder              mountain           area=0.04/0.04 L_med=32.10/48.44 L_p5=14.45/36.21 L_p95=64.75/77.33 colours_90=4.00/15.00 vsame=0.75/0.42 hsame=0.73/0.45 cluster_mean=10.65/3.28 single=0.65/0.72 checker=0.04/0.10 b=-8.18/-4.75 (n=19)
near bank lit        left bank (fore)   area=0.07/0.11 L_med=39.22/43.42 L_p5=11.07/10.78 L_p95=61.24/60.26 colours_90=4.00/4.00 vsame=0.58/0.70 hsame=0.26/0.34 cluster_mean=3.53/6.15 single=0.46/0.39 checker=0.03/0.05 b=34.34/35.29 (n=19)
near bank shade      right bank (fore)  area=0.10/0.13 L_med=15.67/14.17 L_p5=1.06/0.00 L_p95=24.03/26.39 colours_90=4.00/4.00 vsame=0.67/0.68 hsame=0.31/0.36 cluster_mean=5.17/5.57 single=0.34/0.41 checker=0.02/0.04 b=13.03/14.34 (n=19)
grove                framing trees      area=0.06/0.16 L_med=12.03/15.57 L_p5=1.06/0.00 L_p95=39.84/45.32 colours_90=3.00/3.00 vsame=0.51/0.56 hsame=0.59/0.52 cluster_mean=4.57/5.17 single=0.66/0.64 checker=0.03/0.07 b=0.76/0.00 (n=19)

[exited with code 0]

cd ~/work/pixelart-studies/pedagogy/analysis && cat > src/compare_plates.py <<'EOF'
"""Comparison plates: the same analyses on Ferrari and on painted cells, side by side."""
import sys; sys.path.insert(0,'src'); from util import *
from scipy.ndimage import gaussian_filter
from atlas import atlas
from edges import draw as edge_draw
CELLS='sheets/cells'
def notan_img(a, cuts=(28.9,55.6)):
    Lb=gaussian_filter(lum(a),2.5*a.shape[1]/634)   # same squint relative to picture width
    q=np.digitize(Lb,cuts); lv=np.array([25,130,240]); g=lv[q].astype(np.uint8)
    return np.stack([g]*3,-1)
def fit(a,w):
    return np.array(Image.fromarray(a).resize((w,int(a.shape[0]*w/a.shape[1])),Image.NEAREST))
ref=load_ref()
keys=['medium_left_10m_s1','medium_front_10m_s1','medium_back_10m_s1','medium_left_close_s1','medium_left_40m_s1','medium_left_10m_s4']
W0=420
tiles=[label(fit(ref,W0),'Ferrari'),label(fit(notan_img(ref),W0),'Ferrari 3-notan')]
for k in keys:
    a=np.array(Image.open(f'{CELLS}/{k}.png').convert('RGB'))
    tiles+= [label(fit(a,W0),k),label(fit(notan_img(a),W0),'3-notan (same cuts)')]
rows=[]
for i in range(0,len(tiles),4):
    r=tiles[i:i+4]
    h=max(t.shape[0] for t in r)
    r=[np.pad(t,((0,h-t.shape[0]),(0,6),(0,0)),constant_values=255) for t in r]
    while len(r)<4: r.append(np.full_like(r[0],255))
    rows.append(np.pad(np.concatenate(r,1),((0,6),(0,0),(0,0)),constant_values=255))
Image.fromarray(np.concatenate(rows,0)).save('img/20_notan_compare.png')
# cluster atlas for my base cell (same windows by material)
a=np.array(Image.open(f'{CELLS}/medium_left_10m_s1.png').convert('RGB'))
P=np.load(f'{CELLS}/medium_left_10m_s1_planes.npy')
def win(pl,cond=None):
    ys,xs=np.nonzero(P==pl)
    ok=(ys>2)&(ys<a.shape[0]-34)&(xs<a.shape[1]-34)
    if cond is not None: ok&=cond(ys,xs)
    i=np.flatnonzero(ok)
    j=i[len(i)//2] if len(i) else 0
    return (int(xs[j]),int(ys[j]))
wins=[('near grass, lit',win(6,lambda y,x: x<120)),('near grass, shade',win(6,lambda y,x: x>220)),('bank by boulder',win(4)),
      ('boulder',win(5)),('grove (conifer)',win(8)),('water',win(3,lambda y,x:(y>120)&(x>120)&(x<200))),
      ('far forest',win(2)),('mountain',win(1)),('sky',win(0))]
atlas(a,[(t,(max(0,x-4),max(0,y-4))) for t,(x,y) in wins],'21_cluster_atlas_mine.png',s=7,sz=32)
edge_draw(a,'22_edges_mine',3)
EOF
sed -i '' "s|    save(out.astype(np.uint8),f'{prefix}_edges.png',scale)|    save(out.astype(np.uint8),f'{prefix}_edges.png' if not prefix.endswith('mine') else f'{prefix}.png',scale)|" src/edges.py
nice -n 10 python3 src/compare_plates.py && ls img | grep -E "^2[0-2]"

# output:
20_notan_compare.png
21_cluster_atlas_mine.png
22_edges_mine.png

cd ~/work/pixelart-studies/pedagogy/analysis && nice -n 10 python3 -c "
import numpy as np, glob
from PIL import Image
for f in sorted(glob.glob('sheets/cells/*.png')):
    a=np.array(Image.open(f).convert('RGB')); n=len(np.unique(a.reshape(-1,3),axis=0)); print(f.split('/')[-1], a.shape, n)
" | awk '{print $NF}' | sort -n | uniq -c; ls sheets/

# output:
1 26
  15 27
   3 28
cells
sheet_distance.png
sheet_light.png
sheet_light_x_distance.png
sheet_seed.png
sheet_size.png

cd ~/work/pixelart-studies/pedagogy/analysis && cat >> LESSONS.md <<'EOF'

### Sheets (`sheets/`)

Each sheet sweeps one parameter from the base settings (medium, left, 10 m, seed 1), 3× nearest:

* `sheet_size.png`
* `sheet_light.png`
* `sheet_distance.png`
* `sheet_seed.png` (6 seeds)
* `sheet_light_x_distance.png` (all 12 light × distance combinations)

Every cell uses 26–28 of the 32 palette colours.

---

## 4. Checking the sheets with the same analyses (`src/check_sheets.py`, `src/compare_plates.py`)

I ran the value, notan, cluster, dither, palette-coverage and depth code from section 1 unchanged on
all 19 rendered cells, using the planes the painter records. The table gives the median over the
cells, then Ferrari's value for the corresponding plane (`out/check_summary.json`,
`out/check_all.txt`). Squint L = median of the σ=2.5 blurred L\*. "v-same" and "h-same" = share of
vertical and horizontal neighbours that are the same colour. "cols 90%" = colours covering 90% of
the plane.

| my plane ↔ Ferrari plane | squint L | p5–p95 L | cols 90% | v-same / h-same | mean cluster | checker share | b\* |
|---|---|---|---|---|---|---|---|
| near bank, shade ↔ right bank | **15.7 / 14.2** | **1–24 / 0–26** | **4 / 4** | **0.67 / 0.68**, 0.31 / 0.36 | **5.2 / 5.6** | 0.02 / 0.04 | **13 / 14** |
| near bank, lit ↔ left bank | 39.2 / 43.4 | **11–61 / 11–60** | **4 / 4** | 0.58 / 0.70, 0.26 / 0.34 | 3.5 / 6.2 | 0.03 / 0.05 | **34 / 35** |
| bank by boulder ↔ left meadow | **40.3 / 41.9** | **11–61 / 11–61** | 6 / 7 | **0.55 / 0.56**, 0.38 / 0.44 | 3.6 / 4.5 | 0.03 / 0.06 | 34 / 27 |
| grove ↔ framing trees | 12.0 / 15.6 | **1–40 / 0–45** | **3 / 3** | **0.51 / 0.56**, 0.59 / 0.52 | **4.6 / 5.2** | 0.03 / 0.07 | **1 / 0** |
| far forest ↔ far forest | **20.6 / 19.8** | 1–40 / 0–45 | 4 / 10 | 0.31 / 0.46, 0.62 / 0.45 | 4.1 / 3.8 | 0.01 / 0.06 | 1 / 0 |
| mountain ↔ mountain | 56.6 / 48.4 | **37–75 / 36–77** | 5 / 15 | 0.55 / 0.42 | 5.3 / 3.3 | 0.05 / 0.10 | −7 / −5 |
| boulder ↔ mountain rock | 32.1 / 48.4 | 14–65 / 36–77 | 4 / 15 | 0.75 / 0.42 | **10.7 / 3.3** | 0.04 / 0.10 | −8 / −5 |
| water ↔ water | **59.0 / 29.0** | 1–71 / 0–72 | 12 / 69 | 0.37 / 0.33, 0.49 / 0.33 | 2.5 / 2.3 | **0.27 / 0.08** | −8 / +2 |
| sky ↔ sky | 64.9 / 71.4 | 73–75 / 71–75 | 2 / 8 | — | — | 0.08 / 0.25 | 3 / 1 |
| *area share* | water **54%** vs 17%; sky 1% vs 18%; near banks 17% vs 24% | | | | | | |

Bold = a close match.

### Analysis by analysis

**Planes and masses** (`sheets/*`, `img/20_notan_compare.png`). The structure transferred:

* a V of foreground banks opening onto water, lit on one side and dark on the other;
* a promontory carrying the subject;
* dark framing conifers;
* a peak whose reflection sits inside the V.

The proportions did not transfer. **The water takes 54% of my frame against 17%**, and the sky 1%
against 18%. The cause is the task's camera. Looking 10° down with a 29° vertical field puts the
horizon at row 29 of 180, so most of the frame *has* to be ground or water. I leaned into it:
peak and trees taller than the frame, shown whole in the water. But the picture is a different
shape from Ferrari's, whose camera looks level and gives the sky and the trees half the picture.

**Values and notan** (`img/20_notan_compare.png`, `img/chk_*_grey_vs.png`, `img/chk_*_valueplanes.png`).
With Ferrari's own notan cuts, both pictures read as an hourglass: dark masses left and right, and
a light shape pouring down the middle. The balance is inverted, though. **Ferrari's picture is
about 60% dark with a light top. Mine is light-dominant, with a dark top band** (far forest plus
crowns) and a large light water field. Water squint L is 59 against 29, because his water mostly
mirrors tall black trees and mine mostly mirrors sky. The planes themselves sit in the right value
groups. Near shade 15.7 vs 14.2. Lit meadow 40 vs 42. The grove's darks at black. The peak's
darks lifted to L37 (exactly Ferrari's 36). Nothing white: my sky tops out at L75 and only the
back-lit rim and the snow reach L80. **The foreground value groups are the best transfer in the
study. The overall notan balance is the biggest miss.** The lit near bank still runs 4 L too dark:
my lit/shade transition is made of strokes, and some of them are shade.

**Light** (`sheets/sheet_light.png`). One rule, visible in every cell: warm light and cool shade,
per material. Lit ochre against black-olive, peach granite against violet, salmon rock against
violet rock, lit snow against lavender. The four directions each make a different picture, not
just different shading:

* **left and right**: the far side of the V goes into off-frame shadow;
* **front**: the Belt of Venus, the lit boulder front, and the mountain's lit faces turning warm;
* **back**: glow, a rim-lit boulder with a one-pixel peach halo, rim-lit trees, a silhouetted
  violet peak, and the whole foreground in shade.

Front light is my weakest. With the sun behind the viewer, the boulder has little shadow and
reads as a pale mass. A painter would push the terminator and core harder than physics does.

**Form** (the close cells in `sheet_distance.png` and `sheet_light_x_distance.png`). The boulder
has what the form analysis asked for: one clean terminator from the big form, highlight, light and
half-tone zones, a core shadow, a sky-lit shadow top, a flat water contact with a dark lip, and a
reflection with the lit side reading warm. It is **smoother than Ferrari's rock**: mean cluster 10.7
against 3.3, and 4 colours against 15. His rock is a distant mountain made of many small planes
and diagonal strokes. My boulder is one big close form in a 5-colour granite ramp. At 10 m and
40 m it reads as a boulder. At 4.5 m the lumps give it lobes, but not yet the crisp faceted planes
I set out to paint. Ferrari's lozenge hummock (lit rim, dark face) appears in my far-right bank,
but it is only a thin strip at this camera angle.

**Edges** (`img/22_edges_mine.png` against `img/08_edges.png`). The same distribution. The hard
edges are silhouettes against light water: the boulder's reflection, the conifers' reflections,
and the V banks against the water. The soft edges are the grass interiors. The lost edges are dark
against dark: the grove's crowns against the far forest, the boulder's shadow side into its own
reflection (joined only by the 1-px lip), and the bank into the boulder foot, where sedge breaks it.
I did not reproduce the *sky* edges, because there is almost no sky.

**Clusters** (`img/21_cluster_atlas_mine.png` against `img/09_cluster_atlas.png`; `out/cmp_grass.png`
puts my near lit grass beside his at 6×).

* **Near shade grass** is effectively Ferrari's: black and black-green ground with olive strokes, 4
  colours, vertical coherence 0.67 vs 0.68, mean cluster 5.2 vs 5.6. That came straight from
  transcribing his measured proportions.
* **Near lit grass** has the right colours, proportions and warmth (b\* 34 vs 35), but its strokes
  are shorter: mean cluster 3.5 vs 6.2, vertical coherence 0.58 vs 0.70. The paired
  light-and-dark blades add horizontal alternation that he doesn't have at that density.
* **Conifers** match on colour count, cluster size and single-pixel share. But **their reflections
  are too regular**: the tiers repeat as even chevrons, where his are broken and noisy.
* **Water** has **too much checkerboard** (27% of 2×2 blocks against 8%). My reflected sky is a
  large flat area that needs a blend pattern. His reflected sky is small and cut by reflections.
* **Sky** and **far forest**: I have too few colours to judge the sky (2 visible bands). The forest
  flecks read as horizontal strokes (h-same 0.62 vs 0.45), where his are more speckled.

**Palette** (`src/paint/ferrari_method.py` PAL). 32 colours as material ramps, with the same two
hue families (sun ochres and peaches against sky violets and pinks). Chroma peaks mid-value. There
is a pure black, a lifted violet ramp for distance and an iso-luminant sky sweep. The budget is
the obvious difference from 172 colours. I spent it where the analysis said the picture's
structure lives (foreground ramps at 4 colours each, granite at 5, sky at 6). That starves the
mountain (5 colours used, against 15) and the water (12 against 69).

**Depth** (`img/chk_*_depth.png` against `img/12_depth.png`):

* **Overlap**: near V, promontory, boulder, groves, far forest, peak.
* **The black point rises**: black near and in the forest, L37 at the peak, as in the reference.
* **Hue**: ochre near, violet far.
* **Texture scale**: strokes near, speckle at the promontory at 40 m.

All four cues are present and in the right order. What's missing is Ferrari's middle-distance
chroma dip. My promontory is as saturated as the foreground (chroma 34).

**Pixel geometry** (David's note). Silhouettes are clean-slope polygons, and every mass has a
flat base and a dark contact line at the water. The crest is a clean polyline, stones are
lozenges, and blades are straight runs with one change of slope. At native size this is the
biggest single improvement between my first and last sheets: shapes look drawn rather than
sampled. The grammar is still applied as a post-process, though. The boulder's big silhouette
sometimes snaps into over-long straight edges, a slightly boxy octagon, where Ferrari varies his
run lengths along a curve.

---

## 5. What I would do next

1. **Rebalance the notan to Ferrari's roughly 60% dark.** Let the grove crowns and the far forest
   occupy more of the top, and give the conifer reflections more mass and noise. Or, a question
   for the task's owner: let the camera rise to near-level so the sky and tree masses get their
   share. The 10° camera is the biggest reason my pictures are shaped differently from his.
2. **Break the conifer reflections** with per-tier jitter, sky holes, and a speckle-dissolve
   toward the tips, as his do.
3. **Facet the close boulder properly.** Build it as a few large planes carved by fracture lines,
   each plane one value with checker seams, rather than a lumpy ellipsoid nudged by Voronoi facets.
4. **Lengthen the lit-grass strokes.** Draw the lit-edge pairs only on a minority of blades, and
   bring the lit bank's value up 4 L.
5. **Colour cycling.** Reserve 3–4 palette slots as a cycling ramp for the water streak rows and
   shallows, and export an animated GIF per cell. That is the part of Ferrari's craft this study
   only describes.
EOF
wc -l LESSONS.md

# output:
541 LESSONS.md
[This command modified 1 file you've previously read: ../pedagogy/analysis/LESSONS.md. Call Read before editing.]

cd ~/work/pixelart-studies/pedagogy/analysis && nice -n 10 python3 -c "
from PIL import Image; import numpy as np
a=np.array(Image.open('sheets/cells/medium_left_10m_s1.png'))
ref=np.array(Image.open('img/00_native.png'))
z=np.concatenate([np.repeat(np.repeat(a[110:180,0:110],6,0),6,1), np.full((420,12,3),255,np.uint8), np.repeat(np.repeat(ref[330:400,0:110],6,0),6,1)],1)
Image.fromarray(z).save('img/23_grass_mine_vs_ferrari.png')
" && python3 - <<'EOF'
f='LESSONS.md'; s=open(f).read()
s=s.replace("`out/cmp_grass.png`\nputs my near lit grass beside his at 6×","`img/23_grass_mine_vs_ferrari.png`\nputs my near lit grass (left) beside his (right) at 6×")
s=s.replace("Nothing white: my sky tops out at L75 and only the\nback-lit rim and the snow reach L80.","Nothing white: my sky runs L72–81, the brightest end only in\nthe back-lit glow, and only the peach highlight, the back-lit rim and the lit snow go past L80.")
open(f,'w').write(s)
EOF
grep -n "23_grass\|L72–81" LESSONS.md

# output:
452:darks lifted to L37 (exactly Ferrari's 36). Nothing white: my sky runs L72–81, the brightest end only in
486:**Clusters** (`img/21_cluster_atlas_mine.png` against `img/09_cluster_atlas.png`; `img/23_grass_mine_vs_ferrari.png`

cd ~/work/pixelart-studies/pedagogy/analysis && python3 - <<'EOF'
f='src/paint/ferrari_method.py'; s=open(f).read()
a=s.index("    def paint_repoussoir(self, img):"); b=s.index("\ndef paint(")
s=s[:a].rstrip()+"\n\n"+s[b:]
s=s.replace("        # ---------------- near repoussoir bank (dark, bottom corner opposite the boulder)\n        # (the screen-space repoussoir is replaced by the 3D near bank)\n","")
open(f,'w').write(s)
EOF
nice -n 10 python3 -c "
import sys; sys.path.insert(0,'src/paint'); import ferrari_method as fm, numpy as np
rgb=fm.paint('small','back','40m',7); print(rgb.shape, len(np.unique(rgb.reshape(-1,3),axis=0)))" ; ls img | wc -l; du -sh sheets

# output:
(180, 320, 3) 28
     171
 18M    sheets