`nx_dedither.nx` source

↩ module page · 831 lines · 41866 B
1// nx_dedither.nx -- RECOVER A 1990s DITHERED IMAGE WITHOUT TOUCHING THE ORIGINAL BYTES.
2//
3// WHY THIS EXISTS (measured 2026-08-07, page3.com/13Nov96.gif): a 280x403 GIF weighing 81,953 B is a
4// PHOTOGRAPH crushed into a 256-entry palette. The encoder of 1996 traded colour depth for file size by
5// scattering alternating palette entries across smooth regions -- so a plain studio backdrop is stored as
6// high-frequency speckle. The archive serves those bytes FAITHFULLY, and faithful is exactly why the
7// backdrop reads as white fuzz. The fuzz is not our defect and not decode damage: header valid, trailer
8// 0x3B present, extension preserved 1:1 from the 1996 HTML, no re-encode anywhere in the pipeline.
9//
10// *THE ARCHIVE WAS RIGHT AND THE PICTURE STILL LOOKED WRONG. Those are different problems and only the
11// second one is fixable. Rule 25 says build intelligence, never strip features -- so this NEVER rewrites
12// the stored asset. It emits a SEPARATE enhanced render beside it. The original remains the record.
13//
14// HOW: a sigma filter (Lee 1983) -- average only over neighbours whose colour is already CLOSE to the
15// centre. Dither speckle is by construction a set of near-neighbours straddling the true value, so it
16// averages away; a real edge has far neighbours, which are EXCLUDED from the mean and therefore survive.
17// A plain box blur would also lower the noise metric -- and would destroy the picture. That is precisely
18// why the selftest below refuses to pass on noise reduction alone.
19//
20// RULER: mean absolute local deviation (MALD) vs a 3x3 mean, x1000, integer. Reported BEFORE and AFTER
21// so the claim is a measurement and not an adjective.
22//
23// usage: nx_dedither <in-image> <out.png> [radius=2] [threshold=40]
24//        nx_dedither --kat                 (selftest: 4 teeth, 2 of them anti-vacuity)
25// argv[1]=input (any format nx_img_bytes_to_rgb decodes), argv[2]=output PNG.
26// exit 0 ok | 2 decode/write failure | 3 usage | 1 selftest RED
27// license_tier: ORIGINAL   No hw writes (Rule 26).   expect_exit: 0
28import "nx_syscalls.nx"
29import "nx_img_to_rgb.nx"
30import "nx_png_write.nx"
31import "nx_img_resample.nx"
32
33// SCALE STAGE -- added 2026-08-07 on OCR EVIDENCE, not taste. A neutral OCR instrument
34// (Windows.Media.Ocr, an oracle in the qemu/openssl sense, never a runtime dep) read the archive's
35// prop.gif as "PropertyXET" at native 250x48; ground truth is "PropertyNET", fixed by the 1996 href
36// god.co.uk/propertynet/. At x2 and x3 the SAME instrument reads "PropertyNET" exactly; at x4 and x6 it
37// degrades again to "PropenyXET"/"PropenyNET" as the resampler fuses r+t into n. So the useful band is
38// MEASURED at x2-x3 with a real optimum, not assumed monotonic -- more upscale is NOT more legible.
39// *BICUBIC ON PURPOSE: the evidence above was produced with a bicubic resampler, so shipping bilinear
40// would be quoting a measurement taken with a different instrument than the one that runs.
41const DD_MAXR: i64 = 8
42const DD_MAXSCALE: i64 = 4
43// DITHER THRESHOLD -- CALIBRATED FROM A POPULATION, not from the two examples that inspired the feature.
44// `nx_dedither --census` over 78 real archive assets (JPEG photos, GIF logos, line art, and one known
45// heavily-dithered 1996 photograph) produced: bulk 212-405, then 457, then 549. The known-dithered photo
46// IS the corpus maximum, and the gap between 405 and 457 is the only real gap in the distribution.
47// 450 sits in that gap. This is an EMPIRICAL boundary for this corpus, not a physical constant --
48// it is quoted with the census that produced it precisely so a future seat can re-derive or move it.
49// CONFIRMATION LOOP (unplanned, and the strongest evidence here): running the filter on that photo drops
50// its altrate 549 -> 388, back into the bulk. The feature detects the property, the filter removes it,
51// and the feature then agrees it is gone -- measured on the same asset, both directions.
52// Erring permissive is CHEAP and deliberate: the sigma filter is measurably INERT on non-dithered art
53// (-22 permille on crisp line art), so a false positive costs disk, while a false negative leaves the
54// fuzz the operator actually complained about.
55const DD_DITHER_MIN: i64 = 450
56const DD_MAXTHR: i64 = 255
57
58func dp(s: *u8) -> i64 { var n: i64=0; while s[n]!=(0 as u8){n=n+1} sys_write(1,s,n); return 0 }
59func de(s: *u8) -> i64 { var n: i64=0; while s[n]!=(0 as u8){n=n+1} sys_write(2,s,n); return 0 }
60func dnum(v: i64) -> i64 {
  var m: i64 = v
  if m < 0 { dp("-" as *u8); m = 0 - m }
  let t: *u8 = sys_mmap(32)
  var k: i64 = 0
  if m == 0 { t[0] = 48 as u8; k = 1 }
  while m > 0 { t[k] = (48 + (m % 10)) as u8; m = m / 10; k = k + 1 }
  let b: *u8 = sys_mmap(32)
  var i: i64 = 0
  while i < k { b[i] = t[k-1-i]; i = i + 1 }
  sys_write(1, b, k)
  return 0
72}
73func dd_atoi(s: *u8) -> i64 {
  var v: i64 = 0
  var i: i64 = 0
  while s[i] != (0 as u8) {
      let c: i64 = s[i] as i64
      if c < 48 { return 0 - 1 }
      if c > 57 { return 0 - 1 }
      v = v * 10 + (c - 48)
      i = i + 1
  }
  if i == 0 { return 0 - 1 }
  return v
85}
86
87// MEAN ABSOLUTE LOCAL DEVIATION vs a 3x3 mean, x1000. Border pixels excluded (no clamped mean to bias it).
88// This is the dither ruler: speckle scores high, a smooth gradient scores near zero, and a hard edge also
89// scores high -- which is WHY the selftest cannot rely on this number alone.
90func dd_mald(rgb: *u8, w: i64, h: i64) -> i64 {
  if w < 3 { return 0 }
  if h < 3 { return 0 }
  var acc: i64 = 0
  var cnt: i64 = 0
  var y: i64 = 1
  while y < h - 1 {
      var x: i64 = 1
      while x < w - 1 {
          var c: i64 = 0
          while c < 3 {
              var sum: i64 = 0
              var yy: i64 = y - 1
              while yy <= y + 1 {
                  var xx: i64 = x - 1
                  while xx <= x + 1 {
                      sum = sum + (rgb[(yy*w + xx)*3 + c] as i64)
                      xx = xx + 1
                  }
                  yy = yy + 1
              }
              var d: i64 = (rgb[(y*w + x)*3 + c] as i64) - (sum / 9)
              if d < 0 { d = 0 - d }
              acc = acc + d
              cnt = cnt + 1
              c = c + 1
          }
          x = x + 1
      }
      y = y + 1
  }
  if cnt == 0 { return 0 }
  return (acc * 1000) / cnt
123}
124
125// LOCAL MEAN of the 3x3 window at (x,y) for channel c. Callers must keep 1 <= x < w-1, 1 <= y < h-1.
126func dd_localmean(rgb: *u8, w: i64, x: i64, y: i64, c: i64) -> i64 {
  var sum: i64 = 0
  var yy: i64 = y - 1
  while yy <= y + 1 {
      var xx: i64 = x - 1
      while xx <= x + 1 {
          sum = sum + (rgb[(yy*w + xx)*3 + c] as i64)
          xx = xx + 1
      }
      yy = yy + 1
  }
  return sum / 9
138}
139
140// MEAN ABSOLUTE GRADIENT OF THE LOCAL-MEAN FIELD, x1000 -- the SECOND ruler, and the one that makes the
141// first one usable. MALD alone cannot identify dither: it reads high for palette speckle AND for genuine
142// text strokes (MEASURED -- the photo scored 6863 and a crisp logo scored 5062, and they need OPPOSITE
143// remedies). The discriminator is what the high frequency is sitting ON:
144//   dither  = high-frequency noise over a SMOOTH underlying mean  -> MALD high, MEANGRAD low
145//   edges   = high frequency BECAUSE the underlying mean moves    -> MALD high, MEANGRAD high
146// So the ratio separates them where either number alone cannot.
147// *A SINGLE STATISTIC THAT TWO OPPOSITE PHENOMENA BOTH MAXIMISE IS NOT A CLASSIFIER, IT IS A COINCIDENCE
148// DETECTOR -- it took a second, independent axis to tell them apart.
149func dd_meangrad(rgb: *u8, w: i64, h: i64) -> i64 {
  if w < 4 { return 0 }
  if h < 4 { return 0 }
  var acc: i64 = 0
  var cnt: i64 = 0
  var y: i64 = 1
  while y < h - 2 {
      var x: i64 = 1
      while x < w - 2 {
          var c: i64 = 0
          while c < 3 {
              let m0: i64 = dd_localmean(rgb, w, x, y, c)
              var dx: i64 = dd_localmean(rgb, w, x+1, y, c) - m0
              if dx < 0 { dx = 0 - dx }
              var dy: i64 = dd_localmean(rgb, w, x, y+1, c) - m0
              if dy < 0 { dy = 0 - dy }
              acc = acc + dx + dy
              cnt = cnt + 1
              c = c + 1
          }
          x = x + 1
      }
      y = y + 1
  }
  if cnt == 0 { return 0 }
  return (acc * 1000) / cnt
175}
176
177// SIGN-ALTERNATION RATE, permille -- THE discriminator, after two weaker ones were measured and rejected.
178// MALD alone failed: it reads high for dither AND for text strokes (6863 photo vs 5062 logo).
179// MALD/meangrad failed too: only a 1.27x margin, and the photo's mean-gradient came out HIGHER than the
180// logo's because a photograph has real structure everywhere. Both were plausible and both were wrong.
181// *A FEATURE THAT MERELY CORRELATES WITH THE TARGET LOSES TO ONE DERIVED FROM ITS MECHANISM.
182// Dither is not just high-frequency -- it has a specific PHASE. Two palette entries approximate an
183// in-between value by alternating ABOVE and BELOW it on adjacent pixels, so the deviation-from-local-mean
184// FLIPS SIGN nearly every pixel (-> ~1000). Natural photographic texture has no phase discipline (~500 =
185// chance). A hard edge does not alternate at all. That is a property of how dithering WORKS, not a
186// statistic that happens to co-vary with it.
187// Flat regions are EXCLUDED (|deviation| < 2): they have no phase to measure, and counting their rounding
188// noise would drag every image toward chance and destroy the very separation this is for.
189func dd_altrate(rgb: *u8, w: i64, h: i64) -> i64 {
  if w < 5 { return 0 }
  if h < 5 { return 0 }
  var flips: i64 = 0
  var pairs: i64 = 0
  var y: i64 = 1
  while y < h - 1 {
      var x: i64 = 1
      while x < w - 2 {
          var c: i64 = 0
          while c < 3 {
              let d0: i64 = (rgb[(y*w+x)*3+c] as i64) - dd_localmean(rgb, w, x, y, c)
              let d1: i64 = (rgb[(y*w+x+1)*3+c] as i64) - dd_localmean(rgb, w, x+1, y, c)
              var m0: i64 = d0
              if m0 < 0 { m0 = 0 - m0 }
              var m1: i64 = d1
              if m1 < 0 { m1 = 0 - m1 }
              var ok: i64 = 1
              if m0 < 2 { ok = 0 }
              if m1 < 2 { ok = 0 }
              if ok == 1 {
                  pairs = pairs + 1
                  var flip: i64 = 0
                  if d0 > 0 { if d1 < 0 { flip = 1 } }
                  if d0 < 0 { if d1 > 0 { flip = 1 } }
                  flips = flips + flip
              }
              c = c + 1
          }
          x = x + 1
      }
      y = y + 1
  }
  if pairs == 0 { return 0 }
  return (flips * 1000) / pairs
224}
225
226// SIGMA FILTER. Window bounds are clamped BEFORE the inner loops so the hot path carries no nested
227// bounds tests -- flat ifs on purpose (a 4-deep nested if is a known nx_cc landmine).
228func dd_sigma(src: *u8, dst: *u8, w: i64, h: i64, r: i64, thr: i64) -> i64 {
  var y: i64 = 0
  while y < h {
      var x: i64 = 0
      while x < w {
          let po: i64 = (y*w + x)*3
          let pr: i64 = src[po] as i64
          let pg: i64 = src[po+1] as i64
          let pb: i64 = src[po+2] as i64
          var y0: i64 = y - r
          if y0 < 0 { y0 = 0 }
          var y1: i64 = y + r
          if y1 > h - 1 { y1 = h - 1 }
          var x0: i64 = x - r
          if x0 < 0 { x0 = 0 }
          var x1: i64 = x + r
          if x1 > w - 1 { x1 = w - 1 }
          var sr: i64 = 0
          var sg: i64 = 0
          var sb: i64 = 0
          var n: i64 = 0
          var yy: i64 = y0
          while yy <= y1 {
              var xx: i64 = x0
              while xx <= x1 {
                  let qo: i64 = (yy*w + xx)*3
                  let qr: i64 = src[qo] as i64
                  let qg: i64 = src[qo+1] as i64
                  let qb: i64 = src[qo+2] as i64
                  var da: i64 = qr - pr
                  if da < 0 { da = 0 - da }
                  var db: i64 = qg - pg
                  if db < 0 { db = 0 - db }
                  var dc: i64 = qb - pb
                  if dc < 0 { dc = 0 - dc }
                  // THRESHOLD IS THE PER-CHANNEL MEAN, NOT THE 3-CHANNEL SUM. The sum form shipped first
                  // and T2 caught it immediately: a grey dither of 120 vs 136 is 16 PER CHANNEL but 48
                  // SUMMED, so a threshold of 40 excluded the very speckle the filter exists to average --
                  // the organ ran, reported success, and changed nothing. Comparing against thr*3 keeps the
                  // arithmetic exact (no divide, no rounding) while letting the operator think in 0-255
                  // levels, which is the only unit a threshold on 8-bit colour can honestly be quoted in.
                  if da + db + dc <= thr * 3 { sr = sr + qr; sg = sg + qg; sb = sb + qb; n = n + 1 }
                  xx = xx + 1
              }
              yy = yy + 1
          }
          if n == 0 { sr = pr; sg = pg; sb = pb; n = 1 }
          dst[po] = (sr/n) as u8
          dst[po+1] = (sg/n) as u8
          dst[po+2] = (sb/n) as u8
          x = x + 1
      }
      y = y + 1
  }
  return 0
283}
284
285// mean absolute difference between column xa and column xb (edge-contrast probe)
286func dd_coldiff(rgb: *u8, w: i64, h: i64, xa: i64, xb: i64) -> i64 {
  var acc: i64 = 0
  var cnt: i64 = 0
  var y: i64 = 0
  while y < h {
      var c: i64 = 0
      while c < 3 {
          var d: i64 = (rgb[(y*w + xa)*3 + c] as i64) - (rgb[(y*w + xb)*3 + c] as i64)
          if d < 0 { d = 0 - d }
          acc = acc + d
          cnt = cnt + 1
          c = c + 1
      }
      y = y + 1
  }
  if cnt == 0 { return 0 }
  return acc / cnt
303}
304
305func dd_kat() -> i64 {
  let w: i64 = 64
  let h: i64 = 64
  let a: *u8 = sys_mmap(w*h*3 + 16)
  let b: *u8 = sys_mmap(w*h*3 + 16)
  var pass: i64 = 0
  var total: i64 = 0
312
  // ---- fixture 1: a DITHERED flat field. Two palette entries (120 and 136) alternating on a
  // checkerboard -- the exact structure a 1996 encoder produces for a smooth mid-grey backdrop.
  var y: i64 = 0
  while y < h {
      var x: i64 = 0
      while x < w {
          var v: i64 = 120
          if (x + y) % 2 == 0 { v = 136 }
          let o: i64 = (y*w + x)*3
          a[o] = v as u8; a[o+1] = v as u8; a[o+2] = v as u8
          x = x + 1
      }
      y = y + 1
  }
  let m0: i64 = dd_mald(a, w, h)
  dd_sigma(a, b, w, h, 2, 40)
  let m1: i64 = dd_mald(b, w, h)
  total = total + 1
  if m0 > 3000 { pass = pass + 1; dp("T1 GREEN dither fixture registers on the ruler (mald=" as *u8); dnum(m0); dp(")\n" as *u8) } else { dp("T1 RED fixture did not register (mald=" as *u8); dnum(m0); dp(")\n" as *u8) }
  total = total + 1
  if m1 * 2 < m0 { pass = pass + 1; dp("T2 GREEN dither removed >50pct (" as *u8); dnum(m0); dp(" -> " as *u8); dnum(m1); dp(")\n" as *u8) } else { dp("T2 RED dither NOT removed (" as *u8); dnum(m0); dp(" -> " as *u8); dnum(m1); dp(")\n" as *u8) }
334
  // ---- fixture 2: ANTI-VACUITY. A hard vertical edge, black|white at x=32. A box blur would smear
  // this and still score well on T2, so T3 is the tooth that a mere blur CANNOT pass.
  var y2: i64 = 0
  while y2 < h {
      var x2: i64 = 0
      while x2 < w {
          var v2: i64 = 0
          if x2 >= 32 { v2 = 255 }
          let o2: i64 = (y2*w + x2)*3
          a[o2] = v2 as u8; a[o2+1] = v2 as u8; a[o2+2] = v2 as u8
          x2 = x2 + 1
      }
      y2 = y2 + 1
  }
  let e0: i64 = dd_coldiff(a, w, h, 31, 32)
  dd_sigma(a, b, w, h, 2, 40)
  let e1: i64 = dd_coldiff(b, w, h, 31, 32)
  total = total + 1
  if e1 * 10 >= e0 * 9 { pass = pass + 1; dp("T3 GREEN edge PRESERVED (" as *u8); dnum(e0); dp(" -> " as *u8); dnum(e1); dp(") -- a box blur cannot pass this\n" as *u8) } else { dp("T3 RED edge was smeared (" as *u8); dnum(e0); dp(" -> " as *u8); dnum(e1); dp(")\n" as *u8) }
354
  // ---- fixture 3: ANTI-VACUITY. An ALREADY-CLEAN flat field must come out unchanged: a filter that
  // invents texture on smooth input would be worse than the disease.
  var y3: i64 = 0
  while y3 < h {
      var x3: i64 = 0
      while x3 < w {
          let o3: i64 = (y3*w + x3)*3
          a[o3] = 128 as u8; a[o3+1] = 128 as u8; a[o3+2] = 128 as u8
          x3 = x3 + 1
      }
      y3 = y3 + 1
  }
  dd_sigma(a, b, w, h, 2, 40)
  var flat: i64 = 1
  var i3: i64 = 0
  while i3 < w*h*3 { if b[i3] != (128 as u8) { flat = 0; i3 = w*h*3 } else { i3 = i3 + 1 } }
  total = total + 1
  if flat == 1 { pass = pass + 1; dp("T4 GREEN clean input unchanged (no invented texture)\n" as *u8) } else { dp("T4 RED filter altered an already-clean field\n" as *u8) }
373
  // ---- T5/T6: the PHASE discriminator, with a control that isolates phase and NOTHING else.
  // Both fixtures use the SAME two palette entries (120/136) and therefore the same amplitude and
  // nearly the same MALD. They differ ONLY in phase: T5 alternates every pixel (real dither), T6 uses
  // 2x2 blocks (same colours, same contrast, no per-pixel alternation). If altrate could be fooled by
  // amplitude or palette size it would score these two alike -- so T6 is what makes T5 mean something.
  var y5: i64 = 0
  while y5 < h {
      var x5: i64 = 0
      while x5 < w {
          var v5: i64 = 120
          if (x5 + y5) % 2 == 0 { v5 = 136 }
          let o5: i64 = (y5*w + x5)*3
          a[o5] = v5 as u8; a[o5+1] = v5 as u8; a[o5+2] = v5 as u8
          var v6: i64 = 120
          if ((x5/2) + (y5/2)) % 2 == 0 { v6 = 136 }
          let o6: i64 = (y5*w + x5)*3
          b[o6] = v6 as u8; b[o6+1] = v6 as u8; b[o6+2] = v6 as u8
          x5 = x5 + 1
      }
      y5 = y5 + 1
  }
  let ar_dith: i64 = dd_altrate(a, w, h)
  let ar_blok: i64 = dd_altrate(b, w, h)
  total = total + 1
  if ar_dith >= 900 { pass = pass + 1; dp("T5 GREEN per-pixel dither has dither PHASE (altrate=" as *u8); dnum(ar_dith); dp("/1000)\n" as *u8) } else { dp("T5 RED dither phase not detected (altrate=" as *u8); dnum(ar_dith); dp(")\n" as *u8) }
  total = total + 1
  if ar_blok + 200 < ar_dith { pass = pass + 1; dp("T6 GREEN 2x2 blocks SAME colours REJECTED on phase (" as *u8); dnum(ar_blok); dp(" vs " as *u8); dnum(ar_dith); dp(") -- amplitude alone cannot pass\n" as *u8) } else { dp("T6 RED phase control not separated (" as *u8); dnum(ar_blok); dp(" vs " as *u8); dnum(ar_dith); dp(")\n" as *u8) }
401
  // ---- T7: SELECTIVITY WITH BOTH SIGNALS PRESENT AT ONCE.
  // T2 proves noise falls on a pure-dither fixture; T3 proves an edge survives on a pure-edge fixture.
  // Neither proves the filter can tell them apart WHEN THEY OVERLAP, which is the only case a real
  // photograph ever presents. This fixture is a hard edge (60|200) with per-pixel dither laid over
  // BOTH sides, and it demands the two outcomes SIMULTANEOUSLY: the speckle goes and the edge stays.
  // A filter that passed T2 and T3 separately can still fail here by smearing the edge wherever noise
  // sits on it -- and an image is nothing but edges with noise sitting on them.
  var y7: i64 = 0
  while y7 < h {
      var x7: i64 = 0
      while x7 < w {
          var base: i64 = 60
          if x7 >= 32 { base = 200 }
          var v7: i64 = base - 8
          if (x7 + y7) % 2 == 0 { v7 = base + 8 }
          let o7: i64 = (y7*w + x7)*3
          a[o7] = v7 as u8; a[o7+1] = v7 as u8; a[o7+2] = v7 as u8
          x7 = x7 + 1
      }
      y7 = y7 + 1
  }
  let n7a: i64 = dd_mald(a, w, h)
  let e7a: i64 = dd_coldiff(a, w, h, 20, 44)
  dd_sigma(a, b, w, h, 2, 40)
  let n7b: i64 = dd_mald(b, w, h)
  let e7b: i64 = dd_coldiff(b, w, h, 20, 44)
  total = total + 1
  var sel: i64 = 0
  if n7b * 2 < n7a { if e7b * 10 >= e7a * 9 { sel = 1 } }
  if sel == 1 { pass = pass + 1; dp("T7 GREEN SELECTIVE with both present: noise " as *u8); dnum(n7a); dp("->" as *u8); dnum(n7b); dp(" while edge " as *u8); dnum(e7a); dp("->" as *u8); dnum(e7b); dp(" held\n" as *u8) } else { dp("T7 RED not selective: noise " as *u8); dnum(n7a); dp("->" as *u8); dnum(n7b); dp(" edge " as *u8); dnum(e7a); dp("->" as *u8); dnum(e7b); dp("\n" as *u8) }
432
  dp("nx_dedither KAT " as *u8); dnum(pass); dp("/" as *u8); dnum(total); dp("\n" as *u8)
  if pass == total { return 0 }
  return 1
436}
437
438// CLASSIFY: report both rulers + their ratio for one image. NO VERDICT IS PRINTED YET, ON PURPOSE.
439// A threshold separating DITHERED from CLEAN has not been MEASURED, and a constant invented at authoring
440// time would be indistinguishable in the output from one derived from evidence -- which is precisely the
441// failure this organ already committed once (a threshold whose unit nobody had stated).
442// *AN UNCALIBRATED CLASSIFIER MUST REPORT NUMBERS, NEVER VERDICTS: a verdict claims a decision boundary
443// exists; numbers only claim what was observed. Calibrate against known assets, THEN earn the verdict.
444func dd_classify(path: *u8) -> i64 {
  let wh: *i64 = sys_mmap(32) as *i64
  let rgb: *u8 = nx_img_to_rgb(path, wh)
  if rgb == (0 as *u8) { de("nx_dedither: UNDECODABLE\n" as *u8); return 2 }
  let w: i64 = wh[0]
  let h: i64 = wh[1]
  if w < 4 { de("nx_dedither: image too small to classify\n" as *u8); return 2 }
  if h < 4 { de("nx_dedither: image too small to classify\n" as *u8); return 2 }
  let mald: i64 = dd_mald(rgb, w, h)
  let mg: i64 = dd_meangrad(rgb, w, h)
  let ratio: i64 = (mald * 1000) / (mg + 1)
  dp("{\"organ\":\"nx_dedither\",\"mode\":\"classify\",\"w\":" as *u8); dnum(w)
  dp(",\"h\":" as *u8); dnum(h)
  dp(",\"mald_x1000\":" as *u8); dnum(mald)
  dp(",\"meangrad_x1000\":" as *u8); dnum(mg)
  dp(",\"dither_ratio_x1000\":" as *u8); dnum(ratio)
  let ar: i64 = dd_altrate(rgb, w, h)
  let pal: i64 = dd_is_palette(path)
  dp(",\"altrate_permil\":" as *u8); dnum(ar)
  dp(",\"palette_format\":" as *u8); dnum(pal)
  dp(",\"threshold\":" as *u8); dnum(DD_DITHER_MIN)
  // The verdict is now EARNED: the boundary came from an 78-asset census, and it is printed alongside
  // the number and the threshold so a reader can always re-judge it rather than take the word for it.
  var vd: i64 = 1
  if ar < DD_DITHER_MIN { vd = 0 }
  if pal == 0 { vd = 0 }
  if vd == 1 { dp(",\"verdict\":\"DITHERED\"}\n" as *u8) }
  if vd == 0 { if pal == 0 { dp(",\"verdict\":\"NON-PALETTE\"}\n" as *u8) } else { dp(",\"verdict\":\"CLEAN\"}\n" as *u8) } }
  return 0
473}
474
475// ---- CENSUS ----------------------------------------------------------------------------------
476// WHY THIS EXISTS: two real samples is not a calibration. Classifying the archive one file per
477// invocation cannot produce a DISTRIBUTION, and without a distribution any threshold is an invented
478// constant wearing a measurement's clothes -- the exact failure this organ already committed once.
479// *A CLASSIFIER IS CALIBRATED BY A POPULATION, NOT BY THE TWO EXAMPLES THAT INSPIRED IT.
480// BOUNDED BY CONSTRUCTION (the nx_gate_build_sweep idiom): maxn is REQUIRED and must be > 0, so a
481// census can never run away over a corpus of unknown size.
482// Undecodable entries print SKIP with a reason rather than vanishing -- a census that silently drops
483// what it could not read reports a cleaner corpus than exists.
484const DD_DIRBUF: i64 = 262144
485const DD_RECLEN_OFF: i64 = 16
486const DD_NAME_OFF: i64 = 19
487
488func dd_cat(dst: *u8, off: i64, src: *u8) -> i64 { var o: i64=off; var j: i64=0; while src[j]!=(0 as u8) { dst[o]=src[j]; o=o+1; j=j+1 } return o }
489
490func dd_census(dir: *u8, maxn: i64) -> i64 {
  if maxn <= 0 { de("nx_dedither: --census REFUSES an unbounded run; pass maxfiles > 0\n" as *u8); return 3 }
  let fd: i64 = sys_openat_rd(dir)
  if fd < 0 { de("nx_dedither: cannot open directory\n" as *u8); return 2 }
  let db: *u8 = sys_mmap(DD_DIRBUF)
  dp("# altrate mald meangrad w h name\n" as *u8)
  let path: *u8 = sys_mmap(1024)
  let wh: *i64 = sys_mmap(32) as *i64
  var shown: i64 = 0
  // Same getdents64 batching contract as dd_sweep -- see the note there. Fixed in BOTH, because a
  // census and a sweep that disagree about how much of a directory exists is worse than either bug alone.
  var batches: i64 = 0
  var go: i64 = 1
  while go == 1 {
  let n: i64 = sys_getdents64(fd, db, DD_DIRBUF)
  if n <= 0 { go = 0 } else {
  batches = batches + 1
  var p: i64 = 0
  while p < n {
      let reclen: i64 = (db[p+DD_RECLEN_OFF] as i64) | ((db[p+DD_RECLEN_OFF+1] as i64) << 8)
      if reclen <= 0 { p = n } else {
          let nm: i64 = p + DD_NAME_OFF
          var skip: i64 = 0
          if (db[nm] as i64) == 46 { skip = 1 }
          if shown >= maxn { skip = 1 }
          if skip == 0 {
              var o: i64 = dd_cat(path, 0, dir)
              path[o] = 47 as u8; o = o + 1
              var w2: i64 = nm
              while db[w2] != (0 as u8) { path[o]=db[w2]; o=o+1; w2=w2+1 }
              path[o] = 0 as u8
              let rgb: *u8 = nx_img_to_rgb(path, wh)
              if rgb == (0 as *u8) {
                  dp("SKIP undecodable " as *u8)
                  var w3: i64 = nm
                  while db[w3] != (0 as u8) { sys_write(1, ((db as i64)+w3) as *u8, 1); w3=w3+1 }
                  dp("\n" as *u8)
              } else {
                  let iw: i64 = wh[0]
                  let ih: i64 = wh[1]
                  dnum(dd_altrate(rgb, iw, ih)); dp(" " as *u8)
                  dnum(dd_mald(rgb, iw, ih)); dp(" " as *u8)
                  dnum(dd_meangrad(rgb, iw, ih)); dp(" " as *u8)
                  dnum(iw); dp(" " as *u8); dnum(ih); dp(" " as *u8)
                  var w4: i64 = nm
                  while db[w4] != (0 as u8) { sys_write(1, ((db as i64)+w4) as *u8, 1); w4=w4+1 }
                  dp("\n" as *u8)
              }
              shown = shown + 1
          }
          p = p + reclen
      }
  }
  }
  }
  sys_close(fd)
  if batches == 0 { de("nx_dedither: not a directory (getdents64 refused)\n" as *u8); return 2 }
  dp("# census rows=" as *u8); dnum(shown); dp("\n" as *u8)
  return 0
549}
550
551// ---- FORMAT PRIOR ------------------------------------------------------------------------------
552// MEASURED REFUTATION (2026-08-07): the 450 threshold was calibrated on page3.com (78 assets, bulk
553// topped out at 405, the two true positives BOTH .gif). Run against megastar.co.uk it collapsed --
554// small heavily-compressed JPEGs score 447/468/476/483/503/509/511 routinely. A threshold that
555// separates one corpus and misfires on the next is not a classifier, it is a fitted constant.
556// *A BOUNDARY CALIBRATED ON ONE POPULATION MUST BE RE-TESTED ON A SECOND BEFORE IT IS BELIEVED --
557// the second corpus is where a fit stops being evidence and starts being a coincidence.
558// The fix is a PRIOR FROM THE MECHANISM, not a retuned number: palette dithering is something an
559// INDEXED format does -- approximating an unavailable colour by alternating two palette entries.
560// JPEG has no palette at all (DCT coefficients), so whatever raises its alternation score is ringing
561// and blocking, which a sigma filter is the wrong remedy for anyway. Gating on the container removes
562// every observed false positive by construction and cannot be tuned away by a future corpus.
563// Sniffed from MAGIC BYTES, never the extension -- .gif files that are secretly JPEG are exactly the
564// kind of thing an archive is full of, and the extension is a claim while the header is evidence.
565func dd_is_palette(path: *u8) -> i64 {
  let fd: i64 = sys_openat_rd(path)
  if fd < 0 { return 0 }
  let b: *u8 = sys_mmap(16)
  let n: i64 = sys_read(fd, b, 8)
  sys_close(fd)
  if n < 4 { return 0 }
  // GIF87a / GIF89a -- the dominant 1990s palette container
  var g: i64 = 1
  if (b[0] as i64) != 71 { g = 0 }
  if (b[1] as i64) != 73 { g = 0 }
  if (b[2] as i64) != 70 { g = 0 }
  if g == 1 { return 1 }
  // BMP ("BM") -- indexed at 1/4/8bpp; truecolour BMPs simply will not score as dithered
  var m: i64 = 1
  if (b[0] as i64) != 66 { m = 0 }
  if (b[1] as i64) != 77 { m = 0 }
  if m == 1 { return 1 }
  // PCX (0x0A) -- era palette format
  if (b[0] as i64) == 10 { return 1 }
  return 0
586}
587
588// does name end with sfx?
589func dd_endswith(nm: *u8, sfx: *u8) -> i64 {
  var ln: i64 = 0
  while nm[ln] != (0 as u8) { ln = ln + 1 }
  var ls: i64 = 0
  while sfx[ls] != (0 as u8) { ls = ls + 1 }
  if ln < ls { return 0 }
  var i: i64 = 0
  while i < ls {
      if nm[ln-ls+i] != sfx[i] { return 0 }
      i = i + 1
  }
  return 1
601}
602
603// ---- SWEEP -------------------------------------------------------------------------------------
604// Enhance ONLY what the census says needs it. Blanket enhancement was measured to be waste: the sigma
605// filter moves crisp line art by -22 permille, so re-encoding 78 logos to "fix" them buys nothing and
606// costs disk. The classifier decides per asset, and the DECISION IS PRINTED for every file either way --
607// a sweep that logs only what it changed cannot be audited for what it silently skipped.
608// IDEMPOTENT (rule 10): outputs are skipped by suffix, so a second run over the same directory is a
609// no-op rather than a cascade of .enh.enh.png. THE ORIGINAL IS NEVER WRITTEN.
610func dd_sweep(dir: *u8, maxn: i64, r: i64, thr: i64, scale: i64) -> i64 {
  if maxn <= 0 { de("nx_dedither: --sweep REFUSES an unbounded run; pass maxfiles > 0\n" as *u8); return 3 }
  let fd: i64 = sys_openat_rd(dir)
  if fd < 0 { de("nx_dedither: cannot open directory\n" as *u8); return 2 }
  let db: *u8 = sys_mmap(DD_DIRBUF)
  let inp: *u8 = sys_mmap(1024)
  let outp: *u8 = sys_mmap(1024)
  let wh: *i64 = sys_mmap(32) as *i64
  var seen: i64 = 0
  var enh: i64 = 0
  var clean: i64 = 0
  var nonpal: i64 = 0
  var bad: i64 = 0
  // *ONE getdents64 CALL IS NOT A DIRECTORY LISTING. The kernel returns as many entries as fit the
  // buffer and expects to be called again until it answers 0. A single call happened to cover both
  // archive dirs (69 and 77 entries) ONLY because they are small -- on a corpus large enough to matter
  // this would have processed a PREFIX and then printed a confident total for it. That is precisely the
  // failure this organ warns about two functions up: a census that drops what it did not read reports a
  // cleaner corpus than exists. It passed its first two real runs by luck, which is the worst way to
  // pass. Loop until the kernel says stop, and keep the fd open across calls.
  var batches: i64 = 0
  var go: i64 = 1
  while go == 1 {
  let n: i64 = sys_getdents64(fd, db, DD_DIRBUF)
  if n <= 0 { go = 0 } else {
  batches = batches + 1
  var p: i64 = 0
  while p < n {
      let reclen: i64 = (db[p+DD_RECLEN_OFF] as i64) | ((db[p+DD_RECLEN_OFF+1] as i64) << 8)
      if reclen <= 0 { p = n } else {
          let nmo: i64 = p + DD_NAME_OFF
          let nm: *u8 = ((db as i64) + nmo) as *u8
          var skip: i64 = 0
          if (nm[0] as i64) == 46 { skip = 1 }
          if dd_endswith(nm, ".enh.png" as *u8) == 1 { skip = 1 }
          if seen >= maxn { skip = 1 }
          if skip == 0 {
              seen = seen + 1
              var io: i64 = dd_cat(inp, 0, dir)
              inp[io] = 47 as u8; io = io + 1
              io = dd_cat(inp, io, nm)
              inp[io] = 0 as u8
              let rgb: *u8 = nx_img_to_rgb(inp, wh)
              if rgb == (0 as *u8) {
                  bad = bad + 1
                  dp("SKIP-UNDECODABLE " as *u8); dp(nm); dp("\n" as *u8)
              } else {
                  let iw: i64 = wh[0]
                  let ih: i64 = wh[1]
                  let ar: i64 = dd_altrate(rgb, iw, ih)
                  let pal: i64 = dd_is_palette(inp)
                  var doit: i64 = 1
                  if ar < DD_DITHER_MIN { doit = 0 }
                  if pal == 0 { doit = 0 }
                  if doit == 0 {
                      // COUNT THE TWO CAUSES SEPARATELY. The per-line log already names which reason
                      // applied, but the SUMMARY collapsed both into "skipped_clean" -- so a run that
                      // rejected 60 JPEGs on format read as though it had inspected 60 clean assets and
                      // found them fine. A total that merges two causes is a total that cannot be acted on.
                      if pal == 0 { nonpal = nonpal + 1 } else { clean = clean + 1 }
                      // NAME WHICH REASON. "Skipped" without a cause is unauditable, and these two have
                      // opposite remedies: a low score means the asset is genuinely fine, a non-palette
                      // container means this organ is simply the wrong tool for whatever it does have.
                      if pal == 0 { dp("SKIP-NONPALETTE altrate=" as *u8) } else { dp("SKIP-CLEAN altrate=" as *u8) }
                      dnum(ar); dp(" " as *u8); dp(nm); dp("\n" as *u8)
                  } else {
                      let before: i64 = dd_mald(rgb, iw, ih)
                      let dst: *u8 = sys_mmap(iw*ih*3 + 16)
                      dd_sigma(rgb, dst, iw, ih, r, thr)
                      let after: i64 = dd_mald(dst, iw, ih)
                      var ow: i64 = iw
                      var oh: i64 = ih
                      var fin: *u8 = dst
                      if scale > 1 {
                          ow = iw * scale
                          oh = ih * scale
                          fin = sys_mmap(ow*oh*3 + 16)
                          nx_img_scale_bicubic(dst, iw, ih, 3, fin, ow, oh)
                      }
                      var oo: i64 = dd_cat(outp, 0, dir)
                      outp[oo] = 47 as u8; oo = oo + 1
                      oo = dd_cat(outp, oo, nm)
                      oo = dd_cat(outp, oo, ".enh.png" as *u8)
                      outp[oo] = 0 as u8
                      if nx_png_write_rgb(outp, fin, ow, oh) != 0 {
                          bad = bad + 1
                          dp("WRITE-FAILED " as *u8); dp(nm); dp("\n" as *u8)
                      } else {
                          enh = enh + 1
                          dp("ENHANCED altrate=" as *u8); dnum(ar)
                          dp(" mald " as *u8); dnum(before); dp("->" as *u8); dnum(after)
                          dp(" out " as *u8); dnum(ow); dp("x" as *u8); dnum(oh)
                          dp(" " as *u8); dp(nm); dp(".enh.png\n" as *u8)
                      }
                  }
              }
          }
          p = p + reclen
      }
  }
  }
  }
  sys_close(fd)
  if batches == 0 { de("nx_dedither: not a directory (getdents64 refused)\n" as *u8); return 2 }
  dp("# sweep seen=" as *u8); dnum(seen)
  dp(" enhanced=" as *u8); dnum(enh)
  dp(" skipped_clean=" as *u8); dnum(clean)
  dp(" skipped_nonpalette=" as *u8); dnum(nonpal)
  dp(" undecodable=" as *u8); dnum(bad)
  dp(" threshold=" as *u8); dnum(DD_DITHER_MIN)
  dp("\n" as *u8)
  return 0
722}
723
724func main(argc: i64, argv: *i64) -> i64 {
  if argc < 2 { de("usage: nx_dedither <in-image> <out.png> [radius=2] [threshold=40] | --kat\n" as *u8); sys_exit(3); return 3 }
  let a1: *u8 = argv[1] as *u8
  if a1[0] == (45 as u8) {
      if a1[2] == (107 as u8) { let rc: i64 = dd_kat(); sys_exit(rc); return rc }
      if a1[2] == (99 as u8) {
          if argc < 3 { de("usage: nx_dedither --classify <image> | --census <dir> <maxfiles>\n" as *u8); sys_exit(3); return 3 }
          // --classify and --census both begin "--c"; the 4th char disambiguates ('l' vs 'e').
          if a1[3] == (101 as u8) {
              var mx: i64 = 0
              if argc >= 4 { mx = dd_atoi(argv[3] as *u8) }
              let rc3: i64 = dd_census(argv[2] as *u8, mx)
              sys_exit(rc3); return rc3
          }
          let rc2: i64 = dd_classify(argv[2] as *u8)
          sys_exit(rc2); return rc2
      }
      if a1[2] == (115 as u8) {
          if argc < 4 { de("usage: nx_dedither --sweep <dir> <maxfiles> [radius=2] [threshold=40] [scale=1]\n" as *u8); sys_exit(3); return 3 }
          var smx: i64 = dd_atoi(argv[3] as *u8)
          var sr: i64 = 2
          var sthr: i64 = 40
          var ssc: i64 = 1
          if argc >= 5 { sr = dd_atoi(argv[4] as *u8) }
          if argc >= 6 { sthr = dd_atoi(argv[5] as *u8) }
          if argc >= 7 { ssc = dd_atoi(argv[6] as *u8) }
          if sr < 0 { de("nx_dedither: REFUSED bad radius\n" as *u8); sys_exit(3); return 3 }
          if sr > DD_MAXR { de("nx_dedither: REFUSED radius > 8\n" as *u8); sys_exit(3); return 3 }
          if ssc < 1 { de("nx_dedither: REFUSED scale < 1\n" as *u8); sys_exit(3); return 3 }
          if ssc > DD_MAXSCALE { de("nx_dedither: REFUSED scale > 4 (OCR-measured optimum is x2-x3)\n" as *u8); sys_exit(3); return 3 }
          let rc4: i64 = dd_sweep(argv[2] as *u8, smx, sr, sthr, ssc)
          sys_exit(rc4); return rc4
      }
      de("nx_dedither: unknown flag (--kat | --classify <image> | --census <dir> <n> | --sweep <dir> <n>)\n" as *u8); sys_exit(3); return 3
  }
  if argc < 3 { de("usage: nx_dedither <in-image> <out.png> [radius=2] [threshold=40]\n" as *u8); sys_exit(3); return 3 }
  let outp: *u8 = argv[2] as *u8
  var r: i64 = 2
  var thr: i64 = 40
  if argc >= 4 { r = dd_atoi(argv[3] as *u8) }
  if argc >= 5 { thr = dd_atoi(argv[4] as *u8) }
  // REFUSE nonsense rather than clamp silently: a caller who typed a bad radius wants to know.
  if r < 0 { de("nx_dedither: REFUSED bad radius\n" as *u8); sys_exit(3); return 3 }
  if r > DD_MAXR { de("nx_dedither: REFUSED radius > 8\n" as *u8); sys_exit(3); return 3 }
  if thr < 0 { de("nx_dedither: REFUSED bad threshold\n" as *u8); sys_exit(3); return 3 }
  if thr > DD_MAXTHR { de("nx_dedither: REFUSED threshold > 255 (it is a per-channel level, 0-255)\n" as *u8); sys_exit(3); return 3 }
  var scale: i64 = 1
  if argc >= 6 { scale = dd_atoi(argv[5] as *u8) }
  if scale < 1 { de("nx_dedither: REFUSED scale < 1\n" as *u8); sys_exit(3); return 3 }
  // REFUSE past the MEASURED band rather than silently obeying. x4 and x6 were both tested and both
  // read WORSE than x3 on the OCR instrument, so a caller asking for x8 is asking for a degradation
  // this organ has already measured. The ceiling is evidence, not caution.
  if scale > DD_MAXSCALE { de("nx_dedither: REFUSED scale > 4 (OCR-measured optimum is x2-x3; x4+ degrades)\n" as *u8); sys_exit(3); return 3 }
777
  let wh: *i64 = sys_mmap(32) as *i64
  let src: *u8 = nx_img_to_rgb(a1, wh)
  if src == (0 as *u8) { de("nx_dedither: UNDECODABLE (format unsupported or file unreadable)\n" as *u8); sys_exit(2); return 2 }
  let w: i64 = wh[0]
  let h: i64 = wh[1]
  if w <= 0 { de("nx_dedither: bad width\n" as *u8); sys_exit(2); return 2 }
  if h <= 0 { de("nx_dedither: bad height\n" as *u8); sys_exit(2); return 2 }
785
  let before: i64 = dd_mald(src, w, h)
  let dst: *u8 = sys_mmap(w*h*3 + 16)
  dd_sigma(src, dst, w, h, r, thr)
  // MALD is measured on the FILTERED pixels at NATIVE resolution, before any upscale. Measuring it
  // after resampling would score the resampler's own smoothing as if the filter had earned it.
  let after: i64 = dd_mald(dst, w, h)
  // *NOISE REDUCTION ALONE IS NOT A QUALITY MEASURE -- A FILTER THAT DESTROYS THE PICTURE SCORES
  // PERFECTLY ON IT. Reporting one number invites exactly the conclusion the number cannot support.
  // The second axis is the mean-gradient of the local-mean field: it tracks real STRUCTURE (edges,
  // features), which a selective filter must LEAVE ALONE while it removes speckle. Measured on the
  // 1996 photo the two move at very different rates -- noise falls to 38 percent while structure holds
  // at 82 -- and that GAP, not the reduction, is what says the filter is selective rather than a blur.
  // Quoted together so the trade-off is visible at the point of decision instead of inferred later.
  let mg_before: i64 = dd_meangrad(src, w, h)
  let mg_after: i64 = dd_meangrad(dst, w, h)
  var ow: i64 = w
  var oh: i64 = h
  var final: *u8 = dst
  if scale > 1 {
      ow = w * scale
      oh = h * scale
      final = sys_mmap(ow*oh*3 + 16)
      if nx_img_scale_bicubic(dst, w, h, 3, final, ow, oh) != 0 { de("nx_dedither: SCALE FAILED\n" as *u8); sys_exit(2); return 2 }
  }
  if nx_png_write_rgb(outp, final, ow, oh) != 0 { de("nx_dedither: PNG WRITE FAILED\n" as *u8); sys_exit(2); return 2 }
811
  var red: i64 = 0
  if before > 0 { red = ((before - after) * 1000) / before }
  dp("{\"organ\":\"nx_dedither\",\"w\":" as *u8); dnum(w)
  dp(",\"h\":" as *u8); dnum(h)
  dp(",\"radius\":" as *u8); dnum(r)
  dp(",\"threshold\":" as *u8); dnum(thr)
  dp(",\"mald_before_x1000\":" as *u8); dnum(before)
  dp(",\"mald_after_x1000\":" as *u8); dnum(after)
  dp(",\"noise_reduction_permil\":" as *u8); dnum(red)
  var keep: i64 = 1000
  if mg_before > 0 { keep = (mg_after * 1000) / mg_before }
  dp(",\"meangrad_before_x1000\":" as *u8); dnum(mg_before)
  dp(",\"meangrad_after_x1000\":" as *u8); dnum(mg_after)
  dp(",\"structure_retained_permil\":" as *u8); dnum(keep)
  dp(",\"scale\":" as *u8); dnum(scale)
  dp(",\"out_w\":" as *u8); dnum(ow)
  dp(",\"out_h\":" as *u8); dnum(oh)
  dp(",\"original_untouched\":1}\n" as *u8)
  return 0
831}
nx_dedither.nx source

`nx_dedither.nx` source
