From f1837fb8ce3ef4950b4c52fb287f7ee7f71c025d Mon Sep 17 00:00:00 2001
From: Li Fengmin <2080291162@qq.com>
Date: Fri, 31 Jul 2026 19:35:57 +0800
Subject: [PATCH] feat: public histogram API (luma + per-channel RGB)

---
 histogram.mbt      | 32 +++++++++++++++++
 histogram_test.mbt | 86 ++++++++++++++++++++++++++++++++++++++++++++++
 pkg.generated.mbti |  2 ++
 3 files changed, 120 insertions(+)
 create mode 100644 histogram.mbt
 create mode 100644 histogram_test.mbt

diff --git a/histogram.mbt b/histogram.mbt
new file mode 100644
index 0000000..015035c
--- /dev/null
+++ b/histogram.mbt
@@ -0,0 +1,32 @@
+///|
+/// Public histogram API. The luma histogram reuses the same 256-bin
+/// BT.601 integer binning that Otsu and histogram equalization are built
+/// on, so every consumer of the library sees one consistent definition.
+
+///|
+/// 256-bin luma histogram (BT.601 integer weights): `result[v]` counts the
+/// pixels whose luma is exactly `v`.
+pub fn Image::histogram_luma(self : Image) -> FixedArray[Int] {
+  self.luma_histogram()
+}
+
+///|
+/// Per-channel 256-bin histograms, returned as `(red, green, blue)`.
+pub fn Image::histogram_rgb(
+  self : Image,
+) -> (FixedArray[Int], FixedArray[Int], FixedArray[Int]) {
+  let hr = FixedArray::make(256, 0)
+  let hg = FixedArray::make(256, 0)
+  let hb = FixedArray::make(256, 0)
+  let n = self.pixel_count()
+  for p in 0..<n {
+    let base = p * 4
+    let r = self.data[base].to_int()
+    let g = self.data[base + 1].to_int()
+    let b = self.data[base + 2].to_int()
+    hr[r] = hr[r] + 1
+    hg[g] = hg[g] + 1
+    hb[b] = hb[b] + 1
+  }
+  (hr, hg, hb)
+}
diff --git a/histogram_test.mbt b/histogram_test.mbt
new file mode 100644
index 0000000..b6e7356
--- /dev/null
+++ b/histogram_test.mbt
@@ -0,0 +1,86 @@
+///|
+/// Histogram API tests with hand-counted expectations.
+
+///|
+test "histogram bins sum to the pixel count" {
+  let img = @pixelforge.Image::new(7, 5)
+  for y in 0..<5 {
+    for x in 0..<7 {
+      img.set_pixel(
+        x,
+        y,
+        @pixelforge.clamp_byte(x * 36),
+        @pixelforge.clamp_byte(y * 51),
+        @pixelforge.clamp_byte((x + y) * 20),
+        b'\xFF',
+      )
+    }
+  }
+  let luma = img.histogram_luma()
+  let (hr, hg, hb) = img.histogram_rgb()
+  let mut sl = 0
+  let mut sr = 0
+  let mut sg = 0
+  let mut sb = 0
+  for i in 0..<256 {
+    sl = sl + luma[i]
+    sr = sr + hr[i]
+    sg = sg + hg[i]
+    sb = sb + hb[i]
+  }
+  assert_eq(sl, 35)
+  assert_eq(sr, 35)
+  assert_eq(sg, 35)
+  assert_eq(sb, 35)
+}
+
+///|
+test "flat image concentrates every histogram in one bin" {
+  let img = solid(6, 4, 37, 142, 209, 255)
+  let luma = img.histogram_luma()
+  let (hr, hg, hb) = img.histogram_rgb()
+  assert_eq(hr[37], 24)
+  assert_eq(hg[142], 24)
+  assert_eq(hb[209], 24)
+  // Luma of (37,142,209) = (299*37+587*142+114*209)/1000 = 118.
+  let expect_luma = (299 * 37 + 587 * 142 + 114 * 209) / 1000
+  assert_eq(luma[expect_luma], 24)
+  // Every other bin is empty.
+  for i in 0..<256 {
+    if i != 37 {
+      assert_eq(hr[i], 0)
+    }
+    if i != expect_luma {
+      assert_eq(luma[i], 0)
+    }
+  }
+}
+
+///|
+test "hand-counted mixed image lands in the right bins" {
+  // Three pixels: red 10 twice, red 200 once.
+  let img = @pixelforge.Image::new(3, 1)
+  img.set_pixel(0, 0, b'\x0A', b'\x00', b'\x00', b'\xFF')
+  img.set_pixel(1, 0, b'\x0A', b'\x00', b'\x00', b'\xFF')
+  img.set_pixel(2, 0, b'\xC8', b'\x00', b'\x00', b'\xFF')
+  let (hr, hg, _) = img.histogram_rgb()
+  assert_eq(hr[10], 2)
+  assert_eq(hr[200], 1)
+  assert_eq(hg[0], 3)
+}
+
+///|
+test "histogram_luma agrees with the equalization pipeline's binning" {
+  // The public luma histogram must match what Otsu sees: a bimodal image
+  // has exactly two occupied bins at the expected positions.
+  let img = @pixelforge.Image::new(4, 2)
+  for y in 0..<2 {
+    for x in 0..<4 {
+      let v : Byte = if x < 2 { b'\x28' } else { b'\xD2' } // 40 / 210
+      img.set_pixel(x, y, v, v, v, b'\xFF')
+    }
+  }
+  let h = img.histogram_luma()
+  assert_eq(h[40], 4)
+  assert_eq(h[210], 4)
+}
diff --git a/pkg.generated.mbti b/pkg.generated.mbti
index 86a0895..2f63eec 100644
--- a/pkg.generated.mbti
+++ b/pkg.generated.mbti
@@ -105,6 +105,8 @@ pub fn Image::gaussian(Self, Int) -> Self
 pub fn Image::get_pixel(Self, Int, Int) -> (Byte, Byte, Byte, Byte)
 pub fn Image::grayscale(Self) -> Self
 pub fn Image::histogram_equalize(Self) -> Self
+pub fn Image::histogram_luma(Self) -> FixedArray[Int]
+pub fn Image::histogram_rgb(Self) -> (FixedArray[Int], FixedArray[Int], FixedArray[Int])
 pub fn Image::hue_rotate(Self, Double) -> Self
 pub fn Image::integral_image(Self) -> Integral
 pub fn Image::invert(Self) -> Self