pxart shade

shade FILE[:frame] --ramp d2,d1,base,l1[,l2] [--keys k1,k2] [--base K] [--light nw] [--strength N] [--region x,y,w,h] [--dither] [--preview P.png]

usage: pxart shade [-h] --ramp RAMP [--keys KEYS] [--base BASE] [--light {n,ne,e,se,s,sw,w,nw}]
                   [--strength STRENGTH] [--region REGION] [--dither] [--preview PREVIEW] [-o O]
                   [--dry-run]
                   file

  shade FILE[:frame] --ramp d2,d1,base,l1[,l2] [--keys k1,k2] [--base K] [--light nw]
        [--strength N] [--region x,y,w,h] [--dither] [--preview P.png]
      Re-shade a material with a darkest-to-lightest ramp, by how each pixel faces the light.

positional arguments:
  file

options:
  -h, --help                     show this help message and exit
  --ramp RAMP
  --keys KEYS                    the material's keys (default: the ramp's)
  --base BASE
  --light {n,ne,e,se,s,sw,w,nw}
  --strength STRENGTH
  --region REGION
  --dither
  --preview PREVIEW
  -o O
  --dry-run                      print what the edit says and a diff of the file it would change; write nothing

      Re-shade a material: the pixels whose key is in --keys (default: the ramp's keys, so a
      shaded material re-shades) get ramp tones by how they face the light. The ramp runs
      darkest to lightest; the base is its middle key (d2,d1,base,l1: the extra key goes
      dark), or --base K. Keys are 'a,b,c' or 'abc'. Nothing outside the material changes.
      --region x,y,w,h repaints only the material inside it, shaded as part of the whole
      frame's material: the region's border is not an edge, only a real one is (an empty
      pixel, another material, or the frame's side).
      Algorithm, per pixel of the material (the shape: those pixels, over the whole frame;
      everything else, and off the frame, is outside):
        1. depth: its distance to the shape's edge (a vector distance transform from the
           edge pixels, those with an outside side neighbor; ~Euclidean, 0 on the edge);
        2. normal: which way is out from it: the pull of the outside pixels within depth + 4
           px minus that of the shape's, 1/distance-weighted (a staircase reads as its slope);
        3. lighting = (normal . light direction) * (1 - depth / strength), in -1..1: an edge
           facing the light is +1, one facing away -1, and the value fades to 0 (the base
           tone) --strength px in (default 2: a rim; the shape's radius: full form shading);
        4. banding: 0..1 splits evenly over the lights, -1..0 over the darks, rounding to the
           nearest step, ties toward the base; then a stray pixel (no 8-neighbor of its own
           tone) takes its neighbors' commonest tone. No noise.
      --dither mixes adjacent tones with a 4x4 ordered (Bayer) pattern where the lighting is
      within a quarter step of a band boundary (and skips the stray-pixel pass). --light: n
      ne e se s sw w nw (default nw). --preview P.png renders the result (render's grid and
      rulers) and writes nothing else. Prints the pixels it changed, by the tone they got,
      darkest first: "changed 24 px: 4->A, 8->B, 8->D, 4->E" (with --preview, "would change").
      'shade hero.px:idle/0 --ramp XxcCw --keys c' shades the cloak c with the ramp X x c C w.

See also, in pxart help all: DRAWING (FILE[:SEL], KEY ('.' erases), clipping, 'painted N
  px'); EDITING (-o OUT gets the whole file, only changed lines are rewritten, 'no change');
  FORMAT: selecting frames (FILE:SEL, an unnamed grid's name, zsh's "${F}:sel").

pxart help all has the whole reference, pxart help TOPIC one part of it.

This is the output of pxart help shade. The other drawing commands and their shared notes are in pxart help DRAWING.